session-orchestrator 5.1.0 → 5.3.0

package/hooks/pre-bash-issue-budget.mjs

@@ -53,7 +53,7 @@
 import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
 import { resolveProjectDir } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
-import { findIssueCreateStatements, isLoopedIssueCreate } from './_lib/vcs-create-matcher.mjs';
+import { findIssueCreateStatements, findLoopedIssueCreates } from './_lib/vcs-create-matcher.mjs';
 import {
   loadIssueBudgetConfig,
   resolveIssueBudgetSessionId,
@@ -67,13 +67,10 @@ import {
 } from '../scripts/lib/issue-budget.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
-// Opt-out per session via SO_DISABLED_HOOKS=pre-bash-issue-budget; the
-// "minimal"/"off" profiles disable it like every other non-core hook.
-if (!shouldRunHook('pre-bash-issue-budget')) process.exit(0);
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -187,15 +184,39 @@ function resolveToolCallId(input) {
  * entry #N … nothing is lost", which would be false here — an uncountable bulk
  * request is not parked, it is handed back whole.
  *
+ * ## Why the lane is a parameter (#1379)
+ *
+ * Until 2026-09-17 this text said "sits inside a shell loop body (`do … done`)"
+ * on BOTH lanes, so the `xargs` deny (`echo b | xargs -I% glab issue create
+ * --title junk%` — no loop anywhere) sent the operator looking for a loop the
+ * command does not have. Only the lane SENTENCE varies; every other line is
+ * byte-identical across lanes, and tests pin them.
+ *
  * @param {{ "max-per-session": number }} config
+ * @param {{ lane?: "loop"|"xargs"|"mixed" }} [opts]
  * @returns {string}
  */
-function formatLoopDenyReason(config) {
+function formatLoopDenyReason(config, { lane = 'loop' } = {}) {
+  const LANE_SENTENCES = {
+    loop: [
+      'The `issue create` call sits inside a shell loop body (`do … done`), so the cap cannot',
+      'charge it honestly: the word list is expanded by the shell AFTER this hook runs, so',
+      '`for i in $(seq 1 50)` would file 50 issues against a count of 1.',
+    ],
+    xargs: [
+      'The `issue create` call is driven by `xargs`, so the cap cannot charge it honestly: the',
+      'word list arrives on stdin AFTER this hook runs, so `seq 1 50 | xargs` would file 50',
+      'issues against a count of 1.',
+    ],
+    mixed: [
+      'The `issue create` calls are driven by a shell loop body (`do … done`) AND by `xargs`,',
+      'so the cap cannot charge them honestly: both word lists are produced AFTER this hook',
+      'runs, so `seq 1 50 | xargs` would file 50 issues against a count of 1.',
+    ],
+  };
   return [
     'issue-budget: this command creates an UNKNOWN number of issues — refusing to guess.',
-    'The `issue create` call sits inside a shell loop body (`do … done`), so the cap cannot',
-    'charge it honestly: the word list is expanded by the shell AFTER this hook runs, so',
-    '`for i in $(seq 1 50)` would file 50 issues against a count of 1.',
+    ...(LANE_SENTENCES[lane] ?? LANE_SENTENCES.loop),
     '',
     'Nothing was parked as overflow, because nothing is lost: re-issue the create calls as',
     'SEPARATE commands and each one is counted normally against the cap',
@@ -302,18 +323,59 @@ async function main() {
   const config = loadIssueBudgetConfig(projectDir);
   if (config.mode === 'off') return emitAllow();
 
-  // G3b — bulk creation whose multiplicity is not computable (#1145). The
-  // exemption is asked FIRST, through the same classifier chargeIssueBudget
-  // uses, so a looped carryover sweep keeps its unconditional pass. It is asked
-  // on the FIRST issue-create statement's text, which is the very statement
-  // `isLoopedIssueCreate` judges — classifying it on the whole command would
-  // let an exempt NEIGHBOUR statement lift the loop deny.
-  const uncountableBulk =
-    isLoopedIssueCreate(command) && !classifyExemption(statements[0].text).exempt;
+  // G3b — bulk creation whose multiplicity is not computable (#1145). Two
+  // sources, one policy: a LOOP BODY (#1145) and an `xargs`-driven create
+  // (#1289), where the word list arrives on stdin. Both file N issues for one
+  // statement, so both are denied rather than charged 1 — the fix had to land
+  // here and not only in `isLoopedIssueCreate`, because G3 above short-circuits
+  // on `statements.length === 0` and an xargs create used to produce zero
+  // statements, so no loop-side fix could ever run.
+  //
+  // THE INVARIANT (rewritten 2026-09-16): the exemption is classified on the
+  // statement that CAUSED the bulk classification — never on `statements[0]`,
+  // and never on the whole command. A `[Carryover]` create standing NEXT TO an
+  // uncountable one is an unrelated neighbour and must not lift the deny; a
+  // `[Carryover]` create that IS the bulk statement keeps its documented
+  // unconditional pass (session-end's "those are never deferred" promise, which
+  // holds inside a loop too). Measured 2026-09-16 against the previous
+  // `statements[0]` binding, both lanes ALLOW where they must DENY:
+  //   glab issue create --title "[Carryover] real"; echo X | xargs -I% glab issue create --title %
+  //   glab issue create --title "[Carryover] real"; for i in 1 2 3; do glab issue create --title junk$i; done
+  // Same class as the bypass-scoping regression on `matchesBypass` — a matcher
+  // widened per statement while its exemption stayed whole-command
+  // (`.claude/rules/guard-design.md` § "Widening a matcher without narrowing
+  // its bypass", #1106).
+  //
+  // Fail-CLOSED when a command carries SEVERAL bulk statements and only some are
+  // exempt: `some()` over the non-exempt ones denies, because the command as a
+  // whole still files an uncountable number of untemplated issues.
+  //
+  // EVERY loop, not the first (#1379): the loop lane used to contribute at most
+  // ONE entry here, so an exempt FIRST loop was the only loop classified and
+  // every later loop went unjudged. Reproduced 2026-09-17 @ `9e8146b4`:
+  //   for i in 1 2 3; do glab issue create --label carryover --title x$i; done;
+  //   for j in 1 2 3; do glab issue create --title junk$j; done  → ALLOW (count=1)
+  const bulkEntries = [
+    ...findLoopedIssueCreates(command).map((tokens) => ({
+      lane: 'loop',
+      text: tokens.map((t) => t.text).join(' '),
+    })),
+    ...statements.filter((s) => s.bulk).map((s) => ({ lane: 'xargs', text: s.text })),
+  ];
+  const uncountableEntries = bulkEntries.filter((e) => !classifyExemption(e.text).exempt);
+  const uncountableBulk = uncountableEntries.length > 0;
+  // ONE lane resolution for BOTH reports (#1379 follow-up). The deny already
+  // named the lane it fired on; the `warn` undercount notice at the bottom of
+  // main() said "inside a loop body" unconditionally, so the xargs lane — where
+  // no loop exists anywhere in the command — sent the operator looking for one.
+  // Resolved here rather than twice, so the two reports can never disagree.
+  const uncountableLanes = new Set(uncountableEntries.map((e) => e.lane));
+  const uncountableLane =
+    uncountableLanes.size > 1 ? 'mixed' : ([...uncountableLanes][0] ?? 'loop');
   if (uncountableBulk && config.mode === 'strict') {
     // Nothing is charged and nothing is parked — the command is handed back
     // whole, which is what makes unrolling it the correct next action.
-    return emitDeny(formatLoopDenyReason(config));
+    return emitDeny(formatLoopDenyReason(config, { lane: uncountableLane }));
   }
 
   const sessionId = await resolveSessionId(input, projectDir);
@@ -401,11 +463,32 @@ async function main() {
   // to name the undercount out loud — a silent 1-for-N is the exact failure the
   // deny above exists to prevent, and `warn` must not reintroduce it quietly.
   // emitWarn, not stderr: under exit 0 stderr reaches only the debug log (#916).
-  if (uncountableBulk && verdict.decision === 'allow') {
+  //
+  // GATED ON THE BULK STATEMENTS, NEVER ON THE LAST VERDICT (2026-09-17). The
+  // condition used to read `verdict.decision === 'allow'`, i.e. the verdict of
+  // the LAST statement of the chain — so one exempt statement written AFTER an
+  // uncountable one silenced the notice the two paragraphs above declare
+  // mandatory. Reproduced through this hook binary in `mode: warn`:
+  //   for i in 1 2; do glab issue create --title j$i; done; \
+  //     glab issue create --title "[Carryover] z"
+  //   → stdout EMPTY, ledger count=1 exempt=1 (the trailing exempt statement is
+  //     an unrelated neighbour, exactly as in G3b's own invariant); without it,
+  //     the identical loop reported the UNDERCOUNT.
+  // Reaching this point already means no statement blocked and none warned
+  // (both branches above return), so the uncountable bulk statement — non-exempt
+  // by construction of `uncountableEntries` — was charged as 1. The two negated
+  // conditions are kept explicit so a future reordering of those branches cannot
+  // turn this back into a report about the wrong statement.
+  if (uncountableBulk && !blocked && !verdicts.some((v) => v.decision === 'warn')) {
+    const LANE_PHRASES = {
+      loop: 'inside a loop body',
+      xargs: 'driven by `xargs`',
+      mixed: 'inside a loop body and by `xargs`',
+    };
     return emitWarn(
-      `pre-bash-issue-budget: bulk create inside a loop body charged as 1 ` +
+      `pre-bash-issue-budget: bulk create ${LANE_PHRASES[uncountableLane]} charged as 1 ` +
         `(${verdict.count}/${verdict.max}) — the real number of issues this files is not ` +
-        `knowable before the shell expands the word list, so the count is an UNDERCOUNT. ` +
+        `knowable before the word list is expanded, so the count is an UNDERCOUNT. ` +
         `Set \`issue-budget.mode: strict\` to deny this shape instead.`,
     );
   }
@@ -414,10 +497,18 @@ async function main() {
   return emitAllow();
 }
 
-// Top-level error handler — fail open, same posture as the sibling hooks.
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-issue-budget: 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)) {
+  // Opt-out per session via SO_DISABLED_HOOKS=pre-bash-issue-budget; the
+  // "minimal"/"off" profiles disable it like every other non-core hook.
+  if (!shouldRunHook('pre-bash-issue-budget')) process.exit(0);
+
+  // Top-level error handler — fail open, same posture as the sibling hooks.
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-issue-budget: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0);
+  });
+}

package/hooks/pre-bash-memory-propose-audit.mjs

@@ -13,7 +13,8 @@
  *   G3 — regex match /\bnode\b.*\bmemory-propose\.mjs\b/i (no match → exit 0)
  *   G4 — resolve session_id (from stdin payload or .orchestrator/current-session.json)
  *   G5 — resolve wave (from the active wave-scope.json `wave` field, default 0)
- *   G6 — redact argv: strip --insight/--subject/--evidence/--content/--reason values
+ *   G6 — derive a NON-REVERSIBLE argv summary: sha256 command_hash + known flag
+ *        NAMES + raw length. The command text itself never leaves this process.
  *   G7 — append event JSON line to .orchestrator/metrics/events.jsonl
  *   Always: exit 0 (never block)
  *
@@ -22,6 +23,7 @@
  */
 
 import { readStdin, emitAllow } from '../scripts/lib/io.mjs';
+import crypto from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -29,8 +31,7 @@ import { emitEvent } from '../scripts/lib/events.mjs';
 import { findScopeFile } from '../scripts/lib/hardening.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
-// exit 0 immediately when this hook is disabled via profile/env
-if (!shouldRunHook('pre-bash-memory-propose-audit')) process.exit(0);
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -48,59 +49,78 @@ if (!shouldRunHook('pre-bash-memory-propose-audit')) process.exit(0);
 const MEMORY_PROPOSE_REGEX = /\bnode\b.*\bmemory-propose\.mjs\b/i;
 
 /**
- * Flags whose VALUES are privacy-sensitive and must be redacted from the log.
- * The flag name itself is preserved; only the value is replaced with [REDACTED].
+ * The flag NAMES `scripts/memory-propose.mjs` accepts (its `parseArgs` options
+ * block, plus `--help`). CLOSED LIST BY DESIGN: `flags_present` is built by
+ * intersecting the command with this constant, never by scraping `--\S+` tokens
+ * out of the command. A scrape would re-open the leak this file just closed —
+ * `--insight --my-secret-value` would publish the value as if it were a flag.
  *
- * Matches both forms:
- *   --insight=value            → --insight=[REDACTED]
- *   --insight "quoted value"   → --insight [REDACTED]
- *   --insight unquoted         → --insight [REDACTED]
+ * A flag the CLI does not know is simply not reported. That is the correct
+ * trade: the field exists to say WHICH of the audited CLI's switches were used,
+ * not to mirror the command line.
  */
-// CAVEAT (#554 A3, low severity): The regex operates on the unparsed Bash
-// tool_input.command string. Exotic shell forms bypass redaction by hiding
-// the value behind shell expansion the regex cannot see:
-//   --insight=$VAR           (env-var indirection)
-//   --insight=$(cat secret)  (command substitution)
-//   --insight <<<heredoc     (here-string)
-// The literal token (e.g. `$VAR`) is logged, NOT the resolved value — so an
-// audit-trail leak requires the resolved value to also appear literally
-// elsewhere in the command. Acceptable per the project's local-trust model.
-//
-// Issue #546: `\S+` would match an opening quote `"` or `'` (non-whitespace),
-// and on malformed inputs (e.g. unbalanced or shell-already-unescaped values)
-// could partial-match the value, leaving the tail unredacted. The negative
-// lookahead `(?!["'])` forces `\S+` to be tried only on values that do not
-// start with a quote, preserving the quoted-alt as the sole path for quoted
-// values and preventing tail-leaks on malformed inputs.
-const SENSITIVE_FLAGS_REGEX = /--(?:insight|subject|evidence|content|reason)(?:=("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|(?!["'])\S+)|\s+("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|(?!["'])\S+))/g;
+const KNOWN_FLAGS = Object.freeze([
+  'type',
+  'subject',
+  'insight',
+  'evidence',
+  'confidence',
+  'dry-run',
+  'file-paths',
+  'help',
+]);
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Redact values of privacy-sensitive flags from a command string.
- * Preserves flag names; replaces values with [REDACTED].
+ * sha256(command), truncated to 16 hex characters.
+ *
+ * WORD-FOR-WORD the `hashCommand()` of `hooks/enforce-commands.mjs:69` (itself
+ * taken from `hooks/pre-bash-destructive-guard.mjs:253`, which mirrors
+ * `loop-guard.mjs` `hashArgs()`). Deliberately duplicated rather than shared:
+ * a PreToolUse hook must not gain another loadable module that can fail at
+ * start — three lines are cheaper than a load error on the hot path. Verified
+ * before duplicating that no helper is EXPORTED at any of those sites.
+ *
+ * WHY THE HASH IS HERE (#1415, 2026-09-21): until today this hook wrote a
+ * merely flag-redacted `argv_truncated` (512 chars of command text) into
+ * `orchestrator.memory.propose_invoked` — a TRACKED `events.jsonl` line and,
+ * with the webhook configured, a network payload. Redaction covered only the
+ * five `--insight/--subject/--evidence/--content/--reason` values and said so
+ * in its own caveat: `$VAR`, `$(cat secret)` and any value written elsewhere
+ * on the line passed through. This was the THIRD and last open site of the
+ * class closed by `8f15f77b` (enforce-commands) and #1404 (staging-fence).
+ *
+ * The hash keeps the event COUNTABLE and GROUPABLE — repeat invocations of the
+ * same command still collapse to one key — which is the only property any
+ * consumer needed. Measured 2026-09-21 (`rg argv_truncated` over `scripts/
+ * hooks/ skills/ docs/`): ZERO production readers, the field's only consumers
+ * were this hook's own tests.
  *
  * @param {string} command
  * @returns {string}
  */
-function redactArgv(command) {
-  return command.replace(SENSITIVE_FLAGS_REGEX, (match, eqValue, spaceValue) => {
-    if (eqValue !== undefined) {
-      // --insight=value form: preserve up to and including '=', replace value
-      const eqIndex = match.indexOf('=');
-      return match.slice(0, eqIndex + 1) + '[REDACTED]';
-    }
-    if (spaceValue !== undefined) {
-      // --insight value form: preserve flag + whitespace, replace value
-      const valueIndex = match.lastIndexOf(spaceValue);
-      return match.slice(0, valueIndex) + '[REDACTED]';
-    }
-    // Fallback: keep flag name, drop value
-    const flagMatch = match.match(/^(--[\w-]+)/);
-    return flagMatch ? flagMatch[1] + ' [REDACTED]' : match;
-  });
+function hashCommand(command) {
+  return crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
+}
+
+/**
+ * The subset of KNOWN_FLAGS that appears in the command, in KNOWN_FLAGS order.
+ *
+ * Names only — a value can never reach this array, because the array is built
+ * from the constant above and the command is only ever TESTED against it. Both
+ * spellings count (`--insight=x` and `--insight x`); the trailing boundary
+ * `(?![\w-])` keeps `--insightful` from reporting `insight`.
+ *
+ * @param {string} command
+ * @returns {string[]}
+ */
+function flagsPresent(command) {
+  return KNOWN_FLAGS.filter((flag) =>
+    new RegExp(`--${flag}(?![\\w-])`).test(command),
+  );
 }
 
 /**
@@ -180,8 +200,11 @@ async function main() {
   // G5 — resolve wave
   const wave = await resolveWave(projectDir);
 
-  // G6 — redact argv: strip sensitive flag values, keep flag names
-  const argvRedacted = redactArgv(command);
+  // G6 — derive the non-reversible argv summary (#1415). Nothing downstream
+  // ever sees the command text: hash for grouping, known flag NAMES for
+  // shape, raw length for size — no operands, no paths, no values.
+  const commandHash = hashCommand(command);
+  const flags = flagsPresent(command);
 
   // G7 — emit canonical event via emitEvent (single emission path: schema + webhook,
   // replacing the local hand-rolled appendFileSync bypass).
@@ -193,7 +216,9 @@ async function main() {
     await emitEvent('orchestrator.memory.propose_invoked', {
       session_id: sessionId,
       wave,
-      argv_truncated: argvRedacted.slice(0, 512),
+      command_hash: commandHash,
+      flags_present: flags,
+      argv_length: command.length,
       cwd: process.cwd(),
       exit_code: null,
     });
@@ -203,10 +228,17 @@ async function main() {
   return emitAllow();
 }
 
-// Top-level error handler — never let exit 1 leak
-main().catch((e) => {
-  process.stderr.write(
-    `⚠ pre-bash-memory-propose-audit: internal error — ${e?.message || e}\n`,
-  );
-  process.exit(0); // fail-open on internal errors
-});
+// 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 this hook is disabled via profile/env
+  if (!shouldRunHook('pre-bash-memory-propose-audit')) process.exit(0);
+
+  // Top-level error handler — never let exit 1 leak
+  main().catch((e) => {
+    process.stderr.write(
+      `⚠ pre-bash-memory-propose-audit: internal error — ${e?.message || e}\n`,
+    );
+    process.exit(0); // fail-open on internal errors
+  });
+}