session-orchestrator 5.1.0 → 5.3.0

package/hooks/pre-bash-staging-fence.mjs

@@ -22,23 +22,32 @@
  *     "host":        "string",
  *     "started_at":  "2026-05-23T21:30:00.000Z",
  *     "staged_paths": [
- *       { "command": "git add src/foo.ts", "timestamp": "2026-…" },
+ *       { "paths": ["src/foo.ts"], "command_hash": "a635c66ec7e7bf56",
+ *         "timestamp": "2026-…" },
  *       ...
  *     ]
  *   }
  *
- * The hook does NOT parse the `git add` argv into paths — argv parsing is
- * fragile (globs, pathspec magic, `-A`, `-u`, `--`). Instead it records the
- * raw command string; the commit-guard reconciles staged paths via
- * `git diff --cached --name-only` and cross-checks them against ALL sibling
- * fence files at commit time (where the staged set is unambiguous).
+ * The entry records the PATH OPERANDS, never the command text (#1404): a
+ * staging command can carry a secret (`GIT_TOKEN=… git add x`), and the raw
+ * string was persisted verbatim to disk — the same defect 8f15f77b removed
+ * from hooks/enforce-commands.mjs. Paths are what the only reader
+ * (hooks/wave-scope-commit-guard.mjs) actually needs; `command_hash` keeps
+ * the entry countable and groupable without the text.
+ *
+ * `paths: ["*"]` means "stages a set no operand names" (`git add -A`, `.`,
+ * `-u`) and overlaps EVERY staged path — the case the reader's old raw-text
+ * regex could not see at all, because `-A` contains no path to match.
  *
  * Decision flow (G1-G6 early-return ladder):
  *   G1  tool filter — Bash only
  *   G2  command must be a non-empty string
- *   G3  regex match /\bgit\s+add\b/ — only `git add` invocations
+ *   G3  cheap regex PRE-FILTER — skip the tokenizer for plainly unrelated
+ *       commands (see GIT_ADD_REGEX; it does not decide the question)
  *   G4  context gate — isWaveAgentContext(); exit 0 immediately for
  *       coordinator/manual commits (AC5 safe-default no-op)
+ *   G4b tokenize + extract path operands; exit 0 when no `git add` statement
+ *       resolves (a pre-filter false positive writes nothing)
  *   G5  derive agent_id, build fence dir + path
  *   G6  read-modify-write the fence file (append the staging-intent entry).
  *       Errors are warned + swallowed — the hook NEVER blocks the Bash call.
@@ -64,29 +73,303 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { stableHostname } from '../scripts/lib/host-identity.mjs';
-if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
 /**
- * Matches `git add ...` invocations with word boundaries on both sides so
- * `gitadd` and `git addremote` (hypothetical) do not match. Anchored to the
- * `git` token, so `echo "git add"` is not matched (echo ≠ verb position).
- *
- * We deliberately accept `git add` anywhere in the command string — operators
- * sometimes prefix env-vars (`GIT_COMMITTER_NAME=foo git add ...`) or chain
- * commands (`cd repo && git add ...`). False positives are tolerable here
- * (the hook only writes a log line, never blocks).
+ * Cheap PRE-FILTER for the staging-command gate (G3). It answers "is it worth
+ * loading the tokenizer for this command?", never "is this a staging
+ * command?" — since #1404 that verdict belongs to {@link extractStagedPaths},
+ * which resolves the verb and subcommand properly.
+ *
+ * `git` and `add` must sit in the same statement (the negated class stops at
+ * `;`, `&`, `|` and newline) within 120 characters of each other, so global
+ * flags between them are tolerated: `git -C sub add x` reaches the extractor,
+ * where `\bgit\s+add\b` used to drop it silently. `\badd\b` keeps
+ * `git addremote` out.
+ *
+ * False positives are cheap AND inert: `git commit -m "add x"` matches here,
+ * resolves to no `git add` statement, and writes nothing (G4b).
+ */
+const GIT_ADD_REGEX = /\bgit\b[^;&|\n]{0,120}\badd\b/;
+
+/**
+ * Recorded in place of a path list when the staging command names NO explicit
+ * path operand but stages a set we cannot enumerate — `git add -A`,
+ * `git add .`, `git add -u`, `git add --pathspec-from-file=<f>`. The reader
+ * (hooks/wave-scope-commit-guard.mjs) treats it as "overlaps every staged
+ * path". This is the case the previous raw-command regex silently MISSED:
+ * `-A` contains no path text, so `pathRegex(ours).test('git add -A')` was
+ * always false and the widest staging command of all fenced nothing.
  */
-const GIT_ADD_REGEX = /\bgit\s+add\b/;
+const ALL_PATHS_MARKER = '*';
+
+/** git GLOBAL flags (before the subcommand) that consume the NEXT token. */
+const GIT_GLOBAL_VALUE_FLAGS = new Set([
+  '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env',
+]);
+
+/** `git add` flags that consume the NEXT token as their value. */
+const GIT_ADD_VALUE_FLAGS = new Set(['--chmod']);
+
+/** `git add` long flags that stage a set no path operand names. */
+const GIT_ADD_ALL_FLAGS = new Set(['--all', '--no-ignore-removal', '--update']);
+
+/**
+ * Shells whose `-c <payload>` operand is a command line the shell EXECUTES, so
+ * a `git add` inside it stages this working copy for real.
+ *
+ * DELIBERATE DUPLICATE of `DASH_C_SHELLS` in scripts/lib/command-blocker.mjs —
+ * that module does not export it (nor its `dashCPayloads`), and #1404's own
+ * rule for this hook is to consume the tokenizer, not to edit it (5 other
+ * consumers). Change one, change both.
+ */
+const DASH_C_SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'su']);
+
+/**
+ * Payload recursion depth for {@link scanForStagedPaths}. ONE level: it covers
+ * `bash -c "git add x"` and `xargs -I{} sh -c "git add x"`, which is the whole
+ * measured regression class (2026-09-20), and keeps a hook that runs on EVERY
+ * Bash call from re-tokenizing an arbitrarily nested string.
+ *
+ * NAMED CEILING (BV-004): `bash -c "bash -c 'git add x'"` is not recorded.
+ * REVISIT TRIGGER: raise to 2 if a doubly-nested staging command is ever
+ * observed in a wave transcript.
+ */
+const MAX_PAYLOAD_DEPTH = 1;
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * sha256(command) truncated to 16 hex chars.
+ *
+ * DELIBERATE DUPLICATE of hooks/enforce-commands.mjs (itself a copy of
+ * hooks/pre-bash-destructive-guard.mjs) — see the 8f15f77b commit message:
+ * the three guards stay import-free of each other on purpose, so a shared
+ * helper is NOT introduced. The hash keeps a fence entry COUNTABLE and
+ * GROUPABLE without persisting command text that may carry a secret
+ * (`GIT_TOKEN=… git add x`) — issue #1404.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function hashCommand(command) {
+  return crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
+}
+
+/**
+ * Normalise a path token so writer and reader compare the same spelling.
+ *
+ * DELIBERATE DUPLICATE of the identically-named function in
+ * hooks/wave-scope-commit-guard.mjs — the reader is a husky pre-commit hook
+ * outside the Claude-Code hook import set, and the two 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;
+}
+
+/**
+ * Extract the PATH OPERANDS of every `git add` statement in a Bash command.
+ *
+ * Reuses the repo's own shell tokenizer (scripts/lib/command-blocker.mjs) —
+ * no second shell grammar is invented here. The import is LAZY: this hook
+ * runs on every Bash call of every session, and only a `git add` command
+ * (G3) ever reaches this function, so the tokenizer's module graph must not
+ * be paid for by the other 99% of calls.
+ *
+ * Handled: `git add -- a b`, quoted operands with spaces, `git -C <dir> add x`
+ * (relative `-C` is prefixed onto the operand), chained statements
+ * (`cd x && git add y` — each statement is its own segment), leading env
+ * assignments, and the enumerate-nothing flags that yield ALL_PATHS_MARKER.
+ *
+ * NAMED CEILINGS (BV-004):
+ *  - Operands are recorded as WRITTEN, relative to the invoking cwd. A
+ *    `cd subdir && git add foo.ts` records `foo.ts` while the staged path is
+ *    `subdir/foo.ts` → a miss. This is exactly the pre-#1404 behaviour (the
+ *    raw-command regex missed it too), not a new gap; revisit if a wave agent
+ *    is ever observed staging from a subdirectory.
+ *  - An ABSOLUTE operand (or an absolute `-C`) is recorded verbatim and will
+ *    not match a repo-relative staged path. Same ceiling, same trigger.
+ *  - A command the tokenizer resolves to no `git add` statement (`echo "git
+ *    add x"` — G3's documented, tolerated false positive) yields an EMPTY
+ *    list, never the marker: over-reporting here would turn a log line into a
+ *    blocked commit, which the hook's fail-safe posture forbids. This is also
+ *    why a blanket "pre-filter hit but nothing resolved → `paths: ['*']`"
+ *    floor was REJECTED at the 2026-09-20 fix: `git commit -m "add x"` matches
+ *    {@link GIT_ADD_REGEX}, and the marker overlaps EVERY staged path, so that
+ *    floor manufactures a collision for a command that stages nothing.
+ *  - A staging command a shell never executes locally is not recorded, and
+ *    should not be: `ssh host 'git add x'` stages a REMOTE index, and
+ *    `git submodule foreach "git add x"` stages the SUBMODULE's — neither can
+ *    collide with a sibling agent in this working copy.
+ *    REVISIT TRIGGER: if the commit-guard ever reconciles submodule indexes.
+ *
+ * @param {string} command
+ * @returns {Promise<{ recognised: boolean, paths: string[] }>}
+ */
+async function extractStagedPaths(command) {
+  let lib;
+  try {
+    lib = await import('../scripts/lib/command-blocker.mjs');
+  } catch {
+    return { recognised: false, paths: [] };
+  }
+
+  const paths = new Set();
+  const state = { recognised: false };
+  scanForStagedPaths(command, lib, paths, state, 0);
+  return { recognised: state.recognised, paths: [...paths] };
+}
+
+/**
+ * Collect the command lines a shell nested in this segment will EXECUTE.
+ *
+ * Two sources, unioned:
+ *  - wrapper payloads `resolveSegmentVerb` already reports (`env -S '…'`),
+ *    across both readings of an ambiguous dual parse (#1000);
+ *  - a `-c`-style operand following a {@link DASH_C_SHELLS} token ANYWHERE in
+ *    the segment, not only in resolved-verb position. The wider scan is what
+ *    covers `xargs -I{} sh -c "git add x"` and `find … -exec sh -c "…" \;`,
+ *    whose resolved verb is `xargs`/`find`; keying on the shell TOKEN instead
+ *    of the verb also keeps `grep -c <pattern>` out, because `grep` is not a
+ *    shell name.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} segment
+ * @param {{ payloads: string[], alt?: { payloads: string[] } }} resolved
+ * @returns {string[]} distinct payload strings
+ */
+function nestedShellPayloads(segment, resolved) {
+  const out = new Set();
+  for (const reading of [resolved, resolved.alt]) {
+    if (!reading) continue;
+    for (const p of reading.payloads) out.add(p);
+  }
+  for (let i = 0; i < segment.length - 1; i++) {
+    const tok = segment[i];
+    if (tok.quoted || !DASH_C_SHELLS.has(path.basename(tok.text))) continue;
+    for (let j = i + 1; j < segment.length - 1; j++) {
+      if (/^-[A-Za-z]*c$/.test(segment[j].text)) {
+        out.add(segment[j + 1].text);
+        break;
+      }
+    }
+  }
+  return [...out];
+}
+
+/**
+ * One tokenize + per-segment pass of {@link extractStagedPaths}, re-entered
+ * once per nested shell payload (bounded by {@link MAX_PAYLOAD_DEPTH}).
+ *
+ * Accumulates into the caller's `paths` set and `state.recognised` flag rather
+ * than returning, so a nested hit and a top-level hit compose:
+ * `git add a && bash -c "git add b"` records BOTH.
+ *
+ * @param {string} command
+ * @param {{ tokenizeCommand: Function, splitChainSegments: Function,
+ *           resolveSegmentVerb: Function }} lib
+ * @param {Set<string>} paths - OUT
+ * @param {{ recognised: boolean }} state - OUT
+ * @param {number} depth
+ * @returns {void}
+ */
+function scanForStagedPaths(command, lib, paths, state, depth) {
+  let segments;
+  try {
+    segments = lib.splitChainSegments(lib.tokenizeCommand(command));
+  } catch {
+    return;
+  }
+
+  for (const segment of segments) {
+    const resolved = lib.resolveSegmentVerb(segment);
+
+    // A staging command nested in `bash -c "…"` resolves to the verb `bash`,
+    // so the loop below never sees it. Before #1404 the raw-text regex matched
+    // it INSIDE the quotes and the reader's path regex found the collision;
+    // the tokenizer rewrite dropped the whole class silently (measured
+    // 2026-09-20: `bash -c "git add src/foo.ts"` → no fence file at all). The
+    // fence is cross-agent collision detection, so a miss is silent in BOTH
+    // directions — re-enter the same extraction on the payload.
+    if (depth < MAX_PAYLOAD_DEPTH) {
+      for (const payload of nestedShellPayloads(segment, resolved)) {
+        // The G3 pre-filter again, on the payload: same cheap question, same
+        // tolerated false positives, and it keeps an unrelated `-c` operand
+        // from paying for a second tokenize.
+        if (typeof payload === 'string' && GIT_ADD_REGEX.test(payload)) {
+          scanForStagedPaths(payload, lib, paths, state, depth + 1);
+        }
+      }
+    }
+
+    const { verb, index } = resolved;
+    if (verb !== 'git' || index < 0) continue;
+
+    let i = index + 1;
+    let chdir = null;
+
+    // git GLOBAL flags sit between `git` and the subcommand.
+    while (i < segment.length) {
+      const tok = segment[i];
+      if (tok.quoted || !tok.text.startsWith('-') || tok.text === '-') break;
+      if (GIT_GLOBAL_VALUE_FLAGS.has(tok.text)) {
+        if (tok.text === '-C' && i + 1 < segment.length) chdir = segment[i + 1].text;
+        i += 2;
+        continue;
+      }
+      i += 1; // boolean global flag, or attached `--git-dir=<p>`
+    }
+
+    if (i >= segment.length || segment[i].quoted || segment[i].text !== 'add') continue;
+    state.recognised = true;
+    i += 1;
+
+    let endOfFlags = false;
+    let stagesAll = false;
+
+    for (; i < segment.length; i++) {
+      const tok = segment[i];
+      const text = tok.text;
+
+      if (!endOfFlags && !tok.quoted && text.startsWith('-') && text !== '-') {
+        if (text === '--') { endOfFlags = true; continue; }
+        if (GIT_ADD_VALUE_FLAGS.has(text)) { i += 1; continue; }
+        if (text === '--pathspec-from-file' || text.startsWith('--pathspec-from-file=')) {
+          stagesAll = true;
+          if (text === '--pathspec-from-file') i += 1;
+          continue;
+        }
+        if (GIT_ADD_ALL_FLAGS.has(text)) { stagesAll = true; continue; }
+        // Short-flag cluster: `-A`, `-u`, `-An`, `-vu` all stage a set no
+        // operand names.
+        if (!text.startsWith('--') && /[Au]/.test(text.slice(1))) stagesAll = true;
+        continue;
+      }
+
+      if (text === '.' || text === './') { stagesAll = true; continue; }
+      const operand = chdir && !chdir.startsWith('/') ? `${chdir}/${text}` : text;
+      const normalised = normalizeStagedPath(operand);
+      if (normalised.length > 0) paths.add(normalised);
+    }
+
+    if (stagesAll) paths.add(ALL_PATHS_MARKER);
+  }
+}
+
 /**
  * Derive a per-agent identifier for the fence filename.
  *
@@ -136,10 +419,10 @@ function resolveProjectDir() {
  * #558 M1). The first call for a given agent_id creates the file with a
  * fresh body.
  *
- * @param {{ fenceFile: string, agentId: string, command: string }} args
+ * @param {{ fenceFile: string, agentId: string, command: string, paths: string[] }} args
  * @returns {{ ok: true } | { ok: false, reason: 'fs-error', error: string }}
  */
-function appendIntent({ fenceFile, agentId, command }) {
+function appendIntent({ fenceFile, agentId, command, paths }) {
   const timestamp = new Date().toISOString();
 
   let body;
@@ -169,7 +452,14 @@ function appendIntent({ fenceFile, agentId, command }) {
     };
   }
 
-  body.staged_paths.push({ command: command.slice(0, 512), timestamp });
+  // #1404 — persist what the READER needs (path operands), never the command
+  // text: a staging command can carry a secret in a leading env assignment.
+  // The hash keeps the entry countable/groupable, mirroring enforce-commands.
+  body.staged_paths.push({
+    paths,
+    command_hash: hashCommand(command),
+    timestamp,
+  });
 
   return writeJsonAtomicSync(fenceFile, body, { tmpPrefix: '.fence.tmp' });
 }
@@ -189,12 +479,20 @@ async function main() {
   const command = input?.tool_input?.command;
   if (typeof command !== 'string' || command.length === 0) return emitAllow();
 
-  // G3 — regex gate. Non-`git add` commands pass through unconditionally.
+  // G3 — cheap regex PRE-FILTER. Commands that cannot possibly be a staging
+  // command pass through without loading the tokenizer.
   if (!GIT_ADD_REGEX.test(command)) return emitAllow();
 
   // G4 — context gate. Coordinator/manual commits are not fenced.
   if (!isWaveAgentContext()) return emitAllow();
 
+  // G4b — the PRECISE gate (#1404). The tokenizer, not the regex, decides
+  // whether this command really stages anything: a pre-filter hit with no
+  // resolvable `git add` statement (`git commit -m "add x"`) writes NO fence
+  // file, where the pre-#1404 hook logged its raw text.
+  const { recognised, paths } = await extractStagedPaths(command);
+  if (!recognised) return emitAllow();
+
   // G5 — derive paths.
   const projectDir = resolveProjectDir();
   const agentId = deriveAgentId();
@@ -206,7 +504,7 @@ async function main() {
   );
 
   // G6 — append intent. Never blocks the Bash call on failure.
-  const result = appendIntent({ fenceFile, agentId, command });
+  const result = appendIntent({ fenceFile, agentId, command, paths });
   if (!result.ok) {
     process.stderr.write(
       `⚠ pre-bash-staging-fence: failed to write fence file — ${result.error}\n`,
@@ -216,12 +514,18 @@ async function main() {
   return emitAllow();
 }
 
-// Top-level error handler — never let exit 1 leak. Fail-open on internal
-// errors to avoid blocking legitimate work (mirrors the destructive-guard
-// posture).
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-staging-fence: internal error — ${e?.message || e}\n`,
-  );
-  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)) {
+  if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak. Fail-open on internal
+  // errors to avoid blocking legitimate work (mirrors the destructive-guard
+  // posture).
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-staging-fence: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}

package/hooks/pre-bash-templates-first.mjs

@@ -44,14 +44,10 @@ import { hasReadInSession } from './_lib/transcript-history.mjs';
 import { resolveHost, matchesBypass } from './_lib/vcs-create-matcher.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { existsSync, readdirSync, lstatSync } from 'node:fs';
 import path from 'node:path';
 
-// #519: opt-in via profile/env. Default profile "full" enables this hook;
-// minimal/off disable. SO_DISABLED_HOOKS=pre-bash-templates-first opts out
-// per session.
-if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
-
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -426,12 +422,21 @@ async function main() {
   });
 }
 
-// Top-level error handler — never let exit 1 leak. Same posture as
-// pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
-// blocking legitimate work.
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,
-  );
-  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)) {
+  // #519: opt-in via profile/env. Default profile "full" enables this hook;
+  // minimal/off disable. SO_DISABLED_HOOKS=pre-bash-templates-first opts out
+  // per session.
+  if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak. Same posture as
+  // pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
+  // blocking legitimate work.
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}