@codedology/code-forge 0.3.2 → 0.5.0

package/src/engines/sentinel.mjs

@@ -131,3 +131,37 @@ export function verifyAck(output, expectedSha8, expectedLines, opts = {}) {
   }
   return { status: 'ok', ack };
 }
+
+/**
+ * A `review-file` ticket id: 24 lowercase hex characters standing alone — not part of a longer hex
+ * run (a commit sha) and not inside a path or file name (no word, `.`, `/` or `-` touching it).
+ */
+const TICKET_IN_LINE = /(?<![\w./-])[0-9a-f]{24}(?![\w/-]|\.\w)/;
+
+/** @param {string} s */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The coder's final report must name the `review-file` ticket of every changed file (B36): a line
+ * that names the path and a ticket id, e.g. `reviewed src/a.mjs ticket 0123456789abcdef01234567`.
+ * A line counts for a file only when it names exactly ONE of the changed files (a line listing two
+ * paths counts for neither) and carries a ticket id outside that path (the path is blanked before
+ * the ticket is looked for). Fail closed: a file with no such line is missing, and the
+ * orchestrator treats the report as FAILED whatever its sentinel says
+ * (`skill/templates/coder-brief.md`).
+ * @param {string} report - the coder's final report (or its whole transcript).
+ * @param {string[]} files - the block's changed files, repo-root-relative.
+ * @returns {string[]} the files with no ticket id in the report, in the order given.
+ */
+export function missingReviewTickets(report, files) {
+  if (typeof report !== 'string') throw new TypeError('missingReviewTickets: report must be a string');
+  const named = files.map((file) => ({ file, re: new RegExp(`(?<![\\w./-])${escapeRe(file)}(?![\\w/-]|\\.\\w)`, 'g') }));
+  /** @type {Set<string>} */
+  const ticketed = new Set();
+  for (const line of report.split('\n')) {
+    const hits = named.filter((n) => line.search(n.re) >= 0);
+    if (hits.length !== 1) continue;
+    if (TICKET_IN_LINE.test(line.replace(hits[0].re, ' '))) ticketed.add(hits[0].file);
+  }
+  return files.filter((file) => !ticketed.has(file));
+}

package/src/keys/onepassword.mjs

@@ -12,6 +12,7 @@
  */
 
 import { reportErrorKind } from '../util/error-kind.mjs';
+import { logWarning } from '../util/error-log.mjs';
 import { exec as realExec } from '../util/exec.mjs';
 
 // Long enough for a person to see and approve the 1Password prompt (Touch ID or password).
@@ -172,6 +173,8 @@ async function runOp(argv, exec, timeoutMs) {
     attempts += 1;
     res = await exec(argv, { timeoutMs });
   } while (res.result !== 'ok' && res.timedOut && attempts === 1);
+  // B37: a call that needed its retry is a recoverable problem worth a warning line
+  if (attempts > 1) await logWarning({ warning: 'op_retry', message: '1Password did not answer in time; the call was retried once' }).catch(() => null);
   return { res, attempts };
 }
 

package/src/ledger/report.mjs

@@ -8,14 +8,15 @@
  * Row conventions read here: `dispatch` {block,level,lane,lines}; `block.close`
  * {block,status,lines_actual} — ANY `block.close` row marks the block completed (a stop is
  * `block.stop`; B19); `review.plan` {block,tier,depth_unconstrained,depth_chosen,
- * degrade_step}; `session` {block,role,provider,level,tokens_in,tokens_out,cost_usd?} — one row per
- * coder/reviewer/judge/s2/author/facts spend; its dollars are `cost_usd` when the row carries it,
- * else ESTIMATED from its tokens × `./prices.mjs` (B19: live session rows carry tokens only); `review.done` {block,file,context_mode,findings_by_severity,round}; `decision`
+ * degrade_step}; `session` {block,role,provider,level,tokens_in,tokens_out,usd,usd_unknown?} — one row per
+ * coder/reviewer/judge/s2/author/facts spend (plus `ledger add coder` manual rows and
+ * `session.background` rows, whose price is unknown); its dollars come from `./spend.mjs`
+ * (`usd`, else `cost_usd`, else ESTIMATED from its tokens × `./prices.mjs`); `review.done` {block,file,context_mode,findings_by_severity,round}; `decision`
  * {block,question,source}; `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
  * `review.unavailable` {block,reason}; `proof` {block,duration_ms}; `run.stop` {reason}.
  */
 
-import { estimateCostUsd } from './prices.mjs';
+import { isSpendRow, rowUsd, spendByRun, sumSpend } from './spend.mjs';
 
 const ROLE_BUCKET = Object.freeze({
   coder: 'coderUsd',
@@ -38,30 +39,60 @@ function countBy(rows, keyOf) {
 }
 
 /**
- * A session row's dollars: `cost_usd` when present, else tokens × the static price table; null when
- * neither is known (no token count, or a provider/level the table does not price).
+ * A session row's dollars (B33: its `usd`; null when `usd_unknown`; older rows: `cost_usd`, else
+ * tokens × the static price table); null when the price is unknown.
  * @param {Record<string, any>} row @returns {number | null}
  */
 export function sessionCostUsd(row) {
-  if (typeof row.cost_usd === 'number') return row.cost_usd;
-  const tokensIn = row.tokens_in ?? 0;
-  const tokensOut = row.tokens_out ?? 0;
-  if (row.tokens_in == null && row.tokens_out == null) return null;
-  try {
-    return estimateCostUsd({ provider: row.provider, level: row.level, tokensIn, tokensOut });
-  } catch {
-    return null;
-  }
+  return rowUsd(row);
+}
+
+/**
+ * B33: spend per run (running totals, open blocks included) and over the whole ledger — kept
+ * beside the 13 sections, not as a 14th (`SECTION_NAMES` stays pinned at 13).
+ * @param {Array<Record<string, any>>} rows
+ * @returns {{runs: Array<{run: string | null, usd: number, unknown: number, sessions: number}>, total: {usd: number, unknown: number, sessions: number}}}
+ */
+export function buildSpend(rows) {
+  const acted = rows.filter((r) => r.source !== 'shadow');
+  return { runs: spendByRun(acted), total: sumSpend(acted) };
 }
 
-/** Cost per SUCCESSFULLY COMPLETED block: review $ / coder $ / S1+S2 $ / facts $ / proof ms. */
+/**
+ * Cost per block — completed AND still open (B33: a running total while the block is open):
+ * review $ / coder $ / S1+S2 $ / facts $ / proof ms, `completed` (any `block.close` row) and
+ * `unknownUsdSessions` (spend rows whose price is unknown, counted 0 in the totals). Grouped by
+ * run + block, so a block id reused in a second run is its own entry; a row without a run joins
+ * the entry of its block when that block id appears in exactly one run (else a `run: null` entry); shadow rows are dropped here too, exactly as `buildSpend` does. An entry is listed
+ * once it has a spend row or a `block.close` row.
+ */
 function costPerBlock(rows) {
   /** @type {Map<string, any>} */
   const byBlock = new Map();
+  /** @type {Set<string>} run+block keys with at least one spend row */
+  const spent = new Set();
+  // never split one block: a row without a run joins its block's entry when that block id appears
+  // in exactly one run; only a block seen in several runs leaves such a row in a `run: null` entry
+  /** @type {Map<string, Set<string>>} */
+  const runsOfBlock = new Map();
+  for (const row of rows) {
+    if (!row.block || row.source === 'shadow' || typeof row.run !== 'string') continue;
+    if (!runsOfBlock.has(row.block)) runsOfBlock.set(row.block, new Set());
+    /** @type {Set<string>} */ (runsOfBlock.get(row.block)).add(row.run);
+  }
+  /** @param {Record<string, any>} row @returns {string | null} */
+  const runOf = (row) => {
+    if (typeof row.run === 'string') return row.run;
+    const runs = runsOfBlock.get(row.block);
+    return runs && runs.size === 1 ? [...runs][0] : null;
+  };
   for (const row of rows) {
-    if (!row.block) continue;
-    if (!byBlock.has(row.block)) {
-      byBlock.set(row.block, {
+    if (!row.block || row.source === 'shadow') continue;
+    const run = runOf(row);
+    const key = `${run ?? ''}\u0000${row.block}`;
+    if (!byBlock.has(key)) {
+      byBlock.set(key, {
+        run,
         block: row.block,
         level: null,
         lane: null,
@@ -73,26 +104,32 @@ function costPerBlock(rows) {
         otherUsd: 0,
         proofTimeMs: 0,
         totalUsd: 0,
+        unknownUsdSessions: 0,
       });
     }
-    const e = byBlock.get(row.block);
+    const e = byBlock.get(key);
     if (row.event === 'dispatch') {
       e.level = row.level ?? e.level;
       e.lane = row.lane ?? e.lane;
     }
     if (row.event === 'block.close') e.completed = true;
-    const cost = row.event === 'session' ? sessionCostUsd(row) : null;
-    if (cost !== null) {
-      // An unrecognized role still spent real money — bucket it as `otherUsd` instead of
-      // silently dropping it from every total (fix round 1: an unknown role must not make
-      // totalUsd under-report actual spend).
-      const bucket = ROLE_BUCKET[row.role] ?? 'otherUsd';
-      e[bucket] = (e[bucket] ?? 0) + cost;
-      e.totalUsd += cost;
+    if (isSpendRow(row)) {
+      spent.add(key);
+      const cost = sessionCostUsd(row);
+      if (cost === null) {
+        e.unknownUsdSessions += 1;
+      } else {
+        // An unrecognized role still spent real money — bucket it as `otherUsd` instead of
+        // silently dropping it from every total (fix round 1: an unknown role must not make
+        // totalUsd under-report actual spend).
+        const bucket = ROLE_BUCKET[row.role] ?? 'otherUsd';
+        e[bucket] = (e[bucket] ?? 0) + cost;
+        e.totalUsd += cost;
+      }
     }
     if (row.event === 'proof' && typeof row.duration_ms === 'number') e.proofTimeMs += row.duration_ms;
   }
-  const out = [...byBlock.values()].filter((e) => e.completed);
+  const out = [...byBlock.entries()].filter(([key, e]) => e.completed || spent.has(key)).map(([, e]) => e);
   for (const e of out) {
     for (const k of ['reviewUsd', 'coderUsd', 's1s2Usd', 'factsUsd', 'otherUsd', 'totalUsd']) e[k] = Math.round(e[k] * 10000) / 10000;
   }

package/src/ledger/spend.mjs

@@ -0,0 +1,288 @@
+/**
+ * Run spend in USD (B33, plan rule R6): the one place that turns ledger rows into dollars for
+ * `report`, `run status`, the `budget.usd` stop in `spawnSession`, and `ledger add coder`.
+ *
+ * Dollars are estimates from the static price table (`./prices.mjs`, provider × level, blended
+ * in+out per 1K tokens). A row whose price is unknown carries `usd: null, usd_unknown: true` —
+ * never a guess — and counts as 0 in totals while being counted in `unknown`.
+ *
+ * Spend rows: `event: 'session'` (one per foreground attempt, plus the manual/cloud coder rows
+ * `ledger add coder` writes with `manual: true`) and `event: 'session.background'` (a detached
+ * coder: its tokens are never seen, so its price is unknown). Shadow rows never count.
+ */
+
+import { logWarning } from '../util/error-log.mjs';
+import { keyedLock } from '../util/locks.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { estimateCostUsd } from './prices.mjs';
+
+/** The ledger events that carry a session's spend. */
+export const SPEND_EVENTS = Object.freeze(['session', 'session.background']);
+
+/** Round to 4 decimals (the price table's precision). @param {number} n */
+export const roundUsd = (n) => Math.round(n * 10000) / 10000;
+
+/** A usable amount: a finite number ≥ 0 (tokens or dollars). @param {unknown} v @returns {v is number} */
+export const isAmount = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+
+/**
+ * Price one session from its token counts. Both counts must be finite numbers ≥ 0 — a null,
+ * missing, NaN, negative or string count is unknown (never read as 0) — and the provider/level
+ * must be in the price table; anything else ⇒ `{usd: null, usd_unknown: true}`.
+ * @param {{provider?: unknown, level?: unknown, tokens_in?: unknown, tokens_out?: unknown}} row
+ * @returns {{usd: number, usd_unknown: false} | {usd: null, usd_unknown: true}}
+ */
+export function priceSession({ provider, level, tokens_in, tokens_out }) {
+  if (!isAmount(tokens_in) || !isAmount(tokens_out)) return { usd: null, usd_unknown: true };
+  try {
+    const usd = estimateCostUsd({ provider: /** @type {string} */ (provider), level: /** @type {string} */ (level), tokensIn: tokens_in, tokensOut: tokens_out });
+    return isAmount(usd) ? { usd, usd_unknown: false } : { usd: null, usd_unknown: true };
+  } catch {
+    return { usd: null, usd_unknown: true };
+  }
+}
+
+/** @param {Record<string, any>} row @returns {boolean} */
+export const isSpendRow = (row) => SPEND_EVENTS.includes(row?.event) && row.source !== 'shadow';
+
+/**
+ * A spend row's dollars, or null when unknown. `usd` when the row carries the key (a non-amount —
+ * null, NaN, Infinity, negative, a string — is unknown); `usd_unknown: true` is unknown; older rows
+ * (before B33): `cost_usd` when present (a non-amount is unknown), else tokens × the price table.
+ * @param {Record<string, any>} row @returns {number | null}
+ */
+export function rowUsd(row) {
+  if (row.usd !== undefined) return isAmount(row.usd) ? row.usd : null;
+  if (row.usd_unknown === true) return null;
+  if (row.cost_usd !== undefined && row.cost_usd !== null) return isAmount(row.cost_usd) ? row.cost_usd : null;
+  if (row.event === 'session.background') return null;
+  return priceSession(row).usd;
+}
+
+/**
+ * Total spend of the rows: `usd` (unknown rows count 0), `unknown` (rows whose price is unknown),
+ * `sessions` (spend rows counted).
+ * @param {Array<Record<string, any>>} rows
+ * @returns {{usd: number, unknown: number, sessions: number}}
+ */
+export function sumSpend(rows) {
+  let usd = 0;
+  let unknown = 0;
+  let sessions = 0;
+  for (const row of rows) {
+    if (!isSpendRow(row)) continue;
+    sessions += 1;
+    const cost = rowUsd(row);
+    if (cost === null) unknown += 1;
+    else usd += cost;
+  }
+  return { usd: roundUsd(usd), unknown, sessions };
+}
+
+/**
+ * Spend of one run (rows whose `run` is `runId`).
+ * @param {Array<Record<string, any>>} rows @param {string} runId
+ */
+export const runSpend = (rows, runId) => sumSpend(rows.filter((r) => r.run === runId));
+
+/**
+ * Spend per run, in first-seen order; rows without a run are grouped under `null`.
+ * @param {Array<Record<string, any>>} rows
+ * @returns {Array<{run: string | null, usd: number, unknown: number, sessions: number}>}
+ */
+export function spendByRun(rows) {
+  /** @type {Map<string | null, Array<Record<string, any>>>} */
+  const groups = new Map();
+  for (const row of rows) {
+    if (!isSpendRow(row)) continue;
+    const key = typeof row.run === 'string' ? row.run : null;
+    if (!groups.has(key)) groups.set(key, []);
+    /** @type {Array<Record<string, any>>} */ (groups.get(key)).push(row);
+  }
+  return [...groups.entries()].map(([run, list]) => ({ run, ...sumSpend(list) }));
+}
+
+/**
+ * `budget.usd` from a loaded config: a finite number > 0, else null (no budget).
+ * @param {Record<string, any> | null | undefined} cfg @returns {number | null}
+ */
+export function budgetUsdOf(cfg) {
+  const v = cfg?.budget?.usd;
+  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null;
+}
+
+/** The plain refusal text (R6). @param {number} budget @param {number} spent */
+export const budgetReachedMessage = (budget, spent) => `budget.usd ${budget.toFixed(2)} reached (spent ${spent.toFixed(2)}); raise budget.usd or end the run`;
+
+/**
+ * B41: the refusal text when the ledger spend is under the budget but the sessions still running
+ * (reserved) plus this session's estimate would pass it.
+ * @param {number} budget @param {number} spent @param {number} reserved @param {number} estimate
+ */
+export const budgetWouldExceedMessage = (budget, spent, reserved, estimate) =>
+  reserved > 0
+    ? `budget.usd ${budget.toFixed(2)} would be exceeded: spent ${spent.toFixed(2)}, reserved by running sessions ${reserved.toFixed(2)}, this session about ${estimate.toFixed(2)}; it starts when running sessions finish or when budget.usd is raised`
+    : `budget.usd ${budget.toFixed(2)} would be exceeded: spent ${spent.toFixed(2)}, this session about ${estimate.toFixed(2)}; raise budget.usd or end the run`;
+
+/** B41: the refusal text when this session's estimate alone is above the budget. @param {number} budget @param {number} estimate */
+export const budgetEstimateAboveMessage = (budget, estimate) => `this session's estimated cost (about ${estimate.toFixed(2)}) is above budget.usd ${budget.toFixed(2)}; raise budget.usd`;
+
+/** The one-time warning text at 80 %. @param {number} budget @param {number} spent */
+export const budgetWarningMessage = (budget, spent) => `budget.usd: spent ${spent.toFixed(2)} of ${budget.toFixed(2)} (≥ 80%); new sessions stop at 100%`;
+
+/**
+ * Runs this process warned about — the FALLBACK dedupe, used only when the warning row could not
+ * be written (no writer, or the write failed). The primary record is the `budget.warning` row.
+ */
+const warnedRuns = new Set();
+
+/**
+ * The budget check run before every session spawn. Reads the run's spend from `rows` (only rows
+ * whose `run` is `run` count): spent ≥ budget, or (B41) spent + reserved + estimate > budget ⇒
+ * `{refuse: true}` and a `budget.refused` row (with `reserved_usd`/`estimate_usd` when either is > 0);
+ * the message is the B33 text when spent ≥ budget, else `budgetEstimateAboveMessage` when the
+ * estimate alone is above the budget, else `budgetWouldExceedMessage`;
+ * spent ≥ 80 % of budget ⇒ one `budget.warning` row and stderr line per run — skipped when the
+ * ledger already holds a `budget.warning` row for the run.
+ * @param {{budget: number, run: string, rows: Array<Record<string, any>>, block?: string | null, role?: string,
+ *   writeRow?: ((row: Record<string, any>) => Promise<unknown>) | null, stderr: {write: (s: string) => unknown},
+ *   reserved?: number, estimate?: number}} opts - B41: `reserved` (other sessions' holds) and
+ *   `estimate` (this session) join the refusal test; the 80 % warning still reads `spent` only.
+ * @returns {Promise<{refuse: boolean, spent: number, message?: string}>}
+ */
+export async function checkBudget({ budget, run, rows, block = null, role, writeRow = null, stderr, reserved = 0, estimate = 0 }) {
+  const { usd: spent, unknown } = runSpend(rows, run);
+  const held = isAmount(reserved) ? reserved : 0;
+  const next = isAmount(estimate) ? estimate : 0;
+  const base = { run, block, ...(role ? { role } : {}), budget_usd: budget, spent_usd: spent, unknown_usd_sessions: unknown };
+  // B41: the sessions still running (reserved) and this one (estimate) count too
+  if (spent >= budget || roundUsd(spent + held + next) > budget) {
+    // spent ≥ budget: the B33 text; else the estimate alone, else the running sessions' holds
+    const message = spent >= budget ? budgetReachedMessage(budget, spent) : next > budget ? budgetEstimateAboveMessage(budget, next) : budgetWouldExceedMessage(budget, spent, held, next);
+    writeSafe(stderr, `code-forge: ${message}\n`);
+    if (writeRow) {
+      try {
+        await writeRow({ event: 'budget.refused', ...base, ...(held > 0 || next > 0 ? { reserved_usd: held, estimate_usd: next } : {}) });
+      } catch {
+        // the refusal stands without its row
+      }
+    }
+    return { refuse: true, spent, message };
+  }
+  // compared at the ledger's 4-decimal precision, so 0.24 of 0.30 is exactly 80 %
+  if (spent >= roundUsd(0.8 * budget) && !rows.some((r) => r.event === 'budget.warning' && r.run === run)) {
+    let recorded = false;
+    if (writeRow) {
+      try {
+        await writeRow({ event: 'budget.warning', ...base });
+        recorded = true;
+      } catch {
+        recorded = false; // fall back to the in-process dedupe below
+      }
+    }
+    if (recorded || !warnedRuns.has(run)) {
+      writeSafe(stderr, `code-forge: ${budgetWarningMessage(budget, spent)}\n`);
+      warnedRuns.add(run); // after the write attempt, never before
+      // B37: a warning line in the local error log — never the amounts (config values)
+      await logWarning({ warning: 'budget_warning', message: 'budget.usd: 80% of the run budget is spent; new sessions stop at 100%' }).catch(() => null);
+    }
+  }
+  return { refuse: false, spent };
+}
+
+/** The fail-closed refusal text: a budget is set but the run's spend cannot be read. */
+export const SPEND_UNREADABLE_MESSAGE = "budget.usd is set but the run's spend cannot be read; not starting a session";
+
+/*
+ * B41 — budget reservations under concurrency.
+ *
+ * Several sessions of one run can start at once (B40 slots, B42 ticket pool). The ledger only
+ * learns a session's cost when its row is written, so a plain "spent < budget" check lets every
+ * session that starts before the first row lands go through. Instead the check AND a reservation
+ * of the session's estimated cost happen under ONE in-process lock per run (`withBudgetLock`):
+ *
+ *   spent ≥ budget, or spent + reserved + estimate > budget ⇒ refused (the B33 message, unchanged)
+ *
+ * The reservation is held until the session row is written (or the spawn fails, throws or is
+ * refused) and then released. Reservations live in this process only (module level, keyed by run).
+ *
+ * The estimate (`estimateSessionUsd`): tokens_in = the packet's bytes / 4 (the ledger's own
+ * `estimateTokens` rule) and a fixed, deliberately high tokens_out per role and level
+ * (`TOKENS_OUT_ESTIMATE`), priced with the static table. A provider/level with no price reserves 0.
+ */
+
+/**
+ * Conservative tokens_out per role and level, used only for reservations. Coders run an agentic
+ * tool loop whose billed tokens dwarf the brief, so they get the largest figures; an author writes a
+ * whole plan; reviewers, facts and judges return one structured answer; S2 a short judgement.
+ * Each is several times what a typical session of that kind reports.
+ */
+export const TOKENS_OUT_ESTIMATE = Object.freeze({
+  coder: Object.freeze({ L0: 8000, L1: 16000, L2: 32000, L3: 64000 }),
+  author: Object.freeze({ L0: 8000, L1: 12000, L2: 16000, L3: 24000 }),
+  reviewer: Object.freeze({ L0: 4000, L1: 6000, L2: 8000, L3: 12000 }),
+  facts: Object.freeze({ L0: 4000, L1: 6000, L2: 8000, L3: 12000 }),
+  judge: Object.freeze({ L0: 2000, L1: 3000, L2: 4000, L3: 6000 }),
+  s2: Object.freeze({ L0: 1000, L1: 1500, L2: 2000, L3: 3000 }),
+});
+
+/** tokens_out when the role or level is not in the table (the coder L3 figure: the largest). */
+export const TOKENS_OUT_FALLBACK = 64000;
+
+/**
+ * The dollars reserved for one session before it starts. `tokensIn` not an amount ⇒ 0 in.
+ * @param {{provider: string, level: string, role: string, tokensIn?: number | null}} args
+ * @returns {number} USD at 4 decimals; 0 when the provider/level has no price.
+ */
+export function estimateSessionUsd({ provider, level, role, tokensIn }) {
+  const out = /** @type {Record<string, Record<string, number>>} */ (TOKENS_OUT_ESTIMATE)[role]?.[level] ?? TOKENS_OUT_FALLBACK;
+  const priced = priceSession({ provider, level, tokens_in: isAmount(tokensIn) ? tokensIn : 0, tokens_out: out });
+  return priced.usd ?? 0;
+}
+
+/** @type {Map<string, Map<number, number>>} run → (reservation id → USD) */
+const reservations = new Map();
+let nextReservation = 0;
+let lockCalls = 0;
+
+/** USD reserved right now for `run` by sessions that have not written their row. @param {string} run */
+export function reservedUsd(run) {
+  let sum = 0;
+  for (const usd of reservations.get(run)?.values() ?? []) sum += usd;
+  return roundUsd(sum);
+}
+
+/**
+ * Reserve `usd` for `run`; call only inside {@link withBudgetLock}. Returns an idempotent release.
+ * @param {string} run @param {number} usd @returns {() => void}
+ */
+export function reserveBudget(run, usd) {
+  const id = ++nextReservation;
+  let map = reservations.get(run);
+  if (!map) reservations.set(run, (map = new Map()));
+  map.set(id, isAmount(usd) ? usd : 0);
+  return () => {
+    const m = reservations.get(run);
+    if (!m) return;
+    m.delete(id);
+    if (m.size === 0) reservations.delete(run);
+  };
+}
+
+/**
+ * Run `fn` under the run's budget lock: budget checks of one run never interleave.
+ * @template T @param {string} run @param {() => T | Promise<T>} fn @returns {Promise<T>}
+ */
+export function withBudgetLock(run, fn) {
+  lockCalls += 1;
+  return keyedLock(`budget:${run}`, fn);
+}
+
+/** Test spy: how many times {@link withBudgetLock} was entered since the last reset. */
+export const budgetLockCalls = () => lockCalls;
+
+/** Test helper: drop every reservation and zero the lock counter. */
+export function resetBudgetReservations() {
+  reservations.clear();
+  lockCalls = 0;
+}

package/src/review/engine.mjs

@@ -5,7 +5,8 @@
  *  1. plans the sessions (`planSessions`):
  *       adaptive (default) — `risk < 1` ⇒ one L2 `quick`; `1 ≤ risk < 2` ⇒ one L2 `full`;
  *       `risk ≥ 2` ⇒ two blind L2 sessions (lens `A`, lens `B`) + one L3 `judge`;
- *       consensus (`review.multimodel: true`) — one L2 `full` per EFFECTIVE provider
+ *       consensus (`review.multimodel: true`, risk above `review.single_reviewer_max_risk` (1),
+ *       and not a docs/contract block unless `review.multimodel_for_docs`; B34) — one L2 `full` per EFFECTIVE provider
  *       (`resolve(L2)` and `review.second_levels.L2` / `review.second_provider`) + one L3 judge;
  *       the same effective provider twice is refused (`consensus-same-provider`);
  *  2. reads the diff once and assembles one packet per lens (`packet.mjs`);
@@ -15,7 +16,10 @@
  *     is `unavailable` with its reason and is NEVER approval; a failed lens means no judge;
  *  5. a valid answer with `needs_file` gets ONE more round with those files attached (git-tracked
  *     files only, never secret-like paths — `attachFiles`); a second `needs_file` is ignored; a
- *     request with a non-repo-relative path is refused (`needs_file-refused`, never approval).
+ *     request with a non-repo-relative path is refused (`needs_file-refused`, never approval);
+ *  6. a session that ends in `timeout` is spawned ONCE more on the same packet and level
+ *     (`session-retry.mjs`, B30); a second timeout is `unavailable: timeout`. The summary's
+ *     `attempts` says how many ran.
  * Approval (until B12b's triage lands) = the final answer (the judge's in dual/consensus mode, else
  * the single reviewer's) passed the guard, says `passed: true`, and carries no `critical` or
  * `warning` finding.
@@ -25,10 +29,12 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { resolveLevel } from '../config/known-ids.mjs';
+import { blockKind, isDocsKind } from '../decide/escalation.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, readFileDiff } from './packet.mjs';
 import { FINDING_SCHEMA, minTokensOut, SMALL_DIFF_ADDED_LINES, validateReview } from './validate-review.mjs';
+import { spawnWithTimeoutRetry } from './session-retry.mjs';
 import { assertRowPath } from '../worker/ticket.mjs';
 
 /**
@@ -60,13 +66,31 @@ export function secondLevel(cfg) {
 }
 
 /**
- * @param {{risk: number, cfg: Record<string, any>}} opts
+ * `review.single_reviewer_max_risk` (B34, default 1): at or below it ONE reviewer runs, no judge.
+ * @param {Record<string, any> | undefined} cfg @returns {number}
+ */
+export function singleReviewerMaxRisk(cfg) {
+  const v = cfg?.review?.single_reviewer_max_risk;
+  // `validate` rejects anything outside 0–3 (schema); this guard only covers an unvalidated config
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 3 ? v : 1;
+}
+
+/**
+ * The review topology — the ONE place it is decided (B34):
+ *  - consensus runs only when `review.multimodel` is true, the block is not a docs/contract block
+ *    (unless `review.multimodel_for_docs` is true), and `risk > review.single_reviewer_max_risk`;
+ *  - otherwise adaptive: `risk ≤ single_reviewer_max_risk` or `risk < 2` ⇒ one L2 session
+ *    (`quick` below risk 1, else `full`); else two blind lenses + an L3 judge.
+ * @param {{risk: number, cfg: Record<string, any>, kind?: unknown}} opts - `kind`: the block kind
+ *   (`blockKind`), default `code`.
  * @returns {SessionPlan}
  */
-export function planSessions({ risk, cfg }) {
+export function planSessions({ risk, cfg, kind = 'code' }) {
   if (typeof risk !== 'number' || !Number.isFinite(risk) || risk < 0 || risk > 3) throw new TypeError('planSessions: risk must be a number from 0 to 3');
   const judge = /** @type {SessionSpec} */ ({ lens: 'judge', role: 'judge', level: 'L3', slot: null });
-  if (cfg?.review?.multimodel === true) {
+  const single = risk <= singleReviewerMaxRisk(cfg);
+  const docsOff = isDocsKind(kind) && cfg?.review?.multimodel_for_docs !== true;
+  if (cfg?.review?.multimodel === true && !single && !docsOff) {
     const second = secondLevel(cfg);
     if (!second.ok) return { mode: 'consensus', depth: null, sessions: [], refused: second.reason };
     return {
@@ -80,7 +104,7 @@ export function planSessions({ risk, cfg }) {
     };
   }
   if (risk < 1) return { mode: 'adaptive', depth: 'quick', sessions: [{ lens: 'quick', role: 'reviewer', level: 'L2', slot: null }] };
-  if (risk < 2) return { mode: 'adaptive', depth: 'full', sessions: [{ lens: 'full', role: 'reviewer', level: 'L2', slot: null }] };
+  if (risk < 2 || single) return { mode: 'adaptive', depth: 'full', sessions: [{ lens: 'full', role: 'reviewer', level: 'L2', slot: null }] };
   return {
     mode: 'adaptive',
     depth: 'dual',
@@ -117,6 +141,7 @@ export function rulesRisk({ file, plusCount, cfg }) {
  * @property {string | null} [base] - the block's base SHA (null ⇒ HEAD).
  * @property {Record<string, any>} cfg
  * @property {number} [risk] - the S1 risk (0–3); absent ⇒ the rules risk.
+ * @property {string} [kind] - the block kind (`code`, `docs`, `contract`; B34); absent ⇒ `blockKind` of the reviewed file.
  * @property {string} [rulesDigest] @property {string} [factsExcerpt]
  * @property {string} workDir - where packet files are written (under the run's temp root).
  */
@@ -161,7 +186,9 @@ export async function reviewFile(input, deps) {
   const { repoRoot, cfg, workDir } = input;
   const diff = await readFileDiff({ repoRoot, file: input.file, base: input.base ?? null });
   const risk = input.risk ?? rulesRisk({ file: diff.file, plusCount: diff.plusCount, cfg });
-  const plan = planSessions({ risk, cfg });
+  // no recorded kind ⇒ the reviewed file's own kind (a lone `.md` is a docs review), never a blind `code`
+  const kind = typeof input.kind === 'string' ? input.kind : blockKind({ owned: [diff.file] });
+  const plan = planSessions({ risk, cfg, kind });
   const head = { engine: plan.mode, depth: plan.depth, risk, file: diff.file };
   if (plan.refused) return { status: 'refused', reason: plan.refused, approved: false, ...head, sessions: [] };
   if (diff.diffText.trim().length === 0) return { status: 'no_change', approved: false, ...head, sessions: [] };
@@ -231,17 +258,30 @@ async function runOne(spec, text, packet, { deps, workDir, min, smallDiff = fals
   writeFileSync(promptPath, text, { mode: 0o600 });
   /** @type {Record<string, any> | null} */
   let res = null;
+  let attempts = 0;
   try {
-    res = await deps.spawn({
-      level: spec.level,
-      role: spec.role,
-      promptPath,
-      schema: FINDING_SCHEMA,
-      rowExtra: { lens: spec.lens, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn },
-      ...(spec.cfg ? { cfg: spec.cfg } : {}),
-    });
+    // a `timeout` is spawned once more on the same packet and level (B30); a spawn that throws
+    // (bad config, refused argv) is an `exit` failure, never approval
+    ({ res, attempts } = await spawnWithTimeoutRetry(
+      deps.spawn,
+      {
+        level: spec.level,
+        role: spec.role,
+        promptPath,
+        schema: FINDING_SCHEMA,
+        rowExtra: { lens: spec.lens, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn },
+        ...(spec.cfg ? { cfg: spec.cfg } : {}),
+      },
+      (row) => note(deps, row),
+      (n) => {
+        attempts = n;
+      },
+    ));
   } catch {
-    res = null; // a spawn that throws (bad config, refused argv) is an `exit` failure, never approval
+    // defensive only: the helper never throws. If it ever did, it is still an `exit` failure,
+    // never approval, with the attempts it had reported so far (at least 1).
+    res = null;
+    attempts = Math.max(attempts, 1);
   } finally {
     rmSync(promptPath, { force: true });
   }
@@ -251,6 +291,7 @@ async function runOne(spec, text, packet, { deps, workDir, min, smallDiff = fals
     provider: res?.provider ?? null,
     model: res?.model ?? null,
     fallback_step: res?.fallback_step ?? 0,
+    attempts,
     tokens_in: res?.usage?.tokens_in ?? null,
     tokens_out: res?.usage?.tokens_out ?? null,
   };