session-orchestrator 3.22.0 → 3.23.0

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

@@ -18,11 +18,20 @@
  *   G1 tool filter — only Bash is gated.
  *   G2 command is a non-empty string.
  *   G3 matcher — `gh|glab … issue create|new` only. PR/MR creation passes.
+ *      Verb-resolved since #1145, so a wrapped (`nohup`), absolute-path or
+ *      env-prefixed create is seen; a `--help` invocation is not (it creates
+ *      nothing).
  *   G4 config — `issue-budget` from CLAUDE.md/AGENTS.md. `mode: off` → allow.
+ *   G3b bulk — a create inside a shell LOOP body creates an unknowable number
+ *      of issues (#1145). `strict` → deny; `warn` → allow with an explicit
+ *      undercount notice. See the block comment above formatLoopDenyReason for
+ *      why not "charge 1".
  *   G5 exemption — priority::critical / carryover class / broken-window /
  *      the overflow collector itself bypass the cap unconditionally, keeping
  *      the session-end promises at SKILL.md:319 and :1113 intact.
- *   G6 charge the counter in .orchestrator/runtime/issue-budget.json.
+ *   G6 charge the counter in .orchestrator/runtime/issue-budget/<hash>.json
+ *      (one file per session since #1141 — see scripts/lib/issue-budget.mjs
+ *      `budgetStateRel`).
  *      under cap → allow; over cap + `warn` → allow with stderr notice;
  *      over cap + `strict` → park in `overflow[]`, then deny via emitDeny.
  *
@@ -38,14 +47,15 @@
  *        which would throw away the deny envelope entirely (#906).
  */
 
-import { readStdin, emitAllow, emitDeny } from '../scripts/lib/io.mjs';
+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 { isIssueCreate, extractTitle } from './_lib/vcs-create-matcher.mjs';
+import { isIssueCreate, isLoopedIssueCreate, extractTitle } from './_lib/vcs-create-matcher.mjs';
 import {
   loadIssueBudgetConfig,
   resolveIssueBudgetSessionId,
   chargeIssueBudget,
+  classifyExemption,
   formatBlockReason,
 } from '../scripts/lib/issue-budget.mjs';
 
@@ -66,12 +76,28 @@ if (!shouldRunHook('pre-bash-issue-budget')) process.exit(0);
  * semantic id can bridge repeated calls only when its recorded raw id exactly
  * matches the native stdin id; it never substitutes for a missing raw id.
  *
+ * ENV FALLBACK (#1141). A PreToolUse payload without `session_id` used to
+ * resolve to `null`, and an identity-less charge neither reads nor persists —
+ * so for that payload shape the cap was silently OFF. The harness also exports
+ * `CLAUDE_CODE_SESSION_ID` (measured: it equals the `session.lock` `session_id`
+ * and survives into subagents), which is a native id of the same kind as the
+ * stdin one, so it is a faithful substitute rather than a guess. Note the
+ * NAME: there is no `CLAUDE_SESSION_ID` — reading that spelling is what left
+ * the identical fallback in `scripts/lib/spiral-carryover.mjs` dead code.
+ *
+ * stdin still wins: it is the id of THIS tool call, whereas the env var is the
+ * id of the process tree, and the two differ in a nested harness.
+ *
  * @param {object|null} input
  * @param {string|null} projectDir
  * @returns {Promise<string|null>}
  */
 async function resolveSessionId(input, projectDir) {
-  const nativeRawId = input?.session_id ?? input?.sessionId ?? null;
+  const stdinRawId = input?.session_id ?? input?.sessionId ?? null;
+  const nativeRawId =
+    typeof stdinRawId === 'string' && stdinRawId.length > 0
+      ? stdinRawId
+      : (process.env.CLAUDE_CODE_SESSION_ID ?? null);
   if (typeof nativeRawId !== 'string' || nativeRawId.length === 0) return null;
 
   let currentSession = null;
@@ -88,6 +114,68 @@ async function resolveSessionId(input, projectDir) {
   return resolveIssueBudgetSessionId(nativeRawId, currentSession);
 }
 
+/**
+ * THE CHOICE (#1145) — stated once, so the loop behaviour is explicit rather
+ * than emergent.
+ *
+ * `for t in a b c; do glab issue create --title $t; done` is textually ONE
+ * create statement that files THREE issues. Three answers were available and
+ * none is obviously right:
+ *
+ *   charge 1  — the ledger then carries a number it KNOWS is wrong.
+ *               `for i in $(seq 1 50)` files 50 issues against a count of 1, so
+ *               the cap stays nominally armed while actually uncapped. That is
+ *               strictly worse than the pre-#1145 miss, because the pre-fix
+ *               state at least did not LOOK accounted.
+ *   charge N  — not computable at hook time. The word list can be
+ *               `$(cat backlog.txt)`, `"$@"`, or a glob; this hook runs BEFORE
+ *               the shell expands any of them.
+ *   deny      — CHOSEN. A quantity gate that cannot count the quantity must
+ *               refuse, not guess. It is fully recoverable: unrolling the loop
+ *               into separate create calls charges each one correctly, and the
+ *               deny reason says exactly that. Denying costs one round-trip;
+ *               guessing costs the cap its credibility.
+ *
+ * The choice is mode-scoped, because `mode` is the operator's declared
+ * enforcement level and this gate has no standing to exceed it:
+ *   strict → deny;  warn → allow + an explicit undercount notice;  off → allow.
+ * The exemption classes (priority::critical, carryover, broken-window) are
+ * checked FIRST and pass through untouched, so session-end's "those are never
+ * deferred" promise survives a looped carryover sweep.
+ *
+ * NAMED CEILING (BV-004): a loop is detected by `do`/`done` in command position
+ * (see `isLoopedIssueCreate`), so an UNROLLED bulk create — 50 create statements
+ * chained with `&&` — is not a "loop" and is charged 50, correctly. Revisit this
+ * choice if the overflow triage of a per-session counter file
+ * (`.orchestrator/runtime/issue-budget/<hash>.json`) shows operators routinely
+ * hitting this deny on loops over a KNOWN literal word list; the cheap answer
+ * then is to count that list, never to fall back to "charge 1".
+ *
+ * Deliberately NOT `formatBlockReason`: that text promises "parked as overflow
+ * entry #N … nothing is lost", which would be false here — an uncountable bulk
+ * request is not parked, it is handed back whole.
+ *
+ * @param {{ "max-per-session": number }} config
+ * @returns {string}
+ */
+function formatLoopDenyReason(config) {
+  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.',
+    '',
+    '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',
+    `(${config['max-per-session']} per session).`,
+    '',
+    'Exempt from the cap even inside a loop: priority::critical, the carryover class',
+    '(SPIRAL/FAILED, [Carryover]), and broken-window closure issues.',
+    'To change the enforcement level, edit `issue-budget.mode` in the Session Config:',
+    '`warn` reports without blocking, `off` disables the gate.',
+  ].join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -112,6 +200,17 @@ 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.
+  const uncountableBulk =
+    isLoopedIssueCreate(command) && !classifyExemption(command).exempt;
+  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));
+  }
+
   const sessionId = await resolveSessionId(input, projectDir);
 
   // G5 + G6 — exemption check and counter charge live in the shared core so
@@ -153,6 +252,20 @@ async function main() {
     emitDeny(formatBlockReason(verdict));
   }
 
+  // A PERMITTED bulk create is charged ONCE, which is an undercount by
+  // construction. `mode: warn` means "report, do not block", so the report has
+  // 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') {
+    return emitWarn(
+      `pre-bash-issue-budget: bulk create inside a loop body 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. ` +
+        `Set \`issue-budget.mode: strict\` to deny this shape instead.`,
+    );
+  }
+
   // 'allow' / 'off'
   return emitAllow();
 }

package/hooks/pre-bash-sessions-ledger-guard.mjs

@@ -40,6 +40,40 @@
  * sessions.jsonl` — piping the writer's `{"action":"appended"}` receipt INTO
  * the ledger. That is a bug, and denying it is correct.
  *
+ * ## The repair CLI (GitLab #385) — allowed by EXACT MATCH, not structurally
+ *
+ * `repair-invalid-sessions.mjs --apply` is a FIFTH sanctioned writer, but it
+ * is allowed by a different mechanism than the four above: it mutates the
+ * ledger through `repairRecord()` (`scripts/lib/session-record-repair.mjs`)
+ * from inside Node, so structurally it is identical to the four writers — no
+ * ledger write-intent for the matcher to see — EXCEPT that this hook's OWN
+ * matcher independently resolves its `node <script> --apply` argv shape as an
+ * ledger-mutating verb (`findWriteVerbTarget`'s `verb === 'node'` branch,
+ * #1005) and denies it on sight. Before this hook had any opinion on the
+ * subject at all, the guard was therefore denying its own validating writer —
+ * the fix-it CLI for a corrupted ledger record could never run, which is the
+ * #385 deadlock.
+ *
+ * The fix (`REPAIR_APPLY_CANONICAL_COMMAND`, see below) is an EXACT STRING
+ * comparison against the trimmed command — not a name check, and not
+ * equivalent to the spoofable name allowlist rejected above. The distinction
+ * that matters: a name allowlist matches a SUBSTRING anywhere in the command
+ * (a comment, an argument, a quoted payload), so an attacker can smuggle the
+ * name into a command that does something else entirely. An exact-command
+ * comparison has no such position to smuggle into — the command either IS,
+ * in its entirety, `node scripts/repair-invalid-sessions.mjs --apply`, or it
+ * is not, and ANY addition (a flag, a wrapper, a second command chained
+ * after it, a subshell) breaks the match and falls through to the existing
+ * deny logic unchanged (`sonst weiter DENY` — see the #385 tests). There is
+ * still nothing to spoof, for the same reason the four structural writers
+ * have nothing to spoof: allowing this ONE exact invocation grants nothing an
+ * attacker did not already have. `repairRecord()` validates every record it
+ * writes the same way `emit-session.mjs` does, so a caller who can already
+ * invoke arbitrary Bash could run this repair CLI directly, or edit
+ * `session-record-repair.mjs` itself, without ever touching this hook — the
+ * hook's protection scope is shell-redirect writes that BYPASS validation,
+ * and this command never does that.
+ *
  * ## Path scope
  *
  * A write target counts as the ledger when its BASENAME is `sessions.jsonl`,
@@ -172,6 +206,11 @@
  *     verbs (a redirect inside an `awk` program string is quoted data here).
  *   - The Write/Edit tools — a different PreToolUse matcher entirely
  *     (`hooks/enforce-scope.mjs` territory), not this hook's surface.
+ *   - The #385 repair-apply subshell/backtick deny (`unwrapSubshellLayers`)
+ *     only unwraps a command that IS, in its entirety, one wrapped run —
+ *     `x=$(node scripts/repair-invalid-sessions.mjs --apply)` (the wrapper is
+ *     part of a larger assignment, not the whole command) still allows. Same
+ *     class as the line above: a determined rewrite, not the accident shape.
  *
  * This is a guard against the accident that actually happened, not a
  * containment boundary. Determined circumvention is out of scope by design.
@@ -351,6 +390,29 @@ const LEDGER_BASENAME = 'sessions.jsonl';
 const REPAIR_SCRIPT_BASENAME = 'repair-invalid-sessions.mjs';
 const REPAIR_APPLY_MARKER = `${REPAIR_SCRIPT_BASENAME} --apply`;
 
+/**
+ * The ONE command string this guard treats as a sanctioned, exact-match
+ * repair-apply invocation (GitLab #385).
+ *
+ * Without this exception the guard denied its OWN validating writer:
+ * `repair-invalid-sessions.mjs --apply` mutates the ledger through
+ * `repairRecord()` in `scripts/lib/session-record-repair.mjs` — the same
+ * validated-write discipline this hook exists to enforce (mandatory `.bak`,
+ * atomic rename, post-verification restore on failure) — yet the module
+ * docblock's own "ALLOWED STRUCTURALLY" section (see the top of this file)
+ * never named it, because the matcher below still resolves `node` as the verb
+ * and denies on sight. The fix is deliberately an EXACT STRING match, not a
+ * pattern: matching by verb/flags (as `findWriteVerbTarget` already does for
+ * the deny case) cannot distinguish "the operator ran the sanctioned
+ * runbook command" from "the operator ran something ADJACENT to it" — a
+ * wrapper, an extra flag, a second command chained after it. `sonst weiter
+ * DENY` (issue text): any deviation — chaining, piping, a wrapper, extra
+ * arguments, a subshell, backticks — falls through UNCHANGED to the existing
+ * deny logic below, which is why this constant is compared against the RAW,
+ * merely-trimmed command string before any tokenizing/unwrapping happens.
+ */
+const REPAIR_APPLY_CANONICAL_COMMAND = `node scripts/${REPAIR_SCRIPT_BASENAME} --apply`;
+
 /**
  * How much of the offending target may appear in the deny reason.
  *
@@ -416,6 +478,68 @@ function refersToRepairScript(target) {
   return path.posix.basename(normalized) === REPAIR_SCRIPT_BASENAME;
 }
 
+/**
+ * Strip exactly ONE layer of `$( … )`, backtick, or bare `( … )` wrapping from
+ * `s`, when `s` (already trimmed) is wholly that one wrapped run. Returns
+ * `null` when `s` is not wrapped, or when a bare-paren/`$(…)` wrapper's
+ * interior has unbalanced parens (ambiguous — leave it alone rather than
+ * unwrap something that was not really a single wrapped command).
+ *
+ * Deliberately narrow: this is NOT a general shell parser. It exists only to
+ * answer "is this string exactly the canonical repair-apply command sitting
+ * inside one layer of command-substitution/subshell syntax" (see
+ * {@link unwrapSubshellLayers} and GitLab #385 test (c)) — the general
+ * `blocker.tokenizeCommand` path glues a leading `$(`/`` ` ``/`(` onto the
+ * next word (#385 measured: `$(node …)` tokenizes as a single `$(node`
+ * token), which is why the existing verb-based matcher never resolves `node`
+ * as the verb for a wrapped command and silently ALLOWS it today.
+ *
+ * @param {string} s - already-trimmed candidate
+ * @returns {string|null} the unwrapped, trimmed interior, or null
+ */
+function unwrapSingleSubshellLayer(s) {
+  const balanced = (inner) => {
+    let depth = 0;
+    for (const ch of inner) {
+      if (ch === '(') depth++;
+      else if (ch === ')') { depth--; if (depth < 0) return false; }
+    }
+    return depth === 0;
+  };
+  if (s.length >= 4 && s.startsWith('$(') && s.endsWith(')')) {
+    const inner = s.slice(2, -1);
+    return balanced(inner) ? inner.trim() : null;
+  }
+  if (s.length >= 2 && s.startsWith('`') && s.endsWith('`')) {
+    return s.slice(1, -1).trim();
+  }
+  if (s.length >= 2 && s.startsWith('(') && s.endsWith(')')) {
+    const inner = s.slice(1, -1);
+    return balanced(inner) ? inner.trim() : null;
+  }
+  return null;
+}
+
+/**
+ * Repeatedly apply {@link unwrapSingleSubshellLayer} up to `maxDepth` times.
+ * Bounded the same way payload recursion is bounded elsewhere in this file —
+ * no realistic hand-typed command nests this deep, and the outer command is
+ * still matched on its own terms regardless of how far this unwrapping gets.
+ *
+ * @param {string} command
+ * @param {number} [maxDepth]
+ * @returns {string}
+ */
+function unwrapSubshellLayers(command, maxDepth = 3) {
+  let current = command.trim();
+  for (let n = 0; n < maxDepth; n++) {
+    const next = unwrapSingleSubshellLayer(current);
+    if (next === null) break;
+    current = next;
+  }
+  return current;
+}
+
 /**
  * Node's own `--help` output is the source of truth for the runtime-option
  * grammar. A hand-maintained option set is necessarily stale as Node adds
@@ -974,6 +1098,41 @@ async function main() {
     );
   }
 
+  // #385 — the repair CLI's own sanctioned invocation is the ONE write this
+  // guard must let through: it mutates the ledger via the SAME validated-write
+  // discipline (`repairRecord()`, mandatory backup, atomic rename, post-verify
+  // restore) this hook exists to enforce, not a hand-composed shell append.
+  // Compared against the RAW, merely-trimmed command — before any
+  // tokenizing/sanitizing — so the exception is exactly as narrow as the
+  // string itself; "conservative" per the issue text means matching the
+  // string, not a pattern that could also match something adjacent to it.
+  const trimmedCommand = command.trim();
+  if (trimmedCommand === REPAIR_APPLY_CANONICAL_COMMAND) {
+    return flushNotices(notices);
+  }
+  // The SAME canonical command wrapped in one layer of command substitution /
+  // backticks / a bare subshell is a DIFFERENT command — bash still executes
+  // the repair mutation for the substitution's side effect, but it no longer
+  // matches the exact sanctioned string, so `sonst weiter DENY` applies. This
+  // also closes a real gap the exact-match alone would not: `blocker`'s
+  // tokenizer glues a leading `$(`/`` ` ``/`(` onto `node`, so the EXISTING
+  // verb-based matcher below never resolves verb `node` for a wrapped command
+  // and silently allowed it before this hook had any opinion on the subject.
+  if (unwrapSubshellLayers(trimmedCommand) === REPAIR_APPLY_CANONICAL_COMMAND) {
+    emitDeny(
+      [
+        `Direct write to the sessions ledger blocked: '${REPAIR_APPLY_MARKER} (wrapped in a subshell/backticks — denied)'`,
+        `The sanctioned repair invocation is allowed ONLY as the exact bare command:`,
+        `  ${REPAIR_APPLY_CANONICAL_COMMAND}`,
+        `Wrapping it in $(...), backticks, or a subshell is denied even though the`,
+        `command is otherwise identical — see hooks/pre-bash-sessions-ledger-guard.mjs #385.`,
+        `Override (intentional maintenance only): run the session with`,
+        `SO_DISABLED_HOOKS=pre-bash-sessions-ledger-guard`,
+      ].join('\n'),
+    );
+    return;
+  }
+
   // G3 — matcher. No direct ledger write → allow.
   const marks = [];
   const target = findLedgerWrite(command, 0, marks);

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

@@ -64,6 +64,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { stableHostname } from '../scripts/lib/host-identity.mjs';
 if (!shouldRunHook('pre-bash-staging-fence')) process.exit(0);
 
 // ---------------------------------------------------------------------------
@@ -159,7 +160,10 @@ function appendIntent({ fenceFile, agentId, command }) {
     body = {
       agent_id: agentId,
       pid: process.pid,
+      // `host` raw + `host_id` normalised (#1072 — os.hostname() flips spelling
+      // on a single machine, so a raw value is not comparable across writes).
       host: os.hostname(),
+      host_id: stableHostname(),
       started_at: timestamp,
       staged_paths: [],
     };