@codedology/code-forge 0.3.2 → 0.5.0

package/src/session/spawn.mjs

@@ -16,13 +16,24 @@
  * Retry ladder (§5.6, V9): step 0 is the level's own model; step `k + 1` is `fallback[k]`. For a
  * Claude coder, `fallback[0]` (same provider) rides on `--fallback-model` inside step 0 and is not
  * spawned again. A step that reports unavailability (CLI missing, login expired, HTTP 402, or
- * rate-limited twice in a row) hands over to the next step; any other failure is final.
+ * rate-limited three times in a row) hands over to the next step; any other failure is final.
+ *
+ * Provider slots and backoff (B40): every attempt holds one slot of the module-level semaphore of
+ * its step's provider (`review.provider_concurrency[provider]`, defaults anthropic 4, openai 2,
+ * xai 2) for as long as the attempt runs, and frees it on every exit path. B41: the slot is taken
+ * FIRST, then the budget gate (check + reservation under the run's lock) runs; a refused session
+ * frees its slot at once, and a session waiting for a slot holds no reservation. A rate-limited attempt frees its slot, waits
+ * `RATE_LIMIT_BACKOFF_MS` (2 s, then 6 s, each ±30 % jitter) and tries the same step again; after
+ * the second wait a third rate limit moves the ladder to the next step.
  *
  * Every spawn prints `level=<Lx> provider=<p> model=<id> effort=<e> fallback_step=<n>` on stderr,
  * and every attempt writes one ledger row (`event: session`) with `tokens_source` `reported` when
  * the CLI's JSON carried usage, else `estimated` (bytes / 4).
  *
- * A coder argv that `isForbidden` matches is refused before anything spawns (§8.4).
+ * A coder argv that `isForbidden` matches is refused before anything spawns (§8.4). A
+ * reviewer/judge/S2/author level on openai is refused too (`closed-book`, B32: Codex always has a
+ * shell); an openai fallback step of such a session is skipped with one stderr line. The opt-in
+ * `review.allow_open_book_codex: true` lifts both and builds Codex's read-only argv.
  *
  * `background: true` (coders, §5.2): the child is started detached with stdout/stderr going to
  * `<run-root>/sessions/<id>/session.log`, its pid written to `<run-root>/sessions/<id>/pid.json`
@@ -36,6 +47,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { Ajv2020 } from 'ajv/dist/2020.js';
+import { CODEX_CLOSED_BOOK_REFUSAL, closedBookRefused, isNoToolRole, openBookCodexAllowed } from '../config/closed-book.mjs';
 import { resolveLevel } from '../config/known-ids.mjs';
 import { compileSchema } from '../config/schema-compile.mjs';
 import { buildArgv } from '../engines/builders/index.mjs';
@@ -43,9 +55,11 @@ import { removeCodexHome } from '../engines/codex-home.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { parseSentinel } from '../engines/sentinel.mjs';
 import { parseUsage } from '../engines/usage-parse.mjs';
-import { appendRow } from '../ledger/write.mjs';
+import { budgetUsdOf, checkBudget, estimateSessionUsd, priceSession, reservedUsd, reserveBudget, SPEND_UNREADABLE_MESSAGE, withBudgetLock } from '../ledger/spend.mjs';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { exec } from '../util/exec.mjs';
 import { isForbidden, mergeForbidden } from '../util/forbidden.mjs';
+import { semaphore } from '../util/locks.mjs';
 import { readStartTime, registerPid, UNKNOWN_START_TIME } from '../util/reaper.mjs';
 import { redact, writeSafe } from '../util/redact.mjs';
 import { currentRunRoot, pidsDir, runRoot, tmpBase, untrustedReason } from '../util/tmp.mjs';
@@ -59,7 +73,58 @@ export const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
 /** Unavailability reasons that move the ladder to the next step (§5.6). */
 export const UNAVAILABLE_REASONS = Object.freeze(['cli-missing', 'login-expired', 'http-402', 'rate-limited']);
 
-/** An error the spawner raises before anything runs (`code`: `usage`, `forbidden`). */
+/** B40: concurrent sessions per provider when `review.provider_concurrency` does not say. */
+export const DEFAULT_PROVIDER_CONCURRENCY = Object.freeze({ anthropic: 4, openai: 2, xai: 2 });
+
+/** B40: the waits before each retry of a rate-limited step (ms, before jitter); its length is the retry count. */
+export const RATE_LIMIT_BACKOFF_MS = Object.freeze([2000, 6000]);
+
+/** B40: each backoff wait is its base ±30 %. */
+export const RATE_LIMIT_JITTER = 0.3;
+
+/**
+ * B40: the session limit of `provider` — `review.provider_concurrency[provider]` when it is an
+ * integer ≥ 1, else the default (1 for a provider with no default).
+ * @param {Record<string, any>} cfg @param {string} provider @returns {number}
+ */
+export function providerLimit(cfg, provider) {
+  const set = /** @type {any} */ (cfg)?.review?.provider_concurrency?.[provider];
+  if (Number.isInteger(set) && set >= 1) return set;
+  return Object.hasOwn(DEFAULT_PROVIDER_CONCURRENCY, provider) ? DEFAULT_PROVIDER_CONCURRENCY[/** @type {"anthropic"|"openai"|"xai"} */ (provider)] : 1;
+}
+
+/** @type {Map<string, import('../util/locks.mjs').Semaphore>} one semaphore per (provider, limit), created on first use. */
+const providerSemaphores = new Map();
+
+/**
+ * B40: the in-process semaphore holding `provider`'s session slots at `limit`.
+ * @param {string} provider @param {number} limit
+ * @returns {import('../util/locks.mjs').Semaphore}
+ */
+export function providerSemaphore(provider, limit) {
+  const key = `${provider}:${limit}`;
+  let sem = providerSemaphores.get(key);
+  if (sem === undefined) {
+    sem = semaphore(limit);
+    providerSemaphores.set(key, sem);
+  }
+  return sem;
+}
+
+/**
+ * B40: the wait before retry number `n` (0-based) of a rate-limited step: the base ±30 %, from
+ * `random` in [0, 1) (0.5 gives the base exactly).
+ * @param {number} n @param {() => number} random @returns {number}
+ */
+export function backoffMs(n, random) {
+  const base = RATE_LIMIT_BACKOFF_MS[n];
+  return Math.round(base * (1 + RATE_LIMIT_JITTER * (2 * random() - 1)));
+}
+
+/** @param {number} ms @returns {Promise<void>} */
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** An error the spawner raises before anything runs (`code`: `usage`, `forbidden`, `closed-book`). */
 export class SessionError extends Error {
   /** @param {string} code @param {string} message */
   constructor(code, message) {
@@ -84,6 +149,125 @@ export function runRootFor(runId, root) {
   return runRoot(runId, { root });
 }
 
+/** How much of a timed-out session's stderr is kept (B30). */
+export const DIAGNOSTIC_TAIL_BYTES = 4096;
+
+/** A timed-out session's stderr over this size keeps no text at all (bounds the redact cost). */
+export const STDERR_MAX_BYTES = 1024 * 1024;
+
+/** How many stdout event types a timed-out session keeps. */
+export const STDOUT_EVENTS_MAX = 20;
+
+/** The longest event type kept. */
+const EVENT_TYPE_MAX = 40;
+
+/**
+ * Packet lines shorter than this are too common to tell apart from ordinary output, so they are
+ * NOT filtered. Accepted risk (B30): a packet line under 16 characters (a brace, `return x;`) can
+ * appear in a stderr tail; such a line carries no meaningful packet content on its own.
+ */
+const PACKET_LINE_MIN = 16;
+
+/** The tail note when the packet cannot be read: no stderr text is kept at all (fail closed). */
+export const TAIL_WITHHELD_PACKET = 'withheld: packet unreadable';
+/** The tail note when stderr is over `STDERR_MAX_BYTES`. */
+export const TAIL_WITHHELD_LARGE = 'stderr too large, withheld';
+/** The tail note when the last 4 KB of stderr is one partial line. */
+export const TAIL_WITHHELD_LONG_LINE = 'one long line, withheld';
+
+/** @param {Buffer} buf @param {number} at @returns {number} the first character start at or after `at`. */
+function charStart(buf, at) {
+  let i = at;
+  while (i < buf.length && (buf[i] & 0xc0) === 0x80) i += 1;
+  return i;
+}
+
+/** @param {unknown} text @returns {string} */
+function asText(text) {
+  return Buffer.isBuffer(text) ? text.toString('utf8') : typeof text === 'string' ? text : '';
+}
+
+const PEM_BEGIN = /-----BEGIN [A-Z0-9 ]*-----/;
+const PEM_END = /-----END [A-Z0-9 ]*-----/;
+
+/**
+ * The stderr tail of a timed-out session (B30), never packet content:
+ *  1. no packet text (unreadable) ⇒ no text: `{tail: null, note: 'withheld: packet unreadable'}`;
+ *     stderr over `STDERR_MAX_BYTES` ⇒ `{tail: null, note: 'stderr too large, withheld'}`;
+ *  2. on the FULL raw text: every PEM block (`-----BEGIN` … `-----END` lines, an unterminated one
+ *     to the end) and every line repeating a packet line (≥ 16 chars) is dropped;
+ *  3. the FULL remaining text goes through B0 `redact`;
+ *  4. over `maxBytes`, the last `maxBytes` bytes are kept, starting on a character, with the first
+ *     (partial) line dropped; when that piece has no line break the tail is withheld.
+ * @param {string | Buffer | null | undefined} text @param {string | null} packetText @param {number} [maxBytes]
+ * @returns {{tail: string | null, note?: string}}
+ */
+export function stderrTail(text, packetText, maxBytes = DIAGNOSTIC_TAIL_BYTES) {
+  if (typeof packetText !== 'string') return { tail: null, note: TAIL_WITHHELD_PACKET };
+  const raw = asText(text);
+  if (raw.length === 0) return { tail: '' };
+  if (Buffer.byteLength(raw) > STDERR_MAX_BYTES) return { tail: null, note: TAIL_WITHHELD_LARGE };
+  const packetLines = [
+    ...new Set(
+      packetText
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length >= PACKET_LINE_MIN),
+    ),
+  ];
+  let inPem = false;
+  /** @type {string[]} */
+  const kept = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (inPem) {
+      if (PEM_END.test(t)) inPem = false;
+      continue;
+    }
+    if (PEM_BEGIN.test(t)) {
+      inPem = !PEM_END.test(t);
+      continue;
+    }
+    if (t.length >= PACKET_LINE_MIN && packetLines.some((p) => t.includes(p))) continue;
+    kept.push(line);
+  }
+  const safe = /** @type {string} */ (redact(kept.join('\n')));
+  const buf = Buffer.from(safe, 'utf8');
+  if (buf.length <= maxBytes) return { tail: safe };
+  const from = charStart(buf, buf.length - maxBytes);
+  const piece = buf.subarray(from).toString('utf8');
+  if (buf[from - 1] === 0x0a) return { tail: piece }; // the cut fell exactly on a line start
+  const nl = piece.indexOf('\n');
+  if (nl === -1) return { tail: '', note: TAIL_WITHHELD_LONG_LINE };
+  return { tail: piece.slice(nl + 1) };
+}
+
+/**
+ * What a timed-out session's stdout says without any of its text (B30): the last
+ * `STDOUT_EVENTS_MAX` event types (JSON lines with a string `type`, each cut to 40 characters and
+ * kept only when it is all `[a-z0-9_.-]`) and the total byte length. Non-JSON stdout gives only
+ * `stdout_bytes`. Event payloads, which can echo the packet, are never kept.
+ * @param {string | Buffer | null | undefined} text
+ * @returns {{stdout_bytes: number, stdout_events?: string[]}}
+ */
+export function stdoutEvents(text) {
+  const raw = asText(text);
+  const bytes = Buffer.byteLength(raw);
+  /** @type {string[]} */
+  const types = [];
+  const lines = raw.split('\n');
+  // scan from the end: stop once enough events are kept, or after a bounded number of lines
+  for (let i = lines.length - 1, scanned = 0; i >= 0 && types.length < STDOUT_EVENTS_MAX && scanned < 5000; i -= 1, scanned += 1) {
+    const line = lines[i].trim();
+    if (!line.startsWith('{')) continue;
+    const event = tryJSON(line);
+    if (!event || typeof event !== 'object' || typeof event.type !== 'string') continue;
+    const type = event.type.slice(0, EVENT_TYPE_MAX);
+    if (/^[a-z0-9_.-]+$/.test(type)) types.unshift(type);
+  }
+  return types.length > 0 ? { stdout_bytes: bytes, stdout_events: types } : { stdout_bytes: bytes };
+}
+
 /** @param {number} bytes */
 export const estimateTokens = (bytes) => Math.ceil(bytes / 4);
 
@@ -317,8 +501,12 @@ function childEnv(/** @type {NodeJS.ProcessEnv} */ env) {
  * @property {Partial<Record<"claude"|"codex"|"grok", string>>} [bins] - replaces argv[0] (tests: the fakes).
  * @property {typeof exec} [exec]
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow]
+ * @property {() => Promise<Array<Record<string, any>>>} [readRows] - the ledger rows the
+ *   `budget.usd` check reads (default: `readAllRows(opts.slug)`).
  * @property {{write: (s: string) => unknown}} [stderr]
  * @property {NodeJS.ProcessEnv} [env]
+ * @property {(ms: number) => Promise<unknown>} [sleep] - B40: the rate-limit backoff wait (tests: a recorder).
+ * @property {() => number} [random] - B40: the backoff jitter source, in [0, 1) (default `Math.random`).
  */
 
 /**
@@ -432,18 +620,67 @@ export async function spawnSession(opts, deps = {}) {
   const runRootDir = opts.runRoot ?? currentRunRoot();
   if (role === 'facts' && opts.cwd !== undefined) assertFactsCwd(opts.cwd, runRootDir);
   const writeRow = deps.writeRow ?? (opts.slug ? (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: /** @type {string} */ (opts.slug) }) : null);
-  const steps = ladderFor(resolveLevel(cfg, level), role);
+  const ladder = ladderFor(resolveLevel(cfg, level), role);
+  // B32: Codex has no no-tools mode, so it runs no reviewer/judge/S2/author session unless the
+  // config opts in (`review.allow_open_book_codex: true`). Without it, step 0 on openai refuses the
+  // session and an openai fallback step is dropped from the ladder.
+  const openBook = openBookCodexAllowed(cfg); // read ONCE: the refusal and every build use it
+  if (closedBookRefused(ladder[0].provider, role, openBook)) throw new SessionError('closed-book', CODEX_CLOSED_BOOK_REFUSAL);
+  const steps = ladder.filter((step) => !closedBookRefused(step.provider, role, openBook));
+  if (steps.length < ladder.length) writeSafe(stderr, `fallback skipped: ${ladder.length - steps.length} openai step(s) — ${CODEX_CLOSED_BOOK_REFUSAL}\n`);
   if (opts.background) steps.length = 1;
 
   const attempts = [];
-  let rateLimitedOnce = false;
+  const sleep = deps.sleep ?? realSleep;
+  const random = deps.random ?? Math.random;
+  let rateLimitWaits = 0; // backoff waits taken on the current step
   for (let i = 0; i < steps.length; i += 1) {
     const step = steps[i];
+    // B40/B41: the provider slot first, then the budget gate — a session queued for a slot never
+    // holds a reservation; a refusal frees the slot at once (the `finally` below)
+    const releaseSlot = await providerSemaphore(step.provider, providerLimit(cfg, step.provider)).acquire();
+    /** @type {number | null} */
+    let waitMs = null;
+    try {
+      const gate = await budgetGate(opts, deps, writeRow, stderr, step);
+      if (gate.refused) return { ...gate.refused, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
+      // B41: the reservation is released once the row is written (inside runAttempt) and, as a net,
+      // in the `finally` below on every other exit path (a throw, a background start)
+      const releaseReservation = gate.release;
+      try {
+        const outcome = await runAttempt(step, i + 1 === steps.length, releaseReservation);
+        if (outcome.result) return outcome.result;
+        waitMs = outcome.waitMs;
+      } finally {
+        releaseReservation();
+      }
+    } finally {
+      releaseSlot();
+    }
+    if (waitMs !== null) {
+      // B40: the slot is free while we wait; the same step is tried again (through the budget gate)
+      writeSafe(stderr, `rate-limited: provider=${step.provider} model=${step.model} retry in ${(waitMs / 1000).toFixed(1)} s\n`);
+      await sleep(waitMs);
+      i -= 1;
+      continue;
+    }
+    rateLimitWaits = 0;
+  }
+  throw new Error('spawnSession: unreachable — the ladder always has a step');
+
+  /**
+   * One attempt of `step` (the caller holds its provider slot).
+   * @param {ReturnType<typeof ladderFor>[number]} step @param {boolean} isLast - no step after this one.
+   * @param {() => void} releaseReservation - B41: called as soon as the session row is written.
+   * @returns {Promise<{result: SessionResult | null, waitMs: number | null}>} a `result` ends the
+   *   session; otherwise `waitMs` = back off and retry the step, null = go to the next step.
+   */
+  async function runAttempt(step, isLast, releaseReservation) {
     const sessionDir = path.join(runRootDir, 'sessions', `${role}-${Date.now()}-${randomBytes(4).toString('hex')}`);
     mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
     let keep = false;
     try {
-      const built = buildStep(opts, step, sessionDir);
+      const built = buildStep(opts, step, sessionDir, openBook);
       const cli = built.cli;
       built.argv[0] = deps.bins?.[cli] ?? built.argv[0];
       if (role === 'coder') {
@@ -458,8 +695,13 @@ export async function spawnSession(opts, deps = {}) {
         // B4.1: the builder's env (the Codex coder's CODEX_HOME) wins over the caller's; a
         // background session's home stays until the run root is swept.
         const bg = startBackground(built, sessionDir, runRootDir, { ...childEnv(deps.env ?? process.env), ...(built.env ?? {}) });
-        if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started' });
-        return { status: 'started', ...bg, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts };
+        // a detached child's tokens are never read back: its price is unknown (use `ledger add coder`)
+        try {
+          if (writeRow) await writeRow({ event: 'session.background', ...base, pid: bg.pid, status: 'started', usd: null, usd_unknown: true });
+        } finally {
+          releaseReservation();
+        }
+        return { waitMs: null, result: { status: 'started', ...bg, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, attempts } };
       }
 
       const attempt = await runForeground(built, opts, deps);
@@ -471,24 +713,117 @@ export async function spawnSession(opts, deps = {}) {
         tokens_in: attempt.usage.tokens_in,
         tokens_out: attempt.usage.tokens_out,
         tokens_source: attempt.usage.tokens_source,
+        ...sessionUsd(step.provider, level, attempt.usage),
         duration_ms: attempt.duration_ms,
         ...(level === 'L3' && step.fallback_step > 0 ? { l3_fallback: true } : {}),
       };
-      if (writeRow) await writeRow(row);
+      try {
+        if (writeRow) await writeRow(row);
+      } finally {
+        releaseReservation(); // B41: the row now carries the spend (or the write failed)
+      }
       attempts.push({ fallback_step: step.fallback_step, provider: step.provider, model: step.model, status: attempt.status, reason: attempt.reason ?? null });
-      if (attempt.status === 'unavailable' && attempt.reason === 'rate-limited' && !rateLimitedOnce) {
-        rateLimitedOnce = true; // rate-limited once: the same step gets one more try (§5.6 "twice in a row")
-        i -= 1;
-        continue;
+      if (attempt.status === 'unavailable' && attempt.reason === 'rate-limited' && rateLimitWaits < RATE_LIMIT_BACKOFF_MS.length) {
+        // B40: back off (2 s, then 6 s, ±30 %) and try the same step again — never at once
+        const waitMs = backoffMs(rateLimitWaits, random);
+        rateLimitWaits += 1;
+        return { waitMs, result: null };
       }
-      rateLimitedOnce = false;
-      if (attempt.status === 'unavailable' && i + 1 < steps.length) continue;
-      return { ...attempt, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, row, attempts };
+      if (attempt.status === 'unavailable' && !isLast) return { waitMs: null, result: null };
+      return { waitMs: null, result: { ...attempt, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, row, attempts } };
     } finally {
       if (!keep) rmSync(sessionDir, { recursive: true, force: true });
     }
   }
-  throw new Error('spawnSession: unreachable — the ladder always has a step');
+}
+
+/**
+ * B33: a session row's dollars from its tokens and the static price table — `{usd, cost_source:
+ * 'estimated'}`, or `{usd: null, usd_unknown: true}` when the provider/level has no price.
+ * @param {string} provider @param {string} level @param {{tokens_in: number, tokens_out: number}} usage
+ */
+function sessionUsd(provider, level, usage) {
+  const priced = priceSession({ provider, level, tokens_in: usage.tokens_in, tokens_out: usage.tokens_out });
+  return priced.usd_unknown ? { usd: null, usd_unknown: true } : { usd: priced.usd, cost_source: 'estimated' };
+}
+
+/**
+ * B33, R6 — the single budget choke point: before every spawn attempt of every role, a run with
+ * `budget.usd` set reads its spend from the ledger (`deps.readRows`, else the `slug` ledger).
+ * ≥ 80 % prints and records one warning per run; ≥ 100 % refuses with a plain message and a
+ * `budget.refused` row, and nothing is spawned. No `budget.usd` or no `run` ⇒ no check. Fail
+ * closed: with a budget and a run but no way to read the spend (no `readRows`, no `slug`, or the
+ * read throws) the session is refused too. It sits at the top of the ladder loop, so every attempt
+ * — each fallback step, the rate-limit retry of a step, and every `spawnSession` call a caller
+ * makes again (B30's timeout retry) — passes it.
+ *
+ * B41: with a budget, the ledger read, the check and the reservation of this attempt's estimated
+ * cost (`estimateSessionUsd`: the packet's bytes / 4 in, a fixed tokens_out per role and level)
+ * run under the run's budget lock, so concurrent sessions of one run see each other's holds. No
+ * budget (or no run) ⇒ no lock, no reservation.
+ * @param {SessionOpts} opts @param {SessionDeps} deps
+ * @param {((row: Record<string, any>) => Promise<unknown>) | null} writeRow
+ * @param {{write: (s: string) => unknown}} stderr
+ * @param {{provider: string}} step - the ladder step about to run (its provider prices the estimate).
+ * @returns {Promise<{refused: SessionResult, release?: undefined} | {refused: null, release: () => void}>}
+ *   the refusal result, or the (idempotent) release of this attempt's reservation.
+ */
+async function budgetGate(opts, deps, writeRow, stderr, step) {
+  const budget = budgetUsdOf(opts.cfg);
+  if (budget === null || typeof opts.run !== 'string' || opts.run.length === 0) return { refused: null, release: () => {} };
+  const run = opts.run;
+  const estimate = estimateSessionUsd({ provider: step.provider, level: opts.level, role: opts.role, tokensIn: packetTokens(opts) });
+  return withBudgetLock(run, async () => {
+    const refused = await checkGate(opts, deps, writeRow, stderr, budget, estimate);
+    if (refused) return { refused };
+    return { refused: null, release: reserveBudget(run, estimate) };
+  });
+}
+
+/**
+ * The packet's (or brief's) tokens plus the system prompt's, by the ledger's bytes / 4 rule (an
+ * unreadable packet counts 0 bytes; tokens_out is still reserved).
+ * @param {SessionOpts} opts @returns {number}
+ */
+function packetTokens(opts) {
+  return estimateTokens(fileSize(opts.promptPath) + (typeof opts.systemPromptText === 'string' ? Buffer.byteLength(opts.systemPromptText) : 0));
+}
+
+/**
+ * The B33 check proper (called under the budget lock): read the run's spend, fail closed, refuse
+ * when spent + reserved + `estimate` passes the budget.
+ * @param {SessionOpts} opts - `opts.run` is a non-empty string (checked by `budgetGate`).
+ * @param {SessionDeps} deps
+ * @param {((row: Record<string, any>) => Promise<unknown>) | null} writeRow
+ * @param {{write: (s: string) => unknown}} stderr @param {number} budget @param {number} estimate
+ * @returns {Promise<SessionResult | null>} the refusal result, or null to go on.
+ */
+async function checkGate(opts, deps, writeRow, stderr, budget, estimate) {
+  /** @type {Array<Record<string, any>> | null} */
+  let rows = null;
+  try {
+    const slug = opts.slug;
+    const read = deps.readRows ?? (slug ? () => readAllRows(slug) : null);
+    const got = read ? await read() : null;
+    rows = Array.isArray(got) ? got : null;
+  } catch {
+    rows = null;
+  }
+  if (rows === null) {
+    // fail closed: a budget we cannot check is never treated as "not reached"
+    writeSafe(stderr, `code-forge: ${SPEND_UNREADABLE_MESSAGE}\n`);
+    if (writeRow) {
+      try {
+        await writeRow({ event: 'budget.refused', run: opts.run, block: opts.block ?? null, role: opts.role, budget_usd: budget, spent_usd: null, reason: 'spend-unreadable' });
+      } catch {
+        // the refusal stands without its row
+      }
+    }
+    return { status: 'unavailable', reason: 'budget', message: SPEND_UNREADABLE_MESSAGE, answer: null, spent_usd: null, budget_usd: budget };
+  }
+  const verdict = await checkBudget({ budget, run: /** @type {string} */ (opts.run), rows, block: opts.block ?? null, role: opts.role, writeRow, stderr, reserved: reservedUsd(/** @type {string} */ (opts.run)), estimate });
+  if (!verdict.refuse) return null;
+  return { status: 'unavailable', reason: 'budget', message: verdict.message, answer: null, spent_usd: verdict.spent, budget_usd: budget };
 }
 
 /**
@@ -498,8 +833,9 @@ export async function spawnSession(opts, deps = {}) {
  * @param {SessionOpts} opts
  * @param {{provider: string, model: string, effort?: string, flagFallback?: {provider: string, model: string}}} step
  * @param {string} sessionDir
+ * @param {boolean} openBook - B32: `review.allow_open_book_codex`, read once by `spawnSession`.
  */
-function buildStep(opts, step, sessionDir) {
+function buildStep(opts, step, sessionDir, openBook) {
   const closedBook = opts.role !== 'coder';
   // B9b.1: the facts delegate may run in the caller's read-only project snapshot; nobody else may
   const snapshot = opts.role === 'facts' && opts.cwd !== undefined ? realpathSync(path.resolve(opts.cwd)) : null; // validated by assertFactsCwd
@@ -514,6 +850,8 @@ function buildStep(opts, step, sessionDir) {
   if (cli === 'claude' && opts.maxBudgetUsd !== undefined) params.maxBudgetUsd = opts.maxBudgetUsd;
   if (closedBook && opts.systemPromptText !== undefined && cli !== 'codex') params.systemPromptText = opts.systemPromptText;
   if (cli === 'codex') params.outPath = path.join(sessionDir, 'out.json');
+  // B32 opt-in: only a no-tools role needs it; coder and facts build exactly as without it
+  if (cli === 'codex' && openBook && isNoToolRole(opts.role)) params.allowOpenBook = true;
   /** @type {Record<string, any> | null} */
   let compiled = null;
   const strict = variantFor(step.provider) === 'strict';
@@ -570,7 +908,22 @@ async function runForeground(built, opts, deps) {
 
   const unavailable = classifyUnavailable(res, read.parsed);
   if (unavailable) return { status: 'unavailable', reason: unavailable, answer: null, ...common };
-  if (res.timedOut) return { status: 'timeout', reason: `killed after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms`, answer: null, ...common };
+  if (res.timedOut) {
+    // B30: what the CLI printed last, so a hang's cause can be seen — stderr redacted, capped and
+    // packet-free; stdout only as event types and a byte count, never its text
+    /** @type {string | null} */
+    let packetText = input !== undefined ? Buffer.from(input).toString('utf8') : null;
+    if (packetText === null) {
+      try {
+        packetText = readFileSync(opts.promptPath, 'utf8');
+      } catch {
+        packetText = null; // fail closed: no tails without the packet to filter against
+      }
+    }
+    const err = stderrTail(res.stderr, packetText);
+    const tails = { stderr_tail: err.tail, ...(err.note ? { tail_note: err.note } : {}), ...stdoutEvents(res.stdout) };
+    return { status: 'timeout', reason: `killed after ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS} ms`, answer: null, ...common, ...tails };
+  }
   if (res.result !== 'ok' || read.parsed?.is_error === true) return { status: 'failed', reason: `exit ${res.code}`, answer: null, ...common };
   if (built.compiled) {
     // validate against the schema the provider was actually given (the cached variant, stable across attempts)

package/src/state/block.mjs

@@ -13,6 +13,7 @@
 
 import { createHash } from 'node:crypto';
 import os from 'node:os';
+import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
 import { StateError } from './paths.mjs';
@@ -125,11 +126,15 @@ function activeBlocks(record) {
 
 /**
  * `block open` — refuses a second open of the same id and any owned set that overlaps another
- * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast.
+ * ACTIVE block's; records base, owned files, level, attempt, acceptance, line forecast and the
+ * block kind (B34: the declared `kind`, else `blockKind` of the owned files). A docs/contract
+ * block asked for below `levels.coder_floor_docs` (default L1) is opened AT the floor: the entry
+ * and the dispatch row carry the floor level, and the row adds `requested_level` and
+ * `trigger: 'docs_floor'`.
  * @param {{
  *   runId: string, id: string, level: string, owned: string[], acceptance: unknown,
  *   attempt?: number, base?: string, lines?: number, brief?: {path: string, content: Buffer | string},
- *   writeRow: WriteRow, now?: Date,
+ *   kind?: string, cfg?: Record<string, any>, writeRow: WriteRow, now?: Date,
  * }} opts
  * @returns {Promise<{block: Record<string, any>, pointer: string | null}>}
  */
@@ -139,8 +144,11 @@ export async function openBlock(opts) {
   if (typeof level !== 'string' || !LEVEL.test(level)) throw new StateError('bad-level', 'level must be L0..L3');
   if (!Number.isInteger(attempt) || attempt < 1) throw new StateError('bad-attempt', 'attempt must be an integer >= 1');
   if (lines !== null && !(Number.isInteger(lines) && lines > 0)) throw new StateError('bad-lines', 'lines forecast must be a positive integer');
+  if (opts.kind !== undefined && !BLOCK_KINDS.includes(opts.kind)) throw new StateError('bad-kind', `kind must be one of ${BLOCK_KINDS.join(', ')}`);
   const owned = assertOwned(opts.owned);
   const acceptance = assertAcceptance(opts.acceptance);
+  const kind = blockKind({ owned, declared: opts.kind });
+  const dispatched = dispatchLevel({ lane: level, kind, cfg: opts.cfg });
   const pointer = opts.brief ? briefPointer(opts.brief.path, opts.brief.content) : null;
 
   const block = await mutateRun(runId, null, writeRow, async (record) => {
@@ -150,11 +158,12 @@ export async function openBlock(opts) {
       if (pair) throw new StateError('overlap', `block ${id} owns ${pair[0]}, which overlaps ${pair[1]} owned by open block ${otherId}`);
     }
     const baseSha = await resolveCommit(opts.base ?? 'HEAD', record.workspace);
-    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], level, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open' };
+    const entry = { block: id, base_sha: baseSha, owned_files: [...owned], level: dispatched.level, kind, attempt, opened_at: now.toISOString(), acceptance, lines_forecast: lines, status: 'open' };
     record.blocks[id] = entry;
+    const floor = dispatched.trigger === 'docs_floor' ? { requested_level: level, trigger: 'docs_floor' } : {};
     return {
       result: entry,
-      rows: [{ event: 'dispatch', block: id, level, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
+      rows: [{ event: 'dispatch', block: id, level: dispatched.level, kind, ...floor, attempt, base_sha: baseSha, owned_files: entry.owned_files, lines_forecast: lines }],
     };
   });
   return { block, pointer };