session-orchestrator 3.22.0 → 3.24.0

package/scripts/vault-mirror.mjs

@@ -56,12 +56,14 @@ 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';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
 import { resolveCanonicalSuffixes } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
+import { canonicalizeSessions } from './lib/sessions-canonical.mjs';
 
 // ── Canonical-vault helpers (#600 D2 / #607 D2) ────────────────────────────────
 // These are module-level (above the CLI bootstrap) so the module is import-safe
@@ -105,6 +107,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 +324,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 +450,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 +473,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,
@@ -339,25 +490,34 @@ async function main() {
     qualityMinConfidence,
   };
 
-  for (const line of lines) {
-    lineNum++;
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-
-    let entry;
+  /**
+   * Dispatch one already-parsed entry to its processor and account for the
+   * result. Extracted (#1186c) so the `--kind session` path below can call it
+   * AFTER a whole-file dedup pass instead of once per raw line; every branch
+   * is byte-identical to the pre-#1186c per-line loop body.
+   * @param {unknown} entry — parsed JSONL value (usually an object; a bare
+   *   `null`/primitive line is a real shape this must keep handling, see the
+   *   #1186c session branch below for why it is never filtered out here).
+   * @param {number} entryLineNum — 1-based JSONL line number, or (for the
+   *   `--kind session` dedup path) the line of the record that WON the
+   *   collapse. `_lineNum` is read ONLY for telemetry (process.mjs
+   *   `emitEntryAction` → `line:` on the per-entry ledger event), never to
+   *   derive content — process.mjs itself tolerates a non-finite value by
+   *   suppressing just that one ledger record, but every call site here
+   *   always supplies a real line number.
+   * @returns {Promise<void>}
+   */
+  async function dispatchEntry(entry, entryLineNum) {
     try {
-      entry = JSON.parse(trimmed);
-    } catch (err) {
-      process.stderr.write(`vault-mirror: malformed JSON on line ${lineNum}: ${err.message}\n`);
-      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, entryLineNum, ctx)
+          : await processSession(entry, entryLineNum, ctx);
+      tally(action);
     } catch (err) {
       // Validation errors (missing required fields) → per-entry skip, not a global failure
       if (err.message.startsWith('vault-mirror:')) {
@@ -366,8 +526,18 @@ async function main() {
         process.stdout.write(
           JSON.stringify({ action: 'skipped-invalid', path: null, kind, id: entryId }) + '\n',
         );
-        skippedInvalidCount++;
-        continue;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: entryLineNum,
+          recordId: entryId,
+          skipClass: 'validation',
+          reason: err.message,
+          dryRun,
+        });
+        return;
       }
       // #718: discriminate genuine filesystem/system errors (which must still
       // abort the whole run — a partially-written vault is worse than a loud
@@ -383,7 +553,7 @@ async function main() {
         (typeof err.code === 'string' && err.code.length > 0) || Boolean(err.syscall);
       if (!isSystemError) {
         process.stderr.write(
-          `vault-mirror: mapper crash on line ${lineNum} (${err.message}) — record skipped\n`,
+          `vault-mirror: mapper crash on line ${entryLineNum} (${err.message}) — record skipped\n`,
         );
         const entryId = entry?.id ?? entry?.session_id ?? null;
         process.stdout.write(
@@ -395,47 +565,127 @@ async function main() {
             reason: 'mapper-crash',
           }) + '\n',
         );
-        skippedInvalidCount++;
-        continue;
+        runState.skippedInvalid++;
+        tally('skipped-invalid');
+        await emitMirrorEvent({
+          action: 'skipped-invalid',
+          kind,
+          line: entryLineNum,
+          recordId: entryId,
+          skipClass: 'mapper-crash',
+          reason: err.message,
+          dryRun,
+        });
+        return;
       }
       // Unexpected filesystem errors → fatal
-      process.stderr.write(`vault-mirror: filesystem error on line ${lineNum}: ${err.message}\n`);
+      process.stderr.write(`vault-mirror: filesystem error on line ${entryLineNum}: ${err.message}\n`);
+      await finishRun('filesystem-error');
       process.exit(2);
     }
   }
 
-  // ── Masking telemetry (#1025) ───────────────────────────────────────────────
-  //
-  // 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.
+  // #1186c: for `--kind session`, every parsed entry is buffered here instead
+  // of dispatched inline — the dedup pass below needs the WHOLE file before it
+  // can tell which of several same-`session_id` lines is the winner. `--kind
+  // learning` is unaffected: it still dispatches per line, inline, immediately
+  // below (a malformed line further down the file must not undo an already-
+  // dispatched learning — pinned by the existing `total: 2, created: 1` abort
+  // test in tests/unit/vault-mirror.test.mjs).
+  const sessionEntries = [];
+  const sessionLineNums = [];
+
+  for (const line of lines) {
+    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);
+    }
+
+    if (kind === 'session') {
+      sessionEntries.push(entry);
+      sessionLineNums.push(lineNum);
+      continue;
+    }
+
+    await dispatchEntry(entry, lineNum);
   }
 
+  if (kind === 'session') {
+    // Only an OBJECT entry carrying a non-empty `session_id` is eligible for
+    // the dedup collapse — the same predicate canonicalizeSessions itself uses
+    // internally (sessions-canonical.mjs `isRecordObject` + `isNonEmptyString`,
+    // not exported, so re-stated here rather than reached into). Everything
+    // else — a bare `null`/primitive JSONL line, or a legacy record with no
+    // `session_id` field — is dispatched EXACTLY as before: unaffected, in
+    // original file order, through the SAME validation/mapper-crash paths
+    // process.mjs already has for those shapes. Two regression-guard tests in
+    // tests/unit/vault-mirror.test.mjs depend on this (a bare `null` line and a
+    // legacy `session`-keyed record both still reach processSession() and its
+    // existing error handling, never silently vanish into the collapse).
+    const isIdentifiable = (e) =>
+      e !== null &&
+      typeof e === 'object' &&
+      !Array.isArray(e) &&
+      typeof e.session_id === 'string' &&
+      e.session_id.length > 0;
+    const identifiable = sessionEntries.filter(isIdentifiable);
+    // canonicalizeSessions never clones — the survivors are the SAME object
+    // references as in `sessionEntries`, so reference identity below is exact,
+    // never a guess (scripts/lib/sessions-canonical.mjs header, "RULE ORDER").
+    const survivors = new Set(canonicalizeSessions(identifiable));
+
+    for (let i = 0; i < sessionEntries.length; i++) {
+      const entry = sessionEntries[i];
+      if (isIdentifiable(entry) && !survivors.has(entry)) {
+        // A losing duplicate: an earlier line whose `session_id` a LATER line
+        // in this same batch supersedes or overwrites (crash-recovery
+        // re-append, #1068 stub/supersede pair). No dispatch, no stdout line,
+        // no tally for it — the winning occurrence (dispatched below, at its
+        // own position) already produces the ONE note this physical session
+        // gets. BV-004 ceiling: `runState.total` still counts this raw line,
+        // so `created+updated+skipped+failed` no longer partitions `total`
+        // for a `--kind session` run that collapsed at least one duplicate —
+        // no test pins that invariant for session kind (only for `learning`,
+        // where duplicates are not collapsed), and a partially-written vault
+        // from a batch that could not be fully deduped is the worse failure
+        // mode. Revisit with a dedicated telemetry action if an operator ever
+        // needs to name WHICH lines were collapsed, not just how many notes
+        // were written.
+        continue;
+      }
+      await dispatchEntry(entry, sessionLineNums[i]);
+    }
+  }
+
+  // ── Run close-out (#1147) ───────────────────────────────────────────────────
+  //
+  // 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 +698,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,10 +101,39 @@ 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, rawSessionId, reason: 'worktree-promotion' })` 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>`. Since #1170, `enterWorktree` releases the source root ITSELF once the destination worktree provably exists — it calls `leaveSourceRoot({ repoRoot, sessionId: rawSessionId, semanticSessionId: sessionId, reason })` from `scripts/lib/session-transition.mjs` internally, on BOTH success exits, so this AUQ handler makes no separate `leaveSourceRoot` call. `rawSessionId` — **read 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)** — is the RAW physical `session_id` owning this root's lock/registry entry; a wrong id aborts the teardown with `left.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. `enterWorktree`'s return value carries the outcome as `left: { ok, steps, reason? }`; `leaveSourceRoot()` never throws, so on `left.ok !== true` `enterWorktree` itself emits the stderr WARN `enterWorktree: leaveSourceRoot: <reason>` and the promotion continues regardless (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.
+  Continue Phase-0 — and run the **Peer-Scope-Union** protocol below before the first write.
+
+### Peer-Scope-Union (Manuell only, #1195)
+
+In-place beside a peer is survivable when the two scopes are DECLARED to each other rather than discovered by collision. Measured 2026-09-02 in a consumer repo: a 4-subagent session ran beside a deep session (wave 4, `enforcement: strict`) in ONE checkout, no worktree, zero collisions — the peer's paths were carried in the deep session's `allowedPaths` union (19 → 41, `--assert-subset` green) across a wave rollover.
+
+Four steps, in order. Steps 1 and 2 are the protocol; 3 and 4 are what keeps it honest.
+
+1. **Declare the COMPLETE path list.** The arriving session sends the peer every path it will write — including the ones a script produces (fixtures, snapshots, result files, temp helpers), not only the ones it plans to edit by hand. A path omitted here is a path the peer's guard reports as a violation. In the same message it adopts the peer's resource rules.
+2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest).
+3. **Probe with ONE real write.** Before dispatching any agent, make one small PLANNED Edit from the declared list. A denial here costs one edit; the same denial found after a fan-out costs the wave.
+4. **Announce before committing.** The arriving session sends its final file list, the peer sequences its own push behind it, and the SHAs come back. The git index is shared (PSA-007) — sequencing it is the only thing that makes two sessions in one checkout committable.
+
+Message template for step 1 (`SendMessage`, first line self-contained per `.claude/rules/cross-session-messaging.md`):
+
+```
+Scope-union request: I will write exactly these paths in <repo> — please add them to your allowedPaths.
+
+Paths (complete, incl. files my scripts write):
+- <path>
+- <path>
+
+Resource rules I adopt from you: no build, no dev-server ports, no service stop/restart,
+commit only via `git commit --only <my files>` after announcing, no push, no tag.
+
+I will probe with ONE planned edit before dispatching, announce my final file list before
+committing, and send you the SHAs afterwards.
+```
+
+Delivery is never guaranteed (CSM-004): an unanswered request establishes nothing. Without a confirmed union, do not write beside the peer — take the worktree instead.
 - **Abbrechen** → exit Phase-0 immediately. No file writes.
 
 ## Always-OK Pass-Through (no AUQ)

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

@@ -134,14 +134,23 @@ async function runParallelAwarePreamble({ repoRoot, callerMode, callerSessionId
     return { outcome: 'EXCLUSIVE_BLOCKED', callerClass, blockingSession: exclusiveActive, active: classifiedActive };
   }
 
+  // GH#67: a registry-sourced peer whose lock is SUPERSEDED (a LIVE lock at
+  // this repoRoot is owned by a DIFFERENT raw session_id) is likely a
+  // finished-but-still-fresh task on a platform without SessionEnd. It stays
+  // visible in `active` (never a filter — the lock is advisory, #1085
+  // contract), but it is not eligible to trigger the Promotion AUQ. Split it
+  // out as advisory before the parallelPeer lookup.
+  const supersededPeers = classifiedActive.filter((e) => e.lockSuperseded === true);
+  const promotionEligible = classifiedActive.filter((e) => e.lockSuperseded !== true);
+
   const parallelPeer = callerClass === 'parallel-ok'
-    ? classifiedActive.find((e) => e._class === 'parallel-ok' && e.sessionId !== callerSessionId)
+    ? promotionEligible.find((e) => e._class === 'parallel-ok' && e.sessionId !== callerSessionId)
     : null;
   if (parallelPeer) {
     return { outcome: 'PROMOTION_OFFER', callerClass, parallelPeer, active: classifiedActive };
   }
 
-  return { outcome: 'PASS_THROUGH', callerClass, active: classifiedActive };
+  return { outcome: 'PASS_THROUGH', callerClass, active: classifiedActive, advisory: supersededPeers };
 }
 ```
 
@@ -153,7 +162,9 @@ 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({ ..., rawSessionId, reason: 'worktree-promotion' })` from worktree-pipeline.mjs (see parallel-aware-auq.md outcome-handling) — since #1170 this ONE call also releases the source root: it calls `leaveSourceRoot({ repoRoot, sessionId: rawSessionId, semanticSessionId, reason })` from `session-transition.mjs` internally, on BOTH success exits, so no separate call is made here. `rawSessionId` 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. The return value's `left` field carries the outcome; `leaveSourceRoot()` never throws, so on `left.ok !== true` `enterWorktree` itself emits the stderr WARN `enterWorktree: leaveSourceRoot: <reason>` and the promotion continues regardless. On "Manuell": append Deviation (`Worktree-Auto-Promotion declined; running in-place alongside session_id=<peer.sessionId>`) and continue. On "Abbrechen": exit. |
+
+**Superseded-lock advisory (GH#67).** A `discovered` peer with `lockSuperseded: true` never fires the Promotion AUQ — it is downgraded to the `advisory` array on the `PASS_THROUGH` result instead (see the `runParallelAwarePreamble` reference above), because a live lock at this repoRoot is owned by a different raw session_id and the entry is likely a finished-but-still-fresh task on a platform without SessionEnd, not a live collision (#1085 advisory-lock contract — the entry is never filtered, only downgraded). The consuming skill prints ONE advisory line per entry: `parallel-aware: registry entry <sessionId> (last heartbeat <N> min ago) is superseded by this root's live lock <lockOwnerId> — likely a finished task on a platform without SessionEnd (GH#67); still counted for PSA-001 awareness`, then continues. `lockSuperseded: false` with `lockOwnerId: null` means "no live lock here" — distinct from "own lock". The same session id remains PSA-002-relevant if it also shows up in STATE.md (`source: 'state-md'`, handled unchanged by Phase 1.2.1/Phase 1b below).
 
 ## Phase 1b Peer-Guard (defense-in-depth)
 
@@ -169,7 +180,11 @@ 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(..., rawSessionId) — releases
+                                           the source root internally (#1170; no
+                                           separate leaveSourceRoot call needed)
+                                           → continue in sibling (process boundary,
+                                             old root released before the new acquire).
                     On "Manuell": appendDeviationOnDisk() + continue in-place.
                     On "Abbrechen": exit cleanly.
 ```