session-orchestrator 3.22.0 → 3.23.0

package/scripts/vault-mirror.mjs

@@ -56,6 +56,7 @@ import { createReadStream } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 
 import { processLearning, processSession, getMaskerStats } from './lib/vault-mirror/process.mjs';
+import { emitMirrorEvent, emitMirrorRunEvent } from './lib/vault-mirror/telemetry.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
@@ -105,6 +106,43 @@ export function _normalizeRemote(url) {
     .replace(/\/+$/, '');
 }
 
+// ── Mirror telemetry (#1116) ──────────────────────────────────────────────────
+//
+// The mirror run itself used to be SILENT in `.orchestrator/metrics/events.jsonl`
+// (measured 2026-08-23: `jq -r '.event' … | grep -icE 'board|mirror'` → 0 of
+// 28 387 records; the only event this CLI emitted was
+// `orchestrator.secret_masker.applied`). The expensive consequence is the
+// `skipped-invalid` path below: a schema-invalid record is reported on stdout
+// and the process still exits 0, so the affected session ends up WITHOUT a vault
+// note and nothing durable records which one.
+//
+// Design constraints, all load-bearing:
+//   - Additive only. The stdout JSON protocol is untouched; consumers parse it.
+//   - Best-effort. A telemetry failure must never fail a mirror run, so every
+//     emit is wrapped and its rejection swallowed (same posture as the masker
+//     emit at the end of main()).
+//   - "Absent is not zero" (docs/events-schema.md): a field that was not
+//     measured is OMITTED, never written as 0/null. Hence no `path` key here —
+//     these emit sites are reached BEFORE any target path is resolved, so there
+//     is no path to report. `record_id` is likewise omitted when the record
+//     carries neither `id` nor `session_id`; `line` is the fallback locator that
+//     is always measured.
+//   - Same ledger as the masker emit: `emitEvent` is called 2-arg so both events
+//     from one run resolve the SAME destination (`SO_PROJECT_DIR`, i.e.
+//     `CLAUDE_PROJECT_DIR` or the CWD walk-up). This CLI has no repo-root flag
+//     and deriving one from `--source` would split a single run's telemetry
+//     across two ledgers.
+//
+// #1147 moved both emitters into `scripts/lib/vault-mirror/telemetry.mjs` and
+// widened the coverage from "the two skipped-invalid branches" to "every entry,
+// plus one run-level roll-up":
+//   - `emitMirrorEvent` is now also called from `process.mjs`'s 18 `emitAction`
+//     sites, so `created`/`updated`/every `skipped-*` gets a record too.
+//   - `emitMirrorRunEvent` adds the DENOMINATOR. Per-entry records alone cannot
+//     distinguish "healthy run over an empty source" from "the emitter is
+//     broken" — both write nothing (HR-105). The run event is emitted
+//     unconditionally, so `total: 0` is a measured zero.
+
 // ── CLI argument parsing ──────────────────────────────────────────────────────
 //
 // Migrated to scripts/lib/cli-flags.mjs (#510). Behaviour changes vs prior
@@ -285,11 +323,115 @@ if (kind !== 'learning' && kind !== 'session') {
 // imports) so they are import-safe and unit-testable; see _resolveCanonicalSuffix
 // / _normalizeRemote there (#607 D2).
 
+// ── Run-level accounting + run close-out (#1147) ──────────────────────────────
+//
+// Deliberately OUTSIDE main(): the run event's whole contract is that it is
+// written ONCE PER RUN and that its ABSENCE is the broken-emitter signal
+// (HR-105). Six exits bypass main's normal tail — the three PRE-LOOP aborts at
+// the top of main (missing vault-dir, non-canonical vault, missing source), the
+// malformed-JSON abort and the filesystem-error abort inside the loop (all five
+// `process.exit`, which no `finally` and no `catch` can intercept), and the
+// top-level `main().catch`, which runs in a scope where main's locals no longer
+// exist. Keeping the counters and the emitter out here is what lets all six
+// close the run out through ONE function instead of each re-deriving the
+// payload.
+const runState = {
+  /** Non-blank JSONL lines the run ATTEMPTED — the denominator. */
+  total: 0,
+  /** Entries that produced `skipped-invalid` (validation error or mapper crash). */
+  skippedInvalid: 0,
+  /** Per-`action` tally, keyed by the same strings the entries wrote to stdout. */
+  actions: new Map(),
+  /** Latch: the run may only be closed out once. */
+  finished: false,
+};
+
+/** Count one entry action into {@link runState}. Ignores a non-string action. */
+const tally = (action) => {
+  if (typeof action !== 'string' || action.length === 0) return;
+  runState.actions.set(action, (runState.actions.get(action) ?? 0) + 1);
+};
+
+/**
+ * Close the run out: emit the run-level roll-up AND the masking roll-up,
+ * exactly once. Never throws, never exits — the caller owns the exit code.
+ *
+ * Both emits are documented as unconditional, and both used to sit only on the
+ * happy tail: an abort skipped them, so the very runs an operator most wants
+ * counted were the ones that vanished from the ledger, in the one shape
+ * ("no record") that the docstring reserves for a broken emitter.
+ *
+ * @param {'missing-vault-dir'|'vault-not-canonical'|'missing-source'|'malformed-json'|'filesystem-error'|'unexpected-error'} [aborted]
+ *   Omitted on a complete run. When present it LABELS the counters as partial:
+ *   every line after the abort was never attempted, so the classes no longer
+ *   partition `total`. On the three PRE-LOOP values (#1151) nothing was
+ *   attempted at all — `total` is a measured 0 and the label is what separates
+ *   "never started" from "ran over an empty source".
+ * @returns {Promise<void>}
+ */
+async function finishRun(aborted) {
+  if (runState.finished) return;
+  runState.finished = true;
+
+  const countOf = (action) => runState.actions.get(action) ?? 0;
+  const actionBreakdown = Object.fromEntries(runState.actions);
+  await emitMirrorRunEvent({
+    kind,
+    total: runState.total,
+    created: countOf('created'),
+    updated: countOf('updated'),
+    // Every non-failure skip class, summed from the SAME map the breakdown is
+    // built from — `skipped-invalid` is deliberately excluded and reported as
+    // `failed`, because those are the entries whose session silently ends up
+    // without a vault note.
+    skipped: [...runState.actions].reduce(
+      (sum, [action, n]) =>
+        action.startsWith('skipped-') && action !== 'skipped-invalid' ? sum + n : sum,
+      0,
+    ),
+    failed: runState.skippedInvalid,
+    actionBreakdown,
+    dryRun,
+    ...(aborted ? { aborted } : {}),
+  });
+
+  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
+  //
+  // Emitted here, at the END of the run, rather than at the lazy build site
+  // inside process.mjs. The build site is only reached once a record is actually
+  // processed, so a run over an empty/fully-skipped source would emit nothing and
+  // "the masker never ran" would be indistinguishable from "this channel has no
+  // masker wired".
+  //
+  // Counts only — never a needle, never a prefix of one, never masked text.
+  // Best-effort: a telemetry write must never be the reason a mirror run fails.
+  try {
+    const maskerStats = getMaskerStats();
+    await emitEvent('orchestrator.secret_masker.applied', {
+      channel: 'vault-mirror',
+      needle_count: maskerStats.needleCount,
+      records: maskerStats.records,
+      hits: maskerStats.hits,
+      dry_run: dryRun,
+    });
+  } catch {
+    // Silent no-op — see the note above.
+  }
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
+  // The three PRE-LOOP aborts below (#1151) close the run out through the same
+  // `finishRun` every other exit uses. They are the runs that never reached
+  // their first entry — a bad vault-dir, a wrong vault, a missing source — and
+  // until now they were the only outcomes that left NO record at all, which is
+  // the one shape the run event reserves for a broken emitter. Their counters
+  // are all `0`, and `aborted` is what makes that zero readable as "never
+  // started" rather than "ran over an empty source".
   if (!existsSync(resolve(vaultDir))) {
     process.stderr.write(`vault-mirror: vault-dir not found: ${vaultDir}\n`);
+    await finishRun('missing-vault-dir');
     process.exit(2);
   }
 
@@ -307,12 +449,14 @@ async function main() {
       process.stderr.write(
         `vault-mirror: refusing to mirror — "${vaultDir}" is not the canonical Meta-Vault (expected git origin ending in one of: ${canonicalSuffixes.join(', ')}; got ${got})\n`,
       );
+      await finishRun('vault-not-canonical');
       process.exit(2);
     }
   }
 
   if (!existsSync(resolve(source))) {
     process.stderr.write(`vault-mirror: source file not found: ${source}\n`);
+    await finishRun('missing-source');
     process.exit(2);
   }
 
@@ -328,7 +472,13 @@ async function main() {
   }
 
   let lineNum = 0;
-  let skippedInvalidCount = 0;
+  // The run-level denominator lives in `runState` above: `runState.total` counts
+  // every NON-BLANK line the run attempted, so
+  // `created + updated + skipped + failed === runState.total` for any run that
+  // does not abort — and an aborted run says so with the `aborted` field rather
+  // than publishing a partial count as a complete one. The breakdown is keyed by
+  // the same `action` string the entry wrote to stdout, so no second vocabulary
+  // is introduced.
   const ctx = {
     vaultDir,
     dryRun,
@@ -343,21 +493,30 @@ async function main() {
     lineNum++;
     const trimmed = line.trim();
     if (!trimmed) continue;
+    runState.total++;
 
     let entry;
     try {
       entry = JSON.parse(trimmed);
     } catch (err) {
       process.stderr.write(`vault-mirror: malformed JSON on line ${lineNum}: ${err.message}\n`);
+      // Close the run out BEFORE exiting: `process.exit` runs no `finally`, so
+      // without this the abort is the one outcome that leaves no run record —
+      // exactly the shape reserved for a broken emitter.
+      await finishRun('malformed-json');
       process.exit(1);
     }
 
     try {
-      if (kind === 'learning') {
-        await processLearning(entry, lineNum, ctx);
-      } else {
-        await processSession(entry, lineNum, ctx);
-      }
+      // Both processors return the `action` string they emitted (every one of
+      // their exit paths is an `emitAction` call), so the tally needs no second
+      // census of the 18 call sites in process.mjs — a census that would go
+      // stale the first time a branch is added.
+      const action =
+        kind === 'learning'
+          ? await processLearning(entry, lineNum, ctx)
+          : await processSession(entry, lineNum, ctx);
+      tally(action);
     } catch (err) {
       // Validation errors (missing required fields) → per-entry skip, not a global failure
       if (err.message.startsWith('vault-mirror:')) {
@@ -366,7 +525,17 @@ async function main() {
         process.stdout.write(
           JSON.stringify({ action: 'skipped-invalid', path: null, kind, id: entryId }) + '\n',
         );
-        skippedInvalidCount++;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: lineNum,
+          recordId: entryId,
+          skipClass: 'validation',
+          reason: err.message,
+          dryRun,
+        });
         continue;
       }
       // #718: discriminate genuine filesystem/system errors (which must still
@@ -395,47 +564,43 @@ async function main() {
             reason: 'mapper-crash',
           }) + '\n',
         );
-        skippedInvalidCount++;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: lineNum,
+          recordId: entryId,
+          skipClass: 'mapper-crash',
+          reason: err.message,
+          dryRun,
+        });
         continue;
       }
       // Unexpected filesystem errors → fatal
       process.stderr.write(`vault-mirror: filesystem error on line ${lineNum}: ${err.message}\n`);
+      await finishRun('filesystem-error');
       process.exit(2);
     }
   }
 
-  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
+  // ── Run close-out (#1147) ───────────────────────────────────────────────────
   //
-  // Emitted UNCONDITIONALLY, exactly once per channel run, and HERE — at the end
-  // of the run rather than at the lazy build site inside process.mjs. The build
-  // site is only reached once a record is actually processed, so a run over an
-  // empty/fully-skipped source would emit nothing and "the masker never ran" would
-  // be indistinguishable from "this channel has no masker wired". Placed BEFORE
-  // the --strict-schema abort so a failing run still reports its masking posture.
-  //
-  // Counts only — never a needle, never a prefix of one, never masked text.
-  // Best-effort: a telemetry write must never be the reason a mirror run fails.
-  try {
-    const maskerStats = getMaskerStats();
-    await emitEvent('orchestrator.secret_masker.applied', {
-      channel: 'vault-mirror',
-      needle_count: maskerStats.needleCount,
-      records: maskerStats.records,
-      hits: maskerStats.hits,
-      dry_run: dryRun,
-    });
-  } catch {
-    // Silent no-op — see the note above.
-  }
+  // The happy tail. Both roll-ups live in `finishRun` above, which every abort
+  // path also calls, so "the run ended" is emitted from ONE place regardless of
+  // HOW it ended. Placed BEFORE the --strict-schema abort so a failing run still
+  // reports its denominator — that run is precisely the one an operator wants
+  // counted.
+  await finishRun();
 
   // --strict-schema: abort with exit 1 when any entry was skipped-invalid.
   // Useful in CI to catch producer-side schema drift early (issue #249).
-  if (strictSchema && skippedInvalidCount > 0) {
+  if (strictSchema && runState.skippedInvalid > 0) {
     process.stdout.write(
-      JSON.stringify({ action: 'strict-schema-abort', skipped: skippedInvalidCount, kind }) + '\n',
+      JSON.stringify({ action: 'strict-schema-abort', skipped: runState.skippedInvalid, kind }) + '\n',
     );
     process.stderr.write(
-      `vault-mirror: --strict-schema: ${skippedInvalidCount} entries failed validation — exiting 1\n`,
+      `vault-mirror: --strict-schema: ${runState.skippedInvalid} entries failed validation — exiting 1\n`,
     );
     process.exit(1);
   }
@@ -448,8 +613,12 @@ async function main() {
   }
 }
 
-  main().catch((err) => {
+  main().catch(async (err) => {
     process.stderr.write(`vault-mirror: unexpected error: ${err.message}\n`);
+    // Same reason as the two in-loop aborts: an unexpected throw is a run that
+    // ENDED, and the ledger has to say so. `finishRun` never throws, so this
+    // cannot turn a diagnosable crash into a silent one.
+    await finishRun('unexpected-error');
     process.exit(2);
   });
 }

package/skills/_shared/monitor-patterns.md

@@ -36,7 +36,17 @@ the GitHub mirror's main-branch SHA so the operator can confirm parity.
 ```bash
 prev=""
 while true; do
-  s=$(glab ci status -R <OWNER>/<REPO> --output json 2>/dev/null || echo '{"jobs":[]}')
+  # Fallback carries an `error` key, NOT '{"jobs":[]}': an empty job list is a
+  # legitimate glab answer, so it makes a dead CLI read as "pipeline with no jobs"
+  # and the watch goes silent (LM-002: silence is not success).
+  s=$(glab ci status -R <OWNER>/<REPO> --output json 2>/dev/null || echo '{"error":"glab-ci-status-failed"}')
+  # Anything that is not a jobs-carrying object — the sentinel above, or raw
+  # non-JSON glab noise — becomes a visible `error:` line, never silence.
+  if ! jq -e 'type=="object" and has("jobs")' <<<"$s" >/dev/null 2>&1; then
+    echo "$(date -u +%H:%M:%SZ) error: glab ci status unusable — $(printf '%.60s' "$s")"
+    sleep 30
+    continue
+  fi
   cur=$(jq -r '.jobs[] | select(.status!="running" and .status!="pending") | "\(.name): \(.status)"' <<<"$s" 2>/dev/null | sort)
   comm -13 <(echo "$prev") <(echo "$cur")
   prev=$cur
@@ -50,10 +60,16 @@ done
 ```
 
 **Coverage.** Emits a line for each job transitioning out of `running` /
-`pending`. Terminates when **all** jobs are in a terminal state (`success`,
-`failed`, `canceled`, `skipped`). The final line prints the GitHub mirror
-SHA — silence at the end means glab JSON parsing failed (the `||` fallbacks
-prevent the whole loop from dying).
+`pending`, **plus an `error:` line on every iteration where glab produced
+nothing usable** — a dead CLI, an auth expiry, or a network drop surfaces as a
+notification rather than as absence. Terminates when **all** jobs are in a
+terminal state (`success`, `failed`, `canceled`, `skipped`). The final line
+prints the GitHub mirror SHA. Silence now carries exactly one meaning: the
+pipeline is running and no job has changed state.
+
+If you feed this snippet's output through a downstream `grep -E` filter, the
+alternation must include `error` alongside the job-status tokens — the failure
+signature is a word, not an absence.
 
 **Probed 2026-08-14 (glab 1.91.0), three corrections — #1022.** The snippet
 above was silence-is-not-success in its own right until that date, and each
@@ -74,6 +90,16 @@ half failed into the next one's fallback:
   terminal test against `{"jobs":[]}` (exit 1 = keep watching) versus the old
   form against `[]` (exit 0 = break).
 
+**Amended 2026-08-24 — #1077.** The `{"jobs":[]}` fallback the third bullet
+describes was still *indistinguishable from a real answer*: a pipeline can
+legitimately report zero jobs, so a dead glab produced a well-formed payload,
+no `error`, and no output. Non-terminal is not the same as visible. The
+fallback is now `{"error":"glab-ci-status-failed"}` plus the shape guard at the
+top of the loop, and the `(.jobs|length) > 0` terminal guard stays as the
+second line of defence for a genuine zero-job response. Probed: the sentinel
+and raw non-JSON glab noise both emit the `error:` line;
+`{"jobs":[],"pipeline":{}}` and a populated payload both take the normal path.
+
 **GitHub-mirror equivalent.** When the pipeline is GitHub-Actions-native (PR
 checks rather than a GitLab pipeline), use
 `gh pr checks -R <OWNER>/<REPO> <pr> --watch --fail-fast`

package/skills/_shared/parallel-aware-auq.md

@@ -101,7 +101,7 @@ The two slots are `parallelPeer.mode` and `parallelPeer.pid`; `<ageHours>` is th
 
 ### Outcome handling
 
-- **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. Once the worktree exists, exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.
+- **Worktree anlegen + starten** → invoke `enterWorktree({ basePath, sessionId, branch, repoRoot })` from `scripts/lib/autopilot/worktree-pipeline.mjs`. The helper creates a sibling worktree at `<basePath>/<repo-name>-<sessionId>/`, runs idempotency + boundary checks, and logs a WARN line to stderr on fresh creation. When `<branch>` is already checked out by another worktree — the normal case, since Phase 0.5 passes the current HEAD — the worktree lands on a fresh `so/<sessionId>` branch created at `<branch>` and the helper returns `{ branch: 'so/<sessionId>', promotedFrom: '<branch>' }` (#1067); the new worktree's STATE.md `branch` MUST record `so/<sessionId>` and note `promoted from <branch>@<repoRoot>`. Once the worktree exists, and BEFORE exiting the preamble flow, call `leaveSourceRoot({ repoRoot, sessionId: <the raw physical session_id owning this root's lock/registry entry>, semanticSessionId, reason: 'worktree-promotion' })` from `scripts/lib/session-transition.mjs`. **Read that `sessionId` from this root's `.orchestrator/session.lock` via `readLock({ repoRoot })` — never the semantic label, and never `current-session.json`, which may describe a peer session (#863); a wrong id aborts the teardown with `ok: false, reason: 'lock-session-mismatch:<owner>'` and removes nothing.** In detail: the promotion is a PROCESS BOUNDARY, not a live migration (#1069) — the old root is deregistered and its `session.lock` released BEFORE the new worktree's own Phase 1.2 acquires, so the two roots never both own a live claim at once. The call never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue (the destination worktree already exists — aborting here would leave the two-live-roots state the call prevents). Then exit the current preamble flow — the new worktree's own session-start runs from scratch (Phase 1 onwards). On failure (`WorktreeBoundaryError` or `git worktree add` non-zero exit), emit a stderr warning `parallel-aware: enterWorktree failed: <error>; falling back to Manuell` and proceed via the Manuell path.
 - **Manuell** → append a Deviation via `appendDeviationOnDisk()`:
   `Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>, mode=<peer.mode>, pid=<peer.pid>. PSA-001/PSA-002/PSA-004 discipline applies.`
   Continue Phase-0.

package/skills/_shared/parallel-aware-preamble.md

@@ -153,7 +153,7 @@ The skill consuming the preamble translates the outcome:
 |---------|--------|
 | `PASS_THROUGH` | Continue immediately. No AUQ. Pre-P1.3 behavior. |
 | `EXCLUSIVE_BLOCKED` | Fire Exclusive-Conflict AUQ from `parallel-aware-auq.md`. Block until user response. On "Abbrechen": exit cleanly. On "Andere Session beenden": surface to user (preamble does NOT kill other session). On "Warten": pause Phase 0; re-run preamble on user retry. |
-| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call enterWorktree() from worktree-pipeline.mjs (see parallel-aware-auq.md outcome-handling). On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
+| `PROMOTION_OFFER` | Fire Promotion AUQ from `parallel-aware-auq.md`. On "Worktree anlegen": call enterWorktree() from worktree-pipeline.mjs, then — BEFORE exiting Phase 0 — `leaveSourceRoot({ repoRoot, sessionId, semanticSessionId, reason: 'worktree-promotion' })` from `session-transition.mjs` (see parallel-aware-auq.md outcome-handling). `sessionId` is the RAW physical `session_id` from this root's `.orchestrator/session.lock` (`readLock({ repoRoot })`), never the semantic label and never `current-session.json` (may describe a peer, #863). The promotion is a process boundary, not a live migration (#1069): the old root is deregistered and its lock released BEFORE the new worktree's own Phase 1.2 acquires — never both roots owning at once. It never throws; on `{ ok: false }` emit a stderr WARN `parallel-aware: leaveSourceRoot: <reason>` and continue. On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
 
 ## Phase 1b Peer-Guard (defense-in-depth)
 
@@ -169,7 +169,9 @@ The guard is a SOFT-GATE — operator can override, but the warning is mandatory
 findPeers(repoRoot, { mySessionId }) → peer = peers.find((p) => p.source === 'state-md') →
   peer === null  →  safe to write STATE.md; continue Phase 1b normally.
   peer !== null  →  fire Promotion AUQ (parallel-aware-auq.md "Promotion" block).
-                    On "Worktree anlegen": enterWorktree() → continue in sibling.
+                    On "Worktree anlegen": enterWorktree() → leaveSourceRoot(this root)
+                                           → continue in sibling (process boundary,
+                                             old root released before the new acquire).
                     On "Manuell": appendDeviationOnDisk() + continue in-place.
                     On "Abbrechen": exit cleanly.
 ```

package/skills/_shared/platform-tools.md

@@ -20,10 +20,12 @@ These tools have the same name and behavior on all platforms. Cursor IDE uses eq
 
 ## Platform-Specific Tool Mapping
 
+> **Every statement about a foreign platform carries a measurement date and the tool version it was measured on** (PSA-006). An undated capability claim about Codex CLI, Cursor IDE, or Pi is unverified — re-measure before relying on it, and stamp what you find.
+
 | Function | Claude Code | Codex CLI | Cursor IDE | Pi |
 |----------|------------|-----------|------------|----|
 | Present choices to user | `AskUserQuestion` tool with structured options | Numbered Markdown list as plain text, wait for user reply | Numbered Markdown list (same as Codex) | Numbered Markdown list v1; native UI adapter planned |
-| Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Delegate via Codex subagents / typed roles (`explorer`, `worker`) when available; otherwise execute sequentially in the main session | Sequential execution — no parallel subagents. Execute tasks one by one within a single session. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
+| Dispatch subagent | `Agent({ description, prompt, subagent_type })` | Native multi-agent collaboration namespace: `spawn_agent`, `list_agents`, `wait_agent`, `send_message`, `followup_task`, `interrupt_agent`, `close_agent`. Measured 2026-08-25 on `codex-cli 0.141.0` — `codex features list` → `multi_agent  stable  true`. | No native in-session Agent tool. Coordinator-side foreign dispatch via the headless `cursor-agent` CLI exists (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150) — measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. | Sequential execution v1. Do not assume native subagents until the Pi SDK dispatcher exists. |
 | Track tasks | `TaskCreate` / `TaskUpdate` / `TaskList` | Plain-text checklist in response context | Plain-text checklist (same as Codex) | Plain-text checklist (same as Codex) |
 | Enter plan mode | `EnterPlanMode` / `ExitPlanMode` tools | `/plan` slash command (prompt-level, not tool-based) | Instruction-based: "Focus on analysis and planning. Do not modify files until the user approves." | `/plan` prompt template; use instruction-based planning when tool mode is unavailable |
 | Web search | `WebSearch` tool | Built-in web search (invoke via instruction) | `@web` in Cursor chat | Use Pi's available web/search tools if configured; otherwise Bash curl or browser handoff |
@@ -53,18 +55,22 @@ Agent({
   description: "3-5 word summary",
   prompt: "full task context...",
   subagent_type: "general-purpose",
-  run_in_background: false
+  run_in_background: true   // RECOMMENDED for wave dispatch since 2026-08-25 (FA-6);
+                            // verify the started set via meta.json sidecars, never via the
+                            // launch ack — see skills/wave-executor/wave-loop.md § Started-Set Verification
 })
 ```
 
 **On Codex CLI / Codex Desktop:**
-Delegate the task in detail using the available Codex subagent mechanism when it exists. Map work to these roles:
+Codex has a native multi-agent collaboration namespace — use it; do not fall back to sequential in-session execution. Measured 2026-08-25 on `codex-cli 0.141.0`: `codex features list` reports `multi_agent  stable  true`, and a tool-call census over `~/.codex/sessions` (`grep -rhoE '"(spawn_agent|send_message|wait_agent|list_agents|followup_task|interrupt_agent|close_agent)"' . | sort | uniq -c`) returns wait_agent 6041 · send_message 2233 · spawn_agent 1748 · list_agents 836 · close_agent 781 · followup_task 656 · interrupt_agent 109 — i.e. the toolset is in routine production use, not a preview.
+
+Lifecycle: `spawn_agent` (launch, one per wave task) → `list_agents` (enumerate the started set) → `wait_agent` (block on completion) → `send_message` / `followup_task` (steer a running agent) → `interrupt_agent` / `close_agent` (abort / reap). Verify the started set via `list_agents`, never via the `spawn_agent` return alone. Map wave work to these prompt-level roles:
 - **explorer** — read-only evidence gathering (maps to Claude Code's `Explore` subagent)
 - **worker** — implementation tasks (maps to Claude Code's `general-purpose` subagent)
-- **session-reviewer** — quality review when a dedicated review role is available; otherwise perform the review in the main session
+- **session-reviewer** — quality review; spawn as a separate agent rather than reviewing in the main session
 
 **On Cursor IDE:**
-No Agent() tool or typed agent roles. Execute wave tasks sequentially within the active Composer session. After completing each task, report status and move to the next. Parallel execution is not possible — `agents-per-wave` config is ignored on Cursor.
+No native Agent() tool or typed agent roles inside the Composer session — wave tasks run sequentially there, and `agents-per-wave` is ignored. This is a statement about the IDE session only: coordinator-side foreign dispatch to Cursor models via the headless `cursor-agent` CLI does exist (`scripts/lib/wave-executor/foreign-dispatch.mjs`, #1150 — detached worktree, filesystem-measured result, `orchestrator.foreign_dispatch.completed` telemetry, mandatory Claude review, `NEVER_FOREIGN_ROLES` lock). Measured 2026-08-25 on `cursor-agent 2026.08.11-e8db854`. Slash commands live in `.cursor/commands/`. There is no Skill tool — Read `skills/<name>/SKILL.md` instead.
 
 **On Pi:**
 No Session Orchestrator Pi subagent dispatcher exists in v1. Execute wave tasks sequentially in the active Pi session. Treat `agents-per-wave` as advisory until the SDK-based dispatcher lands.

package/skills/_shared/state-ownership.md

@@ -143,6 +143,20 @@ The Ownership Model above resolves *STATE.md* specifically, but the same discipl
 
 This is the wave-plan-time analog of PSA-007 (subagents never race the shared git index) applied one layer up, to shared *files* rather than the git index — see [`../../.claude/rules/parallel-sessions.md`](../../.claude/rules/parallel-sessions.md) § PSA-007.
 
+### `wave-scope.json` Session Binding (#1123)
+
+The rule above deconflicts writers *inside one wave*. The same working copy is also shared across SESSIONS, and `<state-dir>/wave-scope.json` is the one control artefact that constrains writes rather than describing them. It lives in the working copy, not in the session — so before #1123 a manifest written by session A governed session B's every Edit. Measured 2026-08-22 (#1082): a Discovery wave's `allowedPaths: []` — prescribed for every Discovery wave — denied all writes of an unrelated parallel session, with a deny reason that could only tell it to fix a wave plan it does not own.
+
+**The manifest is SESSION-BOUND since #1123.** The coordinator that writes it names itself in two optional fields, `session` (raw `session_id`) and `semantic_session`, both from ONE `sessionAttribution(repoRoot)` call (`scripts/lib/events.mjs`) — see `skills/wave-executor/wave-loop.md` § Scope Manifest 1. `hooks/enforce-scope.mjs` Gate 3b classifies the manifest with `readOwnSessionIds()` + `classifyManifestSession()` (`scripts/lib/session-identity/own-session.mjs`):
+
+- **`foreign`** (ids present, none of them ours) → the gate ALLOWS the write and emits one `orchestrator.scope.foreign_session_ignored` event. A foreign manifest is somebody else's wave plan; it never had authority here, and the event keeps the skip counted rather than silent.
+- **`own`** → enforce, unchanged.
+- **`unknown`** — no id in the manifest (legacy, pre-#1123) or our own identity unresolvable → enforce, unchanged. Only what is PROVABLY foreign is treated as foreign; a guess would turn "cannot tell" into a silent enforcement-off.
+
+Two consequences for anyone touching this artefact. A stale manifest left by a crashed or finished PEER session no longer scopes this session out of its own writes — but a stale manifest of THIS session still does, so the § Scope Manifest lifecycle (delete `wave-scope.json` with `filescopes/` at session end) remains the operator's job. And an empty id is never an honest "unbound": `scripts/validate-wave-scope.mjs` (`validateSession()`) rejects `"session": ""` as an ERROR while an ABSENT key is only a warning, because an empty id matches nobody and would make every reader treat the manifest as foreign where the writer meant "binds everyone".
+
+Mechanism, disposition table and named limits: [`../../docs/scope-collision-guard.md`](../../docs/scope-collision-guard.md) § 2.3.
+
 ## Guards
 
 ### Branch Validation
@@ -237,11 +251,24 @@ This replaces the v1 PID-liveness check (`process.kill(pid, 0)`) which was funda
 Despite the v2 liveness rule above existing since Epic #583, `acquire()`'s conflict classifier (`scripts/lib/session-lock.mjs`, the `classifyExisting()` closure) and `checkStale()` still let `pidAlive`/TTL-age act as an independent veto — which let an external `/close` observe the lock's recorded `pid` (the ephemeral hook subprocess / `node -e acquire()` PID, routinely dead within <1s) as dead and misclassify a live, actively-heartbeating session as `stale-pid-dead`, hijacking it mid-wave. Fixed in #744:
 
 - `classifyExisting()` now checks `isLockLive(existing)` **first** and unconditionally returns `{ reason: 'active' }` when true — a dead recorded `pid` can never veto a fresh `last_heartbeat`.
-- Only once `isLockLive()` is false does `pidAlive` pick the stale variant: `stale-pid-dead` when `pidAlive === false` (same-host, confirmed dead), else `stale-pid-alive` — which also covers `pidAlive === null` (cross-host locks, `host !== os.hostname()`, never a confirmable dead PID, so cross-host locks can never land on `stale-pid-dead`).
-- `checkStale()` surfaces the same `isLockLive()` result as an additive `isLive` field alongside the legacy `ttlExpired`/`pidAlive` signals, so recovery-flow diagnostics can observe when the two diverge.
+- Only once `isLockLive()` is false is the lock classified stale — see the #1137 follow-up below for the single reason it now returns.
+- `checkStale()` surfaces the same `isLockLive()` result as an additive `isLive` field alongside the legacy `ttlExpired` signal, so recovery-flow diagnostics can observe when the two diverge.
 
 Net: `pid` (field notes above) stays forensic-only; `last_heartbeat` freshness is the sole determinant of "is this session still active" everywhere in `session-lock.mjs`.
 
+### #1137 — one stale reason, `stale-heartbeat`
+
+#744 left the *stale* half still keyed on `pidAlive`: `stale-pid-dead` when the recorded pid was confirmed dead, `stale-pid-alive` otherwise. Measured 2026-08-23 across the fleet's live locks: **7 of 7 recorded pids were dead**, including the lock of the session that was heartbeating at that very moment. The pid on a lock is the `node -e` / hook subprocess that wrote it, and it exits within about a second of genesis. Two consequences, both live defects:
+
+- `stale-pid-alive` was **structurally unreachable** same-host — nothing could produce it except a pid-number collision.
+- The Phase-1.2 recovery AUQ rendered "pid=… is confirmed dead" for **every** same-host stale lock, presenting a measurement it had not made as the operator's reason to reclaim.
+
+The fix removes the question rather than re-answering it. `classifyExisting()` returns exactly one stale reason, `stale-heartbeat`, carrying `ageHours` (age from `started_at`, unchanged) and `heartbeatAgeMinutes` (age from `last_heartbeat`) — the quantity the liveness rule actually thresholds against, so a recovery prompt states the measured heartbeat age instead of a liveness verdict. `checkStale()` gains the same `heartbeatAgeMinutes` field.
+
+**#1151 follow-up — the `pidAlive` stub is GONE.** #1137 left `checkStale()` returning `pidAlive: null` as a shape-compatible placeholder. It was removed outright: measured @ `f0766e1`, zero production readers repo-wide, so the field only invited a reader to treat `null` as "unknown liveness" — a question this code no longer asks. `checkStale()` now returns `isLive` (the verdict) and `heartbeatAgeMinutes` (the magnitude behind it); anything reasoning about a lock's liveness reads those two. `isPidAliveOnHost` stays exported for `file-lock.mjs` and `lock-reaper.mjs`, where the pid IS the process being asked about.
+
+`isPidAliveOnHost` remains exported from `session-lock.mjs` and is unaffected — `file-lock.mjs` and `lock-reaper.mjs` are legitimate callers, because there the pid IS the process being asked about.
+
 ### Schema v1 → v2 backward-compat
 
 Readers (e.g., `readLock()` in `session-lock.mjs`, `discoverActiveSessions()`) MUST tolerate absent `last_heartbeat` and `semantic_session_id` fields (v1 locks written before Epic #583). When `last_heartbeat` is absent, fall back to TTL-based expiry from `started_at`. When `semantic_session_id` is absent, treat as unknown.

package/skills/autopilot/SKILL.md

@@ -206,7 +206,11 @@ 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
   // new tail entry, etc. This is the contract: live signals every iteration.
-  const signals = await buildLiveSignals({ backlogLimit: 50 });
+  // `repoRoot` is passed explicitly (#1071) rather than left to the helper's
+  // cwd default. Do NOT hand-write a `backlogLimit` here — the window default
+  // lives once, in backlog-scan.mjs (`DEFAULT_BACKLOG_LIMIT`); see
+  // skills/session-start/phase-7-5-mode-selector.md for the same contract.
+  const signals = await buildLiveSignals({ repoRoot: process.cwd() });
   return selectMode(signals);
 };
 

package/skills/bootstrap/SKILL.md

@@ -19,7 +19,7 @@ description: >
 
 This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Config, or `.orchestrator/bootstrap.lock`) or when the user invokes `/bootstrap` directly. It scaffolds the minimum structure required by all session-orchestrator skills, commits it, and writes the lock file that opens the gate for all future invocations.
 
-**Anti-bureaucracy contract:** At most ONE `AskUserQuestion` call in the normal case (tier confirmation). A second question is only asked when the archetype is truly ambiguous on the Public Path for Standard/Deep tiers. No wizard, no multi-step flow.
+**Anti-bureaucracy contract:** On a first-time full bootstrap (no tier flags, no `--no-interview`), expect **7–9** `AskUserQuestion` prompts in three fixed blocks — not an open-ended wizard. (1) **Tier/stack** (Phase 2): one tier-confirmation question, plus an optional second archetype question when `PATH_TYPE = public` and archetype confidence is low (Standard/Deep only). (2) **Owner persona** (Phase 3.5): five questions from `scripts/lib/owner-interview.mjs` (first-run only). (3) **Dispatcher autonomy** (Phase 3.5.1): one question from `scripts/lib/config/dispatcher-autonomy-capture.mjs`. Flagged flows (`--upgrade`, `--retroactive`, `--sync-rules`, `--ecosystem-health`) and `--no-interview` skip some or all of these blocks.
 
 ## Invocation Context
 
@@ -120,7 +120,7 @@ AskUserQuestion({
 })
 ```
 
-Store as `CONFIRMED_ARCHETYPE`. Maximum interactions in bootstrap flow: **2 questions total**.
+Store as `CONFIRMED_ARCHETYPE`. The tier/stack block contributes **1–2** questions; a first-run full bootstrap adds **6 more** from the owner interview (Phase 3.5, five questions) and dispatcher-autonomy capture (Phase 3.5.1, one question) — **7–9 total**.
 
 ## Upgrade Flow (`--upgrade <tier>`)
 
@@ -586,7 +586,7 @@ If invoked directly via `/bootstrap`: report the created files list and stop.
 
 - **NEVER create application code during bootstrap** — only structural files (CLAUDE.md, .gitignore, README.md, manifests, CI). The feature that follows brings its own implementation.
 - **NEVER skip the lock file write** — `.orchestrator/bootstrap.lock` is the gate's mechanical truth. Bootstrap without a lock file is incomplete.
-- **NEVER ask more than 2 questions** — even if the user's intent is unclear, make a best-effort recommendation and let the user correct via `/bootstrap --upgrade` later.
+- **Fixed question budget, no ad-hoc prompts** — tier/stack (1–2), owner interview (5, Phase 3.5), dispatcher-autonomy capture (1, Phase 3.5.1) sum to **7–9** on a first-run full bootstrap; `--no-interview` and flag short-circuits reduce this. Make a best-effort tier recommendation and let the user correct via `/bootstrap --upgrade` later — do not add prompts beyond these blocks.
 - **ALWAYS commit** — bootstrap ends with a git commit. The lock file is part of that commit.
 - **ALWAYS check for retroactive flag** — if `--retroactive` is in `$ARGUMENTS`, skip all scaffolding and jump directly to writing `bootstrap.lock` (tier inferred from existing file inventory, fallback: `fast`).
 - **NEVER abort bootstrap on rules-fetch failure** — rules-fetch is opt-in and best-effort. The legacy Clank sync path is the safety net.