session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/io.mjs

@@ -98,6 +98,45 @@ const DENY_REASON_MAX = 16_000;
  */
 const WARN_MESSAGE_MAX = 16_000;
 
+/**
+ * Hard ceiling (in BYTES, including the trailing newline) for the whole
+ * {@link emitRewrite} envelope.
+ *
+ * Denominated in bytes, not characters, unlike {@link DENY_REASON_MAX} — the
+ * quantity that actually matters here is what the kernel pipe buffer holds, and
+ * a character count only approximates that for ASCII. `Buffer.byteLength` makes
+ * the bound exact for any input.
+ *
+ * Derivation, measured 2026-08-22 against the repo's own AUQ corpus
+ * (`node scripts/auq-audit.mjs --json`, 70 real question blocks, HEAD clean):
+ *
+ * | quantity                                                  | measured |
+ * |-----------------------------------------------------------|----------|
+ * | largest real tool-input in the corpus (plan/SKILL.md:136) | 1 369 B  |
+ * | median / mean over all 70 blocks                          | 549 / 547 B |
+ * | max question text · header · label · description · preview | 269 · 12 · 48 · 180 · 252 |
+ * | protocol-cap worst case: 4 questions × 4 options, each field at its measured max | 9 785 B |
+ *
+ * The protocol caps come from `.claude/rules/ask-via-tool.md` § AUQ-003 (1–4
+ * questions, 2–4 options); the corpus tops out at 3 questions and 4 options, so
+ * the 9 785 B row is already an over-estimate of anything observed. 32 768 sits
+ * **3.35× above that worst case** and **23.9× above the largest real payload**,
+ * while being exactly **half** the 65 536-byte kernel pipe buffer — so a
+ * cap-sized envelope fits one buffer with the whole second half to spare, and a
+ * rewrite that expands its source text several-fold is still nowhere near the
+ * ceiling.
+ *
+ * ## Why this REJECTS where {@link DENY_REASON_MAX} CLAMPS
+ *
+ * A deny reason is prose: clipping it leaves a valid deny with a shorter
+ * explanation. `updatedInput` is structure: clipping it mid-object yields
+ * unparseable JSON, which the harness reads as no-decision — the truncated
+ * envelope would silently discard the rewrite while looking like a successful
+ * emit. So an over-ceiling payload is never sliced; it is refused whole, and the
+ * tool call proceeds with its original input (see {@link emitRewrite}).
+ */
+const REWRITE_ENVELOPE_MAX_BYTES = 32_768;
+
 /**
  * Reason substituted when a caller denies without supplying one.
  *
@@ -489,6 +528,206 @@ export function emitWarn(message) {
   process.exit(0);
 }
 
+/**
+ * Rewrite the **tool input** of the current PreToolUse invocation and let the
+ * normal flow continue: emit exactly one JSON object on stdout, then exit **0**.
+ *
+ * This is the third PreToolUse verb, alongside {@link emitDeny} ("block") and
+ * {@link emitWarn} ("allow, with a notice"). It decides nothing — it hands the
+ * harness a replacement input and steps out of the way.
+ *
+ * ## Emitted payload (single stdout line, nothing else on stdout)
+ *
+ * ```json
+ * {"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":{…}}}
+ * ```
+ *
+ * ## THE TRAP: there is deliberately no `permissionDecision`, and no way to add one
+ *
+ * The shipped Claude Code binary (2.1.239) routes the rewrite through a branch
+ * that is guarded on the ABSENCE of a permission decision:
+ *
+ * ```js
+ * if (p.updatedInput && p.permissionBehavior === void 0)
+ *   yield { type: "hookUpdatedInput", updatedInput: p.updatedInput };
+ * ```
+ *
+ * Pair `updatedInput` with `permissionDecision: "allow"` and a different branch
+ * takes it: the input is still replaced, but the **permission stage is skipped**.
+ * For most tools that is merely a lost prompt. For `AskUserQuestion` it is fatal,
+ * because the permission stage IS the question card — `checkPermissions` returns
+ * `behavior: "ask"`, and that "ask" is what renders the options to the operator.
+ * An `allow` there does not approve the question; it routes the question PAST the
+ * human. The operator is never asked, nothing errors, and the omission is
+ * invisible from both ends.
+ *
+ * The prevention is structural, not advisory. This function takes **one**
+ * parameter — the tool input — and builds `hookSpecificOutput` here as a
+ * two-key object literal with no spread, no `opts` bag, and no caller-reachable
+ * key. There is no argument a caller can pass that lands as a sibling of
+ * `updatedInput`; a `permissionDecision` key inside the caller's own object
+ * nests one level deeper (`updatedInput.permissionDecision`), where the harness
+ * ignores it. Adding a spread or an options parameter here would re-open the
+ * trap — that is what `tests/lib/io.test.mjs` pins, since the structure cannot
+ * defend itself against a future edit.
+ *
+ * A hook that needs BOTH a permission decision and a rewrite cannot have both:
+ * choose the decision, because a rewrite that skips the operator's question is
+ * the exact failure this function is shaped to avoid.
+ *
+ * ## `updatedInput` is the COMPLETE tool input, never a patch
+ *
+ * The bundle types it as a map, not a diff (`updatedInput: oo(H(), Pn())`), and
+ * the harness substitutes it wholesale. A caller that passes only the fields it
+ * changed **deletes every field it omitted** — for `AskUserQuestion`, passing
+ * `{questions: [{question: '…'}]}` drops the options and the header along with
+ * them. Read the original input from the hook payload, modify it, and pass the
+ * whole object back.
+ *
+ * ## Fail-closed on an invalid rewrite is the HARNESS's behaviour, not ours
+ *
+ * A syntactically fine but schema-invalid `updatedInput` (5 questions where 4 is
+ * the cap, 1 option where 2 is the minimum) does not slip through as a silent
+ * pass — the bundle turns it into a deny:
+ *
+ * ```js
+ * if (!f.success && m.length > 0) { … u = { behavior: "deny", message: g, … }; continue }
+ * ```
+ *
+ * So a malformed rewrite costs the tool call, not the operator's trust. Callers
+ * are still responsible for emitting a schema-valid input; this note only
+ * records that the failure direction is safe.
+ *
+ * ## EVIDENCE STATUS — code-evidence, not runtime-evidence
+ *
+ * Everything above is read out of the shipped 2.1.239 bundle. **No hook with a
+ * matcher of `AskUserQuestion` has ever run in this repo**, so the rewrite
+ * branch has not been observed executing. The runtime proof needs a session
+ * restart and is outstanding. Treat the branch conditions as verified source and
+ * the end-to-end behaviour as expected-but-unconfirmed.
+ *
+ * ## When emitRewrite is the WRONG verb
+ *
+ *  1. **You need to block.** A rewrite carries no denial; the tool call proceeds
+ *     whatever the new input says. Use {@link emitDeny}.
+ *  2. **You need to pre-approve.** Skipping the permission prompt is
+ *     `permissionDecision: "allow"`, and combining it with a rewrite is the trap
+ *     above. Emit one or the other, never a hand-rolled envelope carrying both.
+ *  3. **The event is not PreToolUse.** `hookEventName` is hardcoded; PostToolUse
+ *     / Stop / SubagentStop have no `updatedInput` at all and signal through a
+ *     top-level `decision` (same precondition as {@link emitDeny}).
+ *  4. **You cannot reconstruct the whole input.** A partial object deletes the
+ *     rest — if the original input is not in hand, do nothing ({@link emitAllow})
+ *     rather than emit a lossy replacement.
+ *
+ * ## Delivery, and why a failed write still exits 0
+ *
+ * The envelope goes out through {@link writeStdoutLineSync}, never
+ * `console.log`: on macOS a piped stdout is asynchronous, so `console.log` +
+ * `process.exit(0)` drops everything past the 65 536-byte kernel pipe buffer and
+ * the rewrite vanishes without a trace. The payload is additionally bounded by
+ * {@link REWRITE_ENVELOPE_MAX_BYTES} — refused whole rather than clipped, since
+ * a clipped JSON object is not a smaller rewrite but an unparseable one.
+ *
+ * ── BV-004: at TODAY'S ceiling the two bounds are not equally load-bearing ────
+ * Measured 2026-08-22 (`console.log` of an N-byte line + `process.exit(0)`,
+ * piped into a reader that sleeps 300 ms before draining, so the buffer really
+ * fills): N=200 000 → 65 536 delivered, N=70 000 → 65 536, **N=32 768 → 32 768
+ * delivered intact**. Since the ceiling refuses anything larger, no payload this
+ * function can emit is big enough for `console.log` to lose — the clamp alone
+ * carries the guarantee today, and the synchronous write is the redundant half.
+ * It stays anyway, and this is the trigger to re-read before touching either:
+ * **raise {@link REWRITE_ENVELOPE_MAX_BYTES} above 65 536 and the sync write
+ * becomes the ONLY thing standing between a large rewrite and silent
+ * truncation.** Swapping in `console.log` "because the cap already protects us"
+ * is safe only for as long as nobody moves the cap — which is precisely the kind
+ * of coupling that rots unremarked. Note also that no behavioural test can
+ * currently distinguish the two writers here (see `tests/lib/io.test.mjs`).
+ *
+ * {@link emitDeny} exits **2** when stdout is unwritable, because its decision is
+ * "block" and with the structured channel gone the exit code is the only
+ * blocking signal left. **This function must not copy that.** `emitRewrite`
+ * holds no decision to preserve: its degraded state is "the tool call runs with
+ * its original input", which is exactly what happens when no envelope is
+ * emitted. Exit 2 would convert that harmless loss into a block —
+ * `scripts/lib/pi-hook-bridge.mjs:389` treats the status unconditionally
+ * (`const blocked = result.status === 2 || …`, evaluated before stdout is
+ * consulted), and the documented contract says exit 2 discards stdout and feeds
+ * stderr back to Claude as an error. On the `AskUserQuestion` path that means
+ * the operator's question is destroyed to protect a wording improvement. Every
+ * failure here therefore degrades to "no stdout, exit 0, loud stderr" — the same
+ * asymmetry {@link emitWarn} documents, for the same reason.
+ *
+ * Never throws, for the reason {@link emitDeny} spells out: a throw unwinds into
+ * the `main().catch(() => emitAllow())` that four hooks install. Here that
+ * catch would be harmless by luck rather than by design, and a hook whose catch
+ * routes to `emitDeny` instead would turn a failed rewrite into a block.
+ *
+ * @param {object} updatedInput  The COMPLETE replacement tool input. A non-object,
+ *        `null`, an array, or a value `JSON.stringify` rejects degrades to a
+ *        no-op plus a stderr diagnostic — never a throw, never a partial emit.
+ * @returns {never}
+ */
+export function emitRewrite(updatedInput) {
+  /**
+   * Abandon the rewrite: say why on stderr, emit nothing, exit 0. The tool call
+   * then runs with its original input — the intended degraded state, not a
+   * fail-open, because this helper never held a decision to lose.
+   *
+   * @param {string} diagnostic
+   * @returns {never}
+   */
+  const bail = (diagnostic) => {
+    try {
+      process.stderr.write(
+        `⚠ io.mjs: emitRewrite ${diagnostic} — leaving the tool input unchanged\n`,
+      );
+    } catch { /* stderr may be closed; the silent no-op below is what matters */ }
+    process.exit(0);
+  };
+
+  if (updatedInput === null || typeof updatedInput !== 'object' || Array.isArray(updatedInput)) {
+    // `updatedInput` is a MAP in the bundle schema, so an array is as wrong as a
+    // string — and an array would serialize into a shape the harness cannot use.
+    bail(
+      `was called with ${Array.isArray(updatedInput) ? 'an array' : String(updatedInput === null ? 'null' : typeof updatedInput)}, not a tool-input object`,
+    );
+  }
+
+  let line;
+  try {
+    // The whole trap-closure: a two-key object literal, built here. No spread,
+    // no caller-supplied opts — nothing a caller passes can become a sibling of
+    // `updatedInput`, and `permissionDecision` therefore cannot appear.
+    line = JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        updatedInput,
+      },
+    });
+  } catch (err) {
+    // A cycle or a BigInt in the caller's object. JSON.stringify can also return
+    // undefined (a toJSON that yields undefined) — caught by the same guard.
+    bail(`could not serialize the tool input (${err?.message ?? String(err)})`);
+  }
+
+  if (typeof line !== 'string') {
+    bail('serialized the tool input to undefined (a toJSON returning undefined?)');
+  }
+
+  const bytes = Buffer.byteLength(`${line}\n`, 'utf8');
+  if (bytes > REWRITE_ENVELOPE_MAX_BYTES) {
+    // Refused whole, never sliced — see REWRITE_ENVELOPE_MAX_BYTES for why a
+    // clipped structure is worse than no structure.
+    bail(`envelope is ${bytes} bytes, over the ${REWRITE_ENVELOPE_MAX_BYTES}-byte ceiling`);
+  }
+
+  // Return value deliberately ignored: a rewrite that cannot be delivered costs
+  // the improvement, never the tool call. See the asymmetry note above.
+  writeStdoutLineSync(line);
+  process.exit(0);
+}
+
 /**
  * Inject a system message into the hook response without exiting.
  * @param {string} msg  Message text wrapped in a systemMessage JSON envelope on stdout.

package/scripts/lib/issue-budget.mjs

@@ -27,16 +27,89 @@
  * Stdlib only — the hook path must stay cheap enough to run on every Bash call.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
 import { writeJsonAtomicSync } from './io.mjs';
 import { resolveInstructionFile } from './common.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
 
-/** Runtime counter file, relative to the repo root. */
+/**
+ * Legacy single-slot counter file, relative to the repo root.
+ *
+ * Kept as the path for IDENTITY-LESS callers only, and as the one-time
+ * migration source for a session whose spend was recorded before #1141.
+ */
 export const BUDGET_STATE_REL = '.orchestrator/runtime/issue-budget.json';
 
+/** Directory holding the per-session counter files, relative to the repo root. */
+export const BUDGET_STATE_DIR_REL = '.orchestrator/runtime/issue-budget';
+
+/**
+ * Relative path of the counter file for one accounting session (#1141).
+ *
+ * WHY per session and not one file: the counter used to be ONE slot per
+ * WORKING COPY, keyed by whichever `sessionId` happened to write last, and
+ * `readBudgetState` zeroes the state whenever the file's `sessionId` differs
+ * from the reader's. Two concurrent sessions in one working copy therefore
+ * alternately reset each other's counter and BOTH ran with the cap silently
+ * off — measured 2026-08-23, where the live file was owned by a session that
+ * had started 11 h before the one reading it. Session identity belongs in the
+ * FILE NAME, not in a field the next writer overwrites.
+ *
+ * The name is a truncated SHA-256 rather than the id itself because session
+ * ids are operator/host-supplied strings: a semantic id contains `/`-free but
+ * unbounded text, and a raw id is a UUID. Hashing gives a fixed-length,
+ * filesystem-safe, path-traversal-free name for both shapes. 16 hex chars
+ * (64 bits) is far beyond the handful of sessions that ever share one working
+ * copy; revisit only if a repo ever needs the id to be readable from the name
+ * (it never has — every reader already knows which session it is).
+ *
+ * An identity-less caller (`null`/empty) keeps the legacy flat path: it never
+ * reads and never persists (see `readBudgetState` / `chargeIssueBudget`), so
+ * it needs a stable path only to NAME the store in messages.
+ *
+ * @param {string|null|undefined} sessionId accounting session key
+ * @returns {string} repo-relative path
+ */
+export function budgetStateRel(sessionId) {
+  const key = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  if (key === null) return BUDGET_STATE_REL;
+  const digest = digestSha256Short(key, { length: 16 });
+  return `${BUDGET_STATE_DIR_REL}/${digest}.json`;
+}
+
+/**
+ * Resolve the accounting key for a native session id.
+ *
+ * A semantic id is an accounting continuity bridge only after the native id
+ * proves that `current-session.json` belongs to this invocation. This neither
+ * establishes lock ownership nor bridges a host rotation that changes both ids.
+ *
+ * @param {string|null|undefined} candidateRawSessionId native hook/env session id
+ * @param {unknown} currentSession parsed `.orchestrator/current-session.json`
+ * @returns {string|null} semantic key for a verified pair, otherwise raw key
+ */
+export function resolveIssueBudgetSessionId(candidateRawSessionId, currentSession) {
+  const rawSessionId =
+    typeof candidateRawSessionId === 'string' && candidateRawSessionId.length > 0
+      ? candidateRawSessionId
+      : null;
+  if (
+    rawSessionId === null ||
+    !currentSession ||
+    typeof currentSession !== 'object' ||
+    Array.isArray(currentSession) ||
+    currentSession.session_id !== rawSessionId ||
+    typeof currentSession.semantic_session_id !== 'string' ||
+    currentSession.semantic_session_id.length === 0
+  ) {
+    return rawSessionId;
+  }
+  return currentSession.semantic_session_id;
+}
+
 /**
  * Commands whose issue creation MUST NOT be blocked, with the reason recorded
  * for the stderr trace and for the overflow bookkeeping.
@@ -96,12 +169,55 @@ export function loadIssueBudgetConfig(repoRoot) {
 }
 
 /**
- * Absolute path of the runtime counter file for a repo.
+ * Absolute path of the runtime counter file for one session in a repo.
+ *
  * @param {string} repoRoot
+ * @param {string|null} [sessionId] accounting session key; omitted/empty
+ *   yields the legacy identity-less flat path.
  * @returns {string}
  */
-export function budgetStatePath(repoRoot) {
-  return path.join(repoRoot, BUDGET_STATE_REL);
+export function budgetStatePath(repoRoot, sessionId = null) {
+  return path.join(repoRoot, budgetStateRel(sessionId));
+}
+
+/**
+ * Coerce a parsed counter file into a state object, or `null` when it does not
+ * belong to `accountingSessionId`.
+ *
+ * The owner check survives the move to per-session files: the file NAME now
+ * carries identity, but a hand-edited, hash-colliding or hand-copied file must
+ * still not hand its spend to a different session.
+ *
+ * @param {unknown} data
+ * @param {string} accountingSessionId
+ * @returns {{ sessionId: string, count: number, exempt: number, overflow: object[] }|null}
+ */
+function _coerceState(data, accountingSessionId) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+  if (data.sessionId !== accountingSessionId) return null;
+  return {
+    sessionId: accountingSessionId,
+    count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
+    exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
+    overflow: Array.isArray(data.overflow) ? data.overflow : [],
+  };
+}
+
+/**
+ * Read a counter file and coerce it, swallowing every I/O and parse error
+ * (fail-open: an unreadable ledger must never block a creation).
+ *
+ * @param {string} file
+ * @param {string} accountingSessionId
+ * @returns {object|null}
+ */
+function _readStateFile(file, accountingSessionId) {
+  if (!existsSync(file)) return null;
+  try {
+    return _coerceState(JSON.parse(readFileSync(file, 'utf8')), accountingSessionId);
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -109,39 +225,61 @@ export function budgetStatePath(repoRoot) {
  * a fresh zeroed state for `sessionId` — the counter is per session by
  * construction, so a new session never inherits the previous session's spend.
  *
+ * An identity-less invocation always gets a fresh state and never reads a
+ * persisted budget. It therefore cannot provide durable per-session continuity,
+ * but avoiding cross-session budget and overflow attribution wins over a
+ * continuity guess without a verified native identity.
+ *
+ * The counter file is per session since #1141, but an identity-less charge
+ * still must never PERSIST its fresh state — it would land on the shared
+ * legacy path and, before the split, silently zeroed a live session's count
+ * and deleted its parked overflow records. `chargeIssueBudget` enforces that
+ * write-side half.
+ *
+ * MIGRATION (one-time, read-only): a session that started before the per-session
+ * split has its spend in the legacy flat file. When no per-session file exists
+ * yet and the legacy file still names THIS session, seed from it — otherwise the
+ * split itself would hand every in-flight session a fresh cap, which is the very
+ * failure it exists to remove. The legacy file is never written back; the first
+ * charge after the seed persists to the per-session path.
+ *
  * @param {string} repoRoot
  * @param {string|null} sessionId
  * @returns {{ sessionId: string|null, count: number, exempt: number, overflow: object[] }}
  */
 export function readBudgetState(repoRoot, sessionId) {
-  const fresh = { sessionId: sessionId ?? null, count: 0, exempt: 0, overflow: [] };
-  const file = budgetStatePath(repoRoot);
-  if (!existsSync(file)) return fresh;
-  try {
-    const data = JSON.parse(readFileSync(file, 'utf8'));
-    if (!data || typeof data !== 'object') return fresh;
-    if (sessionId && data.sessionId && data.sessionId !== sessionId) return fresh;
-    return {
-      sessionId: data.sessionId ?? sessionId ?? null,
-      count: Number.isInteger(data.count) && data.count >= 0 ? data.count : 0,
-      exempt: Number.isInteger(data.exempt) && data.exempt >= 0 ? data.exempt : 0,
-      overflow: Array.isArray(data.overflow) ? data.overflow : [],
-    };
-  } catch {
-    return fresh;
-  }
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [] };
+  if (accountingSessionId === null) return fresh;
+
+  const ownFile = budgetStatePath(repoRoot, accountingSessionId);
+  const own = _readStateFile(ownFile, accountingSessionId);
+  if (own) return own;
+  // A present-but-unusable own file is a fail-open fresh state, NOT a reason to
+  // fall back to the legacy slot — the migration seed applies only before the
+  // session has a file of its own.
+  if (existsSync(ownFile)) return fresh;
+
+  return _readStateFile(path.join(repoRoot, BUDGET_STATE_REL), accountingSessionId) ?? fresh;
 }
 
 /**
- * Persist the counter file. Best-effort: a write failure never blocks a
- * creation (fail-open), it only means the count is under-reported.
+ * Persist the counter file for `state.sessionId`. Best-effort: a write failure
+ * never blocks a creation (fail-open), it only means the count is
+ * under-reported.
+ *
+ * The target path is derived from `state.sessionId`, so a state object can only
+ * ever be written into its OWN session's slot. `writeJsonAtomicSync` mkdir -p's
+ * the containing directory (`io.mjs#atomicWriteWithBackup`), which is what
+ * creates `.orchestrator/runtime/issue-budget/` on first use.
  *
  * @param {string} repoRoot
  * @param {object} state
  * @returns {boolean} true on success
  */
 export function writeBudgetState(repoRoot, state) {
-  const res = writeJsonAtomicSync(budgetStatePath(repoRoot), state, {
+  const res = writeJsonAtomicSync(budgetStatePath(repoRoot, state?.sessionId ?? null), state, {
     tmpPrefix: '.issue-budget',
   });
   return res.ok === true;
@@ -192,7 +330,12 @@ export function chargeIssueBudget({
   const max = cfg['max-per-session'];
   const mode = cfg.mode;
   const overflowSink = cfg.overflow;
-  const overflowPath = budgetStatePath(repoRoot);
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  // Per-session store (#1141) — the path an operator or session-end must open
+  // to find THIS session's parked overflow, so the verdict has to name the
+  // session's own slot, not the directory or the legacy flat file.
+  const overflowPath = budgetStatePath(repoRoot, accountingSessionId);
 
   const base = { max, mode, overflowSink, overflowPath };
 
@@ -200,13 +343,21 @@ export function chargeIssueBudget({
     return { ...base, decision: 'off', count: 0, overflowCount: 0, reason: null };
   }
 
-  const state = readBudgetState(repoRoot, sessionId);
-  state.sessionId = sessionId ?? state.sessionId;
+  const state = readBudgetState(repoRoot, accountingSessionId);
+  state.sessionId = accountingSessionId;
+
+  // An identity-less charge has no key to account under, so it must not touch
+  // the SHARED counter file at all. Writing its fresh state would reset a live
+  // session's count to 0 AND drop its parked overflow[] entries — breaking the
+  // strict cap (a single identity-less call clears it) and session-end's
+  // "nothing is lost" promise. Read-side isolation alone does not cover this.
+  const persist = (next) =>
+    accountingSessionId === null ? false : writeBudgetState(repoRoot, next);
 
   const { exempt, reason } = classifyExemption(command);
   if (exempt) {
     state.exempt += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return {
       ...base,
       decision: 'exempt',
@@ -218,13 +369,13 @@ export function chargeIssueBudget({
 
   if (state.count < max) {
     state.count += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return { ...base, decision: 'allow', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
   if (mode === 'warn') {
     state.count += 1;
-    writeBudgetState(repoRoot, state);
+    persist(state);
     return { ...base, decision: 'warn', count: state.count, overflowCount: state.overflow.length, reason: null };
   }
 
@@ -234,7 +385,7 @@ export function chargeIssueBudget({
     command: String(command).slice(0, 500),
     at: now,
   });
-  writeBudgetState(repoRoot, state);
+  persist(state);
   return {
     ...base,
     decision: 'block',
@@ -267,3 +418,105 @@ export function formatBlockReason(v) {
     `\`mode: warn\` reports without blocking, \`mode: off\` disables the gate.`,
   ].join('\n');
 }
+
+/**
+ * Default age past which a per-session counter file is reaped (#1151).
+ *
+ * BV-004 ceiling: 14 days is a "nobody will ever drain this now" horizon, not a
+ * measured retention requirement. A session's overflow is drained at ITS OWN
+ * close (session-end Phase 5 Step 3b), so a file still carrying undrained
+ * overflow two weeks later belongs to a session that ended without closing —
+ * its parked items are already unreachable by the drain, which only ever reads
+ * the CURRENT session's file. Revisit if a triage workflow ever reads a foreign
+ * session's overflow after the fact.
+ */
+export const BUDGET_REAP_MAX_AGE_DAYS = 14;
+
+/**
+ * Recognised per-session counter file name — the 16-hex digest `budgetStateRel`
+ * emits, plus `.json`. Anything else in the directory is left alone: the reaper
+ * must only ever remove files it can prove it wrote itself.
+ */
+const BUDGET_FILE_NAME_RE = /^[0-9a-f]{16}\.json$/;
+
+/**
+ * Remove stale per-session counter files (#1151).
+ *
+ * WHY: the per-session split (#1141) writes one file per accounting session
+ * into `.orchestrator/runtime/issue-budget/` and NOTHING ever removed them —
+ * there was not a single unlink site for that directory in the repo. Every
+ * session in a working copy therefore left a permanent 100-200 byte artefact
+ * behind. This is the missing other half of the file's lifecycle, owned by
+ * session-end Phase 5 Step 3b (the drain runs first, this sweeps after).
+ *
+ * Age is judged by MTIME, and the CURRENT session's file is exempt regardless
+ * of age. Both halves are safety, not convenience: a parallel session in the
+ * same working copy (PSA-001) owns a file this process did not write, and its
+ * freshly-touched mtime is the only evidence available here that the owner is
+ * still alive — the same age-gate discipline `session-registry.mjs`
+ * `sweepZombies` uses for in-flight claim files.
+ *
+ * Best-effort by contract: every failure path is swallowed and the file counted
+ * as kept. A reaper that throws would abort the session close it runs inside,
+ * which is a strictly worse outcome than an un-reaped counter file.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   sessionId?: string|null,
+ *   maxAgeDays?: number,
+ *   now?: number,
+ * }} opts `sessionId` is the accounting session id whose file must survive;
+ *   `now` is an epoch-ms injection point for tests.
+ * @returns {{ removed: string[], kept: string[] }} absolute paths, so a caller
+ *   gets both a count (`.length`) and an audit trail.
+ */
+export function reapStaleBudgetFiles({
+  repoRoot,
+  sessionId = null,
+  maxAgeDays = BUDGET_REAP_MAX_AGE_DAYS,
+  now = Date.now(),
+} = {}) {
+  const removed = [];
+  const kept = [];
+  try {
+    const dir = path.join(repoRoot, BUDGET_STATE_DIR_REL);
+    const cutoff = now - maxAgeDays * 24 * 60 * 60 * 1000;
+    const ownFile =
+      typeof sessionId === 'string' && sessionId.length > 0
+        ? budgetStatePath(repoRoot, sessionId)
+        : null;
+
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      // No directory yet (or unreadable) — nothing to reap, not an error.
+      return { removed, kept };
+    }
+
+    for (const name of names) {
+      // Unrecognised entries are not part of this reaper's population at all:
+      // neither removed nor reported as kept.
+      if (!BUDGET_FILE_NAME_RE.test(name)) continue;
+      const file = path.join(dir, name);
+      if (file === ownFile) {
+        kept.push(file);
+        continue;
+      }
+      try {
+        if (statSync(file).mtimeMs >= cutoff) {
+          kept.push(file);
+          continue;
+        }
+        unlinkSync(file);
+        removed.push(file);
+      } catch {
+        // Vanished under us (a peer's own reaper), or permission-denied.
+        kept.push(file);
+      }
+    }
+  } catch {
+    // Unreachable in practice; the contract is "never throws", not "never fails".
+  }
+  return { removed, kept };
+}