session-orchestrator 5.4.0 → 5.5.0

package/scripts/lib/platform.mjs

@@ -8,12 +8,12 @@
  *   - plain constants (no filesystem work): SO_SHARED_DIR, SO_OS, SO_IS_WINDOWS,
  *     SO_IS_WSL, SO_PATH_SEP
  *   - pure resolvers: detectPlatform, resolvePluginRoot, resolveProjectDir,
- *     resolveStateDir, resolveConfigFile
+ *     resolveSessionRoot, resolveStateDir, resolveConfigFile
  *
  * NOTHING in this module touches the filesystem at import time.
  */
 
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
@@ -249,6 +249,210 @@ export function resolveProjectDir(platform) {
   return cwd;
 }
 
+// ---------------------------------------------------------------------------
+// resolveSessionRoot (#1492)
+// ---------------------------------------------------------------------------
+
+/**
+ * Basename of a worktree the HARNESS creates for an `isolation: "worktree"`
+ * subagent: `agent-` + the agent id. Measured 2026-10-02 over this host's
+ * transcripts: 13481 `.claude/worktrees/agent-<hex>` hits, every agent id of the
+ * form `a` + 16 hex (`agent-a00828908cdd83bd8`). A worktree a SESSION enters
+ * (`EnterWorktree`, `claude --worktree <name>`) lives in the same directory under
+ * a chosen name (`landing-produktschau`, `s71-politur`), so the name is the only
+ * discriminator the path offers.
+ */
+const HARNESS_AGENT_WORKTREE_RE = /^agent-[0-9a-f]{8,}$/;
+
+/**
+ * The first non-blank launch-dir env var, in `resolveProjectDir()` order, or `''`.
+ * Trimmed: a whitespace-only value is truthy and would otherwise win
+ * (`development.md` § Error Handling, env-var fallback whitespace trap).
+ *
+ * The ONE definition of "the launch dir the harness states": the clamp in
+ * {@link resolveSessionRoot} and the relocation trace in `hooks/enforce-scope.mjs`
+ * must read the same chain, so a second copy of it is a second definition.
+ *
+ * @returns {string}
+ */
+export function launchDirFromEnv() {
+  for (const name of ['CLAUDE_PROJECT_DIR', 'CODEX_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'PI_PROJECT_DIR']) {
+    const value = (process.env[name] || '').trim();
+    if (value !== '') return value;
+  }
+  return '';
+}
+
+/**
+ * The nearest directory at or above `cwd` holding a `.git` entry — a directory,
+ * or the FILE a linked worktree carries — or `''` when none does. Git's own repo
+ * discovery walks up looking for exactly this entry, so where git answers, both
+ * agree (measured 2026-10-02: same answer, 0.017 ms here vs 4.57 ms for a
+ * `git rev-parse --show-toplevel` spawn). Existence only — the entry is not
+ * validated, which git would do.
+ *
+ * Not `walkUpFor(cwd, '.git', 'any')`: its home-directory boundary exists for
+ * PLATFORM markers (#1139); a repo whose root is `$HOME` is still a repo root.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function dotGitAncestor(cwd) {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, '.git'))) return dir;
+    if (path.dirname(dir) === dir) return '';
+  }
+}
+
+/**
+ * `<P>` when `root` is a harness subagent worktree `<P>/.claude/worktrees/agent-<hex>`
+ * whose parent `<P>` is itself a working copy; otherwise `root` unchanged.
+ *
+ * @param {string} root
+ * @returns {string}
+ */
+function _liftHarnessAgentWorktree(root) {
+  if (!HARNESS_AGENT_WORKTREE_RE.test(path.basename(root))) return root;
+  const worktreesDir = path.dirname(root);
+  if (path.basename(worktreesDir) !== 'worktrees') return root;
+  const stateDir = path.dirname(worktreesDir);
+  if (path.basename(stateDir) !== '.claude') return root;
+  const parent = path.dirname(stateDir);
+  return existsSync(path.join(parent, '.git')) ? parent : root;
+}
+
+/**
+ * The NATIVE realpath, or the resolved spelling when the path does not exist.
+ *
+ * `realpathSync.native`, not the JS `realpathSync`: on a case-insensitive
+ * volume (APFS default) the JS form resolves symlinks but keeps the CALLER's
+ * letter case, so `/users/me/repo` stayed `/users/…` beside the git-found
+ * `/Users/…`, `path.relative` answered `../../users/…` and the clamp was
+ * skipped (#1504 point 8, measured 2026-10-03 on a home dir typed lowercase:
+ * JS `/users/<me>`, native `/Users/<me>`). Every comparison in the clamp chain
+ * goes through this one function — mixing the two forms re-opens the split.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function _canonical(p) {
+  try { return realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * Is `child` a STRICT descendant of `parent` (never `parent` itself)? Both sides
+ * canonical, so macOS `/tmp` vs `/private/tmp` cannot split one directory in two.
+ *
+ * @param {string} child
+ * @param {string} parent
+ * @returns {boolean}
+ */
+function _isStrictlyInside(child, parent) {
+  const rel = path.relative(_canonical(parent), _canonical(child));
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+/**
+ * The SESSION ROOT (#1492) — the working copy whose control files belong to the
+ * session a hook fires in: `wave-scope.json`, the `.orchestrator/` ledgers, the
+ * event records. One resolver for every hook that reads them (enforce-scope,
+ * enforce-commands, post-bash-write-verify, pre-task-scope-disjoint).
+ *
+ * NOT the launch dir whenever the session works elsewhere: `$CLAUDE_PROJECT_DIR`
+ * stays on the dir the session was LAUNCHED in after it enters a worktree
+ * (docs/en/hooks § "Worktrees are different"), while the coordinator writes
+ * `wave-scope.json` into that worktree. Read from the launch dir, the manifest
+ * was absent and every scope gate allowed everything for the whole session,
+ * silently (#1492, measured in session main-2026-10-02-session-21); preferred
+ * for the dispatch ledger it also gave every worktree session of one launch dir
+ * ONE shared ledger and the wave key `w?` (measured on be6a2e3e).
+ *
+ * NOT the payload `cwd` itself: it follows the session's `cd` (docs/en/hooks
+ * § "cwd follows Claude"), and a `cd sub` must not move the session's state into
+ * `<root>/sub` — a second, empty ledger whose collisions were allowed (#1489 Pkt 6).
+ *
+ * NEVER ABOVE the launch dir: a session launched in a repo SUBDIRECTORY (a
+ * monorepo package, a project under a git-tracked `$HOME`) keeps its manifest
+ * there. The repo root above it holds none, so resolving to it switched every
+ * scope gate off (review HIGH-1 on 4fdbc469, measured DENY → ALLOW).
+ *
+ * Precedence:
+ *   1. no payload `cwd` → `resolveProjectDir()`, the pre-#1492 answer unchanged;
+ *   2. the repo root of `cwd` — `toplevel` when the caller already holds
+ *      `git rev-parse --show-toplevel` of it, else the nearest `.git` ancestor
+ *      (`dotGitAncestor`), which answers the same without a spawn, so neither a
+ *      timed-out git (review MED on 63f35e8c) nor a hot-path budget can send a
+ *      worktree session back to the launch dir — lifted to `<P>` when it is a
+ *      harness subagent worktree `<P>/.claude/worktrees/agent-<hex>` (below),
+ *      then replaced by the launch dir from env (`launchDirFromEnv`) when it
+ *      lies strictly ABOVE it;
+ *   3. the launch dir from env (`CLAUDE_PROJECT_DIR` → `CODEX_PROJECT_DIR` →
+ *      `CURSOR_PROJECT_DIR` → `PI_PROJECT_DIR`), only when `cwd` is in no repo;
+ *   4. `cwd`.
+ *
+ * The clamp reads the SAME launch-dir chain as rung 3, not `$CLAUDE_PROJECT_DIR`
+ * alone. The Cursor and Pi bridges delete `CLAUDE_PROJECT_DIR` and set their
+ * own `*_PROJECT_DIR` to the payload `cwd` on every call (`cursor-hook-bridge.mjs`,
+ * `pi-hook-bridge.mjs`); a clamp on `$CLAUDE_PROJECT_DIR` alone therefore never
+ * fired there, and a Cursor/Pi workspace in a repo SUBDIRECTORY climbed to the
+ * repo root, found no manifest and allowed every write (review HIGH-1 on
+ * b57e572c, measured end-to-end through `cursor-hook-bridge.mjs`: DENY at
+ * ff3e43b5 → ALLOW). For a Claude session nothing changes — `$CLAUDE_PROJECT_DIR`
+ * is first in the chain. For a bridge session the answer is the payload `cwd`
+ * whenever it sits in a repo, which is exactly what the bridges resolved before
+ * #1492 (`resolveProjectDir()` → their `*_PROJECT_DIR` → the payload `cwd`).
+ * The clamp does not ask whether `cwd` lies inside the launch dir: an
+ * `isolation: "worktree"` agent's `cwd` never does, and it must clamp too (see
+ * THE LIFT).
+ *
+ * THE LIFT. An `isolation: "worktree"` subagent's hook payload carries the
+ * worktree the harness made for it, `<P>/.claude/worktrees/agent-<hex>`. That
+ * worktree is a repo root of its own and holds no manifest, so rung 2 alone
+ * would disarm scope enforcement for every such agent. The harness puts it under
+ * the LAUNCH checkout, so `<P>` is what `$CLAUDE_PROJECT_DIR` resolved to before
+ * #1492 — the lift keeps exactly that, and the clamp keeps it for a launch in a
+ * subdirectory of `<P>`. It is keyed on the PATH SHAPE, never on which candidate
+ * holds a manifest: a root picked because a control file is readable there
+ * would let any directory that lacks one become the deciding root.
+ *
+ * Ceilings (BV-004):
+ *  - An agent of a session that ENTERED a worktree is still unenforced, as before
+ *    #1492: its worktree sits under the launch checkout (measured: session
+ *    0d5e4fc3, 2026-09-25 — cwd `<main>/.claude/worktrees/landing-produktschau`,
+ *    agent worktreePath `<main>/.claude/worktrees/agent-acd5bfd0aa590e2e8`), so
+ *    the lift lands on the launch root, where that session has no manifest.
+ *    Fixing it needs a design (e.g. find the manifest bound to the payload
+ *    `session_id` among the repo's worktrees). Revisit when an entered-worktree
+ *    session dispatches `isolation: "worktree"` agents under a manifest.
+ *  - Rung 2 is `cd`-relocatable: a session whose `cwd` sits in ANOTHER repo (a
+ *    submodule, a nested or sibling checkout) is checked against that repo's
+ *    manifest — usually none, so its gates allow — where the launch dir's
+ *    manifest used to apply. Same relocation `pre-task-scope-disjoint` has
+ *    keyed its ledger on since #1489. Revisit if an `orchestrator.scope.*`
+ *    record or a review ever shows an out-of-scope write made after such a `cd`.
+ *  - A session worktree NAMED like a harness one (`agent-` + 8 or more hex) is
+ *    lifted to its parent — the pre-#1492 launch-dir behaviour for that one
+ *    session, not a new failure. Revisit if the harness changes its naming.
+ *  - A Cursor/Pi bridge session follows its payload `cwd`, as it did before
+ *    #1492: the bridges hand over no launch dir distinct from that `cwd`, so a
+ *    bridge session whose `cwd` moves into a subdirectory without a manifest is
+ *    unenforced there. Not a new failure — the pre-#1492 bridge answer. Revisit
+ *    when a bridge hands over a stable workspace root separately from the
+ *    payload `cwd` — then clamp on that instead.
+ *
+ * @param {string|undefined} cwd       the hook payload's `cwd`
+ * @param {string} [toplevel]          `git rev-parse --show-toplevel` of `cwd`, `''` when unknown
+ * @returns {string}  Absolute path
+ */
+export function resolveSessionRoot(cwd, toplevel = '') {
+  if (typeof cwd !== 'string' || cwd.trim() === '') return resolveProjectDir();
+  const repoRoot = (typeof toplevel === 'string' ? toplevel : '') || dotGitAncestor(cwd);
+  if (!repoRoot) return launchDirFromEnv() || cwd;
+  const root = _liftHarnessAgentWorktree(repoRoot);
+  const launch = launchDirFromEnv();
+  return launch !== '' && _isStrictlyInside(launch, root) ? launch : root;
+}
+
 // ---------------------------------------------------------------------------
 // resolveStateDir
 // ---------------------------------------------------------------------------

package/scripts/lib/plugin-update-banner.mjs

@@ -260,7 +260,9 @@ async function resolveLatestVersion({ cacheDir, now, fetchImpl }) {
  * @type {Record<"claude"|"codex"|"cursor"|"pi", string>}
  */
 const PLATFORM_UPDATE_INSTRUCTIONS = {
-  claude: '/plugin update session-orchestrator@kanevry, then restart Claude Code',
+  claude:
+    '/plugin update session-orchestrator@kanevry, then restart Claude Code ' +
+    '(from a clone: `npm run update:local` also installs the deps Claude Code refuses — docs/install.md § Upgrade)',
   codex:
     'run `codex plugin marketplace upgrade kanevry && codex plugin add session-orchestrator@kanevry` ' +
     '(docs/codex-setup.md), then restart Codex',

package/scripts/lib/process-group.mjs

@@ -25,17 +25,18 @@
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
-  appendFileSync,
   existsSync,
   lstatSync,
   mkdirSync,
-  readFileSync,
   renameSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
 
+import { NOT_A_REGULAR_FILE, appendNoFollow } from './orphan-reaper/no-follow-append.mjs';
+import { readTailWindow } from './tail-window.mjs';
+
 /**
  * Grace period between SIGTERM and SIGKILL, in ms — the repo's one definition,
  * used by the gate's group ladder here and by `wave-executor/foreign-dispatch.mjs`
@@ -490,6 +491,26 @@ function ledgerPathFor(repoRoot) {
   return path.join(repoRoot, ...GATE_PROCESS_LEDGER_RELPATH.split('/'));
 }
 
+/**
+ * Read the whole ledger without following a link and without blocking on a
+ * FIFO: `readTailWindow`'s `noFollow` open with a window larger than any file,
+ * so a regular ledger reads exactly as `readFileSync` read it. A plain
+ * `readFileSync` FOLLOWED a symlinked ledger (a foreign file parsed as kill
+ * candidates) and blocked for good in `open` on a planted FIFO — inside the
+ * gate's own registration path (#1489). THROWS like `readFileSync`: ENOENT,
+ * ELOOP for a symlink, `ERR_NOT_REGULAR_FILE` for a FIFO or directory.
+ *
+ * Named ceiling (BV-004): the file is read whole, as before — fine for a ledger
+ * pruned to 24 h (one line per gate command); revisit if it ever stops being
+ * pruned.
+ *
+ * @param {string} target
+ * @returns {string}
+ */
+function readLedgerNoFollow(target) {
+  return readTailWindow(target, Number.MAX_SAFE_INTEGER, { noFollow: true }).text;
+}
+
 /**
  * Append one {@link GateProcessRecord} to the gate-process ledger.
  *
@@ -499,6 +520,12 @@ function ledgerPathFor(repoRoot) {
  * vanishing (a ledger that silently stops being written is indistinguishable
  * from a host with no gate processes).
  *
+ * The write is {@link appendNoFollow}, never `appendFileSync(path)`: that
+ * followed a symlinked ledger, so every gate registration landed in the link's
+ * target, and its open of a planted FIFO blocked until a reader appeared — the
+ * gate hung in its own registration path (#1489). A link, FIFO, directory or
+ * hard-linked ledger is now refused with the same one WARN line.
+ *
  * @param {string} repoRoot
  * @param {GateProcessRecord} record
  * @param {object} [opts]
@@ -513,7 +540,7 @@ export function recordGateProcess(repoRoot, record, { appendFn } = {}) {
     if (!appendFn) mkdirSync(path.dirname(target), { recursive: true });
     const line = `${JSON.stringify(record)}\n`;
     if (appendFn) appendFn(target, line);
-    else appendFileSync(target, line, 'utf8');
+    else appendNoFollow(target, line);
   } catch (err) {
     process.stderr.write(
       `process-group: could not record gate process in ${GATE_PROCESS_LEDGER_RELPATH}: ${err?.message ?? String(err)}\n`,
@@ -532,14 +559,24 @@ export function recordGateProcess(repoRoot, record, { appendFn } = {}) {
  * counted separately — they are not candidates for anything, and their PIDs are
  * the most likely to have been recycled.
  *
+ * A symlinked, FIFO or otherwise non-regular ledger yields NO records, like an
+ * unreadable one ({@link readLedgerNoFollow}): never a link target's lines as
+ * candidates, never a blocked open — no records name no process group to
+ * signal. But it is not reported as empty (#1498): `state` tells the three
+ * outcomes apart — `read`, `absent` (no ledger yet, the ordinary case) and
+ * `unreadable` (refused or failed) — because the scan's `ledger-unreadable`
+ * skip was unreachable while a refused ledger looked exactly like a clean one.
+ *
  * @param {string} repoRoot
  * @param {object} [opts]
  * @param {(filePath: string) => string} [opts.readFn]  Reader seam; must throw or
  *   return '' for a missing file.
  * @param {number} [opts.nowMs]
  * @param {number} [opts.maxAgeMs]
- * @returns {{records: GateProcessRecord[], malformedLines: number, expired: number}}
- *   `records` are the fresh, parseable entries in source order.
+ * @returns {{records: GateProcessRecord[], malformedLines: number, expired: number,
+ *   state: 'read'|'absent'|'unreadable'}}
+ *   `records` are the fresh, parseable entries in source order; empty unless
+ *   `state` is `read`.
  */
 export function readGateProcessLedger(repoRoot, {
   readFn,
@@ -547,12 +584,19 @@ export function readGateProcessLedger(repoRoot, {
   maxAgeMs = DEFAULT_LEDGER_MAX_AGE_MS,
 } = {}) {
   const target = ledgerPathFor(repoRoot);
-  let raw = '';
+  let raw;
   try {
-    if (readFn) raw = readFn(target) ?? '';
-    else if (existsSync(target)) raw = readFileSync(target, 'utf8');
-  } catch {
-    return { records: [], malformedLines: 0, expired: 0 };
+    // No `existsSync` pre-check: it FOLLOWS a link, so a dangling symlink read
+    // as "no ledger yet" while `appendNoFollow` refused it on every
+    // registration (#1498 review). The no-follow open itself tells the cases
+    // apart — ENOENT only when nothing is at the path.
+    raw = readFn ? (readFn(target) ?? '') : readLedgerNoFollow(target);
+  } catch (err) {
+    // ENOENT: no ledger yet, or one that vanished (or a `readFn` reporting a
+    // missing file). Anything else — ELOOP (a symlink, dangling or not),
+    // ERR_NOT_REGULAR_FILE, EACCES — was refused.
+    const state = err?.code === 'ENOENT' ? 'absent' : 'unreadable';
+    return { records: [], malformedLines: 0, expired: 0, state };
   }
 
   /** @type {GateProcessRecord[]} */
@@ -580,7 +624,7 @@ export function readGateProcessLedger(repoRoot, {
     records.push(parsed);
   }
 
-  return { records, malformedLines, expired };
+  return { records, malformedLines, expired, state: 'read' };
 }
 
 /**
@@ -594,17 +638,19 @@ export function readGateProcessLedger(repoRoot, {
  * ledger linked to `events.jsonl` emptied the link's target (CWE-59, reproduced
  * 2026-10-01). `rename` replaces the directory entry itself, never a link's
  * target, and the `wx` flag refuses a pre-planted file or link at the tmp name.
- * Kept local, not imported, because this module deliberately has no local
- * imports; `orphan-reaper/reaper-audit.mjs` carries the same few lines.
+ * The ONE copy (#1498): `orphan-reaper/reaper-audit.mjs` imports it for the
+ * audit prune — both ledgers its scan housekeeping rewrites. It lives here, not
+ * there, because this module imports nothing from `orphan-reaper/` beyond the
+ * fs-only `no-follow-append.mjs`, so the graph stays acyclic, and every
+ * importer of the audit module already loads this one.
  *
  * @param {string} target
  * @param {string} body
- * @param {{lstatSync: Function, writeFileSync: Function, renameSync: Function, unlinkSync: Function}} io
+ * @param {{lstatSync: Function, writeFileSync: Function, renameSync: Function, unlinkSync: Function}} [io]
+ *   fs seam for tests; defaults to `node:fs`.
  */
-function replaceRegularFile(target, body, io) {
-  if (!io.lstatSync(target).isFile()) {
-    throw new Error('not a regular file (a symlink is never written through) — left untouched');
-  }
+export function replaceRegularFile(target, body, io = { lstatSync, writeFileSync, renameSync, unlinkSync }) {
+  if (!io.lstatSync(target).isFile()) throw new Error(NOT_A_REGULAR_FILE);
   const tmp = `${target}.tmp-${process.pid}`;
   try {
     io.writeFileSync(tmp, body, { encoding: 'utf8', flag: 'wx' });
@@ -630,8 +676,10 @@ function replaceRegularFile(target, body, io) {
  *
  * In-process fs only — never a shell `rm`/`mv` (PSA-003, and
  * `.orchestrator/metrics/**` deletions are a blocked-command rule for a reason).
- * The rewrite goes through {@link replaceRegularFile}: a symlinked or
- * non-regular ledger is refused with one WARN and left untouched.
+ * The read is {@link readLedgerNoFollow} and the rewrite goes through
+ * {@link replaceRegularFile}: a symlinked, FIFO or otherwise non-regular ledger
+ * is refused with one WARN and left untouched — refused at the READ, so a link
+ * target is never read and a FIFO never blocks the gate's registration path.
  *
  * Named ceiling (BV-004): read-filter-write is not atomic against a concurrent
  * append, so a line appended between the read and the write is lost. Acceptable
@@ -655,13 +703,26 @@ export function pruneGateProcessLedger(repoRoot, {
   maxAgeMs = DEFAULT_LEDGER_MAX_AGE_MS,
   fs: fsSeam,
 } = {}) {
-  const io = fsSeam ?? { existsSync, readFileSync, writeFileSync, lstatSync, renameSync, unlinkSync };
+  const io = fsSeam ?? {
+    existsSync,
+    readFileSync: readLedgerNoFollow,
+    writeFileSync,
+    lstatSync,
+    renameSync,
+    unlinkSync,
+  };
   const target = ledgerPathFor(repoRoot);
   let raw;
   try {
     if (!io.existsSync(target)) return 0;
     raw = io.readFileSync(target, 'utf8');
-  } catch {
+  } catch (err) {
+    // A refused ledger (ELOOP: a symlink; ERR_NOT_REGULAR_FILE: a FIFO, a
+    // directory) gets the same one WARN the rewrite gives it; an unreadable or
+    // vanished one stays silent, as before.
+    if (err?.code === 'ELOOP' || err?.code === 'ERR_NOT_REGULAR_FILE') {
+      process.stderr.write(`process-group: could not prune ${GATE_PROCESS_LEDGER_RELPATH}: ${NOT_A_REGULAR_FILE}\n`);
+    }
     return 0;
   }
 

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,26 +657,38 @@ 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)

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'));