@codedology/code-forge 0.3.2 → 0.4.0

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,171 @@
+/**
+ * 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 { 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`;
+
+/** 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 ⇒ `{refuse: true}` and a `budget.refused` row;
+ * 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}}} opts
+ * @returns {Promise<{refuse: boolean, spent: number, message?: string}>}
+ */
+export async function checkBudget({ budget, run, rows, block = null, role, writeRow = null, stderr }) {
+  const { usd: spent, unknown } = runSpend(rows, run);
+  const base = { run, block, ...(role ? { role } : {}), budget_usd: budget, spent_usd: spent, unknown_usd_sessions: unknown };
+  if (spent >= budget) {
+    const message = budgetReachedMessage(budget, spent);
+    writeSafe(stderr, `code-forge: ${message}\n`);
+    if (writeRow) {
+      try {
+        await writeRow({ event: 'budget.refused', ...base });
+      } 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";

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,
   };

package/src/review/fixloop.mjs

@@ -14,7 +14,10 @@
  *     round (`review.late_findings: sweep`, default; `block` makes it an open finding instead).
  *  3. Strictly shrinking: open(n) ≥ open(n−1) ⇒ `trigger: review_stall` ⇒ +1 level now (rule 2b).
  *  4. Ladder: `escalation.review_rounds_per_level` (2) exhausted with an open finding ⇒ +1 level
- *     (rule 2); the next rounds are coded at that level by a fresh session (`deps.fix`).
+ *     (rule 2); the next rounds are coded at that level by a fresh session (`deps.fix`). Below L2,
+ *     `escalation.after_rounds_with_warnings` (1) heavy rounds at the level — an open set with
+ *     ≥ `escalation.warning_threshold` (2) warnings or any `critical` — climb at once (rule 2c,
+ *     B34: `trigger: review_warnings`); `warn_rounds_at_level` counts them and resets on a climb.
  *  5. Cap: `review.max_rounds_per_file` (4) reached with an open finding ⇒ the L3 patch rung
  *     (rule 6; once per block — shared with rule 5's ceiling), whose `patch_check` round is
  *     OUTSIDE the cap. The rung is also rule 5: rule 2/2b at the running ceiling (L2 — L3 is never
@@ -49,13 +52,14 @@
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
-import { escalationAfterAttempt, reviewRoundStalled } from '../decide/escalation.mjs';
+import { escalationAfterAttempt, heavyRound, reviewRoundStalled } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
 import { assemblePacket, assertPacketPath, readFileDiff } from './packet.mjs';
 import { cameFromJudge, resolvedBand, triageFindings } from './triage.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
+import { spawnWithTimeoutRetry } from './session-retry.mjs';
 
 /** @typedef {import('./triage.mjs').Finding} Finding */
 /** @typedef {import('./context.mjs').Hunk} Hunk */
@@ -74,6 +78,7 @@ import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.
  * @property {string} level - the level the file's fixes are coded at now.
  * @property {number} round - rounds counted so far (patch_check rounds excluded).
  * @property {number} rounds_at_level
+ * @property {number} [warn_rounds_at_level] - heavy rounds at the current level (rule 2c, B34); absent in a state saved before B34 ⇒ 0.
  * @property {Finding[]} open - the open `fix_now` set.
  * @property {Finding[]} late
  * @property {string | null} reviewed_content - the content the last counted round reviewed.
@@ -119,6 +124,8 @@ function settings(cfg) {
     scope: r.recheck_scope === 'file' ? 'file' : 'fix_hunks',
     late: r.late_findings === 'block' ? 'block' : 'sweep',
     perLevel: int(e.review_rounds_per_level, 2),
+    warnAfter: int(e.after_rounds_with_warnings, 1),
+    warnThreshold: e.warning_threshold, // heavyRound falls back to 2 for anything but an integer ≥ 1
     stopAt: typeof e.stop_at === 'string' ? e.stop_at : 'L3',
     l3Mode: e.l3_mode === 'code' ? 'code' : 'patch',
   };
@@ -129,7 +136,7 @@ function settings(cfg) {
  * @returns {FileState}
  */
 export function newFileState({ file, level, l3RungUsed = false }) {
-  return { file, level, round: 0, rounds_at_level: 0, open: [], late: [], reviewed_content: null, l3_rung_used: l3RungUsed, status: 'open', next: null, last_packet: null, pending_kind: null };
+  return { file, level, round: 0, rounds_at_level: 0, warn_rounds_at_level: 0, open: [], late: [], reviewed_content: null, l3_rung_used: l3RungUsed, status: 'open', next: null, last_packet: null, pending_kind: null };
 }
 
 /** @param {string} repoRoot @param {string} file @returns {{rel: string, content: string, hash: string}} */
@@ -209,11 +216,18 @@ async function recheckSession(packet, deps) {
   /** @type {Record<string, any> | null} */
   let res = null;
   try {
+    // a `timeout` is spawned once more on the same packet and level (B30)
     res = deps.spawn
-      ? await deps.spawn({ level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn } })
+      ? (
+          await spawnWithTimeoutRetry(
+            deps.spawn,
+            { level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn } },
+            (row) => note(deps, row),
+          )
+        ).res
       : null;
   } catch {
-    res = null;
+    res = null; // the helper never throws; if it ever did, it is still an `exit` failure
   } finally {
     rmSync(promptPath, { force: true });
   }
@@ -246,12 +260,17 @@ function decideNext(state, openBefore, s, kind) {
     openFixNowFinding: true,
     reviewRoundsAtLevel: state.rounds_at_level,
     reviewRoundsPerLevel: s.perLevel,
+    warningRoundsAtLevel: state.warn_rounds_at_level ?? 0,
+    afterRoundsWithWarnings: s.warnAfter,
     stopAt: s.stopAt,
     l3Mode: /** @type {'patch' | 'code'} */ (s.l3Mode),
     l3RungAlreadyUsed: state.l3_rung_used,
   });
   if (esc.action === 'escalate' && esc.level) {
-    if (esc.level !== state.level) state.rounds_at_level = 0;
+    if (esc.level !== state.level) {
+      state.rounds_at_level = 0;
+      state.warn_rounds_at_level = 0;
+    }
     state.level = esc.level;
     return { action: 'fix', level: state.level, trigger: esc.trigger };
   }
@@ -390,10 +409,13 @@ export async function runRound(state, deps, opts = {}) {
   if (kind !== 'patch_check') {
     draft.round += 1;
     draft.rounds_at_level += 1;
+    // THIS round's open set, after triage: only the warnings still open count
+    if (heavyRound(draft.open, s.warnThreshold)) draft.warn_rounds_at_level = (draft.warn_rounds_at_level ?? 0) + 1;
   } else {
     // the block continues at L2 after the rung with a fresh round counter (§3.6) — also here, not
     // only in `converge`, because the worker runs the patch_check from its own ticket
     draft.rounds_at_level = 0;
+    draft.warn_rounds_at_level = 0;
   }
   draft.reviewed_content = current.content;
   draft.last_packet = packetInfo;
@@ -456,6 +478,7 @@ export async function converge(state, deps) {
     if (next.action === 'patch') {
       state.l3_rung_used = true;
       state.rounds_at_level = 0;
+      state.warn_rounds_at_level = 0;
       await deps.patch?.({ file: state.file, level: 'L3', open: [...state.open] });
       await runRound(state, deps, { kind: 'patch_check' });
       continue;

package/src/review/session-retry.mjs

@@ -0,0 +1,69 @@
+/**
+ * One review session with ONE automatic retry on `timeout` (block B30, issue #2).
+ *
+ * Field data: a reviewer CLI can hang for the whole `review.session_timeout_s` with almost no
+ * output, while the same packet reviews in seconds on a second try. So a session whose status is
+ * `timeout` is spawned once more with the SAME options (same packet file, same level, same lens);
+ * only when the second attempt times out too does the review report `unavailable: timeout`. Any
+ * other failure (exit, schema, unavailable…) is never retried here.
+ *
+ * Both attempts are recorded: `spawnSession` writes one ledger `session` row per spawn as always,
+ * and every timed-out attempt adds a `review.session_timeout` note `{lens, role, level, provider,
+ * model, attempt, retried, duration_ms, stderr_tail, tail_note?, stdout_bytes, stdout_events}`:
+ * the last 4 KB of the session's stderr, packet-free and redacted (`stderrTail`; null with a
+ * `tail_note` when withheld), and stdout only as its byte count and last event types
+ * (`stdoutEvents`) — never stdout text. The helper never throws: a throwing spawn is returned as
+ * `res: null` and a failed note is ignored. `onAttempt(n)` is told each attempt as it starts.
+ */
+
+import { logWarning } from '../util/error-log.mjs';
+
+/** How many times a timed-out session is spawned again. */
+export const TIMEOUT_RETRIES = 1;
+
+/**
+ * @param {(opts: Record<string, any>) => Promise<Record<string, any>>} spawn
+ * @param {Record<string, any>} opts - the spawn options; passed unchanged to every attempt.
+ * @param {(row: Record<string, any>) => Promise<unknown>} note - best-effort ledger note.
+ * @param {(attempt: number) => void} [onAttempt] - told the attempt number as each one starts.
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number}>} the last attempt's result
+ *   (`null` when the spawn threw) and how many attempts ran.
+ */
+export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () => {}) {
+  let attempts = 0;
+  for (;;) {
+    attempts += 1;
+    onAttempt(attempts);
+    /** @type {Record<string, any> | null} */
+    let res;
+    try {
+      res = await spawn(opts);
+    } catch {
+      return { res: null, attempts }; // a throw is an `exit` failure, never retried
+    }
+    if (res?.status !== 'timeout') return { res, attempts };
+    const retried = attempts <= TIMEOUT_RETRIES;
+    try {
+      await note({
+        event: 'review.session_timeout',
+        lens: opts?.rowExtra?.lens ?? null,
+        role: opts?.role ?? null,
+        level: opts?.level ?? null,
+        provider: res.provider ?? null,
+        model: res.model ?? null,
+        attempt: attempts,
+        retried,
+        duration_ms: typeof res.duration_ms === 'number' ? res.duration_ms : null,
+        stderr_tail: typeof res.stderr_tail === 'string' ? res.stderr_tail : null,
+        ...(typeof res.tail_note === 'string' ? { tail_note: res.tail_note } : {}),
+        stdout_bytes: typeof res.stdout_bytes === 'number' ? res.stdout_bytes : null,
+        stdout_events: Array.isArray(res.stdout_events) ? res.stdout_events : [],
+      });
+    } catch {
+      // a failed note never stops the retry or the result
+    }
+    if (!retried) return { res, attempts };
+    // B37: the retry is a recoverable problem: one warning line in the local error log
+    await logWarning({ warning: 'review_retry', message: 'a review session timed out; it was retried once' }).catch(() => null);
+  }
+}