session-orchestrator 5.12.0 → 5.13.0

package/scripts/vault-integration-watcher.mjs

@@ -31,6 +31,9 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { sep as pathSep } from 'node:path';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { resolveRepoSpec, redactUrlCredentials } from './lib/vcs-repo-spec.mjs';
@@ -278,15 +281,59 @@ function buildTickBody(issueMap, depIds, verdict, streak, date) {
 - Verdict: ${verdict}`;
 }
 
+/**
+ * Canonical spelling of an absolute path: realpath (native) when it exists, else as given.
+ * On macOS the native realpath also returns the on-disk letter case.
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalPath(p) {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Path of `root` relative to the home dir, or null when it is not under home (#1622).
+ *
+ * Both sides go through realpath first, so symlinks and (on macOS) a differently
+ * cased spelling of an existing dir resolve to the same string. A root that does not
+ * exist cannot be canonicalised; on darwin/win32 the default volumes are
+ * case-insensitive, so the prefix compare is case-folded there as a fallback.
+ * Ceiling: a case-sensitive APFS volume could fold two distinct non-existent paths
+ * together; the snippet would then name a dir that is not there either way.
+ * @param {string} root
+ * @returns {string|null} '' when root IS home, the relative rest when inside, else null
+ */
+function homeRelative(root) {
+  const home = canonicalPath(homedir());
+  const canonRoot = canonicalPath(root);
+  const fold = process.platform === 'darwin' || process.platform === 'win32';
+  const cmp = (s) => (fold ? s.toLocaleLowerCase('en-US') : s);
+  if (cmp(canonRoot) === cmp(home)) return '';
+  for (const sep of new Set(['/', pathSep])) {
+    if (cmp(canonRoot).startsWith(cmp(`${home}${sep}`))) return canonRoot.slice(home.length + 1);
+  }
+  return null;
+}
+
 /**
  * Build the flip-ready trigger comment body.
  * @param {string[]} repos
+ * @param {string} root — projects root the repo names resolve against
+ *   (getConfinementRoot(), so the snippet follows `projects-root`, #1567)
  * @returns {string}
  */
-function buildFlipBody(repos) {
+function buildFlipBody(repos, root) {
   // Defense-in-depth: regex+confinement upstream already filter, but shell-quote here
   // makes the embedded bash safe under any future bypass.
   const repoList = repos.map(shellQuote).join(' ');
+  // The body is posted to a GitLab issue: a root under the home dir is written
+  // as "$HOME"/… so the comment never carries the owner's home path (#1490).
+  const rel = homeRelative(root);
+  const rootQ = rel === null ? shellQuote(root) : rel === '' ? '"$HOME"' : `"$HOME"/${shellQuote(rel)}`;
   // The sed/add/commit one-liner targets the project-instruction file. Most
   // ecosystem repos use CLAUDE.md, but Codex-CLI repos use AGENTS.md as a
   // transparent alias — see skills/_shared/instruction-file-resolution.md.
@@ -296,14 +343,15 @@ function buildFlipBody(repos) {
 
 Lokaler Befehl (ein-Liner pro Repo, aber besser per Session orchestriert; CLAUDE.md and AGENTS.md sind Aliase):
 \`\`\`bash
+root=${rootQ}
 for d in ${repoList}; do
   for f in CLAUDE.md AGENTS.md; do
-    [ -s ~/Projects/$d/$f ] || continue
-    sed -i.bak 's/mode: warn }/mode: strict }/' ~/Projects/$d/$f
-    git -C ~/Projects/$d add $f
+    [ -s "$root/$d/$f" ] || continue
+    sed -i.bak 's/mode: warn }/mode: strict }/' "$root/$d/$f"
+    git -C "$root/$d" add "$f"
     break
   done
-  git -C ~/Projects/$d commit -m 'chore(orchestrator): Promote vault-integration to strict mode — closes #305'
+  git -C "$root/$d" commit -m 'chore(orchestrator): Promote vault-integration to strict mode — closes #305'
 done
 \`\`\``;
 }
@@ -402,7 +450,7 @@ async function main() {
   // 7. If streak == 3 (or more), post flip-ready trigger
   if (newStreak >= 3) {
     log(`streak=${newStreak} >= 3 — posting flip-ready trigger`);
-    postComment(TRACKING_ISSUE, buildFlipBody(flipRepos));
+    postComment(TRACKING_ISSUE, buildFlipBody(flipRepos, watcherRoot));
     emit({ action: 'flip-ready-posted', issue: TRACKING_ISSUE });
   }
 

package/scripts/vault-mirror.mjs

@@ -798,6 +798,15 @@ async function main() {
   // into `total` like any other line, so the run partition still holds. A
   // malformed archive line is reported and skipped — the archive is secondary
   // input and must not abort a mirror run that already wrote the live store.
+  //
+  // Boundary (BV-004, #1685): the sibling `learnings-inbox.jsonl` (#1516) is
+  // deliberately NOT a mirror source: the mirror reads only the live store (it
+  // checks no store role, and session-end runs it on every host). An inbox
+  // record gets its note on the first mirror run after it is ingested into the
+  // live store, on whichever host that run happens. Ceiling: an inbox host
+  // never mirrors its inbox-only learnings, and every note for an inbox record
+  // lags one ingest. Revisit when a real inbox host needs vault notes before
+  // ingest.
   if (kind === 'learning' && basename(resolve(source)) === 'learnings.jsonl') {
     const archivePath = join(dirname(resolve(source)), 'learnings-archive.jsonl');
     if (existsSync(archivePath)) {

package/skills/_shared/fleet-protocol.md

@@ -106,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,
@@ -161,6 +301,7 @@ sind per Nachricht nicht erreichbar und nutzen dieselben Dateien: vor jeder Well
 ## 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.
 
@@ -139,7 +139,7 @@ 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), plus at most one appended `## Open Questions` entry naming vault-orphan candidates via `appendOpenQuestionOnDisk` (Phase 3.7e, #1563). |
+| **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) |
 
@@ -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/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,