adispatchd 0.0.0-stage → 0.1.0

package/docs/manual-tests/process-supervision.md

@@ -0,0 +1,64 @@
+# Manueller Spike: Prozess-Supervision unter Linux (Spec §13, §24.3)
+
+Ziel: vor der Produktionsfreigabe klären, ob Prozessgruppen + Startidentität (`linux:<boot-id>:<starttime>` aus
+`/proc/<pid>/stat`) für Cancel und Crash-Recovery genügen oder ob systemd-Scopes/cgroups bzw. ein Wrapper nötig sind.
+Automatisierte Tests laufen nur auf macOS bzw. mit simuliertem procfs (WI-05/WI-08). Durchführung auf einer Linux-VM,
+einmal **ohne** systemd (Vordergrund-`start`) und einmal **unter** systemd (`service install`, siehe [systemd.md](systemd.md)).
+
+## Vorbereitung
+
+```bash
+adispatch init --config-dir ~/spike/config --data-dir ~/spike/data
+cd ~/spike/config
+cat > scripts/tree.sh <<'EOF'
+#!/bin/sh
+# Prozessbaum: Vordergrundkind, Hintergrundkind, Enkel mit eigener Session, Zombie-Kandidat
+sleep 600 &
+sh -c 'sleep 600' &
+setsid sh -c 'echo $$ > /tmp/spike-setsid.pid; sleep 600' &
+echo "@@ADISPATCH_EVENT {\"type\":\"status\",\"message\":\"tree started\"}"
+sleep 600
+EOF
+chmod 0750 scripts/tree.sh
+cat > workflows/tree.yaml <<'EOF'
+id: tree
+trigger: { type: manual }
+execute: { type: shell, command: scripts/tree.sh, cancel_grace: 5s }
+EOF
+adispatch start --config-dir ~/spike/config --data-dir ~/spike/data &   # ohne systemd
+start_tree() { curl -s -X POST -H 'X-Adispatch-Request: 1' http://127.0.0.1:8787/api/v1/workflows/tree/start | jq -r .run.id; }
+show() { ps -eo pid,pgid,sid,stat,lstart,cmd --forest | grep -E 'tree.sh|sleep 600' | grep -v grep; }
+```
+
+## Checkliste
+
+| # | Szenario | Erwartung | Ergebnis |
+|---|---|---|---|
+| P1 | `id=$(start_tree); show` | Worker ist Leader einer eigenen Prozessgruppe/Session (PGID = PID = SID); `sleep`-Kinder in derselben Gruppe; setsid-Enkel in eigener Session | |
+| P2 | `curl -s http://127.0.0.1:8787/api/v1/runs/$id \| jq .pid`; `cat /proc/<pid>/stat \| awk '{print $22}'`; `cat /proc/sys/kernel/random/boot_id` | in der DB (`runs.process_start_identity`) steht `linux:<boot-id>:<starttime>` passend zu `/proc` | |
+| P3 | **Cancel:** `curl -X POST -H 'X-Adispatch-Request: 1' …/runs/$id/cancel`; nach 6 s `show` | ganze Gruppe weg (TERM, nach 5 s KILL); Run `cancelled`; **setsid-Enkel lebt weiter** (bekannte Grenze, Skript-Verantwortung) → `kill $(cat /tmp/spike-setsid.pid)` | |
+| P4 | **Timeout:** `timeout: { max_duration: 10s }` ergänzen, Reload, Start | nach 10 s TERM→KILL an die Gruppe, Run `timed_out` | |
+| P5 | **Orchestrator-Absturz ohne systemd:** Run starten, `kill -9 <orchestrator-pid>`, `show` | Worker-Gruppe lebt weiter (verwaist, PPID 1/Subreaper) | |
+| P6 | Orchestrator neu starten | Recovery verifiziert die Identität, beendet die Gruppe (TERM→KILL), Run `crashed` + `on_crash`; `/ready` erst danach `200` | |
+| P7 | **PID-Wiederverwendung simulieren:** P5 wiederholen, Worker-Gruppe manuell beenden, in der DB `process_start_identity` auf einen falschen `starttime` setzen (`sqlite3 data/adispatchd.sqlite "UPDATE runs SET process_start_identity=json_set(process_start_identity,'$.token','linux:<boot-id>:1') WHERE id='$id'"`), dabei einen fremden Prozess mit derselben PID nicht nötig – Neustart | kein Signal an fremde Prozesse; Run `crashed` (Gruppe weg) bzw. `recovery_pending` (Gruppe mit alter PGID existiert) + Notification `recovery_failed` | |
+| P8 | **`recovery_pending` auflösen:** UI „Retry Recovery“ bzw. `POST /api/v1/runs/$id/recovery/retry` (`{"assumeGone":true}`) | Run finalisiert (`crashed`), Lock frei | |
+| P9 | **Zombies:** Worker, dessen Kind nicht gereapt wird (z. B. Container ohne Init, `docker run` ohne `--init`) | Cancel meldet kein falsches `kill_failed` (Zombies zählen nicht); Empfehlung `--init`/tini bestätigt | |
+| P10 | **Container:** Worker startet `docker run --rm alpine sleep 600` (ohne `-d`) | Cancel beendet den `docker`-CLI-Prozess; Container läuft u. U. weiter → Skript braucht `trap 'docker stop …' TERM` bzw. `--init`; dokumentieren | |
+| P11 | **Unter systemd** (`KillMode=mixed`): P5 mit `systemctl kill --kill-whom=main --signal=SIGKILL` | systemd SIGKILLt die ganze cgroup inkl. Worker **und** setsid-Enkel; Recovery findet die Gruppe weg → `crashed` | |
+| P12 | Unter systemd: `systemd-cgls -u adispatchd.service` während eines Runs | alle Worker (auch setsid/nohup) in der Dienst-cgroup; Docker-Container **nicht** (gehören zu dockerd) | |
+| P13 | Unter systemd: `systemctl stop` während P1 | nur der Hauptprozess bekommt SIGTERM (Worker laufen bis Drain-Timeout weiter); danach Cancel der Gruppe | |
+
+## Auswertung / Entscheidung
+
+Festhalten, ob für V1 ausreichend:
+
+- Prozessgruppe + Startidentität für Cancel/Timeout/Recovery (P1–P8),
+- systemd-cgroup als Sicherheitsnetz für Abstürze (P11–P13),
+- oder ob Worker zusätzlich in eigene transiente Scopes (`systemd-run --scope --unit=orch-run-<id>`) bzw. einen Wrapper
+  gehören, um auch setsid-/nohup-Prozesse bei Cancel (nicht nur beim Dienst-Stop) zuverlässig zu erfassen.
+
+## Protokoll
+
+| Datum | Host / Kernel / systemd / Node | Version | Schritte | Beobachtung / Entscheidung |
+|---|---|---|---|---|
+| | | | | |

package/docs/manual-tests/systemd.md

@@ -0,0 +1,68 @@
+# Manuelle Tests: systemd-Dienst (Spec §22.1 „systemd“, §14, §24.4, Szenario 12)
+
+Automatisiert (auf macOS) sind nur die Unit-Generierung (Snapshot), `service install|uninstall --dry-run`, Drain/Cancel-All
+über die API, der Exit-Code-Vertrag des CLI-Starts (SIGTERM → Exit 0), Migration mit Backup und das `npm pack`-Update
+(`npm run test:pack`). Diese Checkliste prüft den echten Service-Vertrag auf einem **Linux-Host mit systemd** (Wegwerf-VM,
+nicht Produktion). Ergebnisse unten protokollieren.
+
+## Vorbereitung
+
+```bash
+# VM: Debian/Ubuntu mit systemd, Node 24 systemweit (/usr/bin/node)
+npm pack                                        # im Repo → adispatchd-0.1.0.tgz
+scp adispatchd-0.1.0.tgz vm:
+ssh vm
+sudo npm install -g ./adispatchd-0.1.0.tgz
+sudo adispatch init --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd
+```
+
+Test-Workflow mit langem, gut erkennbarem Worker (manuell gestartet, ohne GitHub):
+
+```bash
+sudo tee /etc/adispatchd/scripts/long.sh >/dev/null <<'EOF'
+#!/bin/sh
+trap 'echo "got TERM"; exit 143' TERM
+echo "@@ADISPATCH_EVENT {\"type\":\"status\",\"message\":\"sleeping $1s\"}"
+sleep "$1" & wait $!
+EOF
+sudo chmod 0750 /etc/adispatchd/scripts/long.sh
+sudo tee /etc/adispatchd/workflows/long.yaml >/dev/null <<'EOF'
+id: long
+trigger: { type: manual }
+parameters: { seconds: { type: number, default: 600 } }
+execute: { type: shell, command: scripts/long.sh, args: ['{parameters.seconds}'], cancel_grace: 10s }
+on_cancel: [ { type: shell, command: /bin/echo, args: ['on_cancel {run.id}'] } ]
+on_crash:  [ { type: shell, command: /bin/echo, args: ['on_crash {run.id}'] } ]
+EOF
+start_long() { curl -s -X POST -H 'X-Adispatch-Request: 1' -H 'Content-Type: application/json' \
+  -d "{\"parameters\":{\"seconds\":$1}}" http://127.0.0.1:8787/api/v1/workflows/long/start | jq -r .run.id; }
+run_status() { curl -s http://127.0.0.1:8787/api/v1/runs/$1 | jq '{status, finalReason, lifecycleStatus}'; }
+```
+
+## Checkliste
+
+| # | Schritt | Erwartung | Ergebnis |
+|---|---|---|---|
+| S1 | `sudo adispatch service install --dry-run --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --create-user` | Unit mit `/usr/bin/node …/dist/cli/main.js start …`, kein `npx`, `User=adispatchd`, `KillMode=mixed`, `Restart=on-failure`, `TimeoutStopSec=810`; nichts geändert (`id adispatch` → unbekannt, keine Unit-Datei) | |
+| S2 | wie S1 ohne `--dry-run` | Benutzer angelegt (`/usr/sbin/nologin`), `/var/lib/adispatchd` 0750 `adispatchd`, `/etc/adispatchd` `root:adispatchd` 0750/0640, `/etc/default/adispatchd` 0640 (Vorlage), Unit enabled; `systemd-analyze verify /etc/systemd/system/adispatchd.service` ohne Fehler | |
+| S3 | `sudo systemctl start adispatchd; adispatch status --config-dir /etc/adispatchd` | `ready: yes`; `ps -o user= -C node` → `adispatchd`; Dienst kann `/etc/adispatchd` nicht beschreiben (`sudo -u adispatchd touch /etc/adispatchd/x` → Permission denied) | |
+| S4 | **Drain per CLI:** `id=$(start_long 20)`, `adispatch drain --config-dir /etc/adispatchd --wait` | Run läuft zu Ende (`completed`), danach Exit 0; `systemctl status` → `inactive (dead)`, **kein** Neustart (`journalctl` zeigt keinen Restart, `NRestarts=0` in `systemctl show -p NRestarts`) | |
+| S5 | **systemctl stop während eines Runs:** Dienst starten, `id=$(start_long 30)`, `sudo systemctl stop adispatchd` | `stop` blockiert bis der Run fertig ist (Drain; Worker bekam **kein** SIGTERM: kein „got TERM“ im Run-Log), Run `completed`, Exit 0 | |
+| S6 | **Drain-Timeout → Cancel-All:** Unit mit `--drain-timeout 20s --cancel-timeout 30s` neu installieren, `start_long 600`, `systemctl stop` | nach ~20 s Cancel: Worker-Log „got TERM“, Run `cancelled`, `on_cancel` gelaufen, Dienst gestoppt deutlich vor `TimeoutStopSec` | |
+| S7 | **Zweites SIGTERM:** `start_long 600`, `sudo systemctl stop adispatchd &`, dann `sudo systemctl kill --kill-whom=main --signal=SIGTERM adispatchd` | sofortiges Cancel-All, Run `cancelled`, Exit 0 | |
+| S8 | **Cancel-All per CLI:** `start_long 600`, `adispatch cancel-all --config-dir /etc/adispatchd --wait` | Run `cancelled`, `on_cancel`, Exit 0, kein Neustart | |
+| S9 | **App-Absturz:** `start_long 600`, `sudo systemctl kill --kill-whom=main --signal=SIGKILL adispatchd` | systemd tötet die cgroup inkl. Worker (`pgrep -f long.sh` leer), Neustart nach ~5 s (`NRestarts=1`), Recovery: Run `crashed` + `on_crash`, technischer Zähler +1; `/ready` erst nach Recovery | |
+| S10 | **Absturz mit Exit ≠ 0** (z. B. `kill -SEGV <pid>` oder DB-Datei vorübergehend unlesbar machen) | Neustart (`Restart=on-failure`) | |
+| S11 | **Grace länger als Cancel-Timeout:** Unit mit `--drain-timeout 5s --cancel-timeout 5s`, Worker ignoriert TERM (`trap '' TERM`), `cancel_grace: 300s` **ohne** Neuinstallation, `systemctl stop` | `start` warnt beim Start („not smaller than the cancel timeout“); Hauptprozess endet nach ~5 s Drain + 5 s Cancel + bis 10 s Hook-Abbruch (≈ 20–25 s) mit **Exit 0**, ohne dass der Worker SIGKILL bekam; systemd (`KillMode=mixed`) SIGKILLt danach sofort die restliche cgroup inkl. Worker (nicht erst nach `TimeoutStopSec`); nächster Start: Run `crashed` + `on_crash` (kein hängender Lock) | |
+| S11b | **Konfigurationsfehler:** YAML-Syntaxfehler in `config.yaml`, `systemctl restart` | Exit 78, `systemctl status` zeigt `status=78`, **kein** Neustart-Loop (`NRestarts` bleibt) | |
+| S12 | **Boot-Recovery:** `start_long 600`, `sudo reboot` | Dienst startet nach Boot automatisch; Run `crashed` + `on_crash`; Boot-ID-Wechsel → keine fremden Prozesse signalisiert | |
+| S13 | **Update-Migration (Szenario 12):** mit Version N Runs erzeugen, `drain --wait`, Version N+1 (mit neuer Migration) als Tarball `npm install -g ./adispatchd-<N+1>.tgz`, `systemctl start` | `journalctl`: „database backup written before migration“ + Pfad, „database migrated“; `backups/orchestrator-<N>-*.sqlite` vorhanden; alte Runs, Logs, Blocks, config-dir und Env-Datei unverändert; neuer Run funktioniert | |
+| S14 | **Rollback:** Dienst stoppen, Version N installieren, Backup als `adispatchd.sqlite` zurück (inkl. `-wal`/`-shm` entfernen), starten | startet mit Version N; DB mit neuerer Version ohne Rückspielen → Start abgelehnt („newer than this build supports“) | |
+| S15 | **Zweite Instanz:** bei laufendem Dienst `sudo -u adispatchd adispatch start --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --port 8788` | sofortiger Abbruch „Another orchestrator instance is running on this data directory“ | |
+| S16 | `sudo adispatch service uninstall` | Dienst gedraint und deaktiviert, Unit-Datei weg; config-dir, data-dir, Env-Datei, Benutzer bleiben | |
+
+## Protokoll
+
+| Datum | Host / Distribution / systemd / Node | Version | Schritte | Beobachtung |
+|---|---|---|---|---|
+| | | | | |

package/docs/operations.md

@@ -0,0 +1,271 @@
+# Betrieb
+
+Installation als Dienst, Shutdown/Drain, Updates, Backups, Recovery und Fernzugriff. Spec §4, §13, §14, §15, §20, §21.
+API-Referenz: [api.md](api.md) · Worker-Vertrag: [worker-protocol.md](worker-protocol.md) · Cron: [cron-semantics.md](cron-semantics.md)
+
+## Verzeichnisse und Rechte
+
+| Pfad (Vorschlag) | Inhalt | Eigentümer / Modus |
+|---|---|---|
+| `/etc/adispatchd/` (config-dir) | `config.yaml`, `sources.yaml`, `identities.yaml`, `workflows/`, `views/`, `scripts/` | `root:adispatchd`, Verzeichnisse 0750, Dateien 0640, Skripte 0750 |
+| `/etc/default/adispatchd` | Secrets als Umgebungsvariablen (GitHub-App-Keys, Webhook-URLs) | `root:adispatchd`, 0640 |
+| `/var/lib/adispatchd/` (data-dir) | `adispatchd.sqlite` (+ `-wal`/`-shm`), `adispatchd.lock`, `logs/`, `runs/`, `workspaces/`, `backups/` | `adispatchd`, 0750 |
+| Paket, z. B. `/usr/lib/node_modules/adispatchd/` | Code (`dist/`), wird bei Updates ersetzt | `root`, nur lesbar für den Dienst |
+
+- **Schreibrecht auf config-dir = Codeausführung** mit den Rechten des Dienstes (Skripte, Kommandos in YAML, Spec §20.2).
+  Deshalb gehört config-dir `root`, der Dienst kann seine eigene Konfiguration nicht ändern.
+- **data-dir muss auf einem lokalen Dateisystem liegen (kein NFS/SMB).** Der Instanz-Lock (`adispatchd.lock`) beruht auf
+  `fcntl`-Sperren, die auf Netzwerk-Dateisystemen unzuverlässig sind; zwei Instanzen auf demselben data-dir wären möglich.
+- Es läuft genau **eine** Instanz pro data-dir (OS-Sperre, wird bei Prozessende immer freigegeben, auch nach SIGKILL).
+  Mehrere Instanzen mit getrennten data-dirs koordinieren sich nicht.
+- `workspace.base_dir` (Default `<data-dir>/workspaces`) muss für den Dienst schreibbar sein; liegt es außerhalb von
+  data-dir, Rechte selbst setzen.
+
+## Installation als systemd-Dienst (Linux)
+
+Voraussetzungen: Linux mit systemd, Node.js ≥ 22.13 (empfohlen 24 LTS) **systemweit** installiert (z. B. `/usr/bin/node`
+aus Distribution/NodeSource – nicht aus `nvm` im Home-Verzeichnis, das der Dienstbenutzer nicht lesen kann).
+
+```bash
+# 1. Feste Version global installieren (kein npx im Dienst!).
+sudo npm install -g adispatchd@0.1.0
+#    alternativ aus dem Repository-Checkout: npm install && npm pack && sudo npm install -g ./adispatchd-0.1.0.tgz
+
+# 2. Konfiguration anlegen (überschreibt nie bestehende Dateien)
+sudo adispatch init --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd
+sudoedit /etc/adispatchd/sources.yaml /etc/adispatchd/identities.yaml   # anpassen
+sudo adispatch config validate --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd
+
+# 3. Vorschau: Unit-Datei und geplante Schritte (ändert nichts)
+sudo adispatch service install --dry-run \
+  --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --create-user
+
+# 4. Installieren: Benutzer anlegen, Rechte setzen, Env-Datei-Vorlage, Unit schreiben, daemon-reload, enable
+sudo adispatch service install \
+  --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --create-user
+
+# 5. Secrets eintragen und starten
+sudoedit /etc/default/adispatchd
+sudo systemctl start adispatchd
+adispatch status --config-dir /etc/adispatchd
+journalctl -u adispatchd -f
+```
+
+Optionen von `service install`: `--user`/`--group` (Default `adispatchd`), `--create-user`, `--name` (Unit-Name),
+`--node`/`--entry` (absolute Pfade, Default: das laufende Node und diese Installation), `--env-file <pfad|none>`,
+`--drain-timeout` (Default 10m), `--cancel-timeout` (Default 2m), `--unit-dir`, `--now` (sofort starten).
+`service install` verweigert `npx`-Cache-Pfade, relative Pfade, TypeScript-Quellen und `root` als Dienstbenutzer.
+Außerhalb von `--dry-run` bricht `service install` ab, wenn `config.yaml` fehlt oder die Konfiguration ungültig ist
+(Schutz vor Tippfehlern, da `chown -R`/`chmod -R` auf config-dir und data-dir laufen). Systemverzeichnisse (`/`, `/etc`,
+`/var`, `/var/lib`, `/usr`, `/home`, `/opt`, `/root`, `/tmp`, …), Pfade direkt unter `/`, Home-Verzeichnisse sowie gleiche
+oder ineinander verschachtelte config-/data-dirs werden abgelehnt (auch über Symlinks). Ohne `--create-user` muss der Benutzer existieren (Hinweis mit passendem `useradd`-Kommando). Eine bestehende Env-Datei wird
+nie überschrieben. `service status` zeigt `systemctl status`; `service uninstall` stoppt (Drain), deaktiviert und entfernt nur
+die Unit-Datei – config-dir, data-dir und Benutzer bleiben. Auf macOS lehnen die Kommandos mit Erklärung ab
+(`--dry-run` funktioniert überall).
+
+### Generierte Unit (Beispiel)
+
+```ini
+[Service]
+Type=simple
+User=adispatchd
+Group=adispatchd
+ExecStart=/usr/bin/node /usr/lib/node_modules/adispatchd/dist/cli/main.js start --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --drain-timeout 10m --cancel-timeout 2m
+WorkingDirectory=/var/lib/adispatchd
+EnvironmentFile=-/etc/default/adispatchd
+Environment=NODE_ENV=production
+Restart=on-failure
+RestartSec=5s
+RestartPreventExitStatus=78
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=810
+UMask=0027
+NoNewPrivileges=true
+PrivateTmp=true
+```
+
+`NoNewPrivileges` verhindert `sudo`/setuid in Workern, `PrivateTmp` gibt dem Dienst ein eigenes `/tmp`. Werden weitere
+Härtungen (`ProtectSystem=`, `ReadWritePaths=`) gewünscht, per Drop-in (`systemctl edit adispatchd`) ergänzen –
+Agent-Skripte brauchen oft Schreibzugriff auf Caches im Home-Verzeichnis. Änderungen direkt in der Unit-Datei überschreibt
+das nächste `service install`.
+
+### Stop-/Restart-Vertrag (Spec §14, §24.4)
+
+| Ereignis | Verhalten | Exit | systemd |
+|---|---|---|---|
+| `systemctl stop` / `restart` | SIGTERM an den **Hauptprozess** → Drain bis `--drain-timeout`, dann Cancel-All (`on_cancel`) bis `--cancel-timeout`, danach werden Hooks unterbrochen (Recovery setzt sie beim nächsten Start fort) | 0 | gestoppt |
+| zweites SIGTERM (`systemctl kill --kill-whom=main --signal=SIGTERM adispatchd`) | sofort Cancel-All | 0 | gestoppt |
+| drittes Signal | sofortiger Exit (Recovery räumt beim nächsten Start auf) | 1 | – |
+| `adispatch drain` / UI „Drain“ | keine neuen Runs, aktive laufen zu Ende, dann Ende | 0 | inactive, **kein** Neustart |
+| `adispatch cancel-all` / UI „Cancel All“ | alle Runs abbrechen, `on_cancel`, dann Ende | 0 | inactive, **kein** Neustart |
+| Konfigurations-/Startfehler (ungültige YAML, Instanz-Lock belegt, DB-Schema neuer als der Code) | Start abgebrochen | 78 (EX_CONFIG) | **kein** Neustart (`RestartPreventExitStatus=78`) – Fehler beheben, dann `systemctl start` |
+| Absturz / Exit ≠ 0 | – | ≠ 0 | Neustart nach 5 s → Recovery |
+| `TimeoutStopSec` abgelaufen | systemd SIGKILLt die ganze cgroup inkl. Worker | – | gestoppt; nächster Start: Runs `crashed` + `on_crash` |
+
+- **`KillMode=mixed`**: SIGTERM geht nur an den Orchestrator, Worker laufen während des Drains weiter. Mit dem Default
+  `control-group` bekämen alle Worker sofort SIGTERM (gleiche cgroup trotz eigener Prozessgruppe) → kein Drain möglich.
+- **`TimeoutStopSec`** = Drain-Timeout + Cancel-Timeout + größtes `execute.cancel_grace` der Konfiguration + 60 s Puffer
+  (wird bei `service install` aus der Konfiguration berechnet). Die Grace-Zeit (SIGTERM → SIGKILL der Worker-Gruppe) läuft
+  **innerhalb** des Cancel-Timeouts – danach werden Hooks unterbrochen und der Orchestrator beendet sich; der Grace-Term ist
+  nur Sicherheitsmarge. `cancel_grace` muss daher **kleiner als `--cancel-timeout`** sein, sonst beendet sich der Orchestrator
+  ggf. vor dem SIGKILL (dann räumt erst systemd per cgroup ab) – `service install` und `start` warnen.
+- **`Restart=on-failure`**: Ein absichtlicher Shutdown über UI/CLI endet mit Exit 0 und wird **nicht** als Crash neu gestartet.
+- **Lange Runs:** Ein Agent-Run dauert oft länger als der Drain-Timeout. `systemctl stop` kann einen vollständigen Drain daher
+  nicht garantieren – für geplante Stopps vorher `adispatch drain --wait` ausführen (beliebig lange, ohne Timeout)
+  und erst danach `systemctl stop`/Update/Reboot.
+- **Absturz unter systemd:** Stirbt der Hauptprozess, beendet systemd (bei `KillMode=mixed`) auch alle Worker der cgroup per
+  SIGKILL. Die Recovery findet beim Neustart die Prozessgruppen daher i. d. R. bereits beendet und finalisiert die Runs als
+  `crashed` mit `on_crash` (zählt als technischer Fehler, ggf. Retry-Block). Verwaiste, noch lebende Worker (Recovery tötet
+  sie nur bei sicher verifizierter Identität) entstehen v. a. außerhalb von systemd (lokaler Start, `KillMode=process`).
+- **Reboot:** wie Absturz – alle Worker sind weg → `crashed` + `on_crash`. Geplante Reboots daher vorher drainen.
+
+## Pause, Drain, Cancel-All
+
+```bash
+adispatch status    --config-dir /etc/adispatchd     # Zustand, Limits, Auslastung, Blocks
+adispatch pause     --config-dir /etc/adispatchd     # keine automatischen Starts (manuelle weiter möglich)
+adispatch resume    --config-dir /etc/adispatchd
+adispatch drain     --config-dir /etc/adispatchd --wait [--timeout 2h]
+adispatch cancel-all --config-dir /etc/adispatchd --reason "maintenance" --wait
+adispatch config reload --config-dir /etc/adispatchd # atomar; ungültige YAML behält aktive Konfiguration
+adispatch workflow dry-run coder --config-dir /etc/adispatchd   # gegen die laufende Instanz, sonst lokal
+```
+
+Die Kommandos sprechen per HTTP mit der laufenden Instanz: `--url http://127.0.0.1:8787` oder – mit `--config-dir` – Host/Port
+aus `config.yaml` (Wildcard-Binds `0.0.0.0`/`::` werden über Loopback angesprochen). **Als normaler Benutzer (nicht root)
+`--url` verwenden:** das config-dir ist nach `service install` nur für root und die Dienstgruppe lesbar; mit `--config-dir`
+meldet das Kommando dann „not readable (permission denied)“ und fällt auf `http://127.0.0.1:8787` zurück. URLs mit
+Zugangsdaten (`user:pass@`) werden abgelehnt (Exit 2) – Proxy-Authentifizierung unterstützt die CLI nicht; auf dem Host
+selbst die lokale URL nutzen. Sie senden den CSRF-Header
+`X-Adispatch-Request: 1`. Exit-Codes: 0 ok, 1 API-Fehler (z. B. Reload abgelehnt), 2 Aufruffehler, 3 Instanz nicht
+erreichbar, 4 `--wait`-Timeout (der Shutdown läuft im Hintergrund weiter). `workflow dry-run` fällt ohne erreichbare Instanz
+auf die lokale Auswertung zurück (`--local` erzwingt sie; mit explizitem `--url` kein Fallback).
+
+## Update (Spec §4, Szenario 12)
+
+Updates ersetzen nur den Code; config-dir, data-dir und Env-Datei bleiben unverändert.
+
+```bash
+adispatch drain --config-dir /etc/adispatchd --wait    # aktive Runs sauber beenden (ohne Zeitlimit)
+sudo systemctl stop adispatchd                                  # falls noch aktiv (nach Drain bereits beendet)
+sudo cp -a /etc/adispatchd /root/adispatchd-config-$(date +%F)   # optional, config-dir sichern
+sudo npm install -g adispatchd@<neue-version>          # oder Tarball aus dem Checkout (npm pack)
+sudo adispatch config validate --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd
+sudo adispatch service install --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd   # nur wenn sich Pfade/Optionen ändern
+sudo systemctl start adispatchd
+adispatch status --config-dir /etc/adispatchd
+journalctl -u adispatchd -n 50      # "database migrated" + Backup-Pfad, "recovery finished"
+```
+
+- **DB-Migrationen** sind versioniert und laufen beim Start automatisch. Existiert die DB und stehen Migrationen aus, wird
+  **vorher** eine konsistente Kopie geschrieben: `data-dir/backups/orchestrator-<alte-version>-<zeitstempel>.sqlite`
+  (`VACUUM INTO`, auch im WAL-Modus konsistent). Schlägt eine Migration fehl, wird sie zurückgerollt und der Start abgebrochen.
+- Eine DB mit **neuerer** Schemaversion als der Code kennt wird abgelehnt (kein stilles Downgrade).
+- **Rollback:** Dienst stoppen, alte Paketversion installieren, `adispatchd.sqlite`, `adispatchd.sqlite-wal` und
+  `adispatchd.sqlite-shm` beiseitelegen, das passende Backup als `adispatchd.sqlite` zurückkopieren (Eigentümer
+  `adispatchd`), starten. Runs nach dem Backup-Zeitpunkt fehlen dann in der Historie (ihre Logdateien bleiben).
+- Alte Dateien unter `backups/` werden nicht automatisch gelöscht.
+
+## Backups
+
+| Was | Wie |
+|---|---|
+| config-dir | Versionsverwaltung (git) oder Dateikopie; enthält keine Secrets |
+| Env-Datei | sicher (verschlüsselt) aufbewahren – enthält Private Keys |
+| `adispatchd.sqlite` | im laufenden Betrieb konsistent: `sqlite3 /var/lib/adispatchd/adispatchd.sqlite ".backup '/backup/orch.sqlite'"` (bzw. `VACUUM INTO`); bei gestopptem Dienst auch Dateikopie inkl. `-wal`/`-shm` |
+| `logs/`, `runs/` | normale Dateikopie (DB und Logdateien bilden gemeinsam das Run-Journal) |
+| `workspaces/` | meist nicht nötig (Arbeitskopien der Worker) |
+
+**`adispatchd.lock` und `adispatchd.lock.json` nie öffnen, kopieren, archivieren oder wiederherstellen.** Die Instanzsperre
+ist eine POSIX-`fcntl`-Sperre auf `adispatchd.lock`; sie gehört dem Orchestrator-Prozess und fällt, sobald *dieser* Prozess
+irgendeinen Deskriptor auf die Datei schließt – deshalb öffnet der Orchestrator sie selbst (auch bei Retention/Backups) nie
+ein zweites Mal. Externe Werkzeuge, die die Datei als SQLite-DB öffnen (`sqlite3`, Backup-Agenten mit SQLite-Support),
+konkurrieren um die Sperre und scheitern bzw. blockieren; eine kopierte Lock-Datei ist wertlos. Beim Sichern ausschließen, z. B.:
+
+```bash
+rsync -a --exclude 'adispatchd.lock*' --exclude 'adispatchd.sqlite*' /var/lib/adispatchd/ /backup/orch-data/
+sqlite3 /var/lib/adispatchd/adispatchd.sqlite ".backup '/backup/orch-data/adispatchd.sqlite'"
+```
+
+Wiederherstellen nur bei gestopptem Dienst; die Lock-Dateien legt der Orchestrator selbst neu an.
+
+## Recovery nach Absturz
+
+Beim Start erfasst die Recovery alle zuvor aktiven Runs, **bevor** der Scheduler startet (`/ready` erst danach `200`):
+
+- noch lebende, sicher identifizierte Worker-Prozessgruppen (PID + Startzeit/Boot-ID) werden beendet; verschwundene Runs
+  werden `crashed` mit `on_crash` (zählt als technischer Fehler); halb abgearbeitete Lifecycle-Ketten werden fortgesetzt
+  (bereits erfolgreiche Actions laufen nicht erneut; Kommentare werden über Marker abgeglichen).
+- **`recovery_pending`**: Prozess nicht sicher identifizierbar oder nicht beendbar → der Run bleibt sichtbar aktiv, hält
+  seinen Lock (kein Doppelstart) und erzeugt die Notification `recovery_failed`. Lösung: Prozess prüfen/beenden, dann in der
+  UI „Retry Recovery“ bzw. `POST /api/v1/runs/<id>/recovery/retry` (mit `{"assumeGone": true}`, wenn sicher ist, dass der
+  Prozess weg ist).
+- Retry-Blocks (UI „Blocked“), fehlgeschlagene Lifecycle-Actions (UI „Failed Actions“, Retry/Skip) und
+  Benachrichtigungs-Fehlzustellungen bleiben über Neustarts erhalten.
+
+## Fernzugriff, Reverse Proxy (Spec §15, §20.1)
+
+V1 hat **keine Anmeldung**. Standard ist `server.host: 127.0.0.1`. Bei einem Nicht-Loopback-Bind warnt `start` deutlich.
+
+- Zugriff von außen nur über einen **authentifizierenden** Reverse Proxy (z. B. nginx/Caddy mit OIDC über `oauth2-proxy`,
+  Basic-Auth über TLS), VPN oder Tailscale. Der Proxy muss **jede** Anfrage authentifizieren, auch `/api/v1/events` (SSE).
+- Den öffentlichen Namen des Proxys in `server.allowed_hosts` eintragen (DNS-Rebinding-Schutz: jede Anfrage braucht einen
+  erlaubten `Host`, ein gesendeter `Origin` muss exakt passen); der Proxy muss den ursprünglichen `Host` weiterreichen.
+- Keine CORS-Header am Proxy hinzufügen; mutierende Requests brauchen `X-Adispatch-Request: 1` (die UI setzt ihn).
+
+```yaml
+# config.yaml
+server:
+  host: 127.0.0.1
+  port: 8787
+  allowed_hosts: [orchestrator.example.com]
+```
+
+```nginx
+server {
+  listen 443 ssl;
+  server_name orchestrator.example.com;
+  # ssl_certificate …;
+  auth_basic "Agent Dispatch Daemon";                 # oder auth_request an oauth2-proxy
+  auth_basic_user_file /etc/nginx/orchestrator.htpasswd;
+  location / {
+    proxy_pass http://127.0.0.1:8787;
+    proxy_set_header Host $host;                   # muss in server.allowed_hosts stehen
+    proxy_http_version 1.1;
+    proxy_buffering off;                           # SSE (/api/v1/events)
+    proxy_read_timeout 1h;
+  }
+}
+```
+
+Tailscale: `tailscale serve --bg http://127.0.0.1:8787` und den MagicDNS-Namen in `allowed_hosts` eintragen.
+
+## Observability
+
+- `GET /health` (Prozess lebt), `GET /ready` (DB ok, Recovery fertig, Scheduler läuft, kein Shutdown), `adispatch status`.
+- Dienstlog: JSON-Zeilen auf stderr → `journalctl -u adispatchd` (Secrets werden redigiert).
+- Run-Logs: `data-dir/logs/<run-id>/{stdout,stderr}.log`, Events/Status in SQLite, live per SSE.
+- Aufbewahrung über `retention` in `config.yaml` (Default: erfolgreiche Runs 30 d, fehlgeschlagene 90 d, Block-Runs nie,
+  100 MB Log pro Run, Prüfung alle 24 h). Aktive Runs, offene Blocks und unvollständige Aktionsketten werden nie gelöscht.
+
+## Fehlerbilder
+
+| Meldung | Ursache / Lösung |
+|---|---|
+| „Another orchestrator instance is running on this data directory (pid …)“ | Eine andere Instanz nutzt das data-dir. |
+| `cannot listen: EADDRINUSE` | Port belegt → `server.port` ändern oder `start --port`. |
+| `Configuration … is invalid` | `config validate` zeigt Datei:Zeile: Pfad: Meldung. |
+| „Database schema version … is newer than this build supports“ | data-dir stammt von einer neueren Version → passende Version installieren oder Backup einspielen. |
+| `ExperimentalWarning: SQLite` | Node 22: `node:sqlite` ist experimentell; Node 24 verwenden. |
+| `GITHUB_…_PRIVATE_KEY is not set` | Env-Datei fehlt/unvollständig (`systemctl show adispatchd -p EnvironmentFiles`). |
+
+## Bekannte Grenzen
+
+- Die Source-ID ist Teil des Item-Schlüssels (`<source>:<nummer>`): Umbenennen einer Source trennt die Run-Historie und
+  Retry-Blocks von den Items.
+- Prozesse außerhalb der Worker-Prozessgruppe (eigene Session, Container) beendet der Orchestrator nicht (siehe
+  [worker-protocol.md](worker-protocol.md#abbruch-timeout-prozesse)).
+- Linux-spezifisches Verhalten (systemd, cgroups, Prozessidentität über `/proc`) ist manuell zu prüfen:
+  [manual-tests/systemd.md](manual-tests/systemd.md), [manual-tests/process-supervision.md](manual-tests/process-supervision.md);
+  GitHub-Annahmen: [manual-tests/github.md](manual-tests/github.md).

package/docs/worker-protocol.md

@@ -0,0 +1,145 @@
+# Worker-Protokoll
+
+Vertrag zwischen Orchestrator und Haupt-Worker (`execute`) bzw. Shell-Lifecycle-Actions. Spec §8.2, §9, §13, §20.
+Implementierung: `src/core/worker-protocol.ts`, `src/executors/`.
+
+## Start
+
+- Jeder Run bekommt einen **eigenen Workspace** (Default `{workspace.base_dir}/{workflow.id}/{run.id}`, `create_directory: true`);
+  der Orchestrator legt ihn an. Klonen, Git-Worktrees, `npm install`, Docker … erledigt das Skript selbst.
+- Das Kommando wird **ohne Shell** mit Argumentliste gestartet (`command` + `args`); Platzhalter in `args`/`env` werden vorher
+  ersetzt (feste Platzhalterliste, unbekannte sind Konfigurationsfehler). Wer Shell-Syntax braucht, schreibt ein Skript.
+- Eigene Prozessgruppe/Session (`setsid`), stdin = `/dev/null`, cwd = Workspace.
+
+## Input
+
+### Umgebung (Minimalumgebung, Spec §9.1/§20.3)
+
+Der Worker erbt **nicht** die Umgebung des Orchestrators. Er bekommt nur:
+
+| Variable | Inhalt |
+|---|---|
+| `PATH`, `HOME`, `LANG`, `TZ`, `USER`, `LOGNAME`, `TMPDIR` | aus der Controller-Umgebung (Fallback-`PATH` `/usr/local/bin:/usr/bin:/bin`) |
+| `execute.env` | explizite Werte aus der Workflow-YAML (keine Secrets!) |
+| `execute.secrets` | z. B. `GH_TOKEN: { identity: coder }` → kurzlebiges GitHub-App-Installation-Token, nur im Speicher |
+| `ADISPATCH_RUN_ID` | stabile, eindeutige Run-ID (`run-YYYYMMDDTHHMMSSmmmZ-xxxxxxxx`) |
+| `ADISPATCH_WORKFLOW_ID` | Workflow-ID |
+| `ADISPATCH_SOURCE_TYPE`, `ADISPATCH_SOURCE_ID`, `ADISPATCH_SOURCE_ITEM_ID`, `ADISPATCH_SOURCE_URL` | nur bei Runs mit Source-Item (z. B. `github`, `project_a`, `123`, Issue-URL) |
+| `ADISPATCH_CONTEXT_FILE` | Pfad der Kontextdatei (JSON, s. u.) |
+| `ADISPATCH_RESULT_FILE` | Pfad, an den der Worker optional sein Ergebnis schreibt |
+| `ADISPATCH_WORKSPACE` | absoluter Workspace-Pfad |
+
+`ADISPATCH_*` kann durch `env`/`secrets` nicht überschrieben werden (reservierter Präfix).
+
+### Kontextdatei `ADISPATCH_CONTEXT_FILE` (`data-dir/runs/<run-id>/context.json`, Modus 0600)
+
+```json
+{
+  "schema_version": 1,
+  "run": { "id": "run-…", "trigger": "source", "started_at": "2026-10-16T19:00:00Z" },
+  "workflow": { "id": "coder-project-a", "name": "Coder – Project A" },
+  "source": {
+    "id": "project_a", "type": "github", "item_id": "123", "item_key": "project_a:123",
+    "url": "https://github.com/example/project-a/issues/123",
+    "attributes": { "title": "Implement OAuth", "labels": ["coding"] }
+  },
+  "parameters": {},
+  "workspace": { "path": "/var/lib/adispatchd/workspaces/coder-project-a/run-…" }
+}
+```
+
+`source` fehlt bei Cron-/Manual-Runs ohne Item; `run.scheduled_for` gibt es bei Cron-Runs; `parameters` enthält die validierten
+Parameter manueller Starts (inkl. Defaults). Die Datei enthält **nie** Secrets.
+
+## Output
+
+### Exit-Code und Ergebnisdatei (verbindlich, Spec §8.2)
+
+| Exit-Code | Ergebnisdatei | Ergebnis |
+|---|---|---|
+| `0` | `"result": "success"` | `completed` / `success` → `on_success` |
+| `0` | `"result": "failure"` | `completed` / `failure` → `on_failure` (fachlich, **kein** technischer Fehler) |
+| `0` | keine | `completed` / `success` (einfache Shell-Skripte) |
+| `0` | ungültig / zu groß / kein reguläres File | `crashed` (Protokollfehler) → `on_crash` |
+| `≠ 0` | beliebig (wird ignoriert) | `crashed` → `on_crash` |
+| Signal | beliebig | `crashed` (außer durch Cancel/Timeout) |
+| Start unmöglich (ENOENT, kein Exec-Recht, `on_start` gescheitert) | – | `start_error` → `on_start_error` |
+| Timeout (`max_duration`, `idle_timeout`) | beliebig | `timed_out` → `on_timeout` |
+| kontrollierter Abbruch (UI/API/Cancel-All) | beliebig | `cancelled` → `on_cancel` |
+
+- **Ein fachliches `failure` gibt es nur mit gültiger Ergebnisdatei.** Ein Exit-Code allein ist nie „Needs Maintainer“ – ein
+  versehentliches `exit 1` (z. B. `git clone` scheitert) ist ein technischer Fehler.
+- Technische Fehler (`crashed`, `start_error`, `timed_out`) zählen pro Workflow+Item; nach `retry.max_technical_failures`
+  (Default 3) aufeinanderfolgenden Fehlern entsteht ein **Retry-Block** (UI „Blocked“ → „Remove Block“). `failure` und
+  `cancelled` zählen nicht; ein Erfolg setzt den Zähler zurück.
+
+Ergebnisdatei (max. 1 MiB, **atomar schreiben**: temporäre Datei + `mv`):
+
+```json
+{
+  "schema_version": 1,
+  "result": "failure",
+  "message": "OAuth-Anbieter nicht spezifiziert",
+  "details": { "missing_information": ["OAuth provider", "Scopes"] },
+  "artifacts": [ { "type": "url", "name": "Draft PR", "url": "https://github.com/example/project-a/pull/142" } ]
+}
+```
+
+| Feld | Pflicht | Regel |
+|---|---|---|
+| `schema_version` | ja | `1` |
+| `result` | ja | `success` \| `failure` |
+| `message` | nein | ≤ 10 000 Zeichen; als `{result.message}` in Hooks verfügbar |
+| `details` | nein | beliebiges Objekt |
+| `artifacts` | nein | ≤ 100 Einträge `{type, name?, url?}` |
+
+```sh
+tmp="${ADISPATCH_RESULT_FILE}.tmp"
+printf '%s\n' '{"schema_version":1,"result":"success","message":"PR opened"}' > "$tmp"
+mv "$tmp" "$ADISPATCH_RESULT_FILE"
+```
+
+### Logs und Events (Spec §9.3)
+
+- stdout und stderr werden getrennt und unverändert nach `data-dir/logs/<run-id>/{stdout,stderr}.log` geschrieben
+  (best-effort Redaction bekannter Secrets) und live per SSE an die UI gesendet. Limit `retention.max_log_size_per_run`
+  (stdout+stderr zusammen, Default 100 MB): danach wird abgeschnitten und das als Diagnose-Event markiert.
+- Strukturierte Events: eine Zeile `@@ADISPATCH_EVENT {json}` auf stdout oder stderr, JSON-Objekt mit `type`, max. 64 KiB:
+
+```text
+@@ADISPATCH_EVENT {"type":"status","message":"Tests laufen"}
+@@ADISPATCH_EVENT {"type":"progress","value":60}
+@@ADISPATCH_EVENT {"type":"question","message":"Welcher OAuth-Anbieter?"}
+```
+
+  Events sind **nur informativ** (keine Workflow-Transitionen); `status`-Events mit `message` erscheinen als letzte
+  Statusmeldung auf Run-Karten. Ungültige Zeilen bleiben im Log und erzeugen eine Parser-Warnung.
+- `idle_timeout` misst die Zeit seit der letzten Ausgabe (auch Events). Lange stille Phasen → regelmäßig ein
+  `progress`-/`status`-Event ausgeben.
+
+## Abbruch, Timeout, Prozesse
+
+- Cancel/Timeout: `SIGTERM` an die **ganze Prozessgruppe**, nach `execute.cancel_grace` (Default 30 s) `SIGKILL`; der Run
+  gilt erst als beendet, wenn die Gruppe nachweislich weg ist.
+- Bleiben nach normalem Exit noch Prozesse der Gruppe übrig (`cmd &` ohne `wait`), werden sie beendet.
+- Prozesse **außerhalb** der Gruppe (eigene Session via `setsid`, `nohup … &` mit neuer Session, Docker-Container) erfasst
+  der Orchestrator nicht – das Skript ist für deren Cleanup verantwortlich (`trap '…' TERM EXIT`, `docker run --rm --init`).
+- Nach einem Absturz des Orchestrators beendet die Recovery verwaiste Worker nur bei sicher verifizierter Identität
+  (PID + Startzeit/Boot-ID); sonst `recovery_pending` (sichtbar, kein Doppelstart). Unter systemd beendet systemd die
+  Worker beim Absturz ohnehin mit der cgroup (siehe [operations.md](operations.md#systemd)).
+
+## Sicherheit
+
+Worker und Shell-Actions sind **vertrauenswürdiger Konfigurationscode** mit den OS-Rechten des Dienstes – es gibt keine
+Sandbox. Ein Worker kann ihm übergebene Secrets (z. B. `GH_TOKEN`) ausgeben; die Redaction in Logs ist best-effort
+(transformierte Secrets, z. B. base64, werden nicht erkannt). Nur benötigte Secrets deklarieren, App-Rechte minimal halten.
+Event-/Result-/Log-Inhalte werden in API/UI als untrusted Text behandelt.
+
+## Shell-Lifecycle-Actions und Prüfskripte
+
+| Art | Erfolg | Kontext |
+|---|---|---|
+| `shell`-Action in Hooks | Exit 0 (Ergebnisdatei wird ignoriert); sonst Retry gemäß `lifecycle.action_retry` | `ADISPATCH_CONTEXT_FILE` mit `kind: lifecycle_action`, Run, Hook, Action, `result` (außer `on_start`), Minimal-Env + `env` + `ADISPATCH_*`, **keine Secrets** |
+| `conditions.*`, `shell_filter` | Exit 0 = passt, 1 = passt nicht, ≥ 2/Timeout/Signal = Prüffehler (`unknown`, kein Start) | `ADISPATCH_CHECK_CONTEXT_FILE` (Workflow bzw. Item) |
+
+Die Exit-Code-Semantik 0/1/≥2 gilt **nur** für Prüfskripte, nicht für den Haupt-Worker. Dry-Runs führen Prüfskripte nie aus.

package/examples/config/config.yaml

@@ -0,0 +1,35 @@
+# Global settings (Spec §5.1)
+server:
+  host: 127.0.0.1
+  port: 8787
+  # Extra host names accepted in Host/Origin headers (e.g. the public name of an
+  # authenticating reverse proxy); loopback names are always accepted.
+  allowed_hosts: []
+
+scheduler:
+  polling_interval: 30s
+  max_concurrent: 5
+
+workspace:
+  base_dir: /var/lib/adispatchd/workspaces
+  cleanup: on_success  # always | on_success | never
+
+lifecycle:
+  action_retry:
+    max_attempts: 3
+    delay: 30s
+
+retention:
+  completed_runs: 30d
+  failed_runs: 90d
+  blocked_runs: never
+  max_log_size_per_run: 100MB
+  cleanup_interval: 24h
+
+notifications:
+  # Admin/orchestrator notifications (Spec §18). Channels are optional, e.g.:
+  # channels:
+  #   - type: webhook
+  #     url_env: SLACK_WEBHOOK_URL
+  #     headers_env: { Authorization: WEBHOOK_AUTH_HEADER }
+  on: [retry_block_created, lifecycle_action_failed, recovery_failed]

package/examples/config/identities.yaml

@@ -0,0 +1,18 @@
+# identities.yaml (Spec §5.3) – private keys are read from the named
+# environment variables at runtime, never stored here.
+identities:
+  maintainer:
+    type: github_app
+    app_id: 100001
+    installation_id: 200001
+    private_key_env: GITHUB_MAINTAINER_PRIVATE_KEY
+  coder:
+    type: github_app
+    app_id: 100002
+    installation_id: 200002
+    private_key_env: GITHUB_CODER_PRIVATE_KEY
+  reviewer:
+    type: github_app
+    app_id: 100003
+    installation_id: 200003
+    private_key_env: GITHUB_REVIEWER_PRIVATE_KEY

package/examples/config/sources.yaml

@@ -0,0 +1,13 @@
+# sources.yaml (Spec §5.2)
+sources:
+  project_a:
+    type: github
+    owner: example
+    repository: project-a
+    identity: maintainer
+
+  project_b:
+    type: github
+    owner: example
+    repository: project-b
+    identity: maintainer

package/examples/config/views/needs-maintainer.yaml

@@ -0,0 +1,15 @@
+# views/needs-maintainer.yaml (Spec §17)
+id: needs-maintainer
+title: Needs Maintainer
+sources: [project_a, project_b]
+filter:
+  all:
+    - { field: labels, operator: contains, value: needs-maintainer }
+fields:
+  - { field: repository, label: Repository }
+  - { field: number, label: Issue }
+  - { field: title, label: Titel, link: url }
+  - { field: run.last_workflow, label: Letzter Agent }
+  - { field: run.last_result.message, label: Ergebnis }
+  - { field: updated_at, label: Aktualisiert }
+sort: { field: updated_at, direction: desc }