# Mesh File-Based Task Queue — Detail (Stand 2026-08-02)

Entstanden aus Nutzer-Frust über leere Webhook-Antworten und Agenten, die
Aufgaben versprechen aber nie Rückmeldung geben. Nutzer-Präferenz: Agents
sollen sich über den Share DIREKT verständigen, OHNE manuellen Relay. Der
Nutzer mischt sich nur bei kostenpflichtigen Aktionen ein (Essen bestellen,
Token-Kauf).

## Warum File-basiert statt Webhook

- Webhooks A→B liefern 202, aber B antwortet ins Leere (void); Nutzer musste
  Relay spielen.
- Hermes blockt curl/Shell aus Webhook-Sessions (Sandbox).
- Rollback-Pfade unfair: Webhook = einseitig, keine Lebenszeichen.
- File-Status über Ordner ist atomar, idempotent, konfliktfrei per `mv`.

## Ordnerstruktur

```
/srv/work/
├── todo/         # offene Aufgaben (Dateiname = <ZT-IP>_<name>.md)
├── inProgress/   # wird bearbeitet
├── finished/     # erledigt, verifiziert
├── bugged/       # gescheitert / Formatfehler
└── completed/    # fertige Artefakte (HTML, Dateien, ...)
```

## Task-Dateiformat (YAML Frontmatter + Markdown)

```markdown
---
task_id: hello-world-001
assigned_to: 172.24.34.142      # Ziel-Agent-ZT-IP (Dateiname = Präfix)
created_by: agent-a
project: Mesh-Test
retries: 3
status: todo
---
# Titel

Aufgabenbeschreibung. Ergebnis schreibt der Executor unter `# Ergebnis`.
```

## Executor-Regeln (Sub-Agent)

1. Nur Dateien greifen, deren Dateiname die EIGENE ZT-IP trägt
2. `todo/` → `inProgress/`
3. Ergebnis unter `# Ergebnis` in dieselbe Datei
4. `inProgress/` → `finished/` (Erfolg) oder → `bugged/` (eigener Fehler)

## Master-Cron (`scripts/master-task-handler.sh`)

- Cron: `*/5 * * * *`
- Bereinigt verwaiste `.lock` (>15 min)
- Stale inProgress-Dateien (>30 min, ohne Lock) → zurück nach todo
- finished/ validiert: YAML-Frontmatter + `# Ergebnis` vorhanden
- bugged/: `retries > 0` → dekrementieren + zurück nach todo; sonst bleibt
- Artefakte nach completed/ spiegeln (optional auch auf Dokumentations-Website)

## Share-Sicherheit (nur ZeroTier, nie öffentlich)

Samba:
```ini
[work]
  path = /srv/work
  hosts allow = 172.24.           # ZeroTier-Subnetz
  hosts deny = 0.0.0.0/0
```
NFS: `/srv/work <ZT_IP>(rw,sync,no_subtree_check)` in /etc/exports
SSHFS: `sshfs root@<ZT_IP_A>:/srv/work /srv/work`

## Pitfalls

- Aufgabe in `todo/` legen reicht NICHT ohne Executor-Cron auf der Gegenseite
  → bleibt ewig liegen (wie Message Bus ohne Poll-Cron).
- Verwaistes Ergebnis-Slot: Webseite zeigt Aufgabenliste live aus Share;
  Render-Pfad `/completed/` immer anlegen.
- Netzwerk konsolidieren: nur EIN aktives ZT-Netzwerk. Nach Wechsel Samba/NFS-
  Regeln, UFW, Skills, duo_state.json auf neue Subnetze prüfen.
- Nutzer-Präferenz „kein Ghosting": versprochene Aktion AUSFÜHREN und Ergebnis
  melden — nie nur „ich mache es" schreiben und verstummen.

## Beispiel-Projektsync

Eine Dokumentations-Website (z.B. dokumentationen.perfekt-ohne-en.de) zeigt
alle Tasks und ihre Status live aus dem Share; Hello-World-Test als erstes
Mesh-Artefakt.