session-orchestrator 5.4.0 → 5.6.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -114,10 +114,14 @@
  *
  * A deny-capable hook on the DISPATCH path has an asymmetric blast radius: a
  * false positive blocks every agent of the session (the guard becomes a session
- * outage), while a false negative is a double-assignment that three later gates
- * still catch (`validate-wave-scope.mjs`, `enforce-scope.mjs` at write time, and
- * the W5 verification pass). Fail-closed is right for a WRITE guard; it is wrong
- * here. Each row below is a deliberate choice, not an oversight:
+ * outage), while a false negative of the COLLISION check is a double-assignment
+ * that three later gates still catch (`validate-wave-scope.mjs`,
+ * `enforce-scope.mjs` at write time, and the W5 verification pass). The #1485
+ * stale-base check (row 15) has no such later gate — a missed stale base is an
+ * agent editing old code — so it is kept fail-open by a different rule: it
+ * denies only on a MEASUREMENT, and every unknown is ALLOW plus a record.
+ * Fail-closed is right for a WRITE guard; it is wrong here. Each row below is a
+ * deliberate choice, not an oversight:
  *
  *   | # | Condition                              | Decision            | Why |
  *   |---|----------------------------------------|---------------------|-----|
@@ -128,18 +132,21 @@
  *   | 5 | prompt carries no scope marker         | ALLOW + COUNT       | 105 of 147 real prompts (71.4 %) have none. Non-extractable ≠ violation; denying these would deny 7 dispatches in 10. #1092: the allow now carries a counter-only record, so it is no longer byte-identical to "the guard never ran" |
  *   | 6 | scope block present but unparseable    | ALLOW + COUNT       | same reason as 5 — the parser is the fragile part, so its failures must resolve to the harmless side. Counted under a DISTINCT class from row 5 |
  *   | 7 | ledger unreadable / corrupt            | WARN + ALLOW + SELF-HEAL | loss of state is not evidence of a violation; loud so it gets noticed. The verdict now CARRIES a fresh ledger, so the corruption is repaired on the spot — without it the guard stayed OFF for the whole remaining wave, visible only in one `systemMessage` |
- *   | 8 | `git ls-files` failed                  | ALLOW (degraded)    | glob-vs-glob expansion degrades, concrete collisions are still found. A git outage is not a scope violation |
+ *   | 8 | `git ls-files` failed, or the shared git budget (`GIT_BUDGET_MS`) ran out | ALLOW (degraded) + `known_files_skipped` in the record | glob-vs-glob expansion degrades, concrete collisions are still found. A git outage is not a scope violation. #1489 Pkt 7: a HANGING git used to outlive the 5 s harness timeout, which killed the hook — the verdict lost with no record |
  *   | 9 | `findScopeCollisions` → not evaluable   | WARN + ALLOW        | the library says "not evaluable". Denying on a verdict with no witness is an assertion without evidence |
  *   |10 | same agent id re-dispatched         | ALLOW; predecessor pruned only when FINISHED | a retry after a failed agent is legitimate (a failed agent is finished), so the guard must not self-lock. #1480 B4: an unfinished predecessor is KEPT as a claim — a third agent hitting only its scope still collides. With distinct `tool_use_id`s on both it is an ordinary partner (row 11); without them it never collides with its own retry. Replaced WITHOUT a probe only where no claim is lost: the same `tool_use_id` (the same dispatch evaluated again), or — neither carrying an id — a predecessor wholly covered by the retry's scope |
  *   |10a| collision, but EVERY colliding prior agent has FINISHED (positive evidence) | ALLOW (+ prune) | the sequential repair pass. Its ledger records are pruned, so the state cannot re-block the next one either |
- *   |11 | collision with a prior agent still IN FLIGHT | **DENY**       | the one case this hook exists for |
+ *   |11 | collision with a prior agent still IN FLIGHT | **DENY**       | the case this hook was built for (#1020) |
  *   |12 | unexpected throw                       | ALLOW + stderr      | as row 2 |
  *   |13 | liveness probe throws / no positive evidence (no record, unknown result form) | treat as IN FLIGHT | keeps row 11 biting; the blind case is bounded by `IN_FLIGHT_TTL_MS`, never unbounded. A dispatch re-opened by a SendMessage with no completion after it is in flight outright, without TTL |
  *   |14 | ledger lock not acquirable in `LEDGER_LOCK_TIMEOUT_MS` | run UNLOCKED (degraded) | the lock removes the read-modify-write race (below); failing to take it must not deny, so the cycle degrades to the pre-lock behaviour |
+ *   |15 | `isolation: "worktree"`, `worktree.baseRef` not `"head"`, `merge-base --is-ancestor HEAD origin/HEAD` exits 1 in a full-history repo whose FETCH_HEAD is < 24 h old | **DENY**, no ledger write | #1485: the agent would branch from a base missing commits of HEAD and edit OLD code. Every non-measurement — no origin/HEAD, shallow, `stale-remote-ref`, git error, git budget spent (`git-budget`) — is ALLOW + a `skipped` record. No ledger write, so the in-place re-dispatch the deny advises meets no phantom claim. A collision DENY (row 11) wins the terminal emit; this one then goes to stderr. Otherwise the `scope_checked` record carries `ledger_result: 'deny-stale-base'`, never the collision verdict's allow (#1489 Pkt 8) |
  *
  * Every row that reaches a verdict from `decide()` — 5–11 and 13–14 — also
  * leaves an event record (§ Observability), so "which row fired" is answerable
- * after the fact and not only in the moment. Rows 1–4 emit nothing (no decision
+ * after the fact and not only in the moment. Row 15 is decided outside
+ * `decide()` and leaves its own `worktree_base_checked` record for EVERY
+ * worktree dispatch, allow and skip included. Rows 1–4 emit nothing (no decision
  * was made), and neither do the two crash rows 2 and 12: a hook that fell over
  * cannot describe itself, which is precisely why the GUARD INACTIVE banner on
  * stderr is the signal there.
@@ -165,13 +172,21 @@
  * ## Observability — the ledger half of #1092
  *
  * Every dispatch DECISION also appends one `orchestrator.wave_dispatch.scope_checked`
- * record to `<projectDir>/.orchestrator/metrics/events.jsonl`. The reason it
+ * record to `<session root>/.orchestrator/metrics/events.jsonl` — the root
+ * `resolveSessionRoot()` resolves (`scripts/lib/platform.mjs`: the git toplevel
+ * of the payload `cwd` — its nearest `.git` ancestor when git cannot answer —
+ * but never above a launch dir inside it; so neither the subdirectory a `cd`
+ * moved to, #1489 Pkt 6, nor the launch dir a worktree session left), which is
+ * also where the ledger and its lock live. The reason it
  * exists is matrix rows 5/6: the no-signal ALLOW used to be byte-identical to
  * "the guard never ran", and the in-ledger counter added first is a WAVE tally —
  * it cannot say WHICH dispatch carried a scope. Payload: `wave` (omitted, never
  * `0`, when unknown), `agent_id`, `declared_path_count`, `injected`, `shape`,
- * `signal`, `ledger_result`, `collision_count`, `hook`, plus `session_id` /
- * `semantic_session_id` when a session lock is readable.
+ * `signal`, `ledger_result`, `collision_count`, `hook`, `known_files_skipped`
+ * (only when the tracked-file listing degraded, matrix row 8), `collision_result`
+ * (only beside `ledger_result: 'deny-stale-base'` — the collision verdict it
+ * replaced), plus `session_id` / `semantic_session_id` when a session lock is
+ * readable.
  *
  * WHAT IT PROVES: this hook SAW (or did not see) a `FILE-SCOPE` declaration in
  * the prompt the coordinator handed to the dispatch tool, and what the guard
@@ -229,6 +244,7 @@ import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { mkdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 
@@ -249,7 +265,12 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 /** @type {typeof import('../scripts/lib/io.mjs').writeJsonAtomicSync} */ let writeJsonAtomicSync;
 /** @type {typeof import('../scripts/lib/file-lock.mjs').withFileLock} */ let withFileLock;
 /** @type {typeof import('../scripts/lib/scope-echo.mjs').scopeDigest} */ let scopeDigest;
+/** @type {typeof import('../scripts/lib/platform.mjs').resolveSessionRoot} */ let resolveSessionRoot;
 let findScopeCollisions;
+/** @type {typeof import('../scripts/lib/scope-gate.mjs').scopeEntrySpelling} */ let scopeEntrySpelling;
+let findOwnScopeFile;
+let readProcessLocalSessionIds;
+let classifyManifestSession;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
 
@@ -263,11 +284,43 @@ const HOOK_NAME = 'pre-task-scope-disjoint';
  */
 const DISPATCH_TOOL = 'Agent';
 
-/** Ledger location, relative to the project dir. */
-const LEDGER_REL = path.join('.orchestrator', 'wave-dispatch-scopes.json');
+/**
+ * Ledger location (#1493.3): ONE FILE PER SESSION,
+ * `.orchestrator/wave-dispatch-scopes.<session>.json`, each with its own lock
+ * `.orchestrator/wave-dispatch-scopes.<session>.lock` (§ Ledger concurrency).
+ *
+ * Until #1493 every session of the working copy shared ONE file holding ONE
+ * `waveKey`, and `decide()` keeps prior agents only under the same key — whose
+ * first segment IS the session id. So cross-session claims were never compared
+ * (nothing is lost by splitting), but a peer session's dispatch reset the file
+ * and erased this session's live claims, and the deny's "delete the ledger"
+ * remedy erased the peer's. One file per session removes both.
+ *
+ * A flat sibling, not a directory, on purpose: bootstrap's `store-lock-ignore`
+ * step (#1495) ignores `.orchestrator/wave-dispatch-scopes.*` in consumer repos,
+ * which covers this name; a directory would surface untracked in each of them.
+ */
+const LEDGER_DIR_REL = '.orchestrator';
+const LEDGER_STEM = 'wave-dispatch-scopes';
+
+/**
+ * The pre-#1493 single shared ledger. READ only, for migration: adopted when
+ * this session has no file yet AND its `waveKey` names this session; never
+ * written and never deleted — it may still be a peer's live state.
+ * Revisit-Trigger: remove this read one minor release after the split ships,
+ * when no session that recorded claims in the old file can still be running.
+ */
+const LEGACY_LEDGER_REL = path.join(LEDGER_DIR_REL, `${LEDGER_STEM}.json`);
 
-/** Mutex for the ledger's read-modify-write cycle — see § Ledger concurrency. */
-const LEDGER_LOCK_REL = path.join('.orchestrator', 'wave-dispatch-scopes.lock');
+/**
+ * Longest session token a ledger file name carries. Harness session ids are
+ * UUIDs (36 chars) and pass through unchanged; the cap only keeps a pathological
+ * id below the 255-byte file-name limit. Two ids that sanitise to ONE token
+ * share a file again — degraded to the pre-#1493 behaviour, never worse, since
+ * `waveKey` still carries the raw id. Revisit if a harness ships ids that are
+ * not path-safe.
+ */
+const MAX_SESSION_TOKEN_CHARS = 128;
 
 /**
  * Ledger-lock budget. Short on purpose: the whole locked region is a read, a
@@ -278,6 +331,28 @@ const LEDGER_LOCK_REL = path.join('.orchestrator', 'wave-dispatch-scopes.lock');
 const LEDGER_LOCK_TIMEOUT_MS = 2000;
 const LEDGER_LOCK_POLL_MS = 25;
 
+/**
+ * ONE deadline for ALL git work of one hook fire (#1489 Pkt 7). Every spawn
+ * gets at most what is LEFT of it, so the git work as a whole — never a single
+ * call — is what is bounded.
+ *
+ * The number is arithmetic, not taste: `hooks/hooks.json` gives this hook
+ * `"timeout": 5` (seconds) for the WHOLE process. The git work runs first; after
+ * it the ledger lock may wait up to `LEDGER_LOCK_TIMEOUT_MS` (2000). 5000 − 2000
+ * − 1500 leaves 1500 ms for node start, the late-bound imports, the transcript
+ * scan (≤ ~210 ms at the largest measured 70 MB) and the two awaited event
+ * appends — ~20× the 69 ms full path measured idle (§ Measured cost). The git
+ * work itself measured 27.8 ms together with lock, ledger and compare, so 1500
+ * binds only a git that hangs (a stuck lock file, a network-backed `HEAD`, a
+ * frozen filesystem). Before, each worktree call had its own 5 s and
+ * `listTrackedFiles` none: one hanging git outlived the harness, which killed
+ * the hook — a silent fail-open with no record of the lost verdict.
+ *
+ * Revisit-Trigger: a change of this hook's `timeout` in `hooks/hooks.json` or of
+ * `LEDGER_LOCK_TIMEOUT_MS` — the three numbers must keep summing below 5000.
+ */
+const GIT_BUDGET_MS = 1500;
+
 /** Payload bounds — see § stdout discipline. */
 const MAX_REPORTED_COLLISIONS = 5;
 const MAX_EVIDENCE_PER_COLLISION = 4;
@@ -307,14 +382,14 @@ const SHAPE_NONE = 'none';
 const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
 
 /**
- * The worktree-base observability record (#1413).
+ * The worktree-base observability record (#1413; carries the #1485 `decision`).
  *
  * Same `wave_dispatch` domain and same `_checked` verb as `SCOPE_EVENT`, and
  * written for EVERY `isolation: "worktree"` dispatch rather than only the
  * alarming one. That is HR-105 applied at the source: a numerator-only stream
- * cannot tell "genuinely rare" from "silently broken", and the firing rate this
- * warning must stay under is then unfalsifiable. With every outcome in one
- * stream the rate is `stale:true / all records of this name`.
+ * cannot tell "genuinely rare" from "silently broken", and the firing rate of
+ * the #1485 deny is then unfalsifiable. With every outcome in one stream the
+ * rate is `decision:"deny" / all records of this name`.
  *
  * #1424 widened "every outcome" from two to three: the `stale: true|false`
  * split was already covered, but each NON-measurement (peer STATE.md, no
@@ -326,9 +401,6 @@ const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
  */
 const WORKTREE_BASE_EVENT = 'orchestrator.wave_dispatch.worktree_base_checked';
 
-/** State-dir candidates, in the same order `waveKeyOf()` probes them. */
-const STATE_DIR_CANDIDATES = ['.pi', '.cursor', '.codex', '.claude'];
-
 /**
  * The receive-side instruction line `renderScopeEchoInstruction()` renders and
  * the coordinator appends immediately after the fenced block
@@ -486,6 +558,7 @@ async function bootstrap() {
     {
       io: { specifier: lib('io.mjs') },
       scopeGate: { specifier: lib('scope-gate.mjs') },
+      sessionIdentity: { specifier: lib('session-identity', 'own-session.mjs') },
       fileLock: { specifier: lib('file-lock.mjs') },
       // ONE normalization for the digest, shared with the receive side (#1092):
       // `scope-echo.mjs` is pure (stdlib + `crypto-digest-utils.mjs`) and its
@@ -495,6 +568,10 @@ async function bootstrap() {
       // names. Late-bound like every other repo module so a load failure
       // banners instead of disarming the guard silently (#993).
       scopeEcho: { specifier: lib('scope-echo.mjs') },
+      // #1492: ONE session-root resolver for every hook that reads the
+      // session's control files — this ledger, and `wave-scope.json` in
+      // enforce-scope / enforce-commands / post-bash-write-verify.
+      platform: { specifier: lib('platform.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -505,9 +582,11 @@ async function bootstrap() {
   );
 
   ({ readStdin, emitAllow, emitDeny, emitWarn, writeJsonAtomicSync } = modules.io);
-  ({ findScopeCollisions } = modules.scopeGate);
+  ({ findScopeCollisions, findOwnScopeFile, scopeEntrySpelling } = modules.scopeGate);
+  ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
   ({ withFileLock } = modules.fileLock);
   ({ scopeDigest } = modules.scopeEcho);
+  ({ resolveSessionRoot } = modules.platform);
 }
 
 // ---------------------------------------------------------------------------
@@ -661,36 +740,6 @@ function cleanScopeLine(line) {
     .trim();
 }
 
-/**
- * Canonicalise a scope entry's SPELLING so two agents writing the same file two
- * ways are not read as disjoint (review LOW). Measured before this existed:
- * `['./scripts/lib/foo.mjs']` vs `['scripts/lib/foo.mjs']` compared `ok: true`
- * — the hook extracts from PROSE, and `looksLikeRepoPath` admits a `./` prefix,
- * so both spellings reach the comparison verbatim.
- *
- * Purely syntactic and meaning-preserving: `./` prefixes, `/./` segments and
- * duplicated slashes are removed. A TRAILING slash is deliberately kept — it is
- * the directory-prefix operator of `pathMatchesPattern`, so stripping it would
- * silently narrow a scope. The `dir` ↔ `dir/` case is handled by
- * {@link promoteDirEntries}, which decides it on evidence rather than guessing.
- *
- * `scope-gate.mjs` is a hook-safe pure library and out of this change's scope,
- * so the normalisation lives on THIS side of the call, applied to both sides of
- * every comparison.
- *
- * @param {string} entry
- * @returns {string}
- */
-export function normalizeScopeEntry(entry) {
-  if (typeof entry !== 'string') return '';
-  let s = entry.trim();
-  if (s === '') return '';
-  s = s.replace(/\/{2,}/g, '/');       // `a//b` → `a/b`
-  s = s.replace(/(?:^|\/)\.\//g, (m) => (m.startsWith('/') ? '/' : '')); // `./a`, `a/./b`
-  while (s.startsWith('./')) s = s.slice(2);
-  return s;
-}
-
 /**
  * Promote an entry that names a DIRECTORY to its `dir/` prefix form, on
  * evidence. `scripts/lib` and `scripts/lib/` are the same claim, but
@@ -737,7 +786,11 @@ function collectScopePaths(segments) {
   for (const raw of segments) {
     // A trailing sentence period is punctuation, never part of a path
     // (measured: "docs/events-schema.md." at the end of an inline declaration).
-    const cleaned = normalizeScopeEntry(cleanScopeLine(raw).replace(/\.$/, ''));
+    // Lexical cleaning only (prose → path); the SPELLING rule is
+    // `scopeEntrySpelling` in scope-gate.mjs, applied in `decide()` (#1510 g).
+    // The second trim: a period stripped after `cleanScopeLine`'s trim can
+    // expose a space (`foo.mjs .`), which `looksLikeRepoPath` would reject.
+    const cleaned = cleanScopeLine(raw).replace(/\.$/, '').trim();
     if (!looksLikeRepoPath(cleaned)) continue;
     if (seen.has(cleaned)) continue;
     seen.add(cleaned);
@@ -828,7 +881,8 @@ export function extractScopeSignal(prompt) {
  * (and the tests that pin them) keep the original signature.
  *
  * @param {string} prompt
- * @returns {string[]} repo-relative paths/globs, normalised, deduped, order preserved
+ * @returns {string[]} repo-relative paths/globs as declared (lexically cleaned,
+ *   deduped, order preserved) — the SPELLING rule runs in `decide()` (#1510 g)
  */
 export function extractScopeFromPrompt(prompt) {
   return extractScopeSignal(prompt).files;
@@ -1355,7 +1409,8 @@ export function makeFinishedProbe({
 /**
  * Identify the wave this dispatch belongs to. Derived from the coordinator's
  * own scope file so a wave transition resets the ledger without anyone having to
- * remember to clear it.
+ * remember to clear it. `findOwnScopeFile` skips provably foreign manifests;
+ * unbound or corrupt manifests still decide under the ENFORCE contract.
  *
  * FALLBACK, stated honestly (review MED): with no readable `wave-scope.json` the
  * key degrades to `<session>|w?|?`, so the ledger spans the whole SESSION and a
@@ -1370,22 +1425,75 @@ export function makeFinishedProbe({
  * @param {string} projectDir
  * @param {string} sessionId
  * @param {(p: string, enc: string) => string} readFn — injected `readFileSync`
- *   (the module is late-bound, so it cannot be imported at the top level here)
+ * @param {Set<string>} [ownIds] — process-local ids; repo helpers are late-bound
+ *   by bootstrap, as for the other guard dependencies.
  * @returns {string}
  */
-export function waveKeyOf(projectDir, sessionId, readFn) {
-  for (const dir of ['.pi', '.cursor', '.codex', '.claude']) {
+export function waveKeyOf(projectDir, sessionId, readFn,
+  ownIds = new Set(readProcessLocalSessionIds({ hookInput: { session_id: sessionId } }))) {
+  const { path: scopeFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
+  if (scopeFile) {
     try {
-      const raw = readFn(path.join(projectDir, dir, 'wave-scope.json'), 'utf8');
+      const raw = readFn(scopeFile, 'utf8');
       const data = JSON.parse(raw);
       const wave = data?.wave ?? '?';
       const role = data?.role ?? '?';
       return `${sessionId}|w${wave}|${role}`;
-    } catch { /* try next location */ }
+    } catch { /* corrupt / unreadable own-or-unknown manifest → no wave */ }
   }
   return `${sessionId}|w?|?`;
 }
 
+/**
+ * The session id this dispatch is keyed under — the payload's own, never a
+ * lock or env read (§ 6 limit 10 of `docs/scope-collision-guard.md`).
+ *
+ * @param {object} input parsed PreToolUse payload
+ * @returns {string}
+ */
+function sessionIdOf(input) {
+  return typeof input?.session_id === 'string' ? input.session_id : 'no-session';
+}
+
+/**
+ * The repo-relative paths of THIS session's ledger and its lock (#1493.3).
+ * The session id is reduced to a path-safe token (`[A-Za-z0-9._-]`, capped at
+ * `MAX_SESSION_TOKEN_CHARS`), so no id can name a file outside `.orchestrator/`;
+ * an id with no usable character falls back to `no-session`.
+ *
+ * @param {string} sessionId
+ * @returns {{ ledgerRel: string, lockRel: string }}
+ */
+export function ledgerPathsFor(sessionId) {
+  const token = String(sessionId).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, MAX_SESSION_TOKEN_CHARS);
+  const safe = /[A-Za-z0-9]/.test(token) ? token : 'no-session';
+  const base = path.join(LEDGER_DIR_REL, `${LEDGER_STEM}.${safe}`);
+  return { ledgerRel: `${base}.json`, lockRel: `${base}.lock` };
+}
+
+/**
+ * Migration read of the pre-#1493 shared ledger: the parsed legacy ledger when
+ * its `waveKey` belongs to THIS session (first `|` segment equals the id), else
+ * `null`. An unparseable or foreign legacy file is not this session's state —
+ * it is neither adopted nor reported as corruption (row 7 is about OUR file).
+ *
+ * @param {string|null} raw legacy file contents (`null` = absent)
+ * @param {string} sessionId
+ * @returns {object|null}
+ */
+function adoptLegacyLedger(raw, sessionId) {
+  if (typeof raw !== 'string') return null;
+  try {
+    const legacy = JSON.parse(raw);
+    return legacy !== null && typeof legacy === 'object' && typeof legacy.waveKey === 'string'
+      && legacy.waveKey.startsWith(`${sessionId}|`)
+      ? legacy
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The wave NUMBER out of a `waveKeyOf()` key, for the telemetry record (#1092).
  *
@@ -1406,6 +1514,88 @@ function waveNumberOf(waveKey) {
   return Number.isSafeInteger(n) && n > 0 ? n : null;
 }
 
+/** Thrown instead of spawning once the shared git deadline has passed. */
+class GitBudgetExhausted extends Error {
+  /** @param {string} subcommand */
+  constructor(subcommand) {
+    super(`git ${subcommand}: shared git budget (${GIT_BUDGET_MS} ms) exhausted`);
+    this.name = 'GitBudgetExhausted';
+  }
+}
+
+/**
+ * A git runner bound to ONE deadline shared by every call of this hook fire
+ * (see `GIT_BUDGET_MS`). Each call gets `timeout` = what is left; once nothing
+ * is left it throws without spawning. `exhausted()` turns sticky the moment a
+ * call is refused or timed out, so a caller can tell "git said no" from "git
+ * never got to answer" — the second is a skip, never evidence (§ matrix rows 8,
+ * 15). `SIGKILL`, not the default SIGTERM: a child that ignores SIGTERM keeps
+ * `execFileSync` blocked past its timeout. Safe here — every call is read-only
+ * plumbing that takes no index lock (§ PSA).
+ *
+ * @param {number} deadline — epoch ms
+ * @returns {{run: (args: string[], cwd: string, opts?: {maxBuffer?: number}) => string,
+ *   exhausted: () => boolean}}
+ */
+function makeGitRunner(deadline) {
+  let exhausted = false;
+  const run = (args, cwd, { maxBuffer } = {}) => {
+    const remaining = Math.floor(deadline - Date.now());
+    if (remaining <= 0) {
+      exhausted = true;
+      throw new GitBudgetExhausted(args[0]);
+    }
+    try {
+      return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: remaining,
+        killSignal: 'SIGKILL',
+        ...(maxBuffer === undefined ? {} : { maxBuffer }),
+      });
+    } catch (e) {
+      if (e?.code === 'ETIMEDOUT') exhausted = true;
+      throw e;
+    }
+  };
+  return { run, exhausted: () => exhausted };
+}
+
+/**
+ * `git rev-parse --show-toplevel` of `cwd`, or `''` when git cannot say.
+ *
+ * @param {string} cwd
+ * @param {ReturnType<typeof makeGitRunner>} git
+ * @returns {string}
+ */
+function gitToplevel(cwd, git) {
+  try {
+    return git.run(['rev-parse', '--show-toplevel'], cwd).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Tracked files of the repo rooted at `root`, plus WHY the list is empty when
+ * it had to be (matrix row 8 — degrade, never deny, but leave a reason).
+ *
+ * @param {string} root — a git toplevel, or `''` when none could be resolved
+ * @param {ReturnType<typeof makeGitRunner>} git
+ * @returns {{files: string[], skipped?: 'budget-exhausted'|'git-error'}}
+ */
+function trackedFilesIn(root, git) {
+  const failed = () => ({ files: [], skipped: git.exhausted() ? 'budget-exhausted' : 'git-error' });
+  if (root === '') return failed();
+  try {
+    const stdout = git.run(['ls-files', '-z'], root, { maxBuffer: 32 * 1024 * 1024 });
+    return { files: stdout.split('\0').filter((f) => f.length > 0) };
+  } catch {
+    return failed();
+  }
+}
+
 /**
  * Tracked files, for glob expansion inside `findScopeCollisions`. The library is
  * pure and must not spawn — supplying this is precisely the hook's job.
@@ -1419,82 +1609,181 @@ function waveNumberOf(waveKey) {
  * That is the dangerous direction, because the hook is the last gate before the
  * write.
  *
+ * Standalone entry with its own `GIT_BUDGET_MS`; `main()` composes the same two
+ * steps under the deadline it shares with the worktree-base check.
+ *
  * @param {string} cwd
  * @returns {string[]}
  */
 export function listTrackedFiles(cwd) {
-  const opts = {
-    cwd,
-    encoding: 'utf8',
-    maxBuffer: 32 * 1024 * 1024,
-    stdio: ['ignore', 'pipe', 'ignore'],
-  };
-  try {
-    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], opts).trim();
-    if (!root) return [];
-    const stdout = execFileSync('git', ['ls-files', '-z'], { ...opts, cwd: root });
-    return stdout.split('\0').filter((f) => f.length > 0);
-  } catch {
-    return [];
-  }
+  const git = makeGitRunner(Date.now() + GIT_BUDGET_MS);
+  return trackedFilesIn(gitToplevel(cwd, git), git).files;
+}
+
+/**
+ * The SETTINGS ROOT (#1485) — where `harnessBaseRef()` reads the project's
+ * `.claude/settings{,.local}.json`: `$CLAUDE_PROJECT_DIR`, else the git toplevel
+ * of `cwd`, else `cwd`. The launch dir FIRST, unlike `resolveSessionRoot()`: it is the
+ * root the harness applies project settings from, and after entering a worktree
+ * the gitignored `settings.local.json` exists only there.
+ *
+ * @param {string} cwd — the payload `cwd`
+ * @param {string} cwdToplevel — `gitToplevel(cwd)`, `''` when git could not say
+ * @returns {string}
+ */
+function settingsRootOf(cwd, cwdToplevel) {
+  return (process.env.CLAUDE_PROJECT_DIR || '').trim() || cwdToplevel || cwd;
 }
 
 // ---------------------------------------------------------------------------
-// Stale worktree base (#1413) — a WARNING, never a decision
+// Stale worktree base (#1413 → #1485) — a MEASURED mismatch DENIES the dispatch
 //
 // `isolation: "worktree"` makes the HARNESS create `<repo>/.claude/worktrees/
 // agent-<hex>`; no code in this repo creates it and the `Agent` payload carries
-// no base-ref field (the 147-dispatch key census in the module docblock). The
-// base is the SESSION-START commit, and it does not follow a mid-session commit:
-// measured 2026-09-19 (session s18), worktrees created 25 minutes AFTER commit
-// `240efda6` still stood on its parent `8f15f77b`. A fix agent then silently
-// edits the OLD code, and its test run is structurally red on top — `validate-
-// plugin` is vitest's globalSetup and `check-guard-requires-parity.mjs` compares
-// against `git show HEAD:` inside the stale worktree.
+// no base-ref field (the 147-dispatch key census in the module docblock). Which
+// commit it branches from is documented harness behaviour (code.claude.com/docs
+// /en/worktrees § "Choose the base branch", read 2026-10-02): "Subagent worktrees
+// use the same base branch as `--worktree`, so they branch from your repository's
+// default branch unless `worktree.baseRef` is set to `"head"`" — `"fresh"` (the
+// default) is `origin/HEAD`, `"head"` is the current local HEAD.
+//
+// That REPLACES the #1413 model ("the base is the session-start commit"): it fit
+// s18 only because that session ran on `main`, where origin/main WAS the start
+// commit. #1485 measured the general case on a feature branch — agent worktrees
+// stood on `main` (`0efb3e97`), six commits behind the branch HEAD (`47c49652`),
+// so the agents silently edited old code. Owner decision 2026-10-02, option (a):
+// check with `git merge-base --is-ancestor` before dispatch and stop on mismatch.
 //
-// We have no lever on the base, so the only available fix is to be LOUD. This
-// never touches the verdict: the two functions below are TOTAL (every failure
-// resolves to silence), and the caller ignores their result for the decision.
+// ONLY A MEASURED MISMATCH DENIES (`is-ancestor` exit 1 in a full-history repo,
+// against a cached origin ref the harness will branch from as-is). Every
+// non-measurement — no origin/HEAD, a shallow clone, a cached ref the harness
+// refetches first (`stale-remote-ref`), a git failure, an exit code other than
+// 0/1, a throw — is `stale: null` + `skipped`, recorded and ALLOWED: unknown is
+// not mismatch, and this hook guards the dispatch path, where a wrong deny is a
+// session outage (§ the fail-open note at the bottom of this file).
+//
+// Where the hook's base and the harness's can still DIVERGE (Claude Code
+// 2.1.287 bundle, read 2026-10-02):
+//   - a settings layer this hook cannot read (`harnessBaseRef()`) — either way,
+//     wrong deny or missed mismatch, from any `base_ref_source`;
+//   - no `refs/remotes/origin/HEAD` symref: the harness falls back to
+//     `origin/main|master`, the hook skips `no-origin-head` — a missed mismatch
+//     only, never a wrong deny (measured 2026-10-02: 0 of 28 local repos lack
+//     the symref);
+//   - a stale FETCH_HEAD whose refetch then FAILS (offline): the harness keeps
+//     the cached ref, so the skipped deny would have been right — the price of
+//     not knowing in advance whether a fetch will succeed.
 // ---------------------------------------------------------------------------
 
+/** `worktree.baseRef` values the docs define; anything else sets nothing here. */
+const BASE_REF_VALUES = new Set(['head', 'fresh']);
+
+/**
+ * The harness refetches origin before branching a `"fresh"` worktree when
+ * FETCH_HEAD is older than this (Claude Code 2.1.287 bundle, read 2026-10-02:
+ * `Date.now() - mtimeMs > 86400000`, then `git fetch origin <default>` with a
+ * 5 s timeout). Revisit when the harness changes that constant — a mismatch
+ * either skips a real deny or lets a refetched base be denied again.
+ */
+const FETCH_REFRESH_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The harness's effective `worktree.baseRef`, as far as this hook can see it,
+ * and WHICH layer decided it — read in the documented precedence order (code.
+ * claude.com/docs/en/settings § "Settings precedence", read 2026-10-02): local
+ * → project → user, the FIRST file that sets the key to a defined value wins.
+ * No file sets it → `'fresh'` from `'default'`.
+ *
+ * `settingsRoot` is the SESSION ROOT, not the hook payload's `cwd`: that `cwd`
+ * follows the session's `cd` (docs/en/hooks § "cwd follows Claude"), while the
+ * project settings the harness applies belong to the root it started in.
+ *
+ * Read only on the rare `worktree` branch (14 of 147 measured dispatches carried
+ * `isolation` at all), so the hot dispatch path never pays these reads.
+ *
+ * NAMED CEILING (BV-004): blind to the two layers ABOVE local — managed settings
+ * and the `--settings` CLI flag. The error points BOTH ways: a `"head"` there
+ * with no visible file setting the key reads as `default` → `fresh` → a WRONG
+ * DENY when HEAD is ahead of origin/HEAD; a `"fresh"` there shadowing a visible
+ * `"head"` → a MISSED mismatch. Not read on purpose: `--settings` reaches no
+ * hook, and managed settings arrive through several delivery mechanisms (a
+ * `managed-settings.json` in a system dir, MDM/OS policy, server-managed settings
+ * from the claude.ai console, an embedding host's SDK option — docs settings
+ * § "Managed settings"), combined by their own intra-tier rules; reading the one
+ * file among them would turn an honest "invisible" into a partial view that
+ * still decides. The wrong-deny population is countable instead (HR-105): a
+ * hidden `"head"` with no visible file setting the key yields `decision:"deny"`
+ * records with `base_ref_source:"default"`; a hidden `"head"` shadowed by a
+ * visible `"fresh"` yields them under that file's source instead. Revisit if
+ * such a deny is reported in a session whose `/status` names a managed or
+ * `--settings` source carrying `worktree.baseRef`.
+ *
+ * @param {string} settingsRoot
+ * @returns {{baseRef: 'head'|'fresh', source: 'local'|'project'|'user'|'default'}}
+ */
+function harnessBaseRef(settingsRoot) {
+  const userDir = (process.env.CLAUDE_CONFIG_DIR || '').trim() || path.join(homedir(), '.claude');
+  for (const [source, file] of [
+    ['local', path.join(settingsRoot, '.claude', 'settings.local.json')],
+    ['project', path.join(settingsRoot, '.claude', 'settings.json')],
+    ['user', path.join(userDir, 'settings.json')],
+  ]) {
+    try {
+      const value = JSON.parse(readFileSync(file, 'utf8'))?.worktree?.baseRef;
+      if (BASE_REF_VALUES.has(value)) return { baseRef: value, source };
+    } catch { /* absent or unparseable — the next layer decides */ }
+  }
+  return { baseRef: 'fresh', source: 'default' };
+}
+
+/** Where each `base_ref_source` lives, for the operator-facing deny text. */
+const BASE_REF_SOURCE_LABEL = {
+  local: '.claude/settings.local.json',
+  project: '.claude/settings.json',
+  user: 'user settings.json',
+  default: 'the default — no settings file this hook can read sets it',
+};
+
 /**
  * Facts for the worktree-base check, as a DISCRIMINATED record with three
  * outcomes rather than two (#1424):
  *
- *   - `{stale: true|false, head, session_start_ref, subagent_type?}` — measured.
+ *   - `{stale: true|false, head, base, base_ref, base_ref_source, missing_commits?,
+ *     subagent_type?}` — measured. `stale` means "the worktree would MISS commits
+ *     of HEAD": `git merge-base --is-ancestor HEAD <base>` exited 1 in a repo
+ *     with full history and a FETCH_HEAD younger than `FETCH_REFRESH_MS` (so
+ *     the harness branches from that cached ref without refetching it first).
+ *     A base AHEAD of HEAD (origin moved on, HEAD contained)
+ *     is not stale — nothing of HEAD is lost. `base_ref_source` names the
+ *     settings layer that decided `base_ref` (`harnessBaseRef()`), so a wrong
+ *     deny from a layer this hook cannot read stays countable (HR-105).
  *   - `{stale: null, skipped: <reason>}` — the dispatch WAS on the `worktree`
  *     branch, but the question could not be answered honestly. Still emitted,
- *     because HR-105 needs the denominator: while every such case returned bare
- *     `null` and the caller emitted nothing, "the check never had anything to
- *     say" and "the check was silently disarmed" both read as zero records —
- *     precisely the shape this event exists to close.
- *   - `null` — `isolation !== 'worktree'`. SILENT by construction, and the one
- *     outcome that must stay so: `isolation` appeared in 14 of 147 measured
- *     dispatches, so recording the other ~90% would put the denominator on the
- *     whole hot dispatch path (HR-101).
- *
- * IDENTITY GATE (`.claude/rules/identity-and-locks.md`): `session-start-ref`
- * lives in STATE.md, a SHARED working-copy artefact that routinely belongs to a
- * peer session. It is read only when STATE.md's own `session-id` equals this
- * process's raw id (hook payload `session_id`, else `CLAUDE_CODE_SESSION_ID`) —
- * a process-local witness REPLACES the shared one, never unions with it. On
- * mismatch, absence or any read failure this reports `stale: null`: a confident
- * warning about somebody else's session is worse than no warning at all. The
- * test runs PER CANDIDATE (`continue`, not `break`) — see the loop below.
- *
- * `parseStateMd` is imported DYNAMICALLY and only on the rare `worktree` branch
- * (14 of 147 measured dispatches carried `isolation` at all): it is a leaf module
- * with zero imports and already inside the committed hook-import closure, so
- * reuse costs no new edge, and binding it late keeps a load failure catchable
- * instead of disarming the guard at ESM link time (§ #993 late-bound deps).
+ *     because HR-105 needs the denominator, and never denied (unknown ≠ mismatch).
+ *   - `null` — `isolation !== 'worktree'`. SILENT by construction: recording the
+ *     other ~90% of dispatches would put the denominator on the hot path (HR-101).
+ *
+ * TWO DIRECTORIES, deliberately different: git measures in `cwd` (the payload's,
+ * which follows the session's `cd` — git finds the enclosing repo from any
+ * subdirectory, and inside an entered worktree `"head"` means THAT worktree's
+ * HEAD); settings are read at `settingsRoot` (`settingsRootOf()` — the root the
+ * harness applies project settings from, which is NOT where the record lands:
+ * that is `resolveSessionRoot()`).
+ *
+ * Every git call draws on the hook fire's ONE shared deadline (`GIT_BUDGET_MS`).
+ * A call the budget cut short is no measurement: each skip then reads
+ * `git-budget`, whichever reason the cut call would otherwise have produced — a
+ * timed-out `origin/HEAD` lookup is not evidence that there is none.
  *
  * @param {{tool_input?: unknown}} input — the raw hook payload
- * @param {string} projectDir
- * @param {string} sessionId — `input.session_id`, or `'no-session'`
- * @returns {Promise<{head: string, session_start_ref: string, stale: boolean,
- *   subagent_type?: string}|{stale: null, skipped: string}|null>}
+ * @param {string} cwd — the hook payload's `cwd`
+ * @param {string} settingsRoot — `settingsRootOf()`
+ * @param {ReturnType<typeof makeGitRunner>} gitRunner — the fire's shared runner
+ * @returns {{head: string, base: string, base_ref: 'head'|'fresh',
+ *   base_ref_source: 'local'|'project'|'user'|'default', stale: boolean,
+ *   missing_commits?: number, subagent_type?: string}|{stale: null, skipped: string}|null}
  */
-async function worktreeBaseFacts(input, projectDir, sessionId) {
+function worktreeBaseFacts(input, cwd, settingsRoot, gitRunner) {
   // The applicability gate sits OUTSIDE the try on purpose: everything below it
   // resolves to a `skipped` RECORD, so a throw here must not be able to mint one
   // for a dispatch that was never on the `worktree` branch at all.
@@ -1502,98 +1791,106 @@ async function worktreeBaseFacts(input, projectDir, sessionId) {
   if (toolInput === null || typeof toolInput !== 'object') return null;
   if (toolInput.isolation !== 'worktree') return null;
 
+  /** @param {string} reason */
+  const skip = (reason) => ({ stale: null, skipped: gitRunner.exhausted() ? 'git-budget' : reason });
   try {
-    const ownId = sessionId && sessionId !== 'no-session'
-      ? sessionId
-      : (process.env.CLAUDE_CODE_SESSION_ID || '');
-    if (!ownId) return { stale: null, skipped: 'no-own-id' };
-
-    const { parseStateMd } = await import(
-      pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'state-md', 'yaml-parser.mjs')).href
-    );
-
-    // #1424: the identity test lives INSIDE the loop. Breaking at the first
-    // PARSEABLE STATE.md and testing `session-id` afterwards meant a single
-    // left-over `.pi/STATE.md` — `.pi` sorts before `.claude` in
-    // STATE_DIR_CANDIDATES — disarmed the check for a session whose own
-    // `.claude/STATE.md` sat right there, readable and matching. `sawStateMd`
-    // keeps the two silences apart afterwards: "nothing to read" is a different
-    // fact from "read, and none of it was mine".
-    let frontmatter = null;
-    let sawStateMd = false;
-    for (const dir of STATE_DIR_CANDIDATES) {
-      try {
-        const parsed = parseStateMd(readFileSync(path.join(projectDir, dir, 'STATE.md'), 'utf8'));
-        if (!parsed?.frontmatter) continue;
-        sawStateMd = true;
-        if (parsed.frontmatter['session-id'] !== ownId) continue;
-        frontmatter = parsed.frontmatter;
-        break;
-      } catch { /* try the next state dir */ }
-    }
-    if (frontmatter === null) {
-      return { stale: null, skipped: sawStateMd ? 'identity-mismatch' : 'no-state-md' };
-    }
-
-    const startRef = typeof frontmatter['session-start-ref'] === 'string'
-      ? frontmatter['session-start-ref'].trim()
-      : '';
-    if (startRef === '') return { stale: null, skipped: 'no-start-ref' };
+    /** @param {string[]} args */
+    const git = (args) => gitRunner.run(args, cwd).trim();
 
     let head = '';
-    try {
-      head = execFileSync('git', ['rev-parse', 'HEAD'], {
-        cwd: projectDir,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
-    } catch {
-      return { stale: null, skipped: 'git-error' };
-    }
-    if (head === '') return { stale: null, skipped: 'git-error' };
+    try { head = git(['rev-parse', '--verify', 'HEAD^{commit}']); } catch { /* below */ }
+    if (head === '') return skip('git-error');
 
-    const facts = { head, session_start_ref: startRef, stale: head !== startRef };
+    const { baseRef, source } = harnessBaseRef(settingsRoot);
+    const facts = { head, base_ref: baseRef, base_ref_source: source };
     if (typeof toolInput.subagent_type === 'string' && toolInput.subagent_type !== '') {
       facts.subagent_type = toolInput.subagent_type;
     }
-    return facts;
+    // `"head"` inside a worktree resolves to THAT worktree's HEAD (docs, same
+    // section) — the very `git rev-parse HEAD` above, run in `cwd`.
+    if (baseRef === 'head') return { ...facts, base: head, stale: false };
+
+    // `"fresh"`: origin/HEAD. Not cached locally → the harness fetches, or
+    // falls back to HEAD; neither outcome is knowable here → skip, not deny.
+    let base = '';
+    try { base = git(['rev-parse', '--verify', '--quiet', 'refs/remotes/origin/HEAD^{commit}']); } catch { /* below */ }
+    if (base === '') return skip('no-origin-head');
+    if (base === head) return { ...facts, base, stale: false };
+
+    try {
+      git(['merge-base', '--is-ancestor', head, base]);
+      return { ...facts, base, stale: false };
+    } catch (e) {
+      // Exit 1 is the ONE candidate "no"; 128 (bad object), a timeout or a
+      // signal is a non-measurement and must not accuse anybody.
+      if (e?.status !== 1) return skip('git-error');
+    }
+    // ...and exit 1 is a MEASUREMENT only over full history. A shallow clone's
+    // cut-off graph answers "no" for a HEAD that IS an ancestor (measured
+    // 2026-10-02: `clone --depth 1` + `fetch --depth 1` → exit 1, the full source
+    // → exit 0). Probed only here, on the rare "no": an exit 0, which no missing
+    // history can fake, never pays for it. A failed probe cannot rule shallow
+    // out, so it skips as well. ONE spawn answers both questions below (two
+    // lines, in argument order) — the deny path is the one that must finish
+    // inside the shared budget.
+    let shallow = '';
+    let fetchHeadPath = '';
+    try {
+      [shallow = '', fetchHeadPath = ''] = git(['rev-parse', '--is-shallow-repository', '--git-path', 'FETCH_HEAD'])
+        .split('\n')
+        .map((line) => line.trim());
+    } catch { /* below */ }
+    if (shallow !== 'false') return skip(shallow === 'true' ? 'shallow' : 'git-error');
+
+    // ...and only over a ref the harness will actually branch from. With
+    // FETCH_HEAD older than `FETCH_REFRESH_MS` (or absent — the harness reads
+    // that as mtime 0) it first fetches origin and branches from the FETCHED
+    // tip, which may well contain HEAD by now; this hook never fetches (network
+    // inside a 5 s PreToolUse budget), so the cached ref decides nothing here.
+    let fetchedMs = 0;
+    try { if (fetchHeadPath !== '') fetchedMs = statSync(path.resolve(cwd, fetchHeadPath)).mtimeMs; } catch { /* absent → stale */ }
+    if (Date.now() - fetchedMs > FETCH_REFRESH_MS) return { stale: null, skipped: 'stale-remote-ref' };
+
+    let missing = Number.NaN;
+    try { missing = Number.parseInt(git(['rev-list', '--count', `${base}..${head}`]), 10); } catch { /* optional */ }
+    return { ...facts, base, stale: true, ...(Number.isInteger(missing) ? { missing_commits: missing } : {}) };
   } catch {
-    // Total by construction: no parser, an unreadable state dir, anything else.
-    // Still a RECORD rather than silence — the dispatch WAS on the `worktree`
-    // branch, and a broken probe that emits nothing is indistinguishable from a
-    // probe that had nothing to report (#1424 / HR-105).
+    // Total by construction. Still a RECORD rather than silence (#1424 / HR-105).
     return { stale: null, skipped: 'probe-error' };
   }
 }
 
 /**
- * The operator-facing warning. It names the ACTION, not just the condition —
- * a warning the coordinator cannot act on is noise (HR-106).
- *
- * NO `⚠ ` PREFIX HERE: this text is handed to `emitWarn`, which prefixes it on
- * both channels it writes (stderr and the `systemMessage` payload). Prefixing
- * here too produced `⚠ ⚠ …`.
- *
- * @param {{head: string, session_start_ref: string}} facts
- * @returns {string}
+ * The deny reason + suggestion for a measured stale base. Names the ACTION, not
+ * just the condition (HR-106), and the settings layer that chose `"fresh"`: an
+ * operator whose `"head"` lives where this hook cannot read (managed settings,
+ * `--settings`) then reads "the default" and knows the deny rests on that blind
+ * spot. The reason stays ONE line: `emitDeny` lifts the first line into the
+ * operator-visible `systemMessage` headline.
+ *
+ * @param {{head: string, base: string, base_ref_source?: string, missing_commits?: number}} facts
+ * @returns {{reason: string, suggestion: string}}
  */
-function staleWorktreeWarning(facts) {
-  const head = facts.head.slice(0, 12);
-  const base = facts.session_start_ref.slice(0, 12);
-  return [
-    `${HOOK_NAME}: STALE WORKTREE BASE (#1413) — this dispatch uses `
-      + `isolation: "worktree", but HEAD (${head}) has moved past this session's `
-      + `session-start-ref (${base}).`,
-    '  The harness bases a new agent worktree on the SESSION-START commit and offers',
-    '  no base-ref field, so the agent will silently get the OLDER code — and its test',
-    '  run is structurally red on top (check-guard-requires-parity compares against',
-    '  `git show HEAD:`, and validate-plugin is vitest\'s globalSetup).',
-    '  DO ONE OF: dispatch this wave IN-PLACE (omit `isolation`) — or verify the base',
-    '  before trusting the agent\'s result:',
-    '    git worktree list --porcelain | awk -v h="$(git rev-parse HEAD)" '
-      + '\'/^worktree /{w=$2} /^HEAD /{if (w ~ /\\.claude\\/worktrees\\/agent-/ && $2 != h) '
-      + 'print "STALE " substr($2,1,12) " " w}\'',
-  ].join('\n');
+function staleWorktreeDeny(facts) {
+  const missing = Number.isInteger(facts.missing_commits)
+    ? `${facts.missing_commits} commit(s)`
+    : 'commits';
+  const from = BASE_REF_SOURCE_LABEL[facts.base_ref_source] ?? BASE_REF_SOURCE_LABEL.default;
+  return {
+    reason:
+      `${HOOK_NAME}: STALE WORKTREE BASE (#1485) — isolation: "worktree" would branch this `
+      + `agent from origin/HEAD ${facts.base.slice(0, 12)} (worktree.baseRef "fresh" from ${from}), `
+      + `which is missing ${missing} of HEAD ${facts.head.slice(0, 12)}; the agent would silently edit OLD code.`,
+    suggestion: [
+      'DO ONE OF:',
+      '  1. re-dispatch IN-PLACE — omit `isolation` (isolation "none");',
+      '  2. set `"worktree": {"baseRef": "head"}` in .claude/settings.json so agent',
+      '     worktrees branch from your local HEAD (code.claude.com/docs/en/worktrees) —',
+      '     a higher layer setting "fresh" (local settings, --settings, managed) overrides it;',
+      '  3. get HEAD into the default branch on origin and fetch, then re-dispatch.',
+      'Uncommitted changes reach no worktree under any base — commit first or go in-place.',
+    ].join('\n'),
+  };
 }
 
 /**
@@ -1749,9 +2046,11 @@ export function scopeDigestFields(files, prompt, digestFn) {
  * @param {string} [params.nowIso]            dispatch timestamp recorded on the entry
  * @param {(paths: string[]) => string} [params.digestFn] scope-digest function
  *   (injected for testability; defaults to the late-bound `scopeDigest`)
+ * @param {(entry: string) => string} [params.spellFn] scope-entry spelling rule
+ *   (injected for testability; defaults to the late-bound `scopeEntrySpelling`)
  * @returns {Verdict}
  */
-export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn }) {
+export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn, spellFn }) {
   const toolName = input?.tool_name;
   // Row 4: not our tool.
   if (toolName !== DISPATCH_TOOL) return { action: 'allow' };
@@ -1762,7 +2061,14 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   const at = typeof nowIso === 'string' ? nowIso : new Date().toISOString();
 
   const signal = extractScopeSignal(toolInput.prompt);
-  const files = signal.files;
+  // #1510 g — ONE spelling rule, scope-gate's, applied before the ledger, the
+  // digest and `promoteDirEntries` see an entry: `./scripts/lib` must reach the
+  // dir-promotion as `scripts/lib`, or a bare-dir claim stays a literal and
+  // compares disjoint with the files beneath it. Re-deduped on the spelling.
+  // Unbound (a direct importer that never ran `bootstrap()`) ⇒ entries as
+  // extracted; `findScopeCollisions` still spells both sides itself.
+  const spell = typeof spellFn === 'function' ? spellFn : scopeEntrySpelling;
+  const files = typeof spell === 'function' ? [...new Set(signal.files.map(spell))] : signal.files;
   const id = agentIdOf(toolInput);
   const priorAgents = (ledger !== null && ledger?.waveKey === waveKey && Array.isArray(ledger.agents))
     ? ledger.agents
@@ -1993,7 +2299,8 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
     'Two agents editing one file at the same time race each other (PSA-002). ' +
     'Give the file exactly ONE owner in the wave plan, or wait for the named ' +
     `agent(s) to finish and re-dispatch — a finished agent no longer blocks. ` +
-    `If the ledger is stale, delete ${LEDGER_REL}.`;
+    `If the ledger is stale, delete this session's ${ledgerPathsFor(sessionIdOf(input)).ledgerRel} ` +
+    '— never another session\'s file beside it, which holds that session\'s live claims.';
 
   // Deliberately NOT persisting the ledger on deny: the dispatch did not happen,
   // so recording it would make the retry-after-fix look like a duplicate.
@@ -2009,20 +2316,61 @@ async function main() {
   const input = await readStdin();
   if (!input) return emitAllow();
 
-  const projectDir = typeof input.cwd === 'string' && input.cwd !== ''
+  // The payload `cwd` follows the session's `cd`; it names the repo git measures
+  // in, and only through its git toplevel where this session's state lives
+  // (`resolveSessionRoot()`) — a `cd sub` must not move the ledger.
+  const cwd = typeof input.cwd === 'string' && input.cwd !== ''
     ? input.cwd
     : bannerProjectDir();
-  const sessionId = typeof input.session_id === 'string' ? input.session_id : 'no-session';
+  const sessionId = sessionIdOf(input);
 
   // Cheap pre-check: skip all I/O for the overwhelmingly common non-dispatch call.
   if (input.tool_name !== DISPATCH_TOOL) return emitAllow();
 
-  const waveKey = waveKeyOf(projectDir, sessionId, readFileSync);
-  const knownFiles = listTrackedFiles(projectDir);
+  // ONE git deadline for this whole fire (`GIT_BUDGET_MS`). Worst case 7 spawns
+  // against it: the toplevel below, up to 5 in `worktreeBaseFacts` (HEAD,
+  // origin/HEAD, is-ancestor, shallow+FETCH_HEAD, rev-list) and `ls-files`.
+  const git = makeGitRunner(Date.now() + GIT_BUDGET_MS);
+  const cwdToplevel = gitToplevel(cwd, git);
+  const sessionRoot = resolveSessionRoot(cwd, cwdToplevel);
+
+  const ownIds = new Set(readProcessLocalSessionIds({ hookInput: input }));
+  const waveKey = waveKeyOf(sessionRoot, sessionId, readFileSync, ownIds);
   // `selfUseId`: this dispatch's own tool_use may already stand in the transcript
   // and must not make a finished same-named predecessor look alive (#1480 A).
   const isFinished = makeFinishedProbe({ transcriptPath: input.transcript_path, selfUseId: input.tool_use_id });
-  const ledgerPath = path.join(projectDir, LEDGER_REL);
+  const { ledgerRel, lockRel } = ledgerPathsFor(sessionId);
+  const ledgerPath = path.join(sessionRoot, ledgerRel);
+
+  // #1485 — the stale-worktree-base verdict, computed BEFORE the ledger cycle
+  // (and outside the lock: its git spawns hold nobody up there). It never
+  // reads the collision verdict and a collision DENY always wins; on its own it
+  // denies ONLY a measured mismatch (`stale === true`). Every skip is allowed.
+  // It must be known before the cycle because a dispatch this check will deny
+  // never happens, so the cycle must not persist it: a phantom claim would make
+  // the deny's own remedy — the same agent re-dispatched in place under a new
+  // tool_use_id — collide with it for up to `IN_FLIGHT_TTL_MS`.
+  //
+  // It draws on the shared budget BEFORE the tracked-file listing: a missed
+  // stale base has no later gate (matrix row 15), a missed listing only
+  // degrades glob expansion, and three later gates still see a collision.
+  const worktreeBase = worktreeBaseFacts(input, cwd, settingsRootOf(cwd, cwdToplevel), git);
+  const staleDeny = worktreeBase?.stale === true ? staleWorktreeDeny(worktreeBase) : null;
+
+  // Listed at `cwd`'s toplevel ONLY: the declared paths are repo-relative to the
+  // repo the agents edit, which is the one the session works in (after entering
+  // a worktree: that worktree). Whenever git resolved it, it IS `sessionRoot` —
+  // except inside a harness agent worktree, which `sessionRoot` lifts to its
+  // parent (#1492) and which lists the same repo's files from its own HEAD, and
+  // in a session launched in a repo SUBDIRECTORY, where `sessionRoot` is that
+  // launch dir and the listing stays at the toplevel above it;
+  // when git could not, `sessionRoot` falls back to a `.git` ancestor (git just
+  // failed there), `$CLAUDE_PROJECT_DIR` or a bare `cwd` — another repo, or a
+  // subdirectory from which `ls-files` answers subdir-relative (the review-MED
+  // class above) — so the listing degrades (matrix row 8) instead of following
+  // it there.
+  const known = trackedFilesIn(cwdToplevel, git);
+  const knownFiles = known.files;
 
   // The read-modify-write CYCLE, run under the ledger lock below. Everything
   // inside is synchronous and emits NOTHING — an emit here would `process.exit()`
@@ -2036,7 +2384,15 @@ async function main() {
     } catch (err) {
       // Absent ledger is the normal first-dispatch case, NOT corruption (row 7
       // must not fire on every wave's first agent).
-      if (err?.code !== 'ENOENT') ledgerCorrupt = true;
+      if (err?.code !== 'ENOENT') {
+        ledgerCorrupt = true;
+      } else {
+        // #1493.3 migration: claims this session recorded in the shared
+        // pre-#1493 file before the split still bind. Read, never touched.
+        let legacyRaw = null;
+        try { legacyRaw = readFileSync(path.join(sessionRoot, LEGACY_LEDGER_REL), 'utf8'); } catch { /* absent */ }
+        ledger = adoptLegacyLedger(legacyRaw, sessionId);
+      }
     }
 
     const verdict = decide({
@@ -2049,7 +2405,9 @@ async function main() {
       isFinished,
     });
 
-    if (verdict.ledger) {
+    // Not on a stale-base deny — the same rule as the collision deny path
+    // (`decide()`, "Deliberately NOT persisting the ledger on deny").
+    if (verdict.ledger && staleDeny === null) {
       try {
         writeJsonAtomicSync(ledgerPath, verdict.ledger);
       } catch {
@@ -2061,7 +2419,7 @@ async function main() {
   };
 
   let verdict;
-  const lockPath = path.join(projectDir, LEDGER_LOCK_REL);
+  const lockPath = path.join(sessionRoot, lockRel);
   try {
     mkdirSync(path.dirname(lockPath), { recursive: true });
   } catch { /* the unlocked fallback below still works */ }
@@ -2094,72 +2452,75 @@ async function main() {
   // import is dynamic so a checkout without `scripts/lib/events.mjs` degrades to
   // silence instead of crashing (§ Import safety), and the catch guarantees a
   // failed write cannot change the verdict or the exit code.
+  //
+  // `decide()` never sees the stale-base check, so its `ledger_result` describes
+  // the COLLISION verdict alone. When the stale base is what actually blocks the
+  // dispatch (no collision deny beside it — that one keeps `deny`), the record
+  // says so (#1489 Pkt 8): recorded as `allow`, a refused dispatch counted as a
+  // dispatched one in every later query. The replaced value survives as
+  // `collision_result`, so a `warn-ledger-corrupt` / `warn-not-evaluable` behind
+  // a stale-base deny is not reported on stderr alone.
   if (verdict.telemetry) {
+    const telemetry = {
+      ...verdict.telemetry,
+      ...(staleDeny !== null && verdict.action !== 'deny'
+        ? { ledger_result: 'deny-stale-base', collision_result: verdict.telemetry.ledger_result }
+        : {}),
+      ...(known.skipped === undefined ? {} : { known_files_skipped: known.skipped }),
+    };
     try {
       const { emitEvent, sessionAttribution } = await import(
         pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'events.mjs')).href
       );
       await emitEvent(
         SCOPE_EVENT,
-        { hook: HOOK_NAME, ...verdict.telemetry, ...sessionAttribution(projectDir) },
-        { repoRoot: projectDir }
+        { hook: HOOK_NAME, ...telemetry, ...sessionAttribution(sessionRoot) },
+        { repoRoot: sessionRoot }
       );
     } catch { /* observability is best-effort — it never blocks the decision */ }
   }
 
-  // #1413 — the stale-worktree-base warning, also awaited BEFORE the terminal
-  // emit for the same process.exit() reason as the block above. It reads
-  // `verdict` not at all: it can never turn an allow into a deny, and a git or
-  // STATE.md failure resolves to silence rather than to a wrong accusation.
-  //
-  // ROUTED TO THE OPERATOR, not to stderr alone (w3-5): under the exit-0
-  // PreToolUse protocol stderr goes nowhere — `io.mjs:545` calls it the "Debug
-  // channel … Invisible under exit 0" — so the first cut of this check announced
-  // the s18 incident class to a log and to nobody. The visible channel is the
-  // top-level `systemMessage`, i.e. `emitWarn`, which carries NO
-  // `permissionDecision` and therefore still means ALLOW (io.mjs § "which is
-  // precisely what keeps warn non-blocking").
-  //
-  // The note is CARRIED to the single terminal emit below rather than emitted
-  // here, because `emitWarn` calls `process.exit(0)` and never returns — warning
-  // inline would terminate the process before a collision DENY could be emitted,
-  // flipping a block into an allow (§ stdout discipline, the same reason
-  // `decide()` is pure).
+  // #1485 — the stale-worktree-base record (verdict computed above, before the
+  // cycle), awaited BEFORE the terminal emit for the same process.exit() reason
+  // as the block above.
   //
   // `null` here means "not a worktree dispatch" and stays silent; ANY other
   // shape is emitted, including the `{stale: null, skipped: …}` non-measurements
-  // (#1424). The warning still fires on `stale === true` alone — a skipped probe
-  // accuses nobody.
-  const worktreeBase = await worktreeBaseFacts(input, projectDir, sessionId);
-  let staleNote = null;
+  // (#1424), with this check's own `decision` folded into the SAME record
+  // rather than a second event.
   if (worktreeBase !== null) {
-    if (worktreeBase.stale === true) staleNote = staleWorktreeWarning(worktreeBase);
     try {
       const { emitEvent, sessionAttribution } = await import(
         pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'events.mjs')).href
       );
       await emitEvent(
         WORKTREE_BASE_EVENT,
-        { hook: HOOK_NAME, ...worktreeBase, ...sessionAttribution(projectDir) },
-        { repoRoot: projectDir }
+        {
+          hook: HOOK_NAME,
+          ...worktreeBase,
+          decision: staleDeny === null ? 'allow' : 'deny',
+          ...sessionAttribution(sessionRoot),
+        },
+        { repoRoot: sessionRoot }
       );
     } catch { /* observability is best-effort — it never blocks the decision */ }
   }
 
-  // ONE terminal emit, with the #1413 note folded in where a visible channel is
-  // free. On DENY the dispatch does not happen and `systemMessage` already
-  // carries the ⛔ headline, so the note stays on the debug channel — a stale
-  // base is moot for a dispatch that was just blocked.
+  // ONE terminal emit. A collision DENY keeps its own reason — the dispatch is
+  // blocked either way — and the stale base goes to the debug channel beside it.
   if (verdict.action === 'deny') {
-    if (staleNote !== null) {
-      try { console.error(`⚠ ${staleNote}`); } catch { /* stderr may be closed */ }
+    if (staleDeny !== null) {
+      try { console.error(`⚠ ${staleDeny.reason}`); } catch { /* stderr may be closed */ }
     }
     return emitDeny(verdict.reason, verdict.suggestion);
   }
-  if (verdict.action === 'warn') {
-    return emitWarn(staleNote === null ? verdict.note : `${verdict.note}\n\n${staleNote}`);
+  if (staleDeny !== null) {
+    if (verdict.action === 'warn') {
+      try { console.error(`⚠ ${verdict.note}`); } catch { /* stderr may be closed */ }
+    }
+    return emitDeny(staleDeny.reason, staleDeny.suggestion);
   }
-  if (staleNote !== null) return emitWarn(staleNote);
+  if (verdict.action === 'warn') return emitWarn(verdict.note);
   return emitAllow();
 }
 
@@ -2207,9 +2568,10 @@ if (invokedAsScript()) {
   //      `enforce-scope`'s fail-closed handler — and the reason is the asymmetry
   //      named in the matrix header: enforce-scope guards a WRITE (denying one
   //      write is cheap), this guards the DISPATCH path (denying every dispatch
-  //      is a session outage). The bug this could hide is caught downstream by
+  //      is a session outage). A hidden COLLISION is caught downstream by
   //      `validate-wave-scope.mjs` and by `enforce-scope` at write time; a
-  //      wrongly-denied dispatch is caught by nothing.
+  //      hidden #1485 stale base is not (matrix row 15) — the accepted cost of
+  //      the same asymmetry; a wrongly-denied dispatch is caught by nothing.
   // -------------------------------------------------------------------------
   try {
     await bootstrap();