session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/io.mjs

@@ -17,7 +17,16 @@
  */
 
 import { writeFile, rename, mkdir } from 'node:fs/promises';
-import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync, writeSync } from 'node:fs';
+import {
+  mkdirSync,
+  writeFileSync,
+  renameSync,
+  readFileSync,
+  existsSync,
+  writeSync,
+  copyFileSync,
+  unlinkSync,
+} from 'node:fs';
 import path, { dirname } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 
@@ -89,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.
  *
@@ -480,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.
@@ -556,6 +804,26 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  * used from any layer without violating the layering rule in
  * `scripts/lib/hardening.mjs`.
  *
+ * Implementation: this is the JSON-serializing façade over
+ * {@link atomicWriteWithBackup} (`backup: false`) — the two functions carried
+ * the identical `mkdir → tmp → write → rename → catch` body 60 lines apart,
+ * which is the very duplication `atomicWriteWithBackup` was introduced to end.
+ * Everything below the `JSON.stringify` is the delegate's; the wrapper exists
+ * for the serialization step and for NARROWING the envelope (see @returns).
+ *
+ * Two things are deliberately kept here rather than pushed into the delegate:
+ *
+ *  - **The stringify stays inside a try.** `JSON.stringify` throws on a cycle
+ *    (and on a BigInt). Hoisting it above the delegation call would turn that
+ *    into an escaping TypeError, and 4 of the 9 caller files (`loop-guard`,
+ *    `lock-bootstrap`, `file-lock`, `issue-budget`) invoke this without a
+ *    try/catch of their own. A serialization failure reports as `fs-error`
+ *    because that is what this helper has always returned for it.
+ *  - **The success envelope is narrowed back to `{ ok: true }`.** The delegate
+ *    also reports `path`/`bytes`/`backupPath`; `session-lock.mjs#writeOwnerProof`
+ *    propagates THIS object verbatim on failure (`if (!w.ok) return w`), so the
+ *    key set is part of a contract that reaches further than this file.
+ *
  * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
  * @param {*} data           JSON-serializable value.
  * @param {object} [opts]
@@ -565,15 +833,172 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  */
 export function writeJsonAtomicSync(filePath, data, opts = {}) {
   const { indent = 2, tmpPrefix = '.tmp' } = opts;
+
+  let body;
+  try {
+    body = JSON.stringify(data, null, indent) + '\n';
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+  }
+
+  const res = atomicWriteWithBackup(filePath, body, { tmpPrefix });
+  return res.ok ? { ok: true } : res;
+}
+
+/**
+ * Content-agnostic sibling of {@link writeJsonAtomicSync}: atomically replace a
+ * file with an arbitrary string/Buffer body, optionally snapshotting the
+ * previous contents to a timestamped `.bak-<ISO>` sidecar first (issue #734).
+ *
+ * The repo carries the copy→tmp→rename idiom in ~25 hand-rolled places
+ * (`learnings/io.mjs#rewriteLearnings`, `session-record-repair.mjs`,
+ * `owner-interview.mjs`, `backfill-learnings.mjs`, …). Each spelling differs in
+ * small ways — some take the backup, some do not; some `mkdir -p`, some assume
+ * the directory exists — which is exactly how a crash-safety guarantee rots.
+ * This helper is the shared spelling; **validation policy stays with the
+ * callers** (this function never inspects `body`).
+ *
+ * Crash-safety: write `<dir>/<tmpPrefix>.<rand>`, then `renameSync` over the
+ * target. Same-filesystem rename is atomic on POSIX, so an observer sees either
+ * the previous contents or the new ones — never a half-written file. The tmp
+ * file is created as a SIBLING of the target on purpose: a tmp in `os.tmpdir()`
+ * may sit on a different filesystem, where `rename` degrades to a non-atomic
+ * copy (EXDEV).
+ *
+ * Backup (`backup: true`) copies the CURRENT file to `<filePath>.bak-<ISO>`
+ * before the rename, with `:`/`.` swapped for `-` so a lexical sort of the
+ * siblings is chronological (same convention as `learnings/io.mjs`). A
+ * first-time write has nothing to lose, so no backup is taken when the target
+ * does not exist. **Rotation is deliberately NOT done here** — how many
+ * snapshots a store is worth is a per-caller policy (`learnings/io.mjs` keeps
+ * 3; a re-derivable file wants 0), and a keep-N default baked into the
+ * primitive would silently unlink a caller's snapshots.
+ *
+ * Caller is responsible for path-confinement — this helper does NOT validate
+ * that `filePath` lives inside the project (mirrors {@link writeJsonAtomic} /
+ * {@link writeJsonAtomicSync}).
+ *
+ * On a FAILED write the tmp sibling is unlinked (best-effort) before the error
+ * envelope is returned. Without that, every failed write leaves a
+ * `<tmpPrefix>.<hex>` behind — the board writer's failure mode is a retry loop,
+ * so the litter accumulates in the operator's vault directory. The cleanup is
+ * attempted only when the write actually created the tmp file, and its own
+ * failure is swallowed: a leaked tmp is worse than a silent unlink miss, and
+ * neither may mask the original error.
+ *
+ * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
+ * TWO PRODUCTION CALL-SITES: `vault-status/board-writer.mjs#writeBoard`
+ * (`backup: false`) and {@link writeJsonAtomicSync}, which carries 12 further
+ * call-sites across 9 files behind it. That second one is the load-bearing
+ * evidence — the previous revision of this note recorded ONE call-site and
+ * concluded the signature was unproven, while the function with an identical
+ * body sat 60 lines above in this same file, unmigrated. The cheapest possible
+ * migration going unmade is not a neutral fact about a helper: it is the
+ * measurement that the helper is not paying for itself.
+ *
+ * What the second call-site does NOT prove: `writeJsonAtomicSync` passes
+ * `backup: false` and no `fs`, so the backup half and the injection seam still
+ * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
+ * migrates the remaining hand-rolled sites, re-check before widening:
+ * (a) whether an `async` twin is needed rather than bolting a promise mode onto
+ * this one (three known sites are `fs/promises`), and (b) whether rotation
+ * belongs here after all (it does only if ≥2 migrated callers want the SAME
+ * keep-N). If NO caller ever passes `backup: true` in production, that half is
+ * still the part to shrink back.
+ *
+ * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
+ * @param {string|Buffer} body  Bytes to write, verbatim. Never inspected.
+ * @param {object} [opts]
+ * @param {BufferEncoding} [opts.encoding='utf8']  Encoding for a string `body`.
+ * @param {boolean} [opts.backup=false]  Snapshot the existing file to `.bak-<ISO>` first.
+ * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {Date} [opts.now]  Clock seam for the backup stamp (tests).
+ * @param {{ mkdirSync?: Function, writeFileSync?: Function, renameSync?: Function,
+ *   copyFileSync?: Function, existsSync?: Function, unlinkSync?: Function }} [opts.fs]
+ *   Injectable fs (tests). Omitted methods fall back to `node:fs` — EXCEPT on
+ *   the backup path, which fails closed (see below).
+ * @returns {{ ok: true, path: string, bytes: number, backupPath: string|null }
+ *   | { ok: false, reason: 'fs-error', error: string }}
+ */
+export function atomicWriteWithBackup(filePath, body, opts = {}) {
+  const {
+    encoding = 'utf8',
+    backup = false,
+    tmpPrefix = '.tmp',
+    now = new Date(),
+    fs: injectedFs,
+  } = opts;
+
+  const fsMkdir = injectedFs?.mkdirSync ?? mkdirSync;
+  const fsWriteFile = injectedFs?.writeFileSync ?? writeFileSync;
+  const fsRename = injectedFs?.renameSync ?? renameSync;
+  const fsCopyFile = injectedFs?.copyFileSync ?? copyFileSync;
+  const fsExists = injectedFs?.existsSync ?? existsSync;
+  const fsUnlink = injectedFs?.unlinkSync ?? unlinkSync;
+
+  // ── Partial-adapter fail-closed, backup path only ──────────────────────────
+  //
+  // Per-method fallback to the real `node:fs` is the right default for the
+  // three ALWAYS-used methods: `board-writer.mjs#writeBoard` passes an fs object
+  // on EVERY call, including production, where `renameSync`/`copyFileSync` are
+  // present-but-`undefined` because nothing was injected. "An injected object
+  // must be total" would therefore reject the only real caller — the shape is
+  // not evidence of a fake.
+  //
+  // The backup path is different in kind. It runs ONLY under `backup: true`, and
+  // there a missing method routes a real `copyFileSync`/`existsSync` at the real
+  // filesystem while the write goes to the fake: a suite that believes itself
+  // hermetic drops `.bak-<ISO>` files into the repo, and nothing says so. Both
+  // methods are guarded, not just `copyFileSync` — a missing `existsSync` probes
+  // the real target and silently decides the backup branch from it, which is the
+  // same escape one step earlier.
+  if (backup && injectedFs) {
+    for (const method of ['existsSync', 'copyFileSync']) {
+      if (typeof injectedFs[method] !== 'function') {
+        return {
+          ok: false,
+          reason: 'fs-error',
+          error: `partial fs adapter: ${method} required for backup`,
+        };
+      }
+    }
+  }
+
+  let tmpFile = null;
+  let tmpCreated = false;
+
   try {
     const dir = dirname(filePath);
-    mkdirSync(dir, { recursive: true });
-    const tmpSuffix = randomBytes(6).toString('hex');
-    const tmpFile = path.join(dir, `${tmpPrefix}.${tmpSuffix}`);
-    writeFileSync(tmpFile, JSON.stringify(data, null, indent) + '\n', { encoding: 'utf8' });
-    renameSync(tmpFile, filePath);
-    return { ok: true };
+    fsMkdir(dir, { recursive: true });
+
+    let backupPath = null;
+    if (backup && fsExists(filePath)) {
+      const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
+      backupPath = `${filePath}.bak-${stamp}`;
+      fsCopyFile(filePath, backupPath);
+    }
+
+    tmpFile = path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+    fsWriteFile(tmpFile, body, encoding);
+    tmpCreated = true;
+    fsRename(tmpFile, filePath);
+
+    return {
+      ok: true,
+      path: filePath,
+      bytes: Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding),
+      backupPath,
+    };
   } catch (err) {
+    // Only when the write got far enough to create it. The name carries 12 hex
+    // chars of entropy, so this cannot collide with a caller's real file.
+    if (tmpCreated) {
+      try {
+        fsUnlink(tmpFile);
+      } catch {
+        // Best-effort: never let cleanup replace the error the caller needs.
+      }
+    }
     return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
   }
 }

package/scripts/lib/issue-budget.mjs

@@ -37,6 +37,36 @@ 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';
 
+/**
+ * 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.
@@ -109,20 +139,34 @@ 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 SHARED across invocations, so this read-side isolation is
+ * only half the contract: an identity-less charge must also never PERSIST its
+ * fresh state, or it silently zeroes a live session's count and deletes its
+ * parked overflow records. `chargeIssueBudget` enforces that write-side half.
+ *
  * @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 accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  const fresh = { sessionId: accountingSessionId, count: 0, exempt: 0, overflow: [] };
+  if (accountingSessionId === null) return fresh;
+
   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;
+    if (data.sessionId !== accountingSessionId) return fresh;
     return {
-      sessionId: data.sessionId ?? sessionId ?? null,
+      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 : [],
@@ -200,13 +244,23 @@ export function chargeIssueBudget({
     return { ...base, decision: 'off', count: 0, overflowCount: 0, reason: null };
   }
 
-  const state = readBudgetState(repoRoot, sessionId);
-  state.sessionId = sessionId ?? state.sessionId;
+  const accountingSessionId =
+    typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  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 +272,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 +288,7 @@ export function chargeIssueBudget({
     command: String(command).slice(0, 500),
     at: now,
   });
-  writeBudgetState(repoRoot, state);
+  persist(state);
   return {
     ...base,
     decision: 'block',