session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/io.mjs

@@ -17,7 +17,7 @@
  */
 
 import { writeFile, rename, mkdir } from 'node:fs/promises';
-import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync, writeSync } from 'node:fs';
 import path, { dirname } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 
@@ -27,6 +27,12 @@ import { randomBytes, randomUUID } from 'node:crypto';
 
 /**
  * Build the deny reason string, optionally appending a suggestion.
+ *
+ * Multi-line `reason` values are passed through verbatim — callers that need a
+ * several-line rationale (e.g. hooks/pre-bash-destructive-guard.mjs) rely on
+ * this. `JSON.stringify` later escapes the newlines, so the emitted payload
+ * still occupies exactly one stdout line.
+ *
  * @param {string} reason
  * @param {string|undefined} suggestion
  * @returns {string}
@@ -35,6 +41,161 @@ function _formatReason(reason, suggestion) {
   return suggestion ? `${reason} — ${suggestion}` : reason;
 }
 
+/** Max length of the operator-facing `systemMessage` headline. */
+const DENY_HEADLINE_MAX = 200;
+
+/**
+ * Hard ceiling (in characters) for `permissionDecisionReason`.
+ *
+ * Rationale is empirical, not a round number pulled from the air. Measured
+ * worst-case reason lengths across all 12 live `emitDeny` call sites:
+ *
+ * | call site                                    | measured chars |
+ * |----------------------------------------------|----------------|
+ * | pre-bash-destructive-guard (worst of 14 rules) | 435          |
+ * | pre-bash-templates-first (fixed part)         | 348 + command |
+ * | pre-bash-issue-budget (formatBlockReason)     | 652           |
+ * | config-protection (all 6 reasons at once)     | 432           |
+ * | enforce-scope (LIVE wave-scope, 18 paths)     | 1 322         |
+ * | enforce-scope (deep wave, 144-path union)     | ~9 068        |
+ *
+ * `enforce-scope` joins `allowedPaths` into BOTH the reason and the suggestion,
+ * so its length grows at ~2× the union. A deep session (18 agents) with a wide
+ * union is the binding constraint at ~9 k — which is why the ceiling is NOT the
+ * 8 000 originally proposed: that would clip a legitimate deep-wave scope
+ * violation exactly when the operator most needs the path list. 16 000 sits
+ * ~1.8× above that worst case and ~12× above the largest measured live reason,
+ * while staying ~4× below the 65 536-byte kernel pipe buffer — so even the clamp
+ * ALONE keeps a typical-ASCII envelope inside one buffer.
+ */
+const DENY_REASON_MAX = 16_000;
+
+/**
+ * Hard ceiling (in characters) for the operator-facing `systemMessage` that
+ * {@link emitWarn} emits.
+ *
+ * Same ceiling as {@link DENY_REASON_MAX}, and for the same measured reason:
+ * the warn path shares its call sites with the deny path — `enforce-scope` calls
+ * `emitDeny(reason, suggestion)` under `strict` and `emitWarn(reason — suggestion)`
+ * under `warn`, on the identical text. The binding case is therefore identical
+ * too (a deep wave's 144-path allowedPaths union, ~9 068 chars, interpolated into
+ * both halves), so a tighter warn ceiling would clip exactly the path list the
+ * operator needs. 16 000 stays ~4× below the 65 536-byte kernel pipe buffer.
+ *
+ * NOT reused as a shared alias by accident: `emitDeny` splits its text across a
+ * clipped 200-char headline plus the full `permissionDecisionReason`, whereas
+ * `systemMessage` is the warn path's ONLY carrier — this constant is what makes
+ * that difference explicit rather than incidental.
+ */
+const WARN_MESSAGE_MAX = 16_000;
+
+/**
+ * Reason substituted when a caller denies without supplying one.
+ *
+ * A guard must never fail on its own bookkeeping: throwing here used to land in
+ * the fail-open `main().catch(() => emitAllow())` of four hooks
+ * (pre-bash-destructive-guard, pre-bash-issue-budget, pre-bash-templates-first,
+ * config-protection) and turn a deny into an ALLOW. The programmer-error signal
+ * is preserved as a stderr diagnostic instead of a throw.
+ */
+const EMPTY_REASON_FALLBACK =
+  'Denied by a session-orchestrator guard that did not supply a reason (guard bug — see stderr). '
+  + 'Blocking rather than allowing: a guard must fail closed.';
+
+/** stdout file descriptor. */
+const STDOUT_FD = 1;
+
+/** Backoff between EAGAIN retries in the synchronous stdout writer. */
+const STDOUT_EAGAIN_BACKOFF_MS = 1;
+
+/**
+ * Clip `text` to `max` characters, marking the cut with an ellipsis.
+ *
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function _clip(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/**
+ * Derive the short operator-facing headline from a (possibly multi-line) reason.
+ * First line only, clipped — the full text stays in `permissionDecisionReason`.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function _denyHeadline(reason) {
+  return `⛔ ${_clip(reason.split('\n')[0].trim(), DENY_HEADLINE_MAX)}`;
+}
+
+/**
+ * Clamp a reason/message to `max` characters, appending a visible marker that
+ * names how much was dropped. The marker is budgeted INSIDE the ceiling, so the
+ * returned string never exceeds it.
+ *
+ * @param {string} reason
+ * @param {number} [max=DENY_REASON_MAX]
+ * @returns {string}
+ */
+function _clampReason(reason, max = DENY_REASON_MAX) {
+  if (reason.length <= max) return reason;
+  const marker = `\n… [truncated: showing ${max} of ${reason.length} characters]`;
+  return reason.slice(0, max - marker.length) + marker;
+}
+
+/**
+ * Synchronously write one line (a trailing `\n` is appended) to stdout,
+ * looping until every byte is handed to the kernel.
+ *
+ * ## Why this exists instead of `console.log`
+ *
+ * `process.stdout` is **asynchronous when it is a pipe on macOS** (Node docs,
+ * "process I/O": "Pipes and sockets: … asynchronous on macOS") — exactly the
+ * configuration every Claude Code hook runs under. `console.log` therefore only
+ * QUEUES the write: whatever does not fit into the 65 536-byte kernel pipe
+ * buffer stays in libuv's write queue, and `process.exit()` discards it. The
+ * observable result is a truncated, unparseable JSON envelope delivered with
+ * exit 0.
+ *
+ * Before #906 that truncation was harmless: `emitDeny` exited **2**, which
+ * blocks regardless of stdout. Once the helper moved to `exit 0` + structured
+ * JSON, the same truncation flipped the guard layer from fail-CLOSED to
+ * fail-OPEN — a >64 KB reason meant the harness saw no structured output and
+ * ALLOWED the tool call. `writeSync` bypasses the libuv queue entirely, so the
+ * bytes are in the kernel before `process.exit` runs.
+ *
+ * EAGAIN is expected when fd 1 is non-blocking and the pipe is momentarily
+ * full; the loop backs off and retries rather than dropping the tail. Any other
+ * error (EPIPE — reader gone) is reported to the caller, which must then decide
+ * how to signal WITHOUT stdout. Never throws.
+ *
+ * @param {string} line  Payload without trailing newline.
+ * @returns {{ ok: true, bytesWritten: number } | { ok: false, bytesWritten: number, error: string }}
+ */
+export function writeStdoutLineSync(line) {
+  const buf = Buffer.from(`${line}\n`, 'utf8');
+  let offset = 0;
+  while (offset < buf.length) {
+    let written;
+    try {
+      written = writeSync(STDOUT_FD, buf, offset, buf.length - offset);
+    } catch (err) {
+      const code = err?.code;
+      if (code === 'EAGAIN' || code === 'EINTR') {
+        // Synchronous backoff: Atomics.wait is the only event-loop-free sleep,
+        // and the event loop is precisely what we cannot yield to here.
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, STDOUT_EAGAIN_BACKOFF_MS);
+        continue;
+      }
+      return { ok: false, bytesWritten: offset, error: code ?? String(err) };
+    }
+    offset += written;
+  }
+  return { ok: true, bytesWritten: offset };
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -124,24 +285,198 @@ export function emitAllow() {
 }
 
 /**
- * Deny the current hook invocation with a structured JSON reason on stdout, then exit 2.
- * @param {string} reason  Non-empty human-readable denial reason.
+ * Deny the current **PreToolUse** hook invocation: emit exactly one JSON object
+ * on stdout, then exit **0**.
+ *
+ * ## The contract (code.claude.com/docs/en/hooks), verbatim
+ *
+ * > "**Exit 2** means a blocking error. Claude Code **ignores stdout and any
+ * > JSON in it**. Instead, stderr text is fed back to Claude as an error
+ * > message."
+ *
+ * > "You must choose one approach per hook, **not both**: either use exit codes
+ * > alone for signaling, or exit 0 and print JSON for structured control."
+ *
+ * > "Unlike other hooks that use a top-level `decision` field, **PreToolUse
+ * > returns its decision inside a `hookSpecificOutput` object**" — which
+ * > "requires a `hookEventName` field set to the event name."
+ *
+ * > PreToolUse top-level `decision` / `reason` are deprecated: "Use
+ * > `hookSpecificOutput.permissionDecision` and
+ * > `hookSpecificOutput.permissionDecisionReason` instead."
+ *
+ * Until #906 this function emitted stdout JSON **and** `exit 2` — the mixed
+ * form the second quote forbids. The block still bit, but the reason was
+ * discarded wholesale and the operator saw only `hook error: … No stderr
+ * output`, i.e. what looks like a crash. Do not reintroduce either half of that
+ * mixed form: `exit 2` here, or a flat top-level `{permissionDecision, reason}`.
+ *
+ * ## Emitted payload (single stdout line, nothing else on stdout)
+ *
+ * ```json
+ * {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"<reason — suggestion>"},"systemMessage":"⛔ <first line of reason>"}
+ * ```
+ *
+ * `permissionDecisionReason` is fed to **Claude**; the universal `systemMessage`
+ * field is what the **operator** sees. Both are emitted on purpose: operator
+ * visibility is the entire point of the #906 repair, and a `deny` whose cause is
+ * invisible to the human is what pushed wave agents into circumventing the
+ * enforcement layer. The headline is deliberately short (first line, clipped) —
+ * the long text belongs in `permissionDecisionReason`.
+ *
+ * Multi-line reasons survive intact: `JSON.stringify` escapes the newlines, so
+ * the payload stays exactly one line and consumers that parse stdout line-wise
+ * (e.g. `scripts/lib/pi-hook-bridge.mjs`) keep working.
+ *
+ * ## PRECONDITION — PreToolUse hooks only
+ *
+ * `hookEventName` is hardcoded to `PreToolUse`. PostToolUse / Stop /
+ * SubagentStop signal through a **top-level** `decision` / `reason` pair and
+ * MUST NOT be routed through this helper.
+ *
+ * ## Delivery is part of the contract, not an implementation detail
+ *
+ * The envelope goes out through {@link writeStdoutLineSync}, never
+ * `console.log`. On macOS a piped stdout is asynchronous, so `console.log` +
+ * `process.exit(0)` silently drops everything past the 65 536-byte kernel pipe
+ * buffer — a truncated envelope reads as "no structured output" and the tool
+ * call is ALLOWED. Two independent bounds keep that from happening:
+ *
+ *  1. `permissionDecisionReason` is clamped to {@link DENY_REASON_MAX}, and the
+ *     `opts.systemMessage` override to {@link DENY_HEADLINE_MAX}, so no caller
+ *     — including one that funnels attacker-controlled tool input into the
+ *     reason, as pre-bash-templates-first does with the raw bash command — can
+ *     inflate the envelope past the buffer.
+ *  2. The write itself is synchronous and loops to completion, so even an
+ *     envelope that somehow exceeds the buffer still lands in full.
+ *
+ * Both are load-bearing: the clamp alone would not survive a caller that
+ * bypasses it, and the synchronous write alone would ship 200 KB envelopes to
+ * the harness. If stdout cannot be written at all (EPIPE — the reader is gone),
+ * the helper exits **2**: with no structured channel left, the exit code is the
+ * only remaining way to block, and the "never both" rule is not violated
+ * because no parseable JSON was delivered.
+ *
+ * @param {string} reason  Human-readable denial reason. May be multi-line. When
+ *        blank/absent the call still DENIES (with a generic reason plus a stderr
+ *        diagnostic) — see {@link EMPTY_REASON_FALLBACK} for why this does not
+ *        throw.
  * @param {string} [suggestion]  Optional remediation hint appended after " — ".
+ * @param {object} [opts]
+ * @param {string} [opts.systemMessage]  Override the derived operator headline.
+ *        Ignored when blank; clipped to one short line.
  * @returns {never}
  */
-export function emitDeny(reason, suggestion) {
-  if (!reason) throw new TypeError('io.mjs: emitDeny requires a non-empty reason string');
-  console.log(JSON.stringify({ permissionDecision: 'deny', reason: _formatReason(reason, suggestion) }));
-  process.exit(2);
+export function emitDeny(reason, suggestion, opts = {}) {
+  // Coerce defensively and never throw: a throw inside a deny path unwinds into
+  // the fail-open `main().catch(() => emitAllow())` that four hooks install,
+  // turning the deny into an ALLOW. A guard must never fail open on its own
+  // bookkeeping — so a missing reason degrades to a generic deny plus a loud
+  // stderr diagnostic, which keeps the programmer-error signal without the
+  // fail-open blast radius.
+  const raw = typeof reason === 'string'
+    ? reason
+    : (reason === null || reason === undefined ? '' : String(reason));
+  const missingReason = raw.trim() === '';
+  if (missingReason) {
+    try {
+      process.stderr.write(
+        '⚠ io.mjs: emitDeny called without a reason — denying with a generic message (guard bug)\n',
+      );
+    } catch { /* stderr may be closed; the deny below is what matters */ }
+  }
+  const permissionDecisionReason = _clampReason(
+    String(_formatReason(missingReason ? EMPTY_REASON_FALLBACK : raw, suggestion)),
+  );
+  const override = typeof opts?.systemMessage === 'string' ? opts.systemMessage.trim() : '';
+  const line = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason,
+    },
+    systemMessage: override !== ''
+      ? _clip(override, DENY_HEADLINE_MAX)
+      : _denyHeadline(permissionDecisionReason),
+  });
+  const result = writeStdoutLineSync(line);
+  // stdout delivered → exit 0 (structured channel). stdout unwritable → exit 2,
+  // the only blocking signal left. Never exit 0 on a failed write: that is the
+  // fail-open case this whole helper exists to prevent.
+  process.exit(result.ok ? 0 : 2);
 }
 
 /**
- * Emit a warning message to stderr and exit 0 (allow with notice).
- * @param {string} message  Warning text written to stderr prefixed with "⚠ ".
+ * Emit an operator-visible warning and exit **0** — "allow, with a notice".
+ *
+ * ## Why this is not stderr-only (#916)
+ *
+ * Until #916 this helper wrote only to stderr. Under the exit-0 branch of the
+ * hook contract that channel goes nowhere: `docs/plugin-architecture-v3.md`
+ * states "stderr | Only for debugging. Not surfaced to the user.", and
+ * `skills/hook-development/SKILL.md` puts it plainly — "When the hook exits 0
+ * here it is **silent** — no stdout, no stderr". So every `enforcement: warn`
+ * scope/command violation was announced to a debug log and to nobody else. A
+ * warning that reaches neither the operator nor the model is not a warning.
+ *
+ * The visible channel is the universal top-level `systemMessage` field — the
+ * same one {@link emitDeny} already rides for its ⛔ headline, and the one
+ * {@link emitSystemMessage} documents. It is emitted here WITHOUT any
+ * `hookSpecificOutput` / `permissionDecision`, which is precisely what keeps
+ * warn non-blocking: the harness sees a message but no decision.
+ *
+ * stderr is retained unchanged for debug-log and CI-capture parity.
+ *
+ * ## Consumer contract — stdout in the warn path is no longer empty
+ *
+ * `scripts/lib/pi-hook-bridge.mjs#readHookDecision` scans stdout line-wise and
+ * keeps the first line that actually carries a `permissionDecision`; a
+ * decision-less JSON line (this one) is skipped, so the Pi lane reports
+ * `{decision: null, deny: false, malformed: false}` ⇒ not blocked. Verified
+ * empirically, not assumed. Codex does not wire these hooks at all
+ * (`hooks/hooks-codex.json` has `"PreToolUse": []`), and `hooks/hooks-cursor.json`
+ * is a documentation-only mapping reference with no in-repo executor.
+ *
+ * ## Delivery: the same two bounds {@link emitDeny} uses, for a sharper reason
+ *
+ * The write goes through {@link writeStdoutLineSync}, never `console.log`, and
+ * the message is clamped to {@link WARN_MESSAGE_MAX}. On macOS a piped stdout is
+ * asynchronous, so `console.log` + `process.exit(0)` drops everything past the
+ * 65 536-byte kernel pipe buffer — and `enforce-scope` interpolates the whole
+ * `allowedPaths` union into its warn text TWICE, so this path genuinely reaches
+ * five figures. A truncated line here is worse than a lost warning: the Pi
+ * bridge classifies an unparseable `{`-prefixed line as `malformed`, which for
+ * PreToolUse fails CLOSED — i.e. pipe truncation would silently convert
+ * `enforcement: warn` into a hard block. Both bounds are load-bearing.
+ *
+ * ## Deliberate asymmetry to emitDeny: an unwritable stdout still exits 0
+ *
+ * {@link emitDeny} exits 2 when stdout cannot be written, because with no
+ * structured channel left the exit code is its only way to block. The warn path
+ * inverts that: its decision is "allow", so a failed write must cost the
+ * NOTICE, never the permission. Exiting non-zero here would turn a dropped
+ * warning into a blocked tool call.
+ *
+ * @param {string} message  Warning text. Emitted on stderr and as the
+ *        `systemMessage` payload, both prefixed with "⚠ ".
  * @returns {never}
  */
 export function emitWarn(message) {
-  console.error(`⚠ ${message}`);
+  // Coerce defensively: a throw here would unwind into the callers' top-level
+  // `main().catch(() => emitDeny(...))`, turning an allow-with-notice into a DENY.
+  const raw = typeof message === 'string'
+    ? message
+    : (message === null || message === undefined ? '' : String(message));
+  const text = `⚠ ${_clampReason(raw, WARN_MESSAGE_MAX)}`;
+
+  // Debug channel — unchanged. Invisible under exit 0, kept for log/CI capture.
+  try {
+    console.error(text);
+  } catch { /* stderr may be closed; the visible channel below is what matters */ }
+
+  // Visible channel. Return value is deliberately ignored — see the asymmetry
+  // note above: a warning that cannot be delivered must not become a block.
+  writeStdoutLineSync(JSON.stringify({ systemMessage: text }));
   process.exit(0);
 }
 

package/scripts/lib/issue-budget.mjs

@@ -0,0 +1,269 @@
+/**
+ * issue-budget.mjs — per-session issue-creation cap: state, exemptions, verdict.
+ *
+ * WHY: measured on the private instance over four weeks, sessions created 1784
+ * issues against 1285 closed (net +499), with a median inter-creation gap of
+ * 2.6 s and 62 % of creations inside bursts of >= 5 per minute. The pre-existing
+ * `discovery-severity-threshold` / `discovery-confidence-threshold` keys cannot
+ * bound that: they filter individual FINDINGS by quality (and the `low` default
+ * filters nothing), they are only consulted in skill prose, and the biggest
+ * producers — session-end carryover filing, plan issue creation,
+ * `scripts/lib/spiral-carryover.mjs` — never read them at all.
+ *
+ * This module is the single decision point for BOTH producer paths:
+ *   - shell path:        `hooks/pre-bash-issue-budget.mjs` (PreToolUse/Bash)
+ *   - programmatic path: `scripts/lib/spiral-carryover.mjs` `runCli()`
+ *
+ * EXEMPTIONS ARE LOAD-BEARING. `skills/session-end/SKILL.md` carries two
+ * standing promises the cap must not break:
+ *   - `:319` — "SPIRAL / FAILED agent carryover → auto-carry candidate …
+ *     (non-deselectable)"
+ *   - `:1113` — "ALWAYS create issues for unfinished PLANNED work … nothing
+ *     planned-but-unfinished is 'remembered' without one."
+ * A cap that silently swallowed a SPIRAL carryover would turn a hard promise
+ * into a lie, so the carryover class plus `priority::critical` bypass the cap
+ * entirely (they are counted for observability, but never blocked).
+ *
+ * Stdlib only — the hook path must stay cheap enough to run on every Bash call.
+ */
+
+import { existsSync, readFileSync } 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. */
+export const BUDGET_STATE_REL = '.orchestrator/runtime/issue-budget.json';
+
+/**
+ * Commands whose issue creation MUST NOT be blocked, with the reason recorded
+ * for the stderr trace and for the overflow bookkeeping.
+ *
+ * Each entry is `[regex, reason]`. Both the scoped (`priority::critical`) and
+ * the legacy unscoped (`priority:critical`) spellings are accepted: the label
+ * migration to scoped `priority::` runs alongside this change and a
+ * half-migrated producer must not lose its exemption mid-flight.
+ */
+const EXEMPT_RULES = [
+  [/priority::?critical\b/i, 'priority::critical'],
+  // `[Carryover] [SPIRAL] …` / `[Carryover] [FAILED] …` — the exact title
+  // template `createSpiralCarryoverIssue` emits, plus the `type::carryover`
+  // and bare `carryover` labels used by the vault/drift/docs strict fallbacks.
+  [/\[(SPIRAL|FAILED)\]/, 'spiral-failed-auto-carry'],
+  [/\[Carryover\]/i, 'carryover-class'],
+  [/\btype::?carryover\b/i, 'carryover-class'],
+  [/(^|[\s,"'=])carryover([\s,"']|$)/i, 'carryover-class'],
+  [/(^|[\s,"'=])broken-window([\s,"']|$)/i, 'broken-window-closure'],
+  [/\[Backlog-Sammel\]/i, 'overflow-collector'],
+];
+
+/**
+ * Decide whether an issue-create command bypasses the cap.
+ *
+ * @param {string} command — the full shell command (or a reconstructed argv join)
+ * @returns {{ exempt: boolean, reason: string|null }}
+ */
+export function classifyExemption(command) {
+  if (typeof command !== 'string' || command.length === 0) {
+    return { exempt: false, reason: null };
+  }
+  for (const [re, reason] of EXEMPT_RULES) {
+    if (re.test(command)) return { exempt: true, reason };
+  }
+  return { exempt: false, reason: null };
+}
+
+/**
+ * Load the `issue-budget` config from the repo's instruction file
+ * (CLAUDE.md / AGENTS.md). Reads only that one file and only that one block —
+ * `parseSessionConfig()` is deliberately NOT used here so the hook path does
+ * not pay for host-path resolution and owner.yaml I/O on every Bash call.
+ *
+ * @param {string} repoRoot
+ * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ */
+export function loadIssueBudgetConfig(repoRoot) {
+  const defaults = { 'max-per-session': 12, mode: 'strict', overflow: 'collect-issue' };
+  try {
+    const resolved = resolveInstructionFile(repoRoot);
+    if (!resolved) return defaults;
+    return _parseIssueBudget(readFileSync(resolved.path, 'utf8'));
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Absolute path of the runtime counter file for a repo.
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+export function budgetStatePath(repoRoot) {
+  return path.join(repoRoot, BUDGET_STATE_REL);
+}
+
+/**
+ * Read the counter file. A missing, malformed, or foreign-session file yields
+ * a fresh zeroed state for `sessionId` — the counter is per session by
+ * construction, so a new session never inherits the previous session's spend.
+ *
+ * @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;
+  }
+}
+
+/**
+ * Persist the counter file. Best-effort: a write failure never blocks a
+ * creation (fail-open), it only means the count is under-reported.
+ *
+ * @param {string} repoRoot
+ * @param {object} state
+ * @returns {boolean} true on success
+ */
+export function writeBudgetState(repoRoot, state) {
+  const res = writeJsonAtomicSync(budgetStatePath(repoRoot), state, {
+    tmpPrefix: '.issue-budget',
+  });
+  return res.ok === true;
+}
+
+/**
+ * Charge one issue creation against the session budget and return the verdict.
+ *
+ * Decision table:
+ *   mode `off`                          → `{ decision: 'off' }`, no state written
+ *   exempt command                      → `{ decision: 'exempt' }`, `exempt` counter++
+ *   count < max                         → `{ decision: 'allow' }`, `count`++
+ *   count >= max, mode `warn`           → `{ decision: 'warn' }`, `count`++ (creation proceeds)
+ *   count >= max, mode `strict`         → `{ decision: 'block' }`, overflow record appended
+ *
+ * In `strict` the blocked creation is NOT counted (it never happened); the
+ * request is parked in `overflow[]` so session-end can file exactly one
+ * collector issue instead of losing the item.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   sessionId?: string|null,
+ *   command: string,
+ *   title?: string|null,
+ *   config?: { "max-per-session": number, mode: string, overflow: string },
+ *   now?: string,
+ * }} opts
+ * @returns {{
+ *   decision: 'off'|'exempt'|'allow'|'warn'|'block',
+ *   count: number,
+ *   max: number,
+ *   mode: string,
+ *   overflowSink: string,
+ *   overflowPath: string,
+ *   overflowCount: number,
+ *   reason?: string|null,
+ * }}
+ */
+export function chargeIssueBudget({
+  repoRoot,
+  sessionId = null,
+  command,
+  title = null,
+  config,
+  now = new Date().toISOString(),
+}) {
+  const cfg = config ?? loadIssueBudgetConfig(repoRoot);
+  const max = cfg['max-per-session'];
+  const mode = cfg.mode;
+  const overflowSink = cfg.overflow;
+  const overflowPath = budgetStatePath(repoRoot);
+
+  const base = { max, mode, overflowSink, overflowPath };
+
+  if (mode === 'off') {
+    return { ...base, decision: 'off', count: 0, overflowCount: 0, reason: null };
+  }
+
+  const state = readBudgetState(repoRoot, sessionId);
+  state.sessionId = sessionId ?? state.sessionId;
+
+  const { exempt, reason } = classifyExemption(command);
+  if (exempt) {
+    state.exempt += 1;
+    writeBudgetState(repoRoot, state);
+    return {
+      ...base,
+      decision: 'exempt',
+      count: state.count,
+      overflowCount: state.overflow.length,
+      reason,
+    };
+  }
+
+  if (state.count < max) {
+    state.count += 1;
+    writeBudgetState(repoRoot, state);
+    return { ...base, decision: 'allow', count: state.count, overflowCount: state.overflow.length, reason: null };
+  }
+
+  if (mode === 'warn') {
+    state.count += 1;
+    writeBudgetState(repoRoot, state);
+    return { ...base, decision: 'warn', count: state.count, overflowCount: state.overflow.length, reason: null };
+  }
+
+  // strict — park the request, do not count it.
+  state.overflow.push({
+    title: title ?? null,
+    command: String(command).slice(0, 500),
+    at: now,
+  });
+  writeBudgetState(repoRoot, state);
+  return {
+    ...base,
+    decision: 'block',
+    count: state.count,
+    overflowCount: state.overflow.length,
+    reason: null,
+  };
+}
+
+/**
+ * Human-readable block message. Shared by the hook (stderr + deny JSON) and the
+ * programmatic path so an agent sees the same instruction either way.
+ *
+ * @param {{ count: number, max: number, overflowPath: string, overflowSink: string, overflowCount: number }} v
+ * @returns {string}
+ */
+export function formatBlockReason(v) {
+  const sink =
+    v.overflowSink === 'vault-note'
+      ? 'a note under `vault/00-inbox/`'
+      : 'ONE collector issue `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte`';
+  return [
+    `issue-budget: session cap reached — ${v.count}/${v.max} issues already created.`,
+    `This request was NOT created. It is parked as overflow entry #${v.overflowCount} in:`,
+    `  ${v.overflowPath}`,
+    `session-end Phase 5 will fold all overflow entries into ${sink}. Nothing is lost.`,
+    `Exempt from the cap: priority::critical, the carryover class (SPIRAL/FAILED, [Carryover]),`,
+    `and broken-window closure issues — those are never deferred.`,
+    `To raise the cap for this repo, edit \`issue-budget.max-per-session\` in the Session Config;`,
+    `\`mode: warn\` reports without blocking, \`mode: off\` disables the gate.`,
+  ].join('\n');
+}