session-orchestrator 5.2.0 → 5.3.0

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

@@ -288,6 +288,29 @@ const SHAPE_NONE = 'none';
 /** The per-dispatch observability record (#1092) — see § Observability. */
 const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
 
+/**
+ * The worktree-base observability record (#1413).
+ *
+ * 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`.
+ *
+ * #1424 widened "every outcome" from two to three: the `stale: true|false`
+ * split was already covered, but each NON-measurement (peer STATE.md, no
+ * STATE.md, no `session-start-ref`, a git failure) returned early and emitted
+ * nothing — so the gate in front of the split reproduced exactly the
+ * zero-records ambiguity the split had removed. Those now carry
+ * `stale: null` plus a `skipped` reason, and only `isolation !== "worktree"`
+ * stays silent (HR-101: it is ~90% of all dispatches).
+ */
+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
@@ -981,6 +1004,163 @@ export function listTrackedFiles(cwd) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Stale worktree base (#1413) — a WARNING, never a decision
+//
+// `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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+/**
+ * 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: 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).
+ *
+ * @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>}
+ */
+async function worktreeBaseFacts(input, projectDir, sessionId) {
+  // 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.
+  const toolInput = input?.tool_input;
+  if (toolInput === null || typeof toolInput !== 'object') return null;
+  if (toolInput.isolation !== 'worktree') return null;
+
+  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' };
+
+    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' };
+
+    const facts = { head, session_start_ref: startRef, stale: head !== startRef };
+    if (typeof toolInput.subagent_type === 'string' && toolInput.subagent_type !== '') {
+      facts.subagent_type = toolInput.subagent_type;
+    }
+    return facts;
+  } 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).
+    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}
+ */
+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');
+}
+
 /**
  * Clip a path for the deny reason without losing the discriminating tail.
  *
@@ -1440,8 +1620,59 @@ async function main() {
     } catch { /* observability is best-effort — it never blocks the decision */ }
   }
 
-  if (verdict.action === 'deny') return emitDeny(verdict.reason, verdict.suggestion);
-  if (verdict.action === 'warn') return emitWarn(verdict.note);
+  // #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).
+  //
+  // `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;
+  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 }
+      );
+    } 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.
+  if (verdict.action === 'deny') {
+    if (staleNote !== null) {
+      try { console.error(`⚠ ${staleNote}`); } 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 (staleNote !== null) return emitWarn(staleNote);
   return emitAllow();
 }
 

package/hooks/subagent-telemetry.mjs

@@ -105,14 +105,14 @@
  */
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('subagent-telemetry')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { appendSubagent } from '../scripts/lib/subagents-schema.mjs';
 import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
+import { readTailWindow } from '../scripts/lib/tail-window.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -593,25 +593,18 @@ function resolveSubagentTranscriptPath(parentTranscriptPath, agentId) {
  * @returns {number|null} epoch-ms of the matching start, or null
  */
 function findStartTimestampMs(filePath, agentId) {
-  let fd;
   try {
     if (typeof agentId !== 'string' || !agentId.trim()) return null;
     if (!fs.existsSync(filePath)) return null;
 
-    const { size } = fs.statSync(filePath);
-    if (size === 0) return null;
+    const window = readTailWindow(filePath, START_JOIN_TAIL_BYTES);
+    if (window.size === 0) return null;
 
-    const readLen = Math.min(size, START_JOIN_TAIL_BYTES);
-    const from = size - readLen;
-    const buf = Buffer.allocUnsafe(readLen);
-    fd = fs.openSync(filePath, 'r');
-    fs.readSync(fd, buf, 0, readLen, from);
-
-    const lines = buf.toString('utf8').split('\n');
+    const lines = window.text.split('\n');
     // When the window does not cover the whole file, the first element is a
     // record sliced mid-line (possibly mid-UTF-8-sequence). Drop it rather than
     // feed a corrupt fragment to JSON.parse.
-    if (from > 0) lines.shift();
+    if (window.cut) lines.shift();
 
     for (let i = lines.length - 1; i >= 0; i--) {
       const line = lines[i].trim();
@@ -631,10 +624,6 @@ function findStartTimestampMs(filePath, agentId) {
     return null;
   } catch {
     return null;
-  } finally {
-    if (fd !== undefined) {
-      try { fs.closeSync(fd); } catch { /* ignore */ }
-    }
   }
 }
 
@@ -815,5 +804,12 @@ async function main() {
   await appendSubagent(jsonlPath(), record);
 }
 
-// Exit 0 always — informational hook must never block Claude.
-main().catch(() => {}).finally(() => process.exit(0));
+// Entry guard (#1393): run only as the node script the harness execs — a bare
+// `import()` must run no handler and must not exit the importing process.
+if (isMainModule(import.meta.url)) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('subagent-telemetry')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block Claude.
+  main().catch(() => {}).finally(() => process.exit(0));
+}

package/hooks/wave-scope-commit-guard.mjs

@@ -41,63 +41,7 @@ import { join } from 'node:path';
 // consumer repo or a test tmp-dir.
 import { pathMatchesPattern, findScopeFile } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
-
-const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-// #801: resolve wave-scope.json via the same precedence every other reader
-// uses (.pi/.cursor/.codex/.claude — scope-gate.mjs findScopeFile). The prior
-// hardcoded `.orchestrator/wave-scope.json` path was DEAD — the coordinator
-// writes wave-scope.json to the state dir (.claude/ on Claude Code; see
-// skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
-// returns null when no scope file exists at any precedence dir, preserving
-// the "no active wave → exit 0" semantics below.
-const scopePath = findScopeFile(repoRoot);
-const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
-
-// ---------------------------------------------------------------------------
-// Sub-mode B — allowedPaths check
-// ---------------------------------------------------------------------------
-
-const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
-const stagedFiles = stagedOutput.split('\n').filter(Boolean);
-
-if (scopePath) {
-  let scope;
-  try {
-    scope = JSON.parse(readFileSync(scopePath, 'utf8'));
-  } catch (err) {
-    process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
-    process.exit(1);
-  }
-
-  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
-  if (allowedPaths.length > 0) {
-    const violations = stagedFiles.filter(
-      (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
-    );
-
-    if (violations.length > 0) {
-      process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
-      for (const v of violations) process.stderr.write(`  - ${v}\n`);
-      process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
-      process.stderr.write('To proceed:\n');
-      process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
-      process.stderr.write('  2) git commit                    # retry\n');
-      process.exit(1);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Sub-mode C — cross-agent staging-fence reconciliation (issue #552)
-// ---------------------------------------------------------------------------
-//
-// Skip entirely when no fence dir exists OR no staged files. The fence dir
-// only appears when a wave-agent invoked `git add` while SO_WAVE_AGENT=1.
-// Manual / coordinator commits never write a fence file, so this branch
-// short-circuits to exit 0 for them (AC5 safe-default).
-if (!existsSync(fenceDir) || stagedFiles.length === 0) {
-  process.exit(0);
-}
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // Resolve the "current" agent id from SO_WAVE_AGENT_ID (when set by the
 // caller) or fall back to a PID-derived marker. The fence files themselves
@@ -105,11 +49,20 @@ if (!existsSync(fenceDir) || stagedFiles.length === 0) {
 // fence entries (we cross-check against SIBLINGS, not ourselves).
 const ownAgentId = process.env.SO_WAVE_AGENT_ID ?? null;
 
+/**
+ * Recorded by the writer when a staging command stages a set no path operand
+ * names (`git add -A`, `git add .`, `git add -u`). Overlaps everything.
+ * Mirrors ALL_PATHS_MARKER in hooks/pre-bash-staging-fence.mjs.
+ */
+const ALL_PATHS_MARKER = '*';
+
 /**
  * Build a regex that finds a staged path inside a `git add` command string.
  * Word-boundary on both sides so `src/foo.ts` does not match `src/foo.ts.bak`.
  * The path is escaped so glob metacharacters (`*`, `?`) and shell metas
  * cannot be reinterpreted.
+ *
+ * LEGACY PATH ONLY since #1404 — see the fallback branch in findOverlaps.
  */
 function pathRegex(p) {
   const escaped = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -117,8 +70,56 @@ function pathRegex(p) {
 }
 
 /**
- * Walk a single sibling fence file and return the staged paths whose path
- * pattern matches any of our staged files.
+ * Normalise a path token so reader and writer compare the same spelling.
+ *
+ * DELIBERATE DUPLICATE of the identically-named function in
+ * hooks/pre-bash-staging-fence.mjs: this guard is a husky pre-commit hook
+ * outside the Claude-Code hook import set, and the two sides must agree byte
+ * for byte. Change one, change both.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeStagedPath(raw) {
+  let p = String(raw).trim();
+  while (p.startsWith('./')) p = p.slice(2);
+  p = p.replace(/\/{2,}/g, '/');
+  while (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  return p;
+}
+
+/**
+ * Does a path a sibling recorded overlap one of OUR staged files? Both sides
+ * arrive already normalised. A DIRECTORY entry overlaps every file beneath it
+ * (`src` overlaps `src/foo.ts`); the marker overlaps everything.
+ *
+ * @param {string} fencePath
+ * @param {string} ourPath
+ * @returns {boolean}
+ */
+function pathsOverlap(fencePath, ourPath) {
+  if (fencePath === ALL_PATHS_MARKER) return true;
+  if (fencePath === ourPath) return true;
+  return ourPath.startsWith(`${fencePath}/`);
+}
+
+/**
+ * Walk a single sibling fence file and return the staged paths a sibling
+ * agent also recorded an intent to stage.
+ *
+ * Two entry shapes are accepted:
+ *  - #1404 shape `{ paths, command_hash, timestamp }` — path LISTS compared
+ *    against our staged set.
+ *  - LEGACY shape `{ command, timestamp }` — a fence file written by a
+ *    pre-#1404 hook version. Live sessions on this host may hold such files
+ *    RIGHT NOW, and dropping them would read as "no overlap" — silently
+ *    weaker than before the change. So the old raw-command regex still runs
+ *    for an entry that has `command` and no `paths`.
+ *    NAMED CEILING (BV-004): this fallback exists only to span the sessions
+ *    running across the upgrade. REVISIT TRIGGER — remove it one minor
+ *    release after 5.3.0 (i.e. in 5.4.0), by which point no process started
+ *    before the upgrade can still be writing fence files. The command text it
+ *    reads is never PRINTED (issue #1404) — only the fact of the match is.
  */
 function findOverlaps(fenceJsonPath, ourStaged) {
   let body;
@@ -131,61 +132,157 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   if (!Array.isArray(body.staged_paths)) return [];
   if (ownAgentId && body.agent_id === ownAgentId) return []; // skip self
 
+  const siblingAgent = body.agent_id ?? '<unknown>';
   const matches = [];
   for (const entry of body.staged_paths) {
+    if (Array.isArray(entry?.paths)) {
+      const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
+      for (const raw of entry.paths) {
+        if (typeof raw !== 'string') continue;
+        const fencePath = normalizeStagedPath(raw);
+        for (const ours of ourStaged) {
+          if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
+            matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
+          }
+        }
+      }
+      continue;
+    }
+
     const cmd = entry?.command;
     if (typeof cmd !== 'string') continue;
     for (const ours of ourStaged) {
       if (pathRegex(ours).test(cmd)) {
-        matches.push({ ourPath: ours, siblingAgent: body.agent_id ?? '<unknown>', cmd });
+        matches.push({
+          ourPath: ours,
+          siblingAgent,
+          fencePath: '<legacy entry, pre-#1404>',
+          hash: '<legacy entry, pre-#1404>',
+        });
       }
     }
   }
   return matches;
 }
 
-let overlaps = [];
-
-try {
-  await withStagingFenceLock(
-    repoRoot,
-    async () => {
-      let entries;
-      try {
-        entries = readdirSync(fenceDir);
-      } catch {
-        return;
-      }
-      for (const name of entries) {
-        if (!name.endsWith('.json')) continue;
-        if (name.startsWith('.')) continue; // skip .commit.lock, tmp files
-        const overlapsFromFile = findOverlaps(join(fenceDir, name), stagedFiles);
-        overlaps = overlaps.concat(overlapsFromFile);
+/**
+ * Both sub-modes, in the order the pre-commit hook needs them. Every statement
+ * here used to sit at module top level, which meant a bare `import()` of this
+ * file ran `git rev-parse` / `git diff --cached` and could exit the IMPORTING
+ * process with 1 (#1393). Moved into a function so the entry guard below can
+ * gate it; the logic and its exit codes are unchanged.
+ */
+async function main() {
+  const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+  // #801: resolve wave-scope.json via the same precedence every other reader
+  // uses (.pi/.cursor/.codex/.claude — scope-gate.mjs findScopeFile). The prior
+  // hardcoded `.orchestrator/wave-scope.json` path was DEAD — the coordinator
+  // writes wave-scope.json to the state dir (.claude/ on Claude Code; see
+  // skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
+  // returns null when no scope file exists at any precedence dir, preserving
+  // the "no active wave → exit 0" semantics below.
+  const scopePath = findScopeFile(repoRoot);
+  const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
+
+  // -------------------------------------------------------------------------
+  // Sub-mode B — allowedPaths check
+  // -------------------------------------------------------------------------
+
+  const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+  const stagedFiles = stagedOutput.split('\n').filter(Boolean);
+
+  if (scopePath) {
+    let scope;
+    try {
+      scope = JSON.parse(readFileSync(scopePath, 'utf8'));
+    } catch (err) {
+      process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
+      process.exit(1);
+    }
+
+    const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+    if (allowedPaths.length > 0) {
+      const violations = stagedFiles.filter(
+        (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
+      );
+
+      if (violations.length > 0) {
+        process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
+        for (const v of violations) process.stderr.write(`  - ${v}\n`);
+        process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
+        process.stderr.write('To proceed:\n');
+        process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
+        process.stderr.write('  2) git commit                    # retry\n');
+        process.exit(1);
       }
-    },
-    { timeoutMs: 5000 },
-  );
-} catch (err) {
-  // Lock acquisition failed — emit a warning but do NOT block the commit.
-  // The race-detection layer is opportunistic; a lock-acquire timeout is
-  // strictly less severe than blocking a legitimate commit on flaky FS.
-  process.stderr.write(
-    `⚠ wave-scope-commit-guard: staging-fence lock failed — ${err?.message ?? err}\n`,
-  );
-  process.exit(0);
-}
+    }
+  }
 
-if (overlaps.length > 0) {
-  process.stderr.write('✗ wave-scope-commit-guard: staging-fence: cross-agent overlap detected:\n');
-  for (const o of overlaps) {
-    process.stderr.write(`  - ${o.ourPath} (also staged by sibling agent ${o.siblingAgent})\n`);
+  // -------------------------------------------------------------------------
+  // Sub-mode C — cross-agent staging-fence reconciliation (issue #552)
+  // -------------------------------------------------------------------------
+  //
+  // Skip entirely when no fence dir exists OR no staged files. The fence dir
+  // only appears when a wave-agent invoked `git add` while SO_WAVE_AGENT=1.
+  // Manual / coordinator commits never write a fence file, so this branch
+  // short-circuits to exit 0 for them (AC5 safe-default).
+  if (!existsSync(fenceDir) || stagedFiles.length === 0) {
+    process.exit(0);
   }
-  process.stderr.write('\nAnother wave-agent recorded a `git add` for one or more of your staged paths.\n');
-  process.stderr.write('To proceed:\n');
-  process.stderr.write('  1) Coordinate with the sibling agent OR\n');
-  process.stderr.write('  2) git restore --staged <path>   # for each conflicting path, then retry\n');
-  process.stderr.write('  3) git commit --no-verify        # bypass (PSA-001/PSA-003 risk — operator opt-out)\n');
-  process.exit(1);
+
+  let overlaps = [];
+
+  try {
+    await withStagingFenceLock(
+      repoRoot,
+      async () => {
+        let entries;
+        try {
+          entries = readdirSync(fenceDir);
+        } catch {
+          return;
+        }
+        for (const name of entries) {
+          if (!name.endsWith('.json')) continue;
+          if (name.startsWith('.')) continue; // skip .commit.lock, tmp files
+          const overlapsFromFile = findOverlaps(join(fenceDir, name), stagedFiles);
+          overlaps = overlaps.concat(overlapsFromFile);
+        }
+      },
+      { timeoutMs: 5000 },
+    );
+  } catch (err) {
+    // Lock acquisition failed — emit a warning but do NOT block the commit.
+    // The race-detection layer is opportunistic; a lock-acquire timeout is
+    // strictly less severe than blocking a legitimate commit on flaky FS.
+    process.stderr.write(
+      `⚠ wave-scope-commit-guard: staging-fence lock failed — ${err?.message ?? err}\n`,
+    );
+    process.exit(0);
+  }
+
+  if (overlaps.length > 0) {
+    process.stderr.write('✗ wave-scope-commit-guard: staging-fence: cross-agent overlap detected:\n');
+    for (const o of overlaps) {
+      process.stderr.write(
+        `  - ${o.ourPath} (sibling agent ${o.siblingAgent} recorded ${o.fencePath}, command ${o.hash})\n`,
+      );
+    }
+    process.stderr.write('\nAnother wave-agent recorded a `git add` for one or more of your staged paths.\n');
+    process.stderr.write('To proceed:\n');
+    process.stderr.write('  1) Coordinate with the sibling agent OR\n');
+    process.stderr.write('  2) git restore --staged <path>   # for each conflicting path, then retry\n');
+    process.stderr.write('  3) git commit --no-verify        # bypass (PSA-001/PSA-003 risk — operator opt-out)\n');
+    process.exit(1);
+  }
+
+  process.exit(0);
 }
 
-process.exit(0);
+// Entry guard (#1393): run only as the node script `.husky/pre-commit` execs —
+// a bare `import()` must run no git command and must not exit the importing
+// process. No shouldRunHook gate here: this file is NOT registered in
+// hooks/hooks.json, so the profile-gate never governed it.
+if (isMainModule(import.meta.url)) {
+  await main();
+}