session-orchestrator 5.11.0 → 5.13.0

package/skills/_shared/fleet-protocol.md

@@ -75,7 +75,14 @@ die vom Lease-Validator akzeptierte `adresse` einer aktiven Lease, sonst `null`
 Lease, kein Eintrag oder ein abgelehnter Wert — nie ein ungeprüfter String). `fallback_due_at` ist
 der Zeitpunkt, ab dem die Standard-Auflagen (unten) gelten, in der Form von `zeit` (Code:
 `fallbackDueAt()`); er steht nur auf stdout, die Check-in-Datei behält ihr Schema. Exit 0
-geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei), 1 Schreibfehler.
+geschrieben, 2 ungültige Eingabe (Fehlerliste auf stderr, keine Datei) oder semantische Session-ID
+von einem anderen Repo belegt (eine Zeile auf stderr mit JSON-escaped Repo-Namen, fremde Datei unverändert,
+tmp entfernt, kein Event), 1 Schreibfehler.
+Vor dem `rename` lehnt der Schreiber ein vorhandenes String-`repo` ungleich dem eigenen ab;
+gleiches `repo`, unlesbare Dateien und ungültiges JSON dürfen überschrieben werden.
+Die Prüfung folgt keinen Symlinks, öffnet nichtblockierend und liest nur reguläre Dateien
+bis 64 KiB. Symlinks, andere Dateitypen, größere Dateien oder fehlende sichere Open-Flags
+gelten für diese Prüfung als unlesbar (fail-open zum `rename`).
 
 | Feld | Inhalt |
 |---|---|
@@ -99,6 +106,146 @@ nur wenn die Lease aktiv ist und `navigator_adresse` (stdout der Check-in-CLI) n
 `ListAgents` erreichbar ist, und nur an genau diesen Namen; nie eine Antwort
 erwarten, nie darauf warten (CSM-004).
 
+## Rücklauf an den Navigator (Pflicht)
+
+In jedem Warte-Zug, den eine Eingabe ausgelöst hat (Anstoß der Owner-Inbox, Nachricht vom Lead,
+Nachricht vom Owner, auch ein Befehl wie `/go` oder `/close`) — keine Arbeit gefunden, Blocker länger
+als 15 min, `/go` oder `/close` ohne Plan, fertig, nur noch Zug/Pipeline offen — genau eine Meldung
+an den Koordinator, im Zug der Warte-Antwort selbst: Session (`<name>`, unten), Wartefall
+(`keine-arbeit`, `blocker-<issue>`, `go-ohne-plan`, `close-ohne-plan`, `fertig`, `zug-<name>`), seit
+wann (Uhr aus `date`, die lokale Systemzeit des Hosts), was gebraucht wird. Auch wenn derselbe Fall
+in einem früheren Zug schon gemeldet wurde (Resume, Verdichtung, erneuter Anstoß): Die Owner-Inbox
+lässt eine Session nur ruhen, wenn sie im Zug ihrer letzten Antwort gemeldet hat (SendMessage oder
+`owner-queue add`) UND diese Antwort als Warte-Antwort erkennt; eine unterdrückte Wiederholung hält
+sie wach und führt zu stündlichen Anstößen (#1611). Ausgenommen sind Züge, die keine Eingabe
+ausgelöst hat: Weckungen durch `/loop`, ein Monitor-Ereignis, ein eigener Hintergrund-Agent oder eine
+eigene Hintergrund-Shell, ScheduleWakeup. Sie melden nicht erneut: solange ein Monitor oder
+Hintergrund-Lauf offen ist, stößt die Inbox ohnehin nicht an; nach einer Weckung durch `/loop` oder
+ScheduleWakeup holt der nächste Anstoß die Meldung nach. Flotte und Lease lesend messen, ohne Check-in zu schreiben
+(derselbe Helfer `readNavigatorLease()`, aus dem die Check-in-CLI `navigator_adresse` gewinnt):
+
+```bash
+node --input-type=module -e "const { pathToFileURL } = await import('node:url'); const m = await import(pathToFileURL(process.argv[1]).href); const r = await m.readNavigatorLease(); console.log(JSON.stringify({flotte: m.fleetIntegrationEnabled(), state: r.state, adresse: r.lease?.adresse ?? null}))" "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/lib/fleet-protocol.mjs"
+```
+
+`flotte: false` (§ Verhalten ohne Flotte): keine Meldung, keine Datei; hier endet der Abschnitt.
+Sonst die Meldung über eine Rückfallkette; die nächste Stufe greift, sobald die vorige nicht greift
+oder scheitert:
+
+1. `state: active`, `adresse` nicht `null` und per `ListAgents` erreichbar: eine `SendMessage` an
+   genau diese Adresse. Werkzeugfehler oder unbekannte Adresse: weiter mit Stufe 2.
+2. Sonst (Lease `none` oder `unreadable`, keine oder keine erreichbare Adresse, Stufe 1
+   gescheitert): ein Lead-Todo in der owner-queue des Koordinators, `<repo>` wie das Check-in-Feld
+   `repo`, Titel mit `<name>` (unten) und dem, worauf die Session wartet. Exit 4 heißt „ähnlicher
+   offener Eintrag liegt schon in der Queue“. Der Befehl selbst muss Exit 0 und 4 auf Exit 0
+   normalisieren: Claude Code markiert jeden Exit ungleich 0 als Werkzeugfehler (`is_error`), und
+   einen gescheiterten Aufruf zählt die Owner-Inbox nicht als Meldung. Pflichtform:
+
+   ```bash
+   navigator owner-queue add --repo <repo> --kind lead-todo --waits-on lead --title '<name>: <worauf die Session wartet>'; rc=$?; [ "$rc" -eq 0 ] || [ "$rc" -eq 4 ] || { echo "Meldung gescheitert: owner-queue add exit $rc" >&2; exit "$rc"; }
+   ```
+
+   `navigator` ist die CLI des Koordinators (lead-session-orchestrator: Binary `navigator`); nennt
+   die Steuerungsregel des Koordinators im Systemprompt der Session einen Aufrufpfad, gilt dieser.
+   Einen eigenen Pfad zum Koordinator-Repo nicht raten.
+3. Scheitert auch Stufe 2 (Exit weder 0 noch 4, z. B. 127, weil `navigator` nicht im `PATH` liegt):
+   der letzte Absatz der Antwort nennt sichtbar `Meldung gescheitert: <Grund>` (Stufe, Exit-Code
+   oder Fehlertext), vor dem Wartesatz. Still warten ist nie zulässig.
+
+**Wartesatz.** Jede Warte-Antwort endet mit einem Satz, den der Koordinator als Warte-Antwort
+erkennt (letzte 600 Zeichen ohne Code-Blöcke, kein `?` am Ende des letzten Absatzes, Muster wie
+unter Übergabe Punkt 3): `Bereit zum Schließen.`, wenn die Übergabe unten gilt, sonst
+`Ich warte auf den nächsten Auftrag.` Eine Meldung oder Statuszeile allein (etwa
+`/go: kein Plan vorhanden – nichts ausgeführt`) erkennt er nicht.
+
+**Flotten-Ordner und Session-Name.** Beide stehen im eigenen Eintrag der Claude-Session-Registry
+`~/.claude/sessions/<pid>.json`, dem mit `sessionId` gleich `$CLAUDE_CODE_SESSION_ID`:
+
+```bash
+jq -c --arg id "$CLAUDE_CODE_SESSION_ID" 'select(.sessionId == $id) | {name, cwd, startedAt}' ~/.claude/sessions/*.json
+```
+
+`<name>` ist das Feld `name` (der Peer-Name, z. B. `session-orchestrator-cf`; fehlt es, die ersten
+acht Zeichen von `sessionId`), nicht `session_id` und nicht `semantic_session_id`. Der Flotten-Ordner
+ist `<cwd>/.orchestrator/runtime/fleet/` mit dem `cwd`, der im Moment des Schreibens in diesem
+Eintrag steht: den Befehl unmittelbar davor ausführen, nie einen früher gemessenen Wert nehmen. Nach
+`EnterWorktree` zeigt `cwd` auf den Worktree, und dort sucht der Koordinator. `/close` kann einen
+auto-promoteten Worktree samt der Datei darin entfernen (session-end Phase 4a); die Datei entsteht
+deshalb erst mit der Meldung, und der Koordinator liest sie vor dem Abschluss.
+
+**Übergabe und Zug-Manifest.** Nur mit Flottenintegration (`flotte: true` in derselben Messung),
+auch ohne aktive Lease: der Koordinator schließt eine von ihm geführte Session, sobald ihre Übergabe
+vorliegt, ohne die Lease zu prüfen. Und nur in der Warte- oder Fertig-Antwort außerhalb von
+session-end (Phase start oder go: das Abschluss-Ergebnis des wave-executor, das Ende des Express Path,
+`/go` ohne Plan, keine Arbeit). Ist die Session fertig oder wartet sie nur noch auf einen Release-Zug oder eine Pipeline
+und hat keine andere Arbeit:
+
+1. Im selben Zug wie diese Antwort schreibt sie selbst mit dem Datei-Werkzeug des Harness (Claude
+   Code: Write), nicht per Shell, in den Flotten-Ordner: fertig die Übergabe
+   `uebergabe-<name>-an-<Nachfolger>.md` (ohne Nachfolger `uebergabe-<name>.md`), bei Zug oder
+   Pipeline das Zug-Manifest `<name>-zug-<zugname>.md` — enthaltene MRs, Köpfe, Migrationen,
+   manuelle Jobs, Nachkontrolle, Rückweg, offene Themen. Der Koordinator erkennt nur genau diese
+   Namen (`uebergabe-<name>.md`, `uebergabe-<name>-….md`, `<name>-zug-….md`) und nur eine Datei, die
+   die Session im Zug ihrer letzten Antwort nachweislich selbst geschrieben hat. Vorher
+   `git -C <cwd> check-ignore --no-index -q .orchestrator/runtime/fleet/<datei>` prüfen: Exit 1
+   (nicht ignoriert) hält das Schreiben nicht auf — der Koordinator braucht die Datei genau
+   dort —, aber Meldung und Antwort nennen „ungetrackte Datei in <repo>:
+   .orchestrator/runtime/fleet/<datei>“. Kein Ausweichen in einen anderen Ordner.
+1a. **Jeder offene Punkt trägt eine Vorgangsmarke (#1639).** Jeder Listenpunkt unter einer
+   Überschrift, die mit „Offen“, „Nachkontrolle“, „Folge“ oder „Danach“ beginnt (ohne „erledigt“ im
+   Titel), endet mit `queue:#<id>`. Hat der Punkt schon ein GitLab-Issue und braucht keinen
+   Zeitpunkt, endet er stattdessen mit `issue:#<iid>`. Erledigte Punkte stehen als `[x]` da. Fehlt die
+   Marke, legt die Session den Vorgang vor dem Schreiben an
+   (`navigator owner-queue add --repo <repo> … --title '<name>: <punkt>'`, `<repo>` wie oben):
+   Prüfung nach Merge oder Zug `--kind nachsorge --waits-on lead --ref <repo>!<iid>`; Folgearbeit,
+   Termin oder Nachfolge-Session `--kind lead-todo --waits-on lead` (mit `--not-before`/`--due`
+   bei Termin oder Frist); Versprechen an einen Peer `--kind zusage --waits-on peer:<session>`;
+   Owner-Frage wie bisher als Entscheid mit `--options`, `--recommendation`, `--class`. Exit 0 und 4
+   gelten als Erfolg; bei 4 die ID des vorhandenen Vorgangs übernehmen (`--json` liefert sie als
+   `ids`). Danach prüft sie die geschriebene Datei mechanisch:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/handover-queue-check.mjs" --file <cwd>/.orchestrator/runtime/fleet/<datei> --name <name> --since <startedAt> --apply --repo <repo> --navigator-cli <koordinator-cli>
+   ```
+
+   `<koordinator-cli>` ist der Aufrufpfad der Koordinator-CLI aus der Steuerungsregel (eine `.js`-Datei
+   läuft unter node), sonst entfällt die Option und `navigator` aus dem `PATH` gilt. `--apply` legt
+   für jeden Punkt ohne Marke den Vorgang an (Nachkontrolle als `nachsorge`, sonst `lead-todo`, Ref
+   aus dem ersten `!N`/`#N` im Punkt, nur wenn die CLI ihn annimmt) und schreibt `queue:#<id>` in die
+   Datei. Punkte unter einer Überschrift mit „Owner“ oder „Entscheid“ legt es nie an, es meldet sie:
+   Owner-Fragen brauchen einen Entscheid mit Optionen und Klasse. `--apply` verlangt `--name`
+   (sonst Exit 2) und schreibt nur in die eigene Datei (`uebergabe-<name>.md`,
+   `uebergabe-<name>-*.md`, `<name>-zug-*.md`); eine fremde Datei, einen Symlink oder eine Datei
+   älter als `--since` (Vorgänger gleichen Namens) lehnt es unverändert ab (Exit 4), nie in einer
+   Schleife über den Flotten-Ordner aufrufen. Hat es Vorgänge
+   angelegt, die Datei danach lesen und mit dem Datei-Werkzeug unverändert neu schreiben: der
+   Koordinator erkennt nur eine selbst geschriebene Datei. Exit 3 heißt, Punkte bleiben ohne Marke
+   (die Liste steht in der Ausgabe): dann nennen Meldung und Antwort „Übergabe ohne Queue-IDs: <n>
+   Punkte“, und die Antwort endet mit `Ich warte auf den nächsten Auftrag.`, nicht mit dem Satz aus
+   Schritt 3. Ohne Flottenintegration prüft das Skript nichts (Exit 0).
+2. Mit jeder weiteren Warte-Antwort schreibt sie die Datei neu, auch wenn sie aus einem früheren Zug
+   schon dasteht, so wie sie in jedem Warte-Zug neu meldet.
+3. Sie meldet „bereit zum Schließen“ (in der Meldung dieses Zugs) und beendet
+   die Antwort mit genau diesem Satz: `Bereit zum Schließen.` Der Koordinator erkennt eine Warte-
+   oder Fertig-Antwort nur in ihren letzten 600 Zeichen (Code-Blöcke zählen nicht mit); ein langer
+   Bericht mit dem Satz weiter oben schließt nicht. Der letzte Absatz endet nicht auf `?`, und die
+   letzten 400 Zeichen enthalten weder `soll ich` noch `weiter mit`, `welche option` oder
+   `freigabe für`: sonst gilt die Antwort als Frage an den Owner, und es schließt ebenfalls nicht.
+   Auch eine Verneinung („noch nicht bereit zum Schließen“) zählt dort als Fertig-Antwort: nie ans
+   Ende stellen. Sie beginnt nichts Neues und beendet Monitore, Hintergrund-Shells und
+   Hintergrund-Agenten (Claude Code: TaskStop); solange einer läuft, gilt sie als nicht fertig.
+4. Sie schließt nicht selbst: `/close` ist nicht modell-aufrufbar (`disable-model-invocation`), und
+   den Abschluss löst der Koordinator aus. session-end (Phase 4.5) meldet im Zug von `/close` genau
+   einmal den Fall `zug-<name>` (eigener Warte-Zug, gewollt) und schreibt keine Datei.
+   Das gilt auch für den Express Path (session-start Phase 8.5, `skills/go/SKILL.md`): mit
+   Flottenintegration ruft `/go` session-end nicht selbst auf, sondern endet nach Deviation-Eintrag
+   mit Meldung, Übergabe und Wartesatz wie oben (#1620). Ohne Flottenintegration bleibt der
+   Express Path beim eigenen Abschluss.
+
+Ohne Flottenintegration keine Meldung, keine Übergabe-Datei und kein Manifest. Nie auf Antwort
+warten, nie eine Entscheidung an einer Antwort festmachen (CSM-004); eine Meldung ist keine Freigabe
+(ADR-002). Schließen nur über session-end, nie durch handgeschriebene Metriken.
+
 ## `auflagen/<session_id>.json` — Navigator an Session
 
 Bedingungen, die der Navigator einer Session schreibt (z. B. Agent-Caps, volle Pipelines je Repo,
@@ -130,15 +277,31 @@ aktiven Navigator ist `fallback_due_at` gleich `zeit`, die Auflagen gelten also
 Lesende Arbeit und Schreiben im eigenen Worktree laufen währenddessen weiter; der Rückfall ist ein
 Dateistand mit Frist, kein Warten auf eine Antwort.
 
+## Verhalten ohne Flotte
+
+Flottenintegration liegt vor, wenn `NAVIGATOR_CONFIG_DIR` gesetzt und nicht leer ist (ausdrückliches
+Opt-in, auch vor dem ersten Anlegen) oder `~/.config/navigator/` als Verzeichnis existiert (Code:
+`fleetIntegrationEnabled()`, #1559). Ein Flottenhost hat das Verzeichnis, weil der Koordinator dort
+die Lease schreibt. Ohne Flottenintegration validiert `fleet-checkin.mjs` die Eingabe wie immer
+(ungültig → Exit 2), schreibt dann aber nichts, legt kein Verzeichnis an, emittiert kein Event und
+meldet `{"ok":true,"skipped":"no-fleet",…}`. Es gelten keine Auflagen, auch keine Standard-Auflagen:
+ohne Flotte gibt es nichts zu koordinieren. Die Navigator-Zeile im Sessionstart-Banner entfällt
+ebenso. Das gilt auch für `plattform: kopflos`: der Datensatz beweist keinen Koordinator, und ein
+Schreiben legte das Verzeichnis an, das danach jede Solo-Session zur Flotte macht. Ein kopfloser
+Lauf ohne Flottenintegration wendet stattdessen die Standard-Auflagen sofort an — er kann niemanden
+fragen. Ein Flotten-Starter, der auf einem frischen Remote-Host startet, setzt deshalb
+`NAVIGATOR_CONFIG_DIR` oder legt das Verzeichnis vorher an.
+
 ## Verhalten ohne Navigator
 
-Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
+Flottenintegration vorhanden, Lease `none` oder `unreadable`: die Check-in-Datei wird **trotzdem** geschrieben (sie ist der
 zählbare Beleg), die Standard-Auflagen gelten sofort, es geht keine Nachricht ab. Kopflose Läufe
 sind per Nachricht nicht erreichbar und nutzen dieselben Dateien: vor jeder Welle `auflagen/` lesen.
 
 ## See Also
 
 `skills/session-start/SKILL.md` Phase 7.6 · `skills/session-start/references/operations-contract.md`
-(Peer-Preflight) · `skills/_shared/state-ownership.md` § Session Identity and Lock Ownership (`role`) ·
+(Peer-Preflight) · Rücklauf-Verweise: `skills/go/SKILL.md` § No plan to execute, `skills/close/SKILL.md`, `skills/wave-executor/SKILL.md` § Completion,
+`skills/session-end/SKILL.md` Phase 4.5 · `skills/_shared/state-ownership.md` § Session Identity and Lock Ownership (`role`) ·
 `docs/events-schema.md` (`orchestrator.fleet.checkin`) · `.claude/rules/cross-session-messaging.md`
 (CSM-003/004) · `scripts/lib/fleet-protocol.mjs` · `scripts/fleet-checkin.mjs`

package/skills/_shared/instruction-file-resolution.md

@@ -33,7 +33,7 @@ Apply these steps in order against the repo root. Stop at the first hit. Never m
 Since the cross-harness portable surface landed, this repo carries BOTH files at its root. That does not weaken the rule above — it is what makes the rule safe to hold while still serving foreign readers:
 
 - **Our own readers still never read both.** `resolveInstructionFile()` picks exactly one (`CLAUDE.md` wins ties), and every consumer listed below goes through it. Nothing merges, diffs, or cross-validates the two as sources.
-- **The root `AGENTS.md` exists for FOREIGN readers**, not for ours. 7 of 8 surveyed harnesses (Codex CLI, Cursor, Copilot CLI, OpenCode, Amp, Kiro, …) read `AGENTS.md`; only Claude Code reads `CLAUDE.md`, and only Copilot CLI reads both. Without a root `AGENTS.md` this repo's `## Session Config` was unreachable from six of them.
+- **The root `AGENTS.md` exists for FOREIGN readers**, not for ours. 7 of 8 surveyed harnesses (Codex CLI, Cursor, Copilot CLI, OpenCode, Amp, Kiro, …) read `AGENTS.md`. Claude Code reads `CLAUDE.md`; Copilot CLI and Cursor read both (Cursor per its rules help, checked 2026-10-21; the 2026-09-06 survey had it as `AGENTS.md` only). Without a root `AGENTS.md` this repo's `## Session Config` was unreachable from six of them.
 - **It is byte-identical by construction, and generated.** `scripts/generate-agents-skills.mjs` copies `CLAUDE.md` verbatim; `--check` (wired into `scripts/validate-plugin.mjs`) fails CI on any divergence. **Never edit `AGENTS.md`** — edit `CLAUDE.md` and regenerate. A consumer repo may instead symlink it; both shapes are accepted by the drift gate.
 - **Why a copy and not a symlink here:** `package.json` `files[]` does not publish `CLAUDE.md`, so a symlink would be DANGLING in the npm tarball; and `core.symlinks` defaults to false on Windows without Developer Mode, where git materialises the link as a 10-byte regular file containing the literal text `CLAUDE.md` — a pointer with no Session Config, which is precisely the failure this file guards against.
 - **The invariant is "the two cannot disagree", not "exactly one file exists."** `claude-md-drift-check` Check 7 (`vault-dir-parity`) enforces it: alias-by-construction → parity satisfied; two independent files that diverge → error. Check 9's probe 2a uses the same predicate so a defect in `CLAUDE.md` is never reported twice.

package/skills/_shared/monitor-patterns.md

@@ -2,7 +2,7 @@
 
 > Vetted Monitor-tool snippets for the recurring observation points in the
 > session-orchestrator workflow. Each snippet ships with the description
-> string, recommended timeout / persistent flag, and an explicit failure
+> string, recommended timeout, and an explicit failure
 > coverage note (per the **silence-is-not-success** rule from
 > `.claude/rules/loop-and-monitor.md`).
 
@@ -10,8 +10,9 @@
 
 Anthropic recommends `Monitor` over `/loop` for any stream-able event
 (https://code.claude.com/docs/en/scheduled-tasks). The Monitor tool turns
-each stdout line into a notification, avoiding poll-token cost. But a
-naïve filter that matches only the success marker reads identical to a
+each output or exit event into one notification, avoiding poll-token cost.
+Output may contain multiple stdout lines; it is not a notification per line.
+A naïve filter that matches only the success marker reads identical to a
 crash — silent. The snippets below are calibrated to emit on **every
 terminal state**, not just the happy path.
 
@@ -21,6 +22,27 @@ coverage check.
 
 ---
 
+## Deadline and re-arm (Claude Code v2.1.271+)
+
+Every Monitor watch has a deadline: 5 minutes by default, at most 30 minutes
+(10 in single-prompt `-p` runs). The former no-timeout option was removed. At
+the deadline the watch ends and Claude gets one exit notice, so the coordinator
+re-arms the same snippet if the watch is still needed. Output and exit each
+produce one notification; an exit notice is not proof that the watched job
+succeeded. Inspect the terminal state and actual exit code. Filters keep the
+coverage rule: match every terminal state, so silence at expiry is the
+deadline notice, never a success signal. Source: CHANGELOG 2.1.271 and
+https://code.claude.com/docs/en/tools-reference (retrieved 2026-10-12).
+
+The snippets below use interactive timeout recommendations. For a `-p` run,
+set `timeout_ms` to at most `600000` (10 minutes), as stated at each snippet.
+Background detachment and Monitor watches do not keep a single-prompt run alive
+after its turn ends. In unattended `-p` workflows, wait in the foreground with
+a bounded command, read its actual exit, and repeat the wait if needed; do not
+finish the turn while a watched job is still running.
+
+---
+
 ## Pattern 1 — GitLab pipeline + GitHub mirror sync (post-push)
 
 **When.** After `git push origin main` from `skills/close/SKILL.md` Phase 6.
@@ -29,9 +51,7 @@ the GitHub mirror's main-branch SHA so the operator can confirm parity.
 
 **Description.** `pipeline + mirror sync after push`
 
-**timeout_ms.** `1800000` (30 min — most pipelines finish well inside)
-
-**persistent.** `false`
+**timeout_ms.** Interactive: `1800000` (30 min). Single-prompt `-p`: `600000` (10 min). Re-arm on expiry while the pipeline is still running.
 
 ```bash
 prev=""
@@ -116,9 +136,7 @@ and any failure signature without re-running the suite.
 
 **Description.** `vitest progress + failure signatures`
 
-**timeout_ms.** `1200000` (20 min)
-
-**persistent.** `false`
+**timeout_ms.** Interactive: `1200000` (20 min). Single-prompt `-p`: `600000` (10 min). Re-arm on expiry while the suite is still running.
 
 ```bash
 # Pre-req: npm test 2>&1 | tee vitest.log was started in another terminal
@@ -142,10 +160,9 @@ a live dashboard in terminal B without building telemetry tooling.
 
 **Description.** `autopilot iteration + kill-switch tail`
 
-**timeout_ms.** `3600000` (1 h — the 1 h ceiling this file uses; repo-internal convention, upstream documents no explicit `timeout_ms` maximum)
+**timeout_ms.** Interactive: `1800000` (30 min, the upstream maximum since v2.1.271). Single-prompt `-p`: `600000` (10 min).
 
-**persistent.** `true` (run for the lifetime of the session — autopilot
-runs can take hours)
+**Re-arm.** The watch ends at its deadline; autopilot runs can take hours, so re-arm on the expiry notice (see "Deadline and re-arm").
 
 ```bash
 tail -f .orchestrator/metrics/autopilot.jsonl | jq -r --line-buffered '
@@ -160,7 +177,8 @@ kill-switch firings (the ten tracked in
 silent autopilot run means autopilot is not actually writing to the
 JSONL — that itself is a signal worth surfacing manually.
 
-**Detachment seam (Spike #640).** A headless autopilot run detached via
+**Interactive detachment seam (Spike #640).** In an interactive session,
+a headless autopilot run detached via
 Bash `run_in_background` (`node scripts/autopilot.mjs --headless … &`)
 is observed through the returned **task-id**, its **output-file**
 (`.../tasks/<id>.output`), and the **completion notification** — never
@@ -180,9 +198,9 @@ fires only at session-end / evolve. Surfaces drift before it accumulates.
 
 **Description.** `vault 40-learnings/50-sessions backlog`
 
-**timeout_ms.** `3600000` (1 h)
+**timeout_ms.** Interactive: `1800000` (30 min, the upstream maximum since v2.1.271). Single-prompt `-p`: `600000` (10 min).
 
-**persistent.** `true`
+**Re-arm.** Re-arm on the expiry notice while the backlog is still of interest (see "Deadline and re-arm").
 
 ```bash
 prev=0
@@ -198,7 +216,9 @@ done
 
 **Coverage.** Emits **only on change** to keep the stream quiet during
 idle work. A drop to zero is also reported (e.g. when session-end runs
-mirror-commit). Silence = no drift, which is the desired idle state. The
+mirror-commit). Silence = no drift, which is the desired idle state. For
+single-prompt `-p` runs, replace `sleep 1800` with `sleep 300` so the
+watch can observe another sample before its 10-minute deadline. Interactive
 30-min sleep matches the `1200s+` idle-tick band from
 `.claude/rules/loop-and-monitor.md` LM-003 (idle observation-rate; under the
 1-hour subscription cache TTL there is no cache penalty here anyway).
@@ -214,9 +234,7 @@ parity bit the operator a day later.
 
 **Description.** `github mirror parity vs local main`
 
-**timeout_ms.** `300000` (5 min — push usually completes in seconds; this is the wall-clock ceiling **for this watch**, **not** the `/loop` cadence band that LM-003 in `.claude/rules/loop-and-monitor.md` warns against)
-
-**persistent.** `false`
+**timeout_ms.** `300000` (5 min, valid for both interactive and single-prompt `-p` runs — push usually completes in seconds; this is the wall-clock ceiling **for this watch**, **not** the `/loop` cadence band that LM-003 in `.claude/rules/loop-and-monitor.md` warns against)
 
 ```bash
 local_sha=$(git rev-parse main)
@@ -301,7 +319,7 @@ discipline:
 
 ---
 
-## Pattern — `/tmux-layout` (operator-side persistent visualization)
+## Pattern — `/tmux-layout` (operator-side standing visualization)
 
 > Per ADR-0007 + GitLab #561 #562 #563. Opt-in skill, NOT Monitor/loop replacement.
 
@@ -309,9 +327,9 @@ discipline:
 
 | Primitive | Purpose | When to use |
 |---|---|---|
-| **`Monitor` tool** | Event-driven stream → coordinator reaction | The coordinator must REACT to each terminal-state line (CI fails → take action, build error → patch). Each stdout line = one coordinator notification. |
+| **`Monitor` tool** | Event-driven stream → coordinator reaction | The coordinator must REACT to each terminal-state line (CI fails → take action, build error → patch). Each output or exit event produces one coordinator notification; output may contain multiple lines. |
 | **`/loop` skill** | Periodic coordinator-side polling | "Check vault-staleness every 30 minutes while session runs." Lives inside the coordinator's turn budget. |
-| **`/tmux-layout` skill** | Operator-side persistent visualization (4-pane) | The OPERATOR (human) wants to peripherally observe side-channels — STATE.md tail, CI watch, events.jsonl — in a SECOND terminal without coordinator reaction. Pure observability. |
+| **`/tmux-layout` skill** | Operator-side standing visualization (4-pane) | The OPERATOR (human) wants to peripherally observe side-channels — STATE.md tail, CI watch, events.jsonl — in a SECOND terminal without coordinator reaction. Pure observability. |
 
 **Key distinction:** `/tmux-layout` visualizes the *outputs* of `Monitor` and `/loop` peripherally so the coordinator pane stays focused on decisions (AUQ-001). It does NOT replace either — Pane 3 of the default layout, for example, runs a `glab ci status` poll-loop equivalent to a `/loop` cadence, but the coordinator does not see those refreshes (the operator does).
 
@@ -326,9 +344,10 @@ discipline:
   spams notifications and gets auto-stopped by Monitor's volume guard.
 - **Forgetting `--line-buffered`** in `grep` pipes — pipe buffering
   delays events by minutes, which usually masks itself as "no events".
-- **Unbounded `tail -f` for one-shot signals** — use Bash with
-  `run_in_background` and an `until` loop instead. See the Monitor tool
-  docs.
+- **Unbounded `tail -f` for one-shot signals** — use a bounded foreground
+  wait in single-prompt `-p` runs and inspect the actual exit code. Interactive
+  sessions may use a Bash background task with a completion notification;
+  do not carry that detachment pattern into unattended `-p` runs.
 - **Using Monitor as a `/loop` replacement for periodic scans without a
   stream** (e.g. polling `glab issue list`). Use `/loop` dynamic mode.
 

package/skills/_shared/platform-tools.md

@@ -15,6 +15,13 @@ harness expose those exact tools. Use the current runtime's available tools.
 Measured in Codex Desktop 0.153.4 on 2026-09-19: `exec_command` runs shell
 commands (`cat`, `rg`, `rg --files` for Read/Grep/Glob); `apply_patch` performs
 file edits. These may be exposed through a `functions.exec` tools namespace.
+Hook boundary, measured 2026-10-20 on `codex-cli 0.160.1` (`codex exec`, #1669):
+a PreToolUse hook sees a shell call as `tool_name: "Bash"` with
+`tool_input.command` as a string, and `matcher: "Bash"` fires. Codex honours a
+PreToolUse `deny` (measured 2026-10-20 on `codex-cli 0.160.1`, #1691): the
+blocked command does not run. The Bash guards are wired on Codex except
+`pre-bash-templates-first` (it needs `transcript_path`, which Codex sends as
+`null`); see `docs/codex-setup.md`.
 Never call an unavailable `Read`, `Bash`, or `Skill` tool by name. An instruction
 to invoke `session-orchestrator:<name>` means read and follow the canonical
 `skills/<name>/SKILL.md` relative to the plugin root when no Skill tool exists.

package/skills/_shared/state-ownership.md

@@ -26,7 +26,7 @@ session-start-ref: <sha>     # git ref at session start
 ### Required vs. optional fields
 
 - `schema-version`, `session-type`, `branch`, `issues`, `started_at`, `status`, `current-wave`, `total-waves` — **required** in every session-owned STATE.md.
-- `session-id` — **optional**, additive under `schema-version: 1` (#1368). The RAW/native harness session id, taken from `.orchestrator/session.lock` via `resolveSessionIds()` (`scripts/lib/state-md.mjs`). Writers OMIT the key when the lock yields none; readers MUST tolerate its absence. It exists so `/close`'s #429 pre-check can join STATE.md to sessions.jsonl on a NATIVE identity (`findRecordedSession`'s UUID fast path) instead of falling through to the semantic label. Like `session`, it grants no lock or registry ownership.
+- `session-id` — **optional**, additive under `schema-version: 1` (#1368). The RAW/native harness session id, taken from `.orchestrator/session.lock` via `resolveSessionIds()` (`scripts/lib/state-md.mjs`), and only when the lock id is this process's own (`readProcessLocalSessionIds()`, #1663) — a lock naming a peer yields `null`. Writers OMIT the key when the lock yields none; readers MUST tolerate its absence. It exists so `/close`'s #429 pre-check can join STATE.md to sessions.jsonl on a NATIVE identity (`findRecordedSession`'s UUID fast path) instead of falling through to the semantic label. Like `session`, it grants no lock or registry ownership.
 - `started_at` is SOURCED from the same lock (`resolveSessionStartedAt()`), never from the writer's clock — see `skills/wave-executor/references/wave-executor-state-init.md` § Pre-Wave 1b for the template and the 48-minute drift that motivated it (#1368). On the READ side `started_at` is a CORROBORATING signal, never an identity key: `findRecordedSession()` (`scripts/lib/session-close-backfill.mjs`) joins STATE.md to `sessions.jsonl` on the native `session-id` FIRST and never consults `started_at` on that path — only the legacy-LABEL path compares the two timestamps, and it tolerates up to `STARTED_AT_DRIFT_TOLERANCE_MS` = **6 h** of drift (`session-close-backfill.mjs:559`, the single definition) before vetoing a label match: wider than any plausible write-lag (the 48 minutes above), narrower than the day the label's own date component already distinguishes.
 - `updated`, `session`, `session-start-ref` — **optional**. Added by #184. STATE.md files without these fields remain valid and should be treated as `updated: null` / `session: null`. Writers SHOULD populate these fields but readers MUST tolerate their absence. `session` is an attribution/history label, normally `<branch>-<YYYY-MM-DD>-<mode>-<n>` since #573 (Epic #568 Parallel-Aware Sessions P2.2); pre-#573 files may contain a UUID-v4 — both formats are read via `parseSessionId()` from `scripts/lib/session-id.mjs` per PRD §3 P2 row 3 (backward-compat). Neither form grants lock or registry ownership.
 
@@ -40,7 +40,7 @@ The `session-type: none` + `status: idle` combination is used only for bootstrap
 | `## Wave History` | Completed wave records | wave-executor (post-wave) |
 | `## Deviations` | Plan adaptation log | wave-executor (step 3) |
 | `## What Not To Retry` | Failed/abandoned approaches not to repeat (#623) | session-end (Phase 1.6) |
-| `## Open Questions` | Unresolved user-facing questions (agent → gate → next session) | wave-executor (inter-wave) + session-end (marks answered) |
+| `## Open Questions` | Unresolved user-facing questions (agent → gate → next session) | wave-executor (inter-wave) + session-end (marks answered; appends one vault-orphan entry at Phase 3.7e, #1563) |
 
 Wave History lines MAY include a `→ issue #NNN` suffix (or `→ existing #NNN` when a duplicate was detected) for SPIRAL/FAILED agents, linking to the auto-created carryover issue (#261). This is optional and backward-compatible; readers that do not recognize the notation can skip it. Session-end Phase 1.6 uses the presence of this suffix to decide whether to retro-file a carryover as a fallback safety net.
 
@@ -139,8 +139,8 @@ growing across sessions is the CCU-009 anti-pattern.
 | Skill | Access | Operations |
 |-------|--------|------------|
 | **wave-executor** | Read + Write (owner) | Creates STATE.md (Pre-Wave 1b), updates after each wave (current-wave, Wave History, Deviations); appends deduped `## Open Questions` at inter-wave checkpoints via `appendOpenQuestionOnDisk` (see `wave-loop.md` § 3e + Post-Wave step 6). |
-| **session-end** | Read + Status-only write | Reads for metrics extraction (Phase 1.7), sets `status: completed` (Phase 3.4). Exception: only fields modified are `status` in frontmatter and marking entries answered in `## Open Questions` via `markOpenQuestionAnsweredOnDisk` (Close Handover-Alignment-Gate). |
-| **session-start** | Read + conditional reset | Reads for continuity checks (Phase 1.5): inspects `status` field to detect crashed/paused sessions. Surfaces `## What Not To Retry` as a forced-read HISTORICAL block (Phase 6.5.1). May reset STATE.md to idle at the boundary between a completed session and a new session — only when prior `status: completed`. The reset clears `current-wave` (→ 0), sets `status: idle`, demotes `## Wave History` into `## Previous Session`, and empties `## Deviations` — but PRESERVES `## What Not To Retry` (cross-session continuity, #623) and `## Open Questions` (Close Handover-Alignment-Gate, PRD 2026-07-07). Never resets on `active` or `paused` (those paths are user-interactive). |
+| **session-end** | Read + Status-only write | Reads for metrics extraction (Phase 1.7), sets `status: completed` (Phase 3.4, `markStateMdCompletedOnDisk`: same locked write also sets `updated` and `current-wave` and re-stamps `session-id` to the closing process's own raw id, #1640) and the five recommendation keys (Phase 3.7a, same explicit `statePath`). Exception: only fields modified are these frontmatter keys and marking entries answered in `## Open Questions` via `markOpenQuestionAnsweredOnDisk` (Close Handover-Alignment-Gate), plus at most one appended `## Open Questions` entry naming vault-orphan candidates via `appendOpenQuestionOnDisk` (Phase 3.7e, #1563). |
+| **session-start** | Read + conditional reset | Reads for continuity checks (Phase 1.5): inspects `status` field to detect crashed/paused sessions. Surfaces `## What Not To Retry` as a forced-read HISTORICAL block (Phase 6.5.1). May reset STATE.md to idle at the boundary between a completed session and a new session — only when prior `status: completed`, via `scripts/state-md-idle-reset.mjs` (#1560). The reset keeps the five recommendation keys in the frontmatter for the Phase 7.5 Mode-Selector, clears `current-wave` (→ 0), sets `status: idle`, demotes `## Wave History` into `## Previous Session`, and empties `## Deviations` — but PRESERVES `## What Not To Retry` (cross-session continuity, #623) and `## Open Questions` (Close Handover-Alignment-Gate, PRD 2026-07-07). Never resets on `active` or `paused` (those paths are user-interactive). |
 | **evolve** | Read-only | Reads `## Deviations` section for deviation pattern extraction (Step 2.2, pattern 5) |
 
 ### Shared-File Single-Writer Rule (`isolation: none` waves)
@@ -246,6 +246,7 @@ The `.orchestrator/session.lock` file is written mechanically by `hooks/_lib/loc
 | `pid` | v1 | **Forensic only — do NOT use for liveness.** Records the writer's process PID (the hook subprocess, ~500ms lifetime). Dead PIDs are expected and normal. See D2 / D3 notes below. |
 | `host` | v1 | `os.hostname()` of the machine that wrote the lock. Cross-host locks skip PID checks. |
 | `ttl_hours` | v1 | Maximum age before the lock is considered stale regardless of other signals. Default 4h. |
+| `claude_pid` | optional (#1641) | The Claude Code process id from `CLAUDE_PID`, written only when that process is the writer hook's DIRECT parent (a Codex child of a Claude session inherits the variable and must not carry it); absent otherwise (Codex, Cursor). Not a liveness signal either: it is the witness that survives `/clear`, where the raw id and the label are minted anew. A `clear`/`resume` start whose own admitted pid equals it on the same host treats the lock as its own predecessor — it takes it over (`reclaimed: own-process`) or, on a #1635 lead yield, releases it. Ceilings: two pid namespaces with one hostname (WSL2 distros, container and host on one checkout). |
 
 ### Liveness rule (v2)
 

package/skills/architecture/references/domain-model.md

@@ -3,7 +3,7 @@
 > Reference material for the `architecture` skill — **not a skill of its own.**
 > Merged here in v4.0.0 from the former `skills/domain-model/` (retired: zero
 > telemetry, zero fleet invocations, reference-only usage — see
-> `docs/audits/2026-09-06-360-audit.md` § 5A). Invoke it by reading this file
+> § 5A of the 2026-09-06 360° audit, an internal report not in the public mirror). Invoke it by reading this file
 > from `/architecture`, not via a slash command.
 >
 > Adapted from [`mattpocock/skills@90ea8ee`](https://github.com/mattpocock/skills/tree/main/domain-model), MIT — Copyright (c) 2026 Matt Pocock. See the repo-root `NOTICE`.

package/skills/autopilot/SKILL.md

@@ -249,8 +249,9 @@ import { detectPeers } from '$PLUGIN_ROOT/scripts/lib/session-registry.mjs';
 const flags = parseFlags(process.argv.slice(2));
 
 const modeSelector = async () => {
-  // Each iteration rebuilds signals from current disk state. STATE.md will be
-  // freshly idle-reset by the previous /close, sessions.jsonl will have the
+  // Each iteration rebuilds signals from current disk state. STATE.md will
+  // carry the recommendation the previous /close wrote (the idle reset at the
+  // next session-start keeps those keys, #1560), sessions.jsonl will have the
   // new tail entry, etc. This is the contract: live signals every iteration.
   // `repoRoot` is passed explicitly (#1071) rather than left to the helper's
   // cwd default. Do NOT hand-write a `backlogLimit` here — the window default

package/skills/bootstrap/SKILL.md

@@ -124,6 +124,8 @@ Present exactly one `AskUserQuestion` unless:
 - `$ARGUMENTS` includes `--fast`, `--standard`, or `--deep` (tier pre-selected, skip question)
 - `--retroactive` flag (no scaffolding at all, skip to Phase 4)
 
+**Language (#1562).** The question texts in this skill are written in German. Render every question, option description and report line in the operator's language: `owner.language` from `~/.config/session-orchestrator/owner.yaml` when that file exists (`de` or `en`), otherwise the language the operator writes in this session. Tier labels (`fast`, `standard`, `deep`) and archetype ids stay verbatim, because they are values; `(Empfohlen)` and `Abbrechen` follow the language (`(Recommended)`, `Cancel`).
+
 ```
 AskUserQuestion({
   questions: [{
@@ -272,7 +274,7 @@ selection, scaffolding and initial commit. Rule selection may read the lock ID.
    export PLUGIN_ROOT CONFIRMED_ARCHETYPE DRY_RUN RULES_CATEGORIES
    node --input-type=module <<'NODE'
    import { pathToFileURL } from 'node:url';
-   const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+   const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
    const categories = (process.env.RULES_CATEGORIES || '').split(',').map(value => value.trim()).filter(Boolean);
    const result = await syncBootstrapRules({ repoRoot: process.cwd(), archetype: process.env.CONFIRMED_ARCHETYPE || undefined,
      dryRun: process.env.DRY_RUN === 'true', categories: categories.length ? categories : null });

package/skills/bootstrap/_shared-template.md

@@ -28,7 +28,7 @@ mkdir -p "$REPO_ROOT/.claude"
 export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
 RULES_RESULT=$(node --input-type=module <<'NODE'
 import { pathToFileURL } from 'node:url';
-const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const result = await syncBootstrapRules({ repoRoot: process.env.REPO_ROOT, archetype: process.env.CONFIRMED_ARCHETYPE || undefined });
 process.stdout.write(`${JSON.stringify(result)}\n`);
 if (result.status === 'error') process.exitCode = 2;
@@ -151,7 +151,7 @@ if [[ "${PATH_TYPE:-public}" = "private" ]]; then
   export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
   BASELINE_RULES_RESULT=$(node --input-type=module <<'NODE'
 import { pathToFileURL } from 'node:url';
-const { applyBaselineRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { applyBaselineRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const result = await applyBaselineRules({
   repoRoot: process.env.REPO_ROOT,
   archetype: process.env.CONFIRMED_ARCHETYPE,
@@ -200,7 +200,7 @@ MANIFEST
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-const { pluginRuleTargets } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { pluginRuleTargets } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const owned = new Set(pluginRuleTargets(process.env.PLUGIN_ROOT));
 const files = readFileSync(process.env.RULES_MANIFEST, 'utf8').split('\n')
   .filter(file => file && !owned.has(path.posix.basename(file)));
@@ -281,7 +281,7 @@ if [[ "${PATH_TYPE:-public}" = private ]]; then
   export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
   POLICY_RESULT=$(node --input-type=module <<'NODE'
 import { pathToFileURL } from 'node:url';
-const { writeBaselineQualityPolicy } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { writeBaselineQualityPolicy } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const result = await writeBaselineQualityPolicy({ repoRoot: process.env.REPO_ROOT, archetype: process.env.CONFIRMED_ARCHETYPE });
 process.stdout.write(`${JSON.stringify(result)}\n`);
 if (result.status === 'error') process.exitCode = 2;

package/skills/bootstrap/fast-template.md

@@ -195,7 +195,7 @@ mkdir -p "$REPO_ROOT/.claude"
 export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE
 RULES_RESULT=$(node --input-type=module <<'NODE'
 import { pathToFileURL } from 'node:url';
-const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const result = await syncBootstrapRules({ repoRoot: process.env.REPO_ROOT,
   archetype: process.env.CONFIRMED_ARCHETYPE || undefined, minimal: !process.env.CONFIRMED_ARCHETYPE });
 process.stdout.write(`${JSON.stringify(result)}\n`);

package/skills/bootstrap/private-contract.md

@@ -41,7 +41,7 @@ interactive setup script, package installation, Git, or a remote service.
 export PLUGIN_ROOT REPO_ROOT CONFIRMED_ARCHETYPE REPO_NAME
 SCAFFOLD_RESULT=$(node --input-type=module <<'NODE'
 import { pathToFileURL } from 'node:url';
-const { scaffoldBaselineArchetype } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
+const { scaffoldBaselineArchetype } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`).href);
 const result = await scaffoldBaselineArchetype({
   repoRoot: process.env.REPO_ROOT,
   archetype: process.env.CONFIRMED_ARCHETYPE,

package/skills/bootstrap/references/bootstrap-retroactive-flow.md

@@ -49,13 +49,24 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
    plugin-version: <current plugin version from $PLUGIN_ROOT/package.json>
    ```
 
-6. **Patch Session Config (#182).** Run the validator against the current `## Session Config` block; append any missing mandatory fields with defaults. The 7 mandatory fields (per `scripts/lib/config-schema.mjs`) are: `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`.
+6. **Patch Session Config (#182, #1567).** Find the mandatory fields the `## Session Config` block does not carry and append them with defaults. The mandatory fields are the keys of the FIRST `## Session Config` block in `$PLUGIN_ROOT/docs/session-config-template.md` (today the 7 validated by `scripts/lib/config-schema.mjs`): `test-command`, `typecheck-command`, `lint-command`, `agents-per-wave`, `waves`, `persistence`, `enforcement`.
+
+   Presence is read from the FILE, not from the validator: `parseSessionConfig()` fills every mandatory field with its default, so `parse-config.mjs` / `validate-config.mjs` never report an ABSENT field (a pnpm repo without `test-command` would silently run `npm test`). `missingStarterKeys()` (`scripts/lib/config/template-keys.mjs`) compares the template's starter keys against `collectTopLevelKeyLines()` — the top-level keys the runtime reads, in every accepted spelling (`key:`, `- key:`, `- **key:**`).
 
    ```bash
-   CONFIG_OUT="$(node "$PLUGIN_ROOT/scripts/parse-config.mjs" 2>&1 >/dev/null)"
-   # parse-config.mjs emits validation warnings to stderr when enforcement=warn.
-   # Grep for 'must be' lines (issued by validate-config.mjs) to detect missing fields.
-   MISSING_FIELDS="$(echo "$CONFIG_OUT" | grep -oE '(test-command|typecheck-command|lint-command|agents-per-wave|waves|persistence|enforcement)' | sort -u || true)"
+   CONFIG_FILE="CLAUDE.md"
+   [[ -f "AGENTS.md" ]] && CONFIG_FILE="AGENTS.md"
+
+   MISSING_FIELDS="$(node --input-type=module -e "
+     import { readFileSync } from 'node:fs';
+     import { missingStarterKeys } from '$PLUGIN_ROOT/scripts/lib/config/template-keys.mjs';
+     const missing = missingStarterKeys(
+       readFileSync(process.argv[1], 'utf8'),
+       readFileSync('$PLUGIN_ROOT/docs/session-config-template.md', 'utf8'),
+     );
+     if (missing === null) { console.error('template has no Session Config block — mandatory-field check did not run'); process.exit(1); }
+     console.log(missing.join(' '));
+   " "$CONFIG_FILE")"
    if [[ -n "$MISSING_FIELDS" ]]; then
      # Detect package manager to pick sensible defaults for commands.
      PM_DEFAULTS="$(node --input-type=module -e "
@@ -67,9 +78,6 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
        console.log('lint-command: ' + cmds.lint.command);
      " 2>/dev/null)"
 
-     CONFIG_FILE="CLAUDE.md"
-     [[ -f "AGENTS.md" ]] && CONFIG_FILE="AGENTS.md"
-
      # Append each missing field under the ## Session Config block.
      for field in $MISSING_FIELDS; do
        case "$field" in
@@ -89,7 +97,7 @@ Entered when `$ARGUMENTS` contains `--retroactive`. Writes the lock file and, pe
    fi
    ```
 
-   This patch is best-effort: existing fields are never overwritten. If no fields are missing, this step is a no-op.
+   This patch is best-effort: existing fields are never overwritten, and an INVALID value of a present field is left for `parse-config.mjs` to report. If no fields are missing, this step is a no-op; if the check did not run (exit 1), report that line instead of `No config changes.`.
 
 7. **Commit.** Stage the lock file (and the patched config file, if it changed) and commit:
    ```bash

package/skills/bootstrap/templates/agents/project-code-review.md

@@ -1,6 +1,6 @@
 ---
 name: project-code-review
-description: Use this agent when you need to review code changes for convention compliance, security issues, or correctness before merging. <example>Context: A wave of implementation work has completed and the coordinator needs a review pass before committing. user: "Review the auth module changes" assistant: "I'll use the project-code-review agent to check convention compliance and surface any security concerns." <commentary>Convention enforcement and security review are the project-code-review agent's responsibilities.</commentary></example>
+description: Use this agent when you need to review code changes for convention compliance, security issues, or correctness before merging.
 model: inherit
 color: green
 tools: Read, Grep, Glob
@@ -16,3 +16,7 @@ Performs read-only review of code changes. Use this agent to:
 - Verify adherence to naming conventions and file structure
 
 Edit this file to add project-specific review checklists, e.g. banned patterns, required linting rules, security invariants, or architecture constraints.
+
+## Examples
+
+<example>Context: A wave of implementation work has completed and the coordinator needs a review pass before committing. user: "Review the auth module changes" assistant: "I'll use the project-code-review agent to check convention compliance and surface any security concerns." <commentary>Convention enforcement and security review are the project-code-review agent's responsibilities.</commentary></example>

package/skills/bootstrap/templates/agents/project-discovery.md

@@ -1,6 +1,6 @@
 ---
 name: project-discovery
-description: Use this agent when you need to audit project state, map affected modules, or verify assumptions before implementation. <example>Context: Before adding a new feature, the coordinator needs to understand existing code paths. user: "Audit the auth flow" assistant: "I'll use the project-discovery agent to map auth modules and identify dependencies." <commentary>Read-only audit work is the project-discovery agent's sweet spot.</commentary></example>
+description: Use this agent when you need to audit project state, map affected modules, or verify assumptions before implementation.
 model: inherit
 color: cyan
 tools: Read, Grep, Glob, Bash
@@ -16,3 +16,7 @@ Performs read-only audits of the project codebase. Use this agent to:
 - Surface potential conflicts or constraints
 
 Edit this file to add project-specific discovery queries, e.g. common file paths, known patterns to grep for, or project-specific terminology to watch for.
+
+## Examples
+
+<example>Context: Before adding a new feature, the coordinator needs to understand existing code paths. user: "Audit the auth flow" assistant: "I'll use the project-discovery agent to map auth modules and identify dependencies." <commentary>Read-only audit work is the project-discovery agent's sweet spot.</commentary></example>