session-orchestrator 3.23.0 → 4.0.0

package/scripts/validate-wave-scope.mjs

@@ -73,6 +73,7 @@ import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
+import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
 import {
   assertFileScopeSubset,
   assertTestSiblingCoverage,
@@ -289,10 +290,13 @@ function validateOptionalSessionId(obj, key, errors) {
 }
 
 /**
- * Validate the OPTIONAL session binding (#1123): `session` (the raw
- * `session_id` of the session that WROTE this manifest) and its human-readable
- * twin `semantic_session`. Both come from one `sessionAttribution(repoRoot)`
- * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest.
+ * Validate the OPTIONAL session binding (#1123): `session_id` (the raw session
+ * id of the session that WROTE this manifest) and its human-readable twin
+ * `semantic_session_id`. Both come from one `sessionAttribution(repoRoot)`
+ * call — see `skills/wave-executor/wave-loop.md` § Scope Manifest. The
+ * pre-#1153 spellings `session` / `semantic_session` are still ACCEPTED here
+ * (read side only, until the next minor release) — key names come from
+ * `MANIFEST_SESSION_KEYS` so the writer and every reader share one list.
  *
  * Deliberately NOT part of {@link validateRequired}, and that is a compatibility
  * constraint rather than a preference: `wave-scope.json` is a shared
@@ -306,9 +310,25 @@ function validateOptionalSessionId(obj, key, errors) {
  * @param {string[]} errors
  * @param {string[]} warnings
  */
-function validateSession(obj, errors, warnings) {
-  const present = validateOptionalSessionId(obj, 'session', errors);
-  validateOptionalSessionId(obj, 'semantic_session', errors);
+function validateSessionBinding(obj, errors, warnings) {
+  let present = false;
+  MANIFEST_SESSION_KEYS.current.forEach((key, i) => {
+    const legacyKey = MANIFEST_SESSION_KEYS.legacy[i];
+    const hasCurrent = validateOptionalSessionId(obj, key, errors);
+    const hasLegacy = validateOptionalSessionId(obj, legacyKey, errors);
+    // Both spellings of the SAME slot, disagreeing, is the one case the reader
+    // cannot resolve honestly: it silently prefers `key` and drops the other
+    // id, so a manifest that names two different sessions would classify as
+    // `own` for one of them. Name it here rather than let the preference decide.
+    if (hasCurrent && hasLegacy && obj[key] !== obj[legacyKey]) {
+      errors.push(
+        `${key} and legacy ${legacyKey} are both present with DIFFERENT values — ` +
+          'a manifest binds to exactly one session; drop the legacy key (accepted on ' +
+          'the read side only, until the next minor release, #1153)',
+      );
+    }
+    if (i === 0) present = hasCurrent || hasLegacy;
+  });
   if (!present) {
     warnings.push(
       'no session field — manifest is not session-bound (legacy, #1123), so every session sharing this ' +
@@ -749,7 +769,7 @@ function validate(
   const warnings = [];
 
   validateRequired(obj, errors);
-  validateSession(obj, errors, warnings);
+  validateSessionBinding(obj, errors, warnings);
   validateAllowedPaths(obj, errors, warnings);
   validateBlockedCommands(obj, errors);
   validateGates(obj, errors);

package/scripts/vault-consolidate.mjs

@@ -84,10 +84,9 @@
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { pathToFileURL } from 'node:url';
 
-import { die, utcTimestamp } from './lib/common.mjs';
+import { die, utcTimestamp, expandTilde } from './lib/common.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import {
   SCRIPT_NAME,
@@ -150,13 +149,6 @@ Exit codes:
   process.stderr.write(usage);
 }
 
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 async function isDir(p) {
   try {
     const st = await fs.stat(p);
@@ -222,8 +214,8 @@ async function main() {
   const isDryRun = !isApply;
   const isJson = parsed.values.json === true;
 
-  const sourceRoot = path.resolve(expandHome(parsed.values.source ?? DEFAULT_SOURCE));
-  const canonicalRoot = path.resolve(expandHome(parsed.values.canonical ?? DEFAULT_CANONICAL));
+  const sourceRoot = path.resolve(expandTilde(parsed.values.source ?? DEFAULT_SOURCE));
+  const canonicalRoot = path.resolve(expandTilde(parsed.values.canonical ?? DEFAULT_CANONICAL));
 
   // Parse --resolve flags into a Map<relPath, "src"|"dst"|"skip">
   const resolutions = new Map();

package/scripts/vault-integration-watcher.mjs

@@ -31,11 +31,10 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 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';
+import { expandTilde } from './lib/common.mjs';
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
@@ -332,9 +331,8 @@ async function main() {
   // Load the config-driven repo list before doing any glab work
   const watcherRoot = getConfinementRoot();
   // Home-expand each entry before confinement, matching sibling scripts (W4-Q2 LOW).
-  const expandHome = (p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p);
   const flipRepos = (await getCrossRepoProjects()).filter((r) => {
-    const guard = validatePathInsideProject(expandHome(r), watcherRoot);
+    const guard = validatePathInsideProject(expandTilde(r), watcherRoot);
     if (!guard.ok) {
       process.stderr.write(
         `vault-integration-watcher: WARN rejecting confined-path violation for ${JSON.stringify(r)} (reason: ${guard.reason})\n`

package/scripts/vault-mirror.mjs

@@ -63,6 +63,7 @@ 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
@@ -489,24 +490,24 @@ async function main() {
     qualityMinConfidence,
   };
 
-  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);
-    }
-
+  /**
+   * 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 {
       // Both processors return the `action` string they emitted (every one of
       // their exit paths is an `emitAction` call), so the tally needs no second
@@ -514,8 +515,8 @@ async function main() {
       // stale the first time a branch is added.
       const action =
         kind === 'learning'
-          ? await processLearning(entry, lineNum, ctx)
-          : await processSession(entry, lineNum, ctx);
+          ? 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
@@ -530,13 +531,13 @@ async function main() {
         await emitMirrorEvent({
           action: 'skipped-invalid',
           kind,
-          line: lineNum,
+          line: entryLineNum,
           recordId: entryId,
           skipClass: 'validation',
           reason: err.message,
           dryRun,
         });
-        continue;
+        return;
       }
       // #718: discriminate genuine filesystem/system errors (which must still
       // abort the whole run — a partially-written vault is worse than a loud
@@ -552,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(
@@ -569,21 +570,105 @@ async function main() {
         await emitMirrorEvent({
           action: 'skipped-invalid',
           kind,
-          line: lineNum,
+          line: entryLineNum,
           recordId: entryId,
           skipClass: 'mapper-crash',
           reason: err.message,
           dryRun,
         });
-        continue;
+        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);
     }
   }
 
+  // #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

package/scripts/wave-scope-binding.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * wave-scope-binding.mjs — print the session binding for a `wave-scope.json`
+ * manifest, and record the fail-closed case as an event (#1153 P4).
+ *
+ * Usage:
+ *   node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
+ *
+ * Prints ONE JSON object on stdout:
+ *
+ *   {"session_id":"<raw session_id>","semantic_session_id":"<semantic id>"}
+ *
+ * Those key names are the canonical ones since #1153 P2 — the same spelling
+ * `.orchestrator/session.lock` and `current-session.json` already use. Readers
+ * additionally accept the pre-#1153 `session` / `semantic_session` spellings
+ * until the next minor release (`MANIFEST_SESSION_KEYS` in
+ * `scripts/lib/session-identity/own-session.mjs`); this writer never emits them.
+ *
+ * Keys whose value is unavailable are OMITTED, never written as `""` — an empty
+ * id is present-but-equal-to-nobody, which every reader classifies as FOREIGN
+ * (the one disposition that skips enforcement entirely), and
+ * `validate-wave-scope.mjs` rejects it outright.
+ *
+ * WHY A COMMAND AND NOT PROSE: this binding used to be an inline
+ * `node --input-type=module -e` block in `skills/wave-executor/wave-loop.md`,
+ * retyped by the coordinator once per wave. An unbound manifest (`{}`) is the
+ * fail-closed direction and therefore SILENT — indistinguishable from a
+ * coordinator that skipped the step. `orchestrator.scope.unbound_manifest` is
+ * what makes the silent case countable; 0 hits repo-wide before this file.
+ *
+ * The binding itself is NOT recomputed here. It is exactly one
+ * `attributionForRecord()` call, which reads `.orchestrator/session.lock` and
+ * confirms the raw `session_id` against this process's own identity before
+ * returning anything — under a peer-owned lock it returns `{}` rather than the
+ * peer's ids. Duplicating that logic would be the one-fact-two-copies class this
+ * repo keeps paying for.
+ */
+
+import { parseArgs } from 'node:util';
+import { resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { attributionForRecord, emitEvent } from './lib/events.mjs';
+import { MANIFEST_SESSION_KEYS } from './lib/session-identity/own-session.mjs';
+
+const HELP = `Usage: node scripts/wave-scope-binding.mjs [--merge] [--wave N] [--role R] [--repo-root DIR]
+
+Print the session-binding keys for a wave-scope.json manifest as one JSON object.
+Empty values are OMITTED; an unbound binding prints {} and emits exactly one
+orchestrator.scope.unbound_manifest event.
+
+With --merge, read the DRAFT manifest as one JSON object on stdin and print that
+same manifest with the binding keys merged in (or with them omitted, plus the
+unbound event, when the binding is {}). Every other field is passed through.
+
+Options:
+  --merge             Read the draft manifest on stdin, print it bound.
+  --wave <n>          Wave number, recorded in the unbound event payload.
+  --role <role>       Wave role, recorded in the unbound event payload.
+  --repo-root <dir>   Repo root to resolve the lock and the events log against
+                      (default: process.cwd()).
+  -h, --help          Show this help and exit 0.
+
+Output:
+  stdout — exactly one JSON object. Diagnostics go to stderr.
+`;
+
+/**
+ * Resolve the manifest binding for `repoRoot`.
+ *
+ * @param {string} repoRoot
+ * @returns {{ session_id?: string, semantic_session_id?: string }} binding with
+ *   empty values omitted
+ */
+export function resolveBinding(repoRoot) {
+  const attribution = attributionForRecord(repoRoot) ?? {};
+  /** @type {{ session_id?: string, semantic_session_id?: string }} */
+  const out = {};
+  const session = typeof attribution.session_id === 'string' ? attribution.session_id.trim() : '';
+  const semantic = typeof attribution.semantic_session_id === 'string'
+    ? attribution.semantic_session_id.trim()
+    : '';
+  if (session) out.session_id = session;
+  if (semantic) out.semantic_session_id = semantic;
+  return out;
+}
+
+async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        wave: { type: 'string' },
+        role: { type: 'string' },
+        'repo-root': { type: 'string' },
+        merge: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+      },
+      allowPositionals: false,
+    });
+  } catch (error) {
+    process.stderr.write(`wave-scope-binding: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.stderr.write(HELP);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (parsed.values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const repoRoot = parsed.values['repo-root'] ?? process.cwd();
+  const binding = resolveBinding(repoRoot);
+
+  if (Object.keys(binding).length === 0) {
+    // The fail-closed case, and the whole reason this is a command: an unbound
+    // manifest enforces against EVERY session in the checkout, and until now it
+    // left no trace at all. Best-effort — the binding is still printed if the
+    // append fails, because a broken events log must not stall a wave.
+    try {
+      await emitEvent(
+        'orchestrator.scope.unbound_manifest',
+        {
+          // Numeric when it parses as one, so the field matches every other
+          // `wave` in the stream; `null` (never `undefined`) when absent, since
+          // an undefined `wave` lets emitEvent's correlation envelope fill it
+          // from the live manifest — the very artefact this event says is
+          // unbound.
+          wave: Number.isFinite(Number(parsed.values.wave)) && parsed.values.wave !== undefined
+            ? Number(parsed.values.wave)
+            : (parsed.values.wave ?? null),
+          role: parsed.values.role ?? null,
+          reason: 'no-confirmed-session-attribution',
+        },
+        { repoRoot },
+      );
+    } catch (error) {
+      process.stderr.write(
+        `wave-scope-binding: could not record unbound_manifest event: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+  }
+
+  if (!parsed.values.merge) {
+    process.stdout.write(`${JSON.stringify(binding)}\n`);
+    return;
+  }
+
+  // --merge: the coordinator pipes the draft manifest in and gets the SAME
+  // manifest back with the binding merged, instead of hand-copying two keys
+  // out of the printed object into the JSON it is about to write (#1207).
+  let draftRaw;
+  try {
+    draftRaw = await readStdin();
+  } catch (error) {
+    process.stderr.write(
+      `wave-scope-binding: could not read the draft manifest from stdin: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let draft;
+  try {
+    draft = JSON.parse(draftRaw);
+  } catch {
+    process.stderr.write('wave-scope-binding: --merge expects ONE JSON object on stdin\n');
+    process.exitCode = 1;
+    return;
+  }
+  if (!draft || typeof draft !== 'object' || Array.isArray(draft)) {
+    process.stderr.write('wave-scope-binding: --merge expects ONE JSON object on stdin\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Any binding key already in the draft is dropped first: under an unbound or
+  // peer-owned lock the merged manifest must name NOBODY, and a stale key
+  // surviving the merge would name somebody. Omitted, never `""` — see above.
+  // BOTH spellings are dropped (close-review 2026-09-04, HIGH): a legacy
+  // `session`/`semantic_session` pair surviving the merge is still READ by every
+  // consumer and would name a foreign session — `foreign` = gates stand down.
+  const merged = { ...draft };
+  for (const key of [...MANIFEST_SESSION_KEYS.current, ...MANIFEST_SESSION_KEYS.legacy]) delete merged[key];
+  // Explicit per-key copy, never Object.assign: `merged` derives from a
+  // JSON.parse'd draft, and a `__proto__` payload key would reach the
+  // Object.prototype setter through [[Set]] semantics (CWE-1321, semgrep
+  // prototype-pollution-object-assign — CI-red on ce6a28aa).
+  for (const key of MANIFEST_SESSION_KEYS.current) {
+    if (typeof binding[key] === 'string' && binding[key]) merged[key] = binding[key];
+  }
+  process.stdout.write(`${JSON.stringify(merged)}\n`);
+}
+
+/**
+ * Read all of stdin as UTF-8. Resolves to `''` when stdin is closed/empty.
+ * @returns {Promise<string>}
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      buf += chunk;
+    });
+    process.stdin.on('end', () => resolve(buf));
+    process.stdin.on('error', reject);
+  });
+}
+
+// `import.meta.main` is not available on every supported Node — compare argv[1]
+// instead, so importing this module from a test never runs the CLI.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolvePath(process.argv[1])) {
+  await main(process.argv.slice(2));
+}

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

@@ -28,6 +28,16 @@ Apply these steps in order against the repo root. Stop at the first hit. Never m
 - Never read both files. Never concatenate, diff, or cross-validate them — the SSOT is whichever the rule selects.
 - The resolved kind (`claude` | `agents`) is part of the contract. Consumers that report paths in JSON output (e.g., `skills/claude-md-drift-check/checker.mjs`) must surface the resolved path so users on either platform can audit the result.
 
+## Interaction with the root `AGENTS.md` this repo now ships
+
+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.
+- **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.
+
 ## Reference implementations
 
 ### Bash one-liner (matches `skills/_shared/bootstrap-gate.md` style)

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. 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.
+- **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)