session-orchestrator 3.24.0 → 4.0.1

package/scripts/sweep-expired-learnings.mjs

@@ -23,6 +23,7 @@
  * Usage:
  *   node scripts/sweep-expired-learnings.mjs [--prune] [--dry-run|--apply] [--json]
  *     [--grace-days N] [--entries PATH] [--file PATH] [--archive PATH]
+ *     [--appended N] [--boosted M] [--duration-ms D] [--skipped a,b] [--repo-root PATH]
  *
  * Flags:
  *   --prune           Decision-driven prune+consolidate+rewrite instead of the
@@ -40,6 +41,23 @@
  *                      store.
  *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
  *   --archive PATH    Archive sidecar (default: .orchestrator/metrics/learnings-archive.jsonl)
+ *   --appended N      PRUNE ONLY (#1206). New learnings written this `/evolve`
+ *                      run (Step 3.5(4)); folded into the mechanical
+ *                      `orchestrator.evolve.completed` emit alongside this
+ *                      call's own `pruned` count. Default 0.
+ *   --boosted M       PRUNE ONLY (#1206). Existing learnings reinforced this
+ *                      run (Step 3.5(2)). Default 0.
+ *   --duration-ms D   PRUNE ONLY (#1206). Elapsed ms since the run's telemetry
+ *                      start marker. Default 0.
+ *   --skipped a,b     PRUNE ONLY (#1206). Comma-separated list of optional
+ *                      steps that ran but were themselves skipped this run
+ *                      (HR-105 — e.g. `skill-evolution-off`). Default none.
+ *   --repo-root PATH  PRUNE ONLY (#1206). Repo root the
+ *                      `orchestrator.evolve.completed` record is pinned to.
+ *                      No default and NO process.cwd() fallback (#1119) — when
+ *                      omitted, no event is emitted at all (stderr WARN, exit
+ *                      code unaffected). Emission is best-effort and never
+ *                      changes this command's exit code or stdout contract.
  *
  * Exit codes:
  *   0  Success (including no-op when nothing is archive-eligible)
@@ -51,6 +69,7 @@
 import { existsSync } from 'node:fs';
 import { sweepExpiredLearnings, pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
 import { readLearnings } from './lib/learnings/io.mjs';
+import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
 const DEFAULT_ARCHIVE = '.orchestrator/metrics/learnings-archive.jsonl';
@@ -97,6 +116,20 @@ function parseArgs(argv) {
     entries: null,
     file: DEFAULT_FILE,
     archive: DEFAULT_ARCHIVE,
+    appended: 0,
+    boosted: 0,
+    durationMs: 0,
+    skipped: [],
+    // #1119 — NO process.cwd() fallback. Most CLI callers (every test in this
+    // file except the SKILL.md-extraction fixture, which sets its own tmp
+    // `cwd`) invoke this script from the repo root without `--repo-root`; a
+    // cwd fallback would silently append synthetic `orchestrator.evolve.
+    // completed` records to the operator's REAL fleet ledger on every
+    // `--prune --apply` run in `npm test`. `emitEvolveCompleted()` already
+    // refuses to emit (stderr WARN, no throw) when repoRoot is absent — same
+    // fail-closed contract as `emitReconcileCompleted` / `express-path.mjs`.
+    repoRoot: null,
+    telemetryExplicit: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -122,6 +155,37 @@ function parseArgs(argv) {
       args.file = argv[++i];
     } else if (a === '--archive') {
       args.archive = argv[++i];
+    } else if (a === '--appended') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isInteger(v) || v < 0) {
+        usageError(`--appended requires a non-negative integer, got: ${raw}`);
+      }
+      args.appended = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--boosted') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isInteger(v) || v < 0) {
+        usageError(`--boosted requires a non-negative integer, got: ${raw}`);
+      }
+      args.boosted = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--duration-ms') {
+      const raw = argv[++i];
+      const v = Number(raw);
+      if (!Number.isFinite(v) || v < 0) {
+        usageError(`--duration-ms requires a non-negative number, got: ${raw}`);
+      }
+      args.durationMs = v;
+      args.telemetryExplicit = true;
+    } else if (a === '--skipped') {
+      const raw = argv[++i];
+      args.skipped = typeof raw === 'string' ? raw.split(',').filter((s) => s.length > 0) : [];
+      args.telemetryExplicit = true;
+    } else if (a === '--repo-root') {
+      args.repoRoot = argv[++i];
+      args.telemetryExplicit = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
       process.exit(0);
@@ -140,6 +204,12 @@ function parseArgs(argv) {
   if (!args.prune && args.entries !== null) {
     usageError('--entries is only valid with --prune');
   }
+  if (!args.prune && args.telemetryExplicit) {
+    usageError(
+      '--appended/--boosted/--duration-ms/--skipped/--repo-root are only valid with --prune ' +
+        '(the sweep path never emits orchestrator.evolve.completed)',
+    );
+  }
   return args;
 }
 
@@ -265,6 +335,26 @@ async function runPrune(args) {
     ...result,
   };
 
+  // #1206 — the ONE mechanical call site for `orchestrator.evolve.completed`:
+  // this `--prune --apply` invocation IS `/evolve analyze`'s Step 3.5(5) store
+  // write, so folding the emit in here (instead of a separate
+  // `emit-event.mjs` call in skill prose) means the event can no longer be
+  // forgotten independently of the write it reports on. Gated on `!dryRun` —
+  // a `--prune --dry-run` preview (the docs' own recommended pre-check for a
+  // hand-assembled `--entries` sidecar) never wrote anything, so it must not
+  // report a completed run either. Best-effort — never changes this
+  // command's exit code or stdout contract.
+  if (!args.dryRun) {
+    await emitEvolveCompleted({
+      repoRoot: args.repoRoot,
+      appended: args.appended,
+      boosted: args.boosted,
+      pruned: result.archived,
+      durationMs: args.durationMs,
+      skipped: args.skipped,
+    });
+  }
+
   if (args.json) {
     process.stdout.write(JSON.stringify(summary) + '\n');
   } else {

package/scripts/sync-vault-schema.mjs

@@ -141,7 +141,9 @@ function stripCommentLine(line) {
     return null;
   }
   // Single-line doc comment
-  if (trimmed.startsWith('// ') && !trimmed.startsWith('// ──')) {
+  // A bare `//` (blank line inside a canonical comment run) is a comment too —
+  // without this the generated block carried a stray `//` (measured 2026-09-03).
+  if (trimmed === '//' || (trimmed.startsWith('// ') && !trimmed.startsWith('// ──'))) {
     // Keep structural separator comments, drop narrative ones
     return null;
   }

package/scripts/telemetry.mjs

@@ -33,7 +33,7 @@ import { queueStats } from './lib/telemetry/queue.mjs';
 import { flush, buildBatch } from './lib/telemetry/sync.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
 import { readPluginVersionFromPackageJson } from './lib/bootstrap-lock-freshness.mjs';
-import { SO_PLUGIN_ROOT } from './lib/platform.mjs';
+import { getPluginRoot } from './lib/platform.mjs';
 
 const EXIT_OK = 0;
 const EXIT_USER = 1;
@@ -69,7 +69,7 @@ ENV KILL-SWITCHES
 
 /** Plugin version for `--version` — single-sourced via readPluginVersionFromPackageJson (null → 'unknown'). */
 function readPkgVersion() {
-  return readPluginVersionFromPackageJson(SO_PLUGIN_ROOT) ?? 'unknown';
+  return readPluginVersionFromPackageJson(getPluginRoot()) ?? 'unknown';
 }
 
 // ---------------------------------------------------------------------------

package/scripts/validate-plugin.mjs

@@ -94,6 +94,42 @@ function runCheck(script) {
   return result.status ?? 1;
 }
 
+/**
+ * Advisory second pass for `check-skill-script-paths.mjs` (#1208): run it a
+ * second time with `--strict-sh --json` so the flag has a run surface inside
+ * validate-plugin, without promoting `.sh` findings to blocking here — the
+ * BLOCKING `.mjs`-only call above stays exactly as it is. Same non-blocking
+ * shape as the `check-unwired-features.mjs` / `check-learning-provenance.mjs`
+ * / `check-vcs-repo-flag.mjs` calls further down (exit code deliberately
+ * ignored; `checkFailed` is never set from this call). `runCheck()` cannot be
+ * reused here because it always spawns `[script, PLUGIN_ROOT]` with no room
+ * for extra flags, so this is a small dedicated spawn instead.
+ *
+ * @returns {void}
+ */
+function runStrictShAdvisory() {
+  const result = spawnSync(
+    'node',
+    [path.join(VALIDATE_DIR, 'check-skill-script-paths.mjs'), PLUGIN_ROOT, '--strict-sh', '--json'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout || '');
+  } catch {
+    process.stdout.write(
+      '  WARN: check-skill-script-paths --strict-sh: could not parse JSON output (advisory)\n',
+    );
+    return;
+  }
+  const shDead = (parsed.findings || []).filter(
+    (f) => f.kind === 'missing-path' && f.path.endsWith('.sh'),
+  ).length;
+  process.stdout.write(
+    `  check-skill-script-paths --strict-sh: ${shDead} dead .sh citation(s) (advisory)\n`,
+  );
+}
+
 /**
  * Run the surface-count drift family (issue #663) from the claude-md-drift-check
  * checker over the doc surfaces that carry artifact counts (README.md +
@@ -175,6 +211,105 @@ function runDriftCheck() {
   return 0;
 }
 
+/**
+ * BLOCKING (#1224): the committed hook-reachable allowlist
+ * (`hooks/_lib/hook-import-set.json`) must match a fresh crawl of the four hook
+ * manifests. The allowlist is what gates `hooks/post-edit-import-probe.mjs`, so
+ * a stale set silently NARROWS that probe — a newly hook-reachable module would
+ * be edited without ever being checked, which is precisely the 2026-09-04
+ * host-wide-block incident class the probe exists to catch. A rotting allowlist
+ * is therefore a real defect, not a cosmetic drift, hence FAIL rather than WARN.
+ *
+ * `scripts/generate-hook-import-set.mjs --check` owns the comparison (it exits 1
+ * on drift); this adapter only translates it into validate-plugin's vocabulary.
+ * `runCheck()` cannot be reused — it spawns from `scripts/lib/validate/` and
+ * passes PLUGIN_ROOT positionally, while the generator takes `--plugin-root`.
+ *
+ * @returns {number} 0 when in sync, 1 on drift or a generator error.
+ */
+function runHookImportSetCheck() {
+  console.log('--- Check: hook-import-set drift (#1224) ---');
+  const script = path.join(SCRIPT_DIR, 'generate-hook-import-set.mjs');
+  const result = spawnSync(
+    process.execPath,
+    [script, '--plugin-root', PLUGIN_ROOT, '--check'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const combined = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+
+  // A silent exit 0 is NOT a pass. The generator's CLI entry is gated on
+  // `import.meta.url === file://${process.argv[1]}`, which does not hold when
+  // the spawned path traverses a symlink (measured: `/tmp` → `/private/tmp` on
+  // macOS makes the whole CLI body a no-op that still exits 0). Demanding the
+  // in-sync marker turns that failure mode from a silent pass into a finding.
+  const inSync = combined.match(/(\d+) modules, in sync/);
+  if (result.status === 0 && inSync) {
+    console.log(`  PASS: hook-import-set: in sync (${inSync[1]} entries)`);
+    totalPass += 1;
+    return 0;
+  }
+  if (result.status === 0) {
+    console.log('  FAIL: hook-import-set: generator exited 0 without reporting a comparison '
+      + `(no in-sync marker in output: ${JSON.stringify(combined.slice(0, 120))})`);
+    totalFail += 1;
+    return 1;
+  }
+  const detail = combined.split('\n').filter(Boolean).pop()
+    ?? `generator exited ${result.status}`;
+  console.log(`  FAIL: hook-import-set: ${detail.replace(/^✗\s*hook-import-set:\s*/, '')}`);
+  console.log('        Remedy: node scripts/generate-hook-import-set.mjs && stage hooks/_lib/hook-import-set.json');
+  totalFail += 1;
+  return 1;
+}
+
+/**
+ * BLOCKING: the cross-harness portable surface (`AGENTS.md` +
+ * `.agents/skills/`) must match a fresh generation from `CLAUDE.md` +
+ * `skills/`. 7 of 8 surveyed harnesses read `AGENTS.md` and never `CLAUDE.md`,
+ * so a stale or absent copy means those harnesses silently see NO Session
+ * Config — a failure that is invisible from inside Claude Code, which is
+ * exactly why it needs a mechanical gate rather than a convention.
+ *
+ * `scripts/generate-agents-skills.mjs --check` owns the comparison (exit 1 on
+ * drift); this adapter only translates it. `runCheck()` cannot be reused — it
+ * spawns from `scripts/lib/validate/` and passes PLUGIN_ROOT positionally,
+ * while the generator takes `--plugin-root`. The in-sync marker is demanded
+ * for the same reason `runHookImportSetCheck()` demands one: a spawn whose
+ * path traverses a symlink can make the generator's CLI body a no-op that
+ * still exits 0.
+ *
+ * @returns {number} 0 when in sync, 1 on drift or a generator error.
+ */
+function runAgentsSurfaceCheck() {
+  console.log('--- Check: cross-harness portable surface (AGENTS.md + .agents/skills/) ---');
+  const script = path.join(SCRIPT_DIR, 'generate-agents-skills.mjs');
+  const result = spawnSync(
+    process.execPath,
+    [script, '--plugin-root', PLUGIN_ROOT, '--check'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const combined = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+
+  const inSync = combined.match(/agents-surface: (\d+) artefact\(s\), in sync/);
+  if (result.status === 0 && inSync) {
+    console.log(`  PASS: agents-surface: in sync (${inSync[1]} artefacts)`);
+    totalPass += 1;
+    return 0;
+  }
+  if (result.status === 0) {
+    console.log('  FAIL: agents-surface: generator exited 0 without reporting a comparison '
+      + `(no in-sync marker in output: ${JSON.stringify(combined.slice(0, 120))})`);
+    totalFail += 1;
+    return 1;
+  }
+  for (const line of combined.split('\n').filter((l) => l.startsWith('✗'))) {
+    console.log(`  FAIL: ${line.replace(/^✗\s*/, '')}`);
+    totalFail += 1;
+  }
+  console.log('        Remedy: node scripts/generate-agents-skills.mjs');
+  return 1;
+}
+
 // ---------------------------------------------------------------------------
 // Run all checks — same order as validate-plugin.sh
 // plugin.json checks are prerequisite; abort early if they fail.
@@ -220,6 +355,9 @@ if (runDriftCheck() !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-hooks-symmetry.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runHookImportSetCheck() !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-guard-requires-parity.mjs') !== 0) checkFailed = 1;
 
@@ -238,6 +376,9 @@ if (runCheck('check-path-utils-canary.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-codex-plugin.mjs') !== 0) checkFailed = 1;
 
+process.stdout.write('\n');
+if (runCheck('check-codex-skills.mjs') !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-pi-package.mjs') !== 0) checkFailed = 1;
 
@@ -247,6 +388,18 @@ if (runCheck('check-pi-prompts.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-cursor-adapter.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING: the vendor-neutral portable surface — root AGENTS.md ↔ CLAUDE.md
+// alias, root plugin.json (agent-plugins.org 1.0.0) manifest-version parity
+// against package.json, and the .agents/skills/ mirror against the
+// agentskills.io field list. The generator's own --check runs first (below);
+// this checker is the INDEPENDENT oracle over the same artefacts, so a
+// generator bug cannot vouch for its own output.
+process.stdout.write('\n');
+if (runCheck('check-agents-skills.mjs') !== 0) checkFailed = 1;
+
+process.stdout.write('\n');
+if (runAgentsSurfaceCheck() !== 0) checkFailed = 1;
+
 process.stdout.write('\n');
 if (runCheck('check-session-plan-routing.mjs') !== 0) checkFailed = 1;
 
@@ -327,6 +480,17 @@ runCheck('check-doc-cli-commands.mjs');
 // citation's own line or the line immediately above.
 process.stdout.write('\n');
 if (runCheck('check-skill-script-paths.mjs') !== 0) checkFailed = 1;
+runStrictShAdvisory();
+
+// BLOCKING (#1157 follow-up): a relative markdown link under skills/, commands/,
+// agents/ or .claude/rules/ that does not resolve from the LINKING file's own
+// directory. The check above judges cited SCRIPT paths; this one judges links
+// between the instruction files themselves — the defect class a `references/`
+// split creates, where the moved text is byte-identical and every `./sibling.md`
+// in it now points one directory too deep. Three such links shipped broken on
+// 2026-09-06 and no gate saw them; the worst silently detached the six
+// session-end tail phases from their dispatcher.
+if (runCheck('check-skill-links.mjs') !== 0) checkFailed = 1;
 
 // WARN-only: a state-mutating `git` call in tests/ that names no target resolves
 // its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19

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/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)