session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/rules-sync.mjs

@@ -3,26 +3,37 @@
  * Syncs canonical rules from the plugin's rules/ library into a consumer repo's .claude/rules/.
  *
  * Stdlib-only, cross-platform, no Zod, no third-party parsers. ESM module.
- * Preserves local rules (files without the plugin source header).
+ * Preserves local rules — files carrying the plugin provenance header in
+ * neither accepted position (see `isPluginOwnedContent`).
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { validateRuleContent, scanVendoringLeaks } from './validate-vendored-rules.mjs';
+import {
+  validateRuleContent,
+  scanVendoringLeaks,
+  isPluginOwnedContent,
+} from './validate-vendored-rules.mjs';
 import { isMainModule } from './is-main-module.mjs';
 
 // The vendoring sanitizer (issue #1098) lives in validate-vendored-rules.mjs —
 // it has that module's shape ("judge one rule file → findings") and its
 // standalone CLI needs it too. Re-exported here so importers that predate the
 // move (and this file's own tests) keep resolving it from rules-sync.mjs.
-export { scanVendoringLeaks };
+//
+// isPluginOwnedContent (#1449) — the ownership predicate below — lives there
+// for the same reason as PLUGIN_HEADER_PREFIX's copy: this module imports
+// validate-vendored-rules.mjs, so defining it here and importing it back into
+// the validator's provenance probe would make the two modules import each
+// other. Re-exported so the ownership rule is reachable from the sync module.
+export { scanVendoringLeaks, isPluginOwnedContent };
 
 // Exported (issue #722 Epic A Wave 2) for external consumers (e.g. tests).
-// NOT imported by validate-vendored-rules.mjs — that module imports
-// validateRuleContent FROM this file (see the pre-write gate below), so
-// importing this constant back would create a module-load cycle; it keeps
-// its own textually-identical copy instead.
+// NOT imported by validate-vendored-rules.mjs — this module imports
+// validateRuleContent FROM that file (see the pre-write gate below), so
+// importing this constant back there would create a module-load cycle; it
+// keeps its own textually-identical copy instead.
 export const PLUGIN_HEADER_PREFIX = '<!-- source: session-orchestrator plugin';
 
 /**
@@ -170,8 +181,9 @@ function escapeRegex(s) {
  *
  * When `validate` is true (the default — issue #722 Epic A Wave 2),
  * validateRuleContent() runs as a pre-write gate on every source file before
- * it is copied. A file with any error-severity violation (paths-frontmatter,
- * missing provenance header, unfilled placeholder) is recorded in `errors[]`
+ * it is copied. A file with any error-severity violation (frontmatter-not-at-top,
+ * globs-paths-mismatch, missing provenance header, unfilled placeholder) is
+ * recorded in `errors[]`
  * and its write is skipped entirely — it is never added to
  * written/skipped/preserved. Warn-severity violations (zero-match-globs,
  * foreign-glob) do NOT block the write; they are collected into the
@@ -405,9 +417,12 @@ export function syncRules({
         continue;
       }
 
-      const firstLine = targetContent.split('\n')[0] ?? '';
-      if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
-        // Local file — preserve it
+      // Ownership accepts BOTH header positions (#1449): line 1 (the format
+      // every copy vendored before #1449 carries, frontmatter or not) and the
+      // first non-blank line after a line-1 frontmatter (the current format).
+      // So an old-format copy is rewritten into the new format below, never
+      // preserved; only a file with no header in either position is local.
+      if (!isPluginOwnedContent(targetContent)) {
         preserved.push(fileName);
         continue;
       }

package/scripts/lib/scope-baseline.mjs

@@ -141,8 +141,11 @@ import { resolveBaselineRange, isQueryFailure } from './vcs-repo-spec.mjs';
 // F1 bug this filter exists to prevent — a caller could hand
 // `writeBaseline()` an unfiltered count with no `filterExcluded()` pass at
 // all). `computeDrift()` filters the numerator at measure time by running
-// the live `git diff --name-only` output through the same
-// `filterExcluded()` helper.
+// the live change set (committed range ∪ working tree ∪ untracked, see its
+// JSDoc) through the same `filterExcluded()` helper. One classification sits
+// OUTSIDE this list on purpose: untracked paths under `.orchestrator/` (see
+// `isUntrackedRuntimeWrite()` below) — it keys on tracked status, which only
+// the live numerator has, so a pattern here could not express it.
 // Deliberately narrows skills/session-end/plan-verification.md:42-45's
 // per-session-state exclusion from "the whole .claude/ directory" down to
 // just the session ARTEFACTS — `.claude/rules/**` stays COUNTED because a
@@ -165,6 +168,24 @@ export const DRIFT_EXCLUDE_PATTERNS = [
   '.codex/STATE.md', '.codex/wave-scope.json', '.codex/metrics/**',
   '.cursor/STATE.md', '.cursor/wave-scope.json', '.cursor/metrics/**',
   '.pi/STATE.md', '.pi/wave-scope.json', '.pi/metrics/**',
+  // The plugin's OWN mid-session writes. They only became visible to the
+  // numerator when it started reading the working tree and untracked files
+  // (#1027). Two classes are excluded HERE, whatever their tracked status:
+  //   - `.orchestrator/metrics/**` — a consumer repo keeps its `*.jsonl`
+  //     TRACKED by design (skills/bootstrap/standard-template.md "Gitignore
+  //     guidance") and hooks append to it all session.
+  //   - `<state-dir>/filescopes/**` and `<state-dir>/worktrees/**` — bootstrap
+  //     writes no ignore line for either. An agent worktree is a nested repo,
+  //     so `ls-files --others` lists each as ONE `.claude/worktrees/<id>/`
+  //     entry (measured 2026-10-02): one false file per isolated agent.
+  // Every OTHER plugin write under `.orchestrator/` (runtime/, tmp/, debug/,
+  // session.lock, current-session.json, ...) is excluded by
+  // `isUntrackedRuntimeWrite()` while untracked, which is how a consumer repo
+  // holds them. Its deliverables (`steering/`, `policy/`, `bootstrap.lock`)
+  // are tracked and count.
+  '.claude/filescopes/**', '.codex/filescopes/**', '.cursor/filescopes/**', '.pi/filescopes/**',
+  '.claude/worktrees/**', '.codex/worktrees/**', '.cursor/worktrees/**', '.pi/worktrees/**',
+  '.orchestrator/metrics/**',
 ];
 
 // ---------------------------------------------------------------------------
@@ -218,6 +239,38 @@ function filterExcluded(files) {
   );
 }
 
+/**
+ * Is this UNTRACKED path the plugin's own runtime output? Same rule as
+ * `isOwnRuntimeArtifact()` in scripts/lib/project-hygiene.mjs (untracked
+ * under `.orchestrator/` = ours), mirrored rather than imported: it is not
+ * exported, and importing that module would pull js-yaml and the command
+ * blocker into this one for a one-line prefix test. Applied to the
+ * `ls-files --others` source only — a tracked `.orchestrator/` file is a
+ * deliverable or a ledger, and `DRIFT_EXCLUDE_PATTERNS` decides which.
+ *
+ * Ceiling (BV-004): a runtime file a consumer has COMMITTED (e.g. a
+ * `session.lock` swept in by `git add -A`) counts whenever the plugin
+ * rewrites it, and a NEW `steering/`/`policy/` file counts only once it is
+ * tracked. Revisit if a drift WARN traces to a tracked runtime file, or a
+ * missed WARN to an uncommitted steering/policy deliverable.
+ *
+ * @param {string} file repo-root-relative path from `git ls-files --others`
+ * @returns {boolean}
+ */
+function isUntrackedRuntimeWrite(file) {
+  return file.startsWith('.orchestrator/');
+}
+
+/** Split git `--name-only`/`ls-files` stdout into trimmed non-empty paths. */
+function outputPaths(stdout) {
+  return stdout.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+// Per-query bound for the three numerator git calls — the same 10 s that
+// scripts/lib/project-hygiene.mjs gives its read-only git queries. A timeout
+// throws like any other failure and lands in the same skip.
+const DRIFT_GIT_TIMEOUT_MS = 10_000;
+
 /**
  * Internal: read + parse STATE.md's frontmatter exactly once. Shared by
  * `readBaseline()` and `computeDrift()` so a single `computeDrift()` call
@@ -464,13 +517,38 @@ export async function writeBaseline({ repoRoot, intent, ownerBoundary, plannedFi
 }
 
 /**
- * Compute the S2 warn-only scope-drift ratio: how many files have actually
- * changed since the session's frozen `session-start-ref`, filtered through
+ * Compute the S2 warn-only scope-drift ratio: how many files differ in this
+ * checkout — committed since the session's frozen `session-start-ref`, plus
+ * whatever is uncommitted or untracked right now — filtered through
  * `DRIFT_EXCLUDE_PATTERNS`, against the `plannedFiles` count frozen by
  * `writeBaseline()`. Sync (`readFileSync` + `execFileSync('git', ...)`
  * only). Never throws, never denies — this is a WARN-only tripwire; the
  * CALLER decides whether/how to surface `breached`.
  *
+ * Numerator (#1027): the deduplicated union of three git queries — the
+ * committed range diff, the working tree against HEAD (staged + unstaged),
+ * and untracked files (`ls-files --others --exclude-standard`, minus the
+ * plugin's own untracked `.orchestrator/` writes, see
+ * `isUntrackedRuntimeWrite()`). Until #1027 only the first was read, so
+ * uncommitted edits and every NEW module — the typical shape of an
+ * overshoot — were invisible until someone committed them. All three must
+ * succeed: if any fails (including ENOBUFS and the per-query timeout) the
+ * result is the `unresolvable-ref` skip, never a ratio over a partial
+ * numerator. That reason is deliberately not split by cause: its readers
+ * (skills/wave-executor/references/wave-loop-review.md step 7a,
+ * skills/session-end/plan-verification.md step 5) render every skip
+ * silently or verbatim and none branches on it.
+ *
+ * Named ceiling (BV-004) — over-report: only the committed source is tied to
+ * `session-start-ref`. The working-tree and untracked sources read the
+ * checkout as it is NOW, so a file that was already dirty when the session
+ * started, and a same-checkout peer session's files, count as this session's
+ * drift. Fixing it means persisting a start-dirty snapshot at freeze time and
+ * subtracting it — a storage change, out of scope for this warn-only
+ * tripwire. Revisit if a drift WARN traces to pre-session dirt or to a
+ * peer's files (`git status` at session start shows the former,
+ * PSA-001 signals the latter).
+ *
  * Skip precedence (first match wins, so `reason` is deterministic):
  *   `no-state-md` → `unreadable-state-md` → `no-baseline` →
  *   `stale-baseline` → (`no-baseline-ref` | `unresolvable-ref`)
@@ -509,13 +587,14 @@ export async function writeBaseline({ repoRoot, intent, ownerBoundary, plannedFi
  *
  * Named ceiling (BV-004) on the local-branch tail of the resolution chain:
  * when the chain lands on a LOCAL `main`/`master` and HEAD is already that
- * branch, `main...HEAD` has merge-base === HEAD and the diff is empty, so
- * the ratio reads `0` instead of skipping. That is the honest floor of the
- * available information (no remote-tracking ref exists to say where the
- * session started) and it is harmless here because both a `0` ratio and a
- * skip are silent under `wave-loop.md`'s WARN-on-breach rule. Revisit if
- * this function ever gains a non-warn consumer that treats `skipped:false`
- * as "measured successfully".
+ * branch, `main...HEAD` has merge-base === HEAD and the COMMITTED source is
+ * empty, so the session's commits are invisible and the ratio counts only
+ * the uncommitted and untracked files instead of skipping. That is the
+ * honest floor of the available information (no remote-tracking ref exists
+ * to say where the session started); it can only under-report, and an
+ * under-report is as silent as a skip under `wave-loop-review.md`'s
+ * WARN-on-breach rule. Revisit if this function ever gains a non-warn
+ * consumer that treats `skipped:false` as "measured successfully".
  *
  * @param {object} args
  * @param {string|undefined} args.repoRoot
@@ -578,36 +657,47 @@ export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
     refUsed = resolved.range;
   }
 
-  let stdout;
+  // Untracked files can be numerous, so the 1 MiB default buffer would turn
+  // a large tree into an ENOBUFS skip.
+  const gitOpts = { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: DRIFT_GIT_TIMEOUT_MS };
+  const changedFiles = new Set();
   try {
-    stdout = execFileSync('git', ['diff', '--name-only', diffRange], { cwd, encoding: 'utf8' });
+    const committed = execFileSync('git', ['diff', '--name-only', diffRange], gitOpts);
+    const workingTree = execFileSync('git', ['diff', '--name-only', 'HEAD'], gitOpts);
+    // `--full-name` + `:/` keep these paths in the same repo-root-relative
+    // space as `git diff --name-only`, even if `cwd` is a subdirectory.
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '--full-name', '--', ':/'], gitOpts);
+    for (const file of [...outputPaths(committed), ...outputPaths(workingTree)]) changedFiles.add(file);
+    for (const file of outputPaths(untracked)) {
+      if (!isUntrackedRuntimeWrite(file)) changedFiles.add(file);
+    }
   } catch {
-    // The range resolved but the diff against it failed — a present-but-dead
-    // `session-start-ref` (rebase, force-push, deleted commit), or a
-    // resolved base that vanished between resolution and diff. Neither can
-    // produce a trustworthy numerator.
+    // The range resolved but a numerator query failed — a present-but-dead
+    // `session-start-ref` (rebase, force-push, deleted commit), a resolved
+    // base that vanished between resolution and diff, a working-tree or
+    // untracked query git could not answer, output over `maxBuffer`
+    // (ENOBUFS), or a query past `DRIFT_GIT_TIMEOUT_MS`. None can produce a
+    // trustworthy numerator, and a partial one must not be reported as
+    // measured. All share `unresolvable-ref`: every reader renders a skip
+    // silently and none branches on the reason (census in the JSDoc above).
     return { ok: true, skipped: true, reason: 'unresolvable-ref' };
   }
 
-  const changedFiles = stdout
-    .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
-
   // Same `filterExcluded()` primitive `writeBaseline()`'s denominator
-  // (`countPlannedFiles()`) calls (#894 review finding F1) — both sides of
-  // the ratio are provably produced by one function.
-  const actualFiles = filterExcluded(changedFiles).length;
+  // (`countPlannedFiles()`) calls (#894 review finding F1), so the pattern
+  // filter on both sides of the ratio is one function. The untracked
+  // `.orchestrator/` rule above is numerator-only by construction: a planned
+  // path carries no tracked status to test.
+  const actualFiles = filterExcluded([...changedFiles]).length;
 
   const plannedFilesRaw = baseline.plannedFiles;
   const plannedFiles = typeof plannedFilesRaw === 'number' && Number.isFinite(plannedFilesRaw)
     ? plannedFilesRaw
     : 0;
 
-  // Mirrors the existing over_delivery_ratio div-by-zero guard in
-  // skills/wave-executor/wave-loop.md (`files_changed / max(planned_files_count, 1)`,
-  // in the per-wave metrics section). Deliberately un-line-pinned: that file is
-  // edited often enough that a pinned number goes stale, as this very comment did.
+  // Division-by-zero guard: a baseline that froze zero planned files (no declared
+  // file scope, or a non-numeric count coerced to 0 above) would otherwise yield
+  // Infinity or NaN; `max(plannedFiles, 1)` keeps the ratio finite and comparable.
   const filesRatio = round2(actualFiles / Math.max(plannedFiles, 1));
   const breached = filesRatio >= threshold;
 

package/scripts/lib/scope-echo.mjs

@@ -51,6 +51,7 @@ import { join, resolve } from 'node:path';
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
 import { isMainModule } from './is-main-module.mjs';
+import { isCoordinatorRecordId } from './scope-gate.mjs';
 
 /** Marker the agent must emit. Case-sensitive by design — a lowercase lookalike is not an echo. */
 export const SCOPE_ECHO_MARKER = 'SCOPE-DIGEST:';
@@ -329,6 +330,11 @@ function parseJsonl(raw) {
  * only iterates the entries is unaffected. (A file that parses to a non-array or
  * to an empty scope stays a silent skip: an empty scope is legitimate.)
  *
+ * `coordinator.json` is skipped too (#1493.2): the coordinator's planned direct
+ * edits are a declaration, never a dispatch, so no injection or echo can ever
+ * claim its digest — digesting it reported the coordinator's own scope as
+ * `injection-missing` on every wave where it planned an edit.
+ *
  * @param {string} stateDir
  * @param {number} wave
  * @param {{readDir?: typeof readdirSync, readFile?: typeof readFileSync}} [io]
@@ -347,6 +353,7 @@ export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFi
   for (const name of names) {
     const file = typeof name === 'string' ? name : name?.name;
     if (typeof file !== 'string' || !file.endsWith('.json')) continue;
+    if (isCoordinatorRecordId(file.slice(0, -'.json'.length))) continue;
     let parsed;
     try {
       parsed = JSON.parse(readFile(join(dir, file), 'utf8'));

package/scripts/lib/scope-gate.mjs

@@ -16,6 +16,9 @@ import path from 'node:path';
 
 import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
 
+/** The harness state dirs a `wave-scope.json` may live in, highest precedence first. */
+const SCOPE_FILE_DIRS = Object.freeze(['.pi', '.cursor', '.codex', '.claude']);
+
 /**
  * Find the wave-scope.json file for the given project root.
  *
@@ -28,11 +31,12 @@ import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './comma
  * Returns the absolute path string, or null if none exist.
  * Sync (uses fs.existsSync).
  *
+ * @deprecated Use findOwnScopeFile because first-file selection ignores manifest ownership and can select a peer session's manifest.
  * @param {string} projectRoot — absolute path to project root
  * @returns {string|null}
  */
 export function findScopeFile(projectRoot) {
-  for (const dir of ['.pi', '.cursor', '.codex', '.claude']) {
+  for (const dir of SCOPE_FILE_DIRS) {
     const candidate = path.join(projectRoot, dir, 'wave-scope.json');
     if (existsSync(candidate)) {
       return candidate;
@@ -41,6 +45,67 @@ export function findScopeFile(projectRoot) {
   return null;
 }
 
+/**
+ * The manifest that governs THIS session: walk the {@link findScopeFile}
+ * precedence (`.pi` > `.cursor` > `.codex` > `.claude`) and return the first
+ * candidate that is NOT provably bound to another session (#1504 point 6).
+ *
+ * `findScopeFile` stops at the first file that EXISTS. When that file is a
+ * peer's — another harness session's manifest in the same working copy — every
+ * guard that stands down on a foreign manifest stood down, and this session's
+ * own `.claude/wave-scope.json` one rung lower was never read: a peer's
+ * manifest switched this session's scope gates off.
+ *
+ * Disposition per candidate, decided INSIDE the loop (an identity check after
+ * the loop makes the first readable candidate the veto-holder —
+ * `.claude/rules/identity-and-locks.md`):
+ *   - `'own'` or `'unknown'` → return it. `'unknown'` covers an unbound/legacy
+ *     manifest, a corrupt or unreadable one (judged as `{}`), and an empty
+ *     `ownIds` (a harness that supplies no session id). Each means ENFORCE
+ *     under the binding contract, so each stays the decider exactly as under
+ *     `findScopeFile` — a truncated manifest cannot skip itself.
+ *   - `'foreign'` → remember the first one and `continue`.
+ *
+ * When EVERY existing candidate is foreign, `path` is null and `foreignPath`
+ * names the first of them, so the caller reaches its existing foreign
+ * disposition (allow + `orchestrator.scope.foreign_session_ignored`) unchanged.
+ *
+ * `classify` is injected, not imported: importing the identity module here
+ * would add it to the import closure of every hook that reaches this file
+ * through the `hardening.mjs` barrel, while only the guards that stand down on
+ * a foreign manifest need it — and each of them already binds it. Pass
+ * `classifyManifestSession` from `session-identity/own-session.mjs`.
+ *
+ * COST: identical to `findScopeFile` when no manifest exists (≤4 `existsSync`).
+ * With one, one extra sync read + parse of that small file. The caller still
+ * reads the returned file itself and classifies THAT read, so a rebind between
+ * the two reads is judged at the same decision point as before.
+ *
+ * Sync. Never throws (unless `classify` does).
+ *
+ * @param {string} projectRoot absolute path to the project root
+ * @param {Set<string>} ownIds process-local own ids (`readProcessLocalSessionIds`)
+ * @param {(scope: object, ownIds: Set<string>) => { verdict: string }} classify
+ * @returns {{ path: string|null, foreignPath: string|null }}
+ */
+export function findOwnScopeFile(projectRoot, ownIds, classify) {
+  let foreignPath = null;
+  for (const dir of SCOPE_FILE_DIRS) {
+    const candidate = path.join(projectRoot, dir, 'wave-scope.json');
+    if (!existsSync(candidate)) continue;
+    let scope = {};
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) scope = parsed;
+    } catch {
+      // unreadable / corrupt → `{}` → no binding → 'unknown' → this candidate decides
+    }
+    if (classify(scope, ownIds).verdict !== 'foreign') return { path: candidate, foreignPath };
+    foreignPath ??= candidate;
+  }
+  return { path: null, foreignPath };
+}
+
 /**
  * Read the enforcement level from a scope file.
  * Defaults to "strict" (fail-closed) on parse error or missing field.
@@ -190,7 +255,8 @@ function literalScopePrefix(entry) {
  * verbatim presence + literal-prefix coverage; it does not prove that e.g.
  * `src/**\/*.ts` ⊆ `src/**\/*.js` is false. The concrete-path branch above is
  * exact and carries the incident-relevant load (the union the coordinator
- * actually writes is verbatim, deduplicated agent scopes). Erring toward
+ * actually writes is the deduplicated agent scopes in canonical spelling, see
+ * {@link unionFileScopes}). Erring toward
  * over-approximating coverage keeps a legitimate union from being rejected on a
  * glob technicality rather than pretending to a precision this matcher lacks.
  *
@@ -211,16 +277,21 @@ export function assertFileScopeSubset(fileScope, allowedPaths) {
   const missing = [];
   for (const entry of fileScope) {
     if (typeof entry !== 'string' || entry.length === 0) continue;
+    // The AGENT side is compared in canonical spelling — the spelling the union
+    // emits and the write path Gate 7 matches. `allowedPaths` stays as written:
+    // a hand-written `./x` there is a pattern Gate 7 cannot match, and spelling
+    // it away here would report coverage the hook then denies.
+    const spelled = scopeEntrySpelling(entry);
     let covered;
-    if (isGlobScopeEntry(entry)) {
+    if (isGlobScopeEntry(spelled)) {
       // GLOB entry: verbatim presence OR literal-prefix coverage.
-      const prefix = literalScopePrefix(entry);
-      covered = allowedPaths.some((p) => p === entry || pathMatchesPattern(prefix, p));
+      const prefix = literalScopePrefix(spelled);
+      covered = allowedPaths.some((p) => p === spelled || pathMatchesPattern(prefix, p));
     } else {
       // CONCRETE entry: must match ≥1 allowedPaths pattern.
-      covered = allowedPaths.some((p) => pathMatchesPattern(entry, p));
+      covered = allowedPaths.some((p) => pathMatchesPattern(spelled, p));
     }
-    if (!covered) missing.push(entry);
+    if (!covered) missing.push(entry); // as declared, so the plan entry is findable
   }
   return { ok: missing.length === 0, missing };
 }
@@ -329,13 +400,16 @@ export function testSiblingExpansionApplies(opts = {}) {
  *
  * ## Why a GLOB and not a computed path
  * The emitted sibling is `tests/**\/{basename}*.test.mjs`, never a concrete
- * path. Measured over all 430 tracked production `.mjs` in this repo:
- * a naive 1:1 mirror (`scripts/lib/X.mjs → tests/lib/X.test.mjs`) is right
- * 301/430 = 70.0% (`hooks/_lib` 0/5, `scripts/ci/` 0/1); a same-basename test
- * ANYWHERE under `tests/` is right 368/430 = 85.6%. The glob takes the 85.6%
- * form, and its failure mode is HARMLESS — it grants write access to files that
- * may not exist. A computed concrete path is wrong 30% of the time AND still
- * denies the real test, which is the original bug wearing a new face.
+ * path: a same-basename test ANYWHERE under `tests/` resolves for far more
+ * production files than a naive 1:1 mirror (`scripts/lib/X.mjs →
+ * tests/lib/X.test.mjs`). The DATED figures — population, both ratios, the
+ * measuring command and the SHA — live in ONE place:
+ * skills/wave-executor/references/wave-loop-scope-manifest.md § Test-Sibling
+ * Expansion (#970). Cite and re-measure them there, never restate them here: an
+ * undated copy drifted to a second, contradicting set of numbers (#1026.5,
+ * PSA-006 item 4). The glob's failure mode is HARMLESS — it grants write access
+ * to files that may not exist. A computed concrete path is wrong more often AND
+ * still denies the real test, which is the original bug wearing a new face.
  *
  * ## Required behaviours (each is a nameable regression)
  *  1. `[]` → `[]` STRUCTURALLY. Discovery waves use an empty scope as a
@@ -403,8 +477,11 @@ export function testSiblingsFor(entries, opts = {}) {
     : DEFAULT_TEST_PATH_PATTERNS;
   const out = [];
   const seen = new Set();
-  for (const entry of Array.isArray(entries) ? entries : []) {
-    if (typeof entry !== 'string' || entry.length === 0) continue;
+  for (const declared of Array.isArray(entries) ? entries : []) {
+    if (typeof declared !== 'string' || declared.length === 0) continue;
+    // Canonical spelling, as the union carries it: a verbatim `./tests/x.mjs`
+    // misses `tests/**` and would be mirrored as if it were production code.
+    const entry = scopeEntrySpelling(declared);
     if (path.isAbsolute(entry)) continue; // behaviour 3
     if (isGlobScopeEntry(entry)) continue; // no single basename to mirror
     if (isTestPathEntry(entry, testPatterns)) continue; // behaviours 2 + 4
@@ -940,6 +1017,53 @@ export function isPeerRecordId(id) {
   return typeof id === 'string' && id.startsWith(PEER_RECORD_PREFIX);
 }
 
+/**
+ * Record id of the COORDINATOR's own planned direct edits (#1020): one
+ * `{id: 'coordinator', files}` record in a wave's aggregate sidecar, and
+ * `<state-dir>/filescopes/wave-<N>/coordinator.json` in the per-agent shape.
+ * Exactly lowercase — `materialize-wave-scope.mjs` rejects any other casing.
+ *
+ * The coordinator is a declarant but never a DISPATCH: no `FILE-SCOPE` block is
+ * injected for it, no digest is echoed back, no agent is counted for it. Every
+ * consumer that joins scope files against dispatches must skip it, or it reports
+ * the coordinator's own scope as an omitted injection (#1493.2). SSOT beside
+ * {@link PEER_RECORD_PREFIX} for the same reason that one lives here.
+ */
+export const COORDINATOR_RECORD_ID = 'coordinator';
+
+/**
+ * Is this record id the coordinator's (see {@link COORDINATOR_RECORD_ID})?
+ * Exact match; a non-string id is not the coordinator.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isCoordinatorRecordId(id) {
+  return id === COORDINATOR_RECORD_ID;
+}
+
+/**
+ * Is this repo-relative path inside a wave's per-agent scope declarations,
+ * `<state-dir>/filescopes/` (shape (a) and the aggregate sidecar, #1020)?
+ *
+ * Those files are coordinator CONTROL STATE like `wave-scope.json` itself,
+ * written by `materialize-wave-scope.mjs` once per wave — never a wave
+ * territory, so a write there is not a scope violation (#1027 Pkt 5). The
+ * caller passes the manifest's own repo-relative path, so the state dir is the
+ * one THIS manifest lives in, never a guessed `.claude/`.
+ *
+ * @param {string} relPath repo-relative, forward slashes
+ * @param {string} scopeRelPath repo-relative path of the active `wave-scope.json`
+ * @returns {boolean}
+ */
+export function isScopeDeclarationPath(relPath, scopeRelPath) {
+  if (typeof relPath !== 'string' || typeof scopeRelPath !== 'string') return false;
+  const scopeRel = scopeRelPath.replace(/\\/g, '/');
+  const cut = scopeRel.lastIndexOf('/');
+  if (cut <= 0) return false;
+  return relPath.startsWith(`${scopeRel.slice(0, cut)}/filescopes/`);
+}
+
 /**
  * Merge many agents' declared file scopes into ONE deduplicated, order-stable
  * list — the mechanical form of "allowedPaths is the UNION of all agent file
@@ -965,6 +1089,14 @@ export function isPeerRecordId(id) {
  * non-array / non-object members and non-string, empty entries are skipped.
  * Pure, sync, no I/O — hook-safe per the module header.
  *
+ * ENTRIES ARE EMITTED IN CANONICAL SPELLING ({@link scopeEntrySpelling}) and
+ * deduplicated on it. Gate 7 matches the repo-relative WRITE path against each
+ * entry, so a verbatim `./scripts/lib/foo.mjs` was a pattern no write could
+ * ever match — the declaring agent's own write was denied — and kept a second
+ * spelling of `scripts/lib/foo.mjs` beside it. The agent-side checks
+ * ({@link assertFileScopeSubset}, {@link testSiblingsFor}) compare the same
+ * spelling, so a per-agent file that keeps the plan's `./x` still passes.
+ *
  * PEER RECORDS ARE EXCLUDED (#1195 follow-through). A record whose id starts
  * with `peer-session-` declares a territory NO agent of this wave may write —
  * it exists so a peer's paths take part in the DISJOINTNESS check and so
@@ -995,9 +1127,10 @@ export function unionFileScopes(scopes) {
     if (files === null) continue;
     for (const entry of files) {
       if (typeof entry !== 'string' || entry.length === 0) continue;
-      if (seen.has(entry)) continue;
-      seen.add(entry);
-      out.push(entry);
+      const spelled = scopeEntrySpelling(entry);
+      if (seen.has(spelled)) continue;
+      seen.add(spelled);
+      out.push(spelled);
     }
   }
   return out;
@@ -1122,8 +1255,11 @@ function globsDisagreeOnLiteralSegment(x, y) {
  * NEGATIVE — the whole point of this function is that an unreviewed scope is
  * exactly the one that collides.
  *
+ * `files` holds each entry's comparison SPELLING ({@link scopeEntrySpelling});
+ * `declared` holds the entry as written, index-aligned, for the evidence report.
+ *
  * @param {Array<{id?: string, files?: string[]}>} agentScopes
- * @returns {Array<{id: string, declaredId: string|null, files: string[]}>}
+ * @returns {Array<{id: string, declaredId: string|null, files: string[], declared: string[]}>}
  */
 function normalizeAgentScopes(agentScopes) {
   const out = [];
@@ -1131,14 +1267,43 @@ function normalizeAgentScopes(agentScopes) {
     const raw = agentScopes[i];
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) continue;
     const declaredId = typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : null;
-    const files = Array.isArray(raw.files)
+    const declared = Array.isArray(raw.files)
       ? raw.files.filter((f) => typeof f === 'string' && f.length > 0)
       : [];
-    out.push({ id: declaredId ?? `<unnamed#${i}>`, declaredId, files });
+    const files = declared.map(scopeEntrySpelling);
+    out.push({ id: declaredId ?? `<unnamed#${i}>`, declaredId, files, declared });
   }
   return out;
 }
 
+/**
+ * One scope entry's canonical SPELLING — THE spelling rule of this module.
+ * Used by the collision comparison (#1026.3), by {@link unionFileScopes} (whose
+ * output IS `allowedPaths`, so Gate 7 sees this spelling), and on the agent side
+ * of {@link assertFileScopeSubset} / {@link testSiblingsFor}, so a per-agent file
+ * that keeps the plan's declaration verbatim still agrees with the union.
+ * Equal-meaning spellings compared unequal before: `./scripts/lib/foo.mjs` vs
+ * `scripts/lib/foo.mjs` was reported disjoint (measured 2026-10-03 @ 8292050e).
+ * It changes no grant's MEANING — only how one is spelled.
+ *
+ * Collapses runs of `/` and drops `.` segments (`./a`, `a/./b`). A leading `/`
+ * (absolute entry) and a trailing `/` survive: the trailing slash is meaning,
+ * not spelling — `scripts/lib/` is a prefix grant, while `scripts/lib` grants
+ * only the literal path `scripts/lib` (`pathMatchesPattern('scripts/lib/foo.mjs',
+ * 'scripts/lib') === false`), so those two stay disjoint.
+ *
+ * NAMED CEILING: `..` segments are left alone — `a/../b` is not provably `b`
+ * when `a` is a glob segment. Revisit if a plan ever declares a `..` entry.
+ *
+ * @param {string} entry - a non-empty scope entry
+ * @returns {string}
+ */
+function scopeEntrySpelling(entry) {
+  const spelled = entry.replace(/\/{2,}/g, '/').replace(/(^|\/)(?:\.\/)+/g, '$1');
+  // `./` alone would spell as '' — keep the entry rather than invent a meaning.
+  return spelled.length > 0 ? spelled : entry;
+}
+
 /**
  * Classify a SINGLE cross-agent entry pair, in the binding three-stage order.
  * Returns the collision `kind`, or `null` when the two entries are disjoint.
@@ -1316,17 +1481,19 @@ export function findScopeCollisions(agentScopes, opts = {}) {
       const b = agents[j];
       if (a.id === b.id) continue; // duplicate-id record: reported separately
       const buckets = new Map();
-      for (const x of a.files) {
-        for (const y of b.files) {
-          const kind = classifyEntryCollision(x, y, expand);
+      // Classify on the comparison spelling; report the entry AS DECLARED, so
+      // the operator can find it in the plan (#1026.3).
+      for (let xi = 0; xi < a.files.length; xi++) {
+        for (let yi = 0; yi < b.files.length; yi++) {
+          const kind = classifyEntryCollision(a.files[xi], b.files[yi], expand);
           if (kind === null) continue;
           let evidence = buckets.get(kind);
           if (evidence === undefined) {
             evidence = new Set();
             buckets.set(kind, evidence);
           }
-          evidence.add(x);
-          evidence.add(y);
+          evidence.add(a.declared[xi]);
+          evidence.add(b.declared[yi]);
         }
       }
       for (const kind of KIND_ORDER) {