session-orchestrator 5.2.0 → 5.4.0

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
@@ -133,7 +133,16 @@ function jsonlPath() {
  * Defense-in-depth byte ceiling for transcript reads (#624). The transcript path
  * is harness-trusted, so this is not an exploitable vector — but the repo follows
  * a bounded-read discipline: a pathologically large transcript is skipped (yields
- * the empty/zero-usage result) rather than read whole into memory.
+ * the null-usage result) rather than read whole into memory.
+ *
+ * CEILING: a skipped transcript yields a stop record with found=true but null
+ * tokens and model; the session rollup counts it as an unpriced cost candidate
+ * (#1474) instead of reading it. Frequency per issue #1474 (2026-09-29): 2 of
+ * 10,482 subagent transcripts exceeded this size. REVISIT when oversized
+ * transcripts exceed ~0.1% of found stop records — count them from transcript
+ * sizes, because the ledger writes the same token-less record for an oversized,
+ * a usage-free and an unreadable transcript — then read large transcripts
+ * streamed instead of skipping them.
  */
 const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // ~50 MB
 
@@ -423,13 +432,23 @@ function readStdinJson() {
  * Four buckets, not two (#1244 / schema_version 2): `input_tokens`,
  * `cache_read_input_tokens`, `cache_creation_input_tokens` and `output_tokens`
  * are accumulated SEPARATELY per deduped turn, because they are billed at three
- * different rates. `model` is captured from `message.model` of the last kept
- * block that carries one (null when absent) — it is what makes a cost estimate
- * possible at all downstream.
+ * different rates. `model` is what makes a cost estimate possible at all
+ * downstream, so it names only a model that actually carried tokens (#1470): a
+ * kept turn is token-bearing when its four clamped buckets sum to > 0. Exactly
+ * one distinct `message.model` across the token-bearing turns → that model;
+ * zero-token turns of another model (a trailing `<synthetic>` turn) are ignored.
+ * Two or more, or a token-bearing turn that names no model → null, an honest
+ * unknown, with the token sums unchanged. No token-bearing turn at all → the
+ * last kept block that carries one (null when absent). Two or more models with
+ * every token-bearing turn named → `modelsUsage` carries the four buckets per
+ * model, so the session rollup can price each part; otherwise it is null.
  *
  * @param {string|undefined|null} transcriptPath — absolute path from stdin
  * @returns {{ tokenInputUncached: number|null, tokenCacheRead: number|null,
- *   tokenCacheCreation: number|null, tokenOutput: number|null, model: string|null }}
+ *   tokenCacheCreation: number|null, tokenOutput: number|null, model: string|null,
+ *   modelsUsage: Array<{ model: string, token_input_uncached: number,
+ *     token_cache_read: number, token_cache_creation: number,
+ *     token_output: number }>|null }}
  */
 function extractTranscriptUsage(transcriptPath) {
   const nullResult = {
@@ -438,6 +457,7 @@ function extractTranscriptUsage(transcriptPath) {
     tokenCacheCreation: null,
     tokenOutput: null,
     model: null,
+    modelsUsage: null,
   };
   try {
     if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return nullResult;
@@ -523,22 +543,73 @@ function extractTranscriptUsage(transcriptPath) {
     let tokenCacheRead = 0;
     let tokenCacheCreation = 0;
     let tokenOutput = 0;
+    /** Last non-null model over ALL kept turns — the zero-token fallback. */
     let model = null;
+    /** Per-model bucket sums of the token-bearing kept turns (#1470). */
+    const billedModels = new Map();
+    /** A token-bearing turn that names no model: its price is unknowable. */
+    let unattributed = false;
+    // Per-turn clamp (#624): a turn's value counts ONLY when it is a non-negative
+    // integer. A poisoned value (negative, NaN, float like 10.5) contributes 0 so
+    // the good turns survive. An absent side contributes 0, not null.
+    const clamp = (value) => (Number.isInteger(value) && value >= 0 ? value : 0);
     for (const { usage, model: turnModel } of kept) {
-      // Per-turn clamp (#624): add a turn's value ONLY when it is a non-negative
-      // integer. A poisoned value (negative, NaN, float like 10.5) is skipped so
-      // the good turns survive. An absent side contributes 0, not null.
-      const inTok = usage.input_tokens;
-      const cacheRead = usage.cache_read_input_tokens;
-      const cacheCreation = usage.cache_creation_input_tokens;
-      const outTok = usage.output_tokens;
-      if (Number.isInteger(inTok) && inTok >= 0) tokenInputUncached += inTok;
-      if (Number.isInteger(cacheRead) && cacheRead >= 0) tokenCacheRead += cacheRead;
-      if (Number.isInteger(cacheCreation) && cacheCreation >= 0) tokenCacheCreation += cacheCreation;
-      if (Number.isInteger(outTok) && outTok >= 0) tokenOutput += outTok;
-      if (turnModel !== null) model = turnModel;
+      const inTok = clamp(usage.input_tokens);
+      const cacheRead = clamp(usage.cache_read_input_tokens);
+      const cacheCreation = clamp(usage.cache_creation_input_tokens);
+      const outTok = clamp(usage.output_tokens);
+      tokenInputUncached += inTok;
+      tokenCacheRead += cacheRead;
+      tokenCacheCreation += cacheCreation;
+      tokenOutput += outTok;
+      const billed = inTok + cacheRead + cacheCreation + outTok > 0;
+      if (turnModel === null) {
+        if (billed) unattributed = true;
+        continue;
+      }
+      model = turnModel;
+      if (!billed) continue;
+      let part = billedModels.get(turnModel);
+      if (part === undefined) {
+        part = {
+          model: turnModel,
+          token_input_uncached: 0,
+          token_cache_read: 0,
+          token_cache_creation: 0,
+          token_output: 0,
+        };
+        billedModels.set(turnModel, part);
+      }
+      part.token_input_uncached += inTok;
+      part.token_cache_read += cacheRead;
+      part.token_cache_creation += cacheCreation;
+      part.token_output += outTok;
     }
 
+    // Model attribution (#1470): only a token-bearing turn is an observation of
+    // its model; one distinct model → that model, two or more → null, none →
+    // the fallback above. A token-bearing turn that names no model also gives
+    // null: its tokens must not be priced at whichever other model was named.
+    // A mixed-model record carries its per-model sums as `modelsUsage`, which
+    // the session rollup prices part by part (#1470). Measured 2026-09-29 over
+    // 10,745 subagent transcripts under `~/.claude/projects`: 17 (0.16%)
+    // contained more than one model on token-bearing turns (0 of 917 in this
+    // repo), while 273 contained more than one model id only through zero-token
+    // `<synthetic>` turns, which this rule ignores. A model-less token-bearing
+    // turn gets no breakdown: its tokens belong to no part, so the record stays
+    // unpriced. The ledger now tells a mixed-model null (`models_usage`
+    // present) from a missing model (absent). The fallback also names the LAST
+    // model of a transcript whose turns all carry 0 tokens — measured 2026-09-29,
+    // 31 of 10,479 records, all `<synthetic>`; the session rollup prices a record
+    // whose four buckets are all 0 at $0 regardless of its model (#1474), so that
+    // name is harmless.
+    let modelsUsage = null;
+    if (unattributed) model = null;
+    else if (billedModels.size > 1) {
+      model = null;
+      modelsUsage = [...billedModels.values()];
+    } else if (billedModels.size === 1) [model] = billedModels.keys();
+
     // The aggregates are guaranteed non-negative integers by per-turn clamping
     // above (Σ of non-negative integers), so emit them directly.
     return {
@@ -547,6 +618,7 @@ function extractTranscriptUsage(transcriptPath) {
       tokenCacheCreation,
       tokenOutput,
       model,
+      modelsUsage,
     };
   } catch {
     return nullResult;
@@ -593,25 +665,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 +696,6 @@ function findStartTimestampMs(filePath, agentId) {
     return null;
   } catch {
     return null;
-  } finally {
-    if (fd !== undefined) {
-      try { fs.closeSync(fd); } catch { /* ignore */ }
-    }
   }
 }
 
@@ -763,7 +824,7 @@ async function main() {
     // NO fallback to input.transcript_path: that path is the parent session
     // transcript, and reading it is the #949 defect (every stop inherited the
     // parent's running totals). A phantom stop gets null — the honest value.
-    const { tokenInputUncached, tokenCacheRead, tokenCacheCreation, tokenOutput, model } =
+    const { tokenInputUncached, tokenCacheRead, tokenCacheCreation, tokenOutput, model, modelsUsage } =
       subagentTranscriptFound
         ? extractTranscriptUsage(subagentTranscriptPath)
         : {
@@ -772,6 +833,7 @@ async function main() {
             tokenCacheCreation: null,
             tokenOutput: null,
             model: null,
+            modelsUsage: null,
           };
 
     // schema_version 2 (#1244): `token_input` is now BILLABLE PROMPT VOLUME —
@@ -787,11 +849,15 @@ async function main() {
     }
     if (tokenOutput !== null) record.token_output = tokenOutput;
 
-    // Model id (#1244) — null when the transcript exposes none. Cost is NOT
+    // Model id (#1244) — null when the transcript exposes none, or when its
+    // token-bearing turns are not attributable to one model (#1470). Cost is NOT
     // computed here: pricing lives in scripts/lib/telemetry/pricing.mjs and is
     // applied by the session rollup, so this hot-path hook keeps its import
     // graph unchanged.
     record.model = model;
+    // Per-model breakdown (#1470) — written only for a mixed-model record, so
+    // the rollup can price it part by part; absent on every other record.
+    if (modelsUsage !== null) record.models_usage = modelsUsage;
 
     // Cost is best-effort / forward-compat (#624): the native transcript does
     // NOT expose total_cost_usd today, so this is null in practice. No rate
@@ -815,5 +881,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();
+}

package/monitors/monitors.json

@@ -2,7 +2,7 @@
   {
     "name": "ecosystem-health",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/ecosystem-health.mjs --watch",
-    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
+    "description": "Local state-file watcher: every 900 s it stats and reads ONE file, .orchestrator/metrics/ecosystem-health.jsonl under the plugin root, and emits one NDJSON line per change (appeared / disappeared / changed). No network, no CI or branch probing, no repo enumeration, no Session Config read. Nothing writes that file yet (0 writers, measured 2026-09-18), so every run emits `no-state-yet` and idles until SIGTERM — ceiling and revisit trigger at DEFAULT_INTERVAL_S in scripts/lib/ecosystem-health.mjs. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
     "when": "on-skill-invoke:session-start"
   },
   {

package/output-styles/wave-summary.md

@@ -32,7 +32,7 @@ Only include if the plan changed:
 
 - One table row per agent — no nested details
 - Status is exactly one of: `done`, `partial`, `failed`
-- File lists use short relative paths (e.g., `hooks/on-stop.sh`)
+- File lists use short relative paths (e.g., `hooks/on-stop.mjs`)
 - Quality gates are pass/fail — no ambiguity
 - Adaptations only when deviating from plan — omit if on track
 - Keep under 20 lines total

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -94,8 +94,8 @@
   },
   "overrides": {
     "vite": "^8.0.16",
-    "fast-uri": "^3.1.5",
-    "brace-expansion": "^5.0.9"
+    "fast-uri": "^3.1.8",
+    "brace-expansion": "^5.0.12"
   },
   "license": "MIT",
   "repository": {

package/pi/prompts/eval.md

@@ -1,5 +1,5 @@
 ---
-description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v1 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 

package/pi/prompts/navigator.md

@@ -0,0 +1,12 @@
+---
+description: "Fleet coordinator persona for sessions running side by side on one host: it measures resources, pipelines and merge readiness itself, writes conditions (\"Auflagen\") as files, starts headless runs behind slot and busy gates, and grants no approvals. Operator-only, invoke as /session-orchestrator:navigator ticker|status|start|fenster|handover."
+argument-hint: "[ticker|status|start|fenster|handover]"
+---
+
+# /navigator
+
+Use the Session Orchestrator skill definition at `skills/navigator/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.