@codedology/code-forge 0.9.0 → 0.11.0

package/src/review/reviewed-lines.mjs

@@ -0,0 +1,94 @@
+/**
+ * B96 (E1): the close report is built by the tool. After the review gate passed (`reviewGateCheck`
+ * over `checkBlockReviews`), every file the gate checked is accepted at its current hash, either
+ * by a signed `review.approved` row or — the gate's `waivedAll` list (B70/B71) — because every
+ * finding its review left open was waived or answered. This module turns that verdict into one
+ * line per file: `{file, ticket, via}`, `via` one of `approved`, `waiver`, `answered`, and
+ * `ticket` the queue's ticket for that file and hash (the caller passes `ticketOf`, the queue's
+ * own rule: `src/review` never imports the worker). It never re-decides the acceptance: the gate
+ * is the only judge, and a file the gate did not accept is never passed here.
+ *
+ * It also reads the coder's hand lines (`reviewed <path> ticket <id>`), to name a hand line that
+ * names another ticket (D1: a warning, the tool lines are the record).
+ *
+ * Its warnings (`onNoTicket`, `onBadTicket`) are callbacks: the close holds what they report and
+ * prints it only when the block closes (src/cli/block.mjs).
+ */
+
+/** @typedef {'approved' | 'waiver' | 'answered'} Via */
+/** @typedef {{file: string, ticket: string, via: Via}} ReviewedLine */
+
+/**
+ * The `via` of a file the gate accepted, read from the gate's own record (`WaivedAll`, built by
+ * `waivedAllOf` in gate-check.mjs): no record at the same hash ⇒ `approved` (a signed approval);
+ * a record whose `by` is null ⇒ `answered` (the gate sets `by` to null exactly when every open
+ * finding was answered); any other `by` (`human` or `autopilot`) ⇒ `waiver` — also for a file
+ * with some findings answered and at least one waived (the waiver is what a human or a grant
+ * decided, so the line names it).
+ * @param {import('./gate-check.mjs').WaivedAll | undefined} record @returns {Via}
+ */
+export function viaOf(record) {
+  if (record === undefined) return 'approved';
+  return record.by === null ? 'answered' : 'waiver';
+}
+
+/** A ticket id as the queue gives it: 24 lowercase hex characters (`assertTicketId`). */
+const TICKET_ID = /^[0-9a-f]{24}$/;
+
+/**
+ * The tool's reviewed lines, sorted by file. Pure but for `onNoTicket` and `onBadTicket`.
+ * @param {{
+ *   files: ReadonlyArray<{file: string, content_hash: string}>,
+ *   waivedAll: ReadonlyArray<import('./gate-check.mjs').WaivedAll>,
+ *   ticketOf: (file: {file: string, content_hash: string}) => unknown,
+ *   onNoTicket?: (file: string) => void,
+ *   onBadTicket?: (file: string) => void,
+ * }} opts `files`: the files the review gate checked and ACCEPTED (it passed); `waivedAll`: the
+ *   gate's `reviewed_by_waiver` files ({@link viaOf}); every other file passed through a signed
+ *   approval. `ticketOf`: the queue's ticket for that file at that hash, or null (or undefined)
+ *   when it cannot be given — then the file has no line (fail closed) and `onNoTicket(file)` is
+ *   called once. Any other value that is not 24 lowercase hex characters (a string of another
+ *   shape, a number…) is a bad ticket: the file has no line either and `onBadTicket(file)` is
+ *   called once instead.
+ * @returns {ReviewedLine[]}
+ */
+export function reviewedLines({ files, waivedAll, ticketOf, onNoTicket = () => {}, onBadTicket = () => {} }) {
+  /** @type {ReviewedLine[]} */
+  const lines = [];
+  for (const f of files) {
+    const via = viaOf(waivedAll.find((w) => w.file === f.file && w.content_hash === f.content_hash));
+    const ticket = ticketOf(f);
+    if (ticket === null || ticket === undefined) onNoTicket(f.file);
+    else if (typeof ticket === 'string' && TICKET_ID.test(ticket)) lines.push({ file: f.file, ticket, via });
+    else onBadTicket(f.file);
+  }
+  return lines.sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0));
+}
+
+/**
+ * A hand line: exactly `reviewed <path> ticket <id>` once trimmed, with backticks dropped and an
+ * optional leading list marker (`- `, `* ` or a number and a dot, `1. `). The id is 24 hex
+ * characters of either case: a ticket id is lowercase, so an id in capitals is read here and then
+ * never equals the tool's ticket ({@link reportMismatches} compares exactly).
+ */
+const HAND_LINE = /^(?:(?:[-*]|\d{1,9}\.)\s+)?reviewed\s+(\S+)\s+ticket\s+([0-9a-fA-F]{24})$/;
+
+/**
+ * D1: the files whose hand line in `report` names a ticket id other than the tool's (compared
+ * exactly, so an id in capitals is another ticket). Only a `reviewed <path> ticket <id>` line
+ * counts ({@link HAND_LINE}); a hash of another length, or a line of any other shape that names
+ * the file, never does.
+ * @param {string} report @param {ReadonlyArray<ReviewedLine>} lines
+ * @returns {string[]} the files with a mismatched hand line, in the order of `lines`.
+ */
+export function reportMismatches(report, lines) {
+  /** @type {Set<string>} */
+  const other = new Set();
+  for (const raw of report.split('\n')) {
+    const m = HAND_LINE.exec(raw.replaceAll('`', '').trim());
+    if (m === null) continue;
+    const line = lines.find((l) => l.file === m[1]);
+    if (line !== undefined && line.ticket !== m[2]) other.add(line.file);
+  }
+  return lines.filter((l) => other.has(l.file)).map((l) => l.file);
+}

package/src/review/route.mjs

@@ -0,0 +1,232 @@
+/**
+ * Size-based review routing (block B90): `review.routes` sends a big file to a named model with
+ * its own session timeout and its own second level, with no `.code-forge.yml` edit and no reload.
+ *
+ * A rule is `{min_lines, level?, model, provider?, effort?, fallback?, session_timeout_s?, second?}`.
+ * `level` is the level it replaces (`L2` default, or `L3`, the judge). The worker picks the route
+ * once per ticket, before any session, from the line count of the file's content in the reviewed
+ * tree (the bytes it hashed). A deleted file has no content and is never routed. Among the rules
+ * of one level, the one with the largest `min_lines` that is at most the count wins.
+ *
+ * The routed ticket runs with a derived config: `levels.<level>` = the rule's model entry
+ * (`model`, `provider`, `effort`, `fallback`; with no `provider` the top-level one, like any level
+ * entry), `review.second_levels.<level>` = `second` when given — except an L2 rule while
+ * `review.multimodel` is on: the consensus second reviewer is `review.second_levels.L2`, so it is
+ * kept. The timeout is ONE value for every session of the ticket: the largest `session_timeout_s`
+ * among the matched rules that set one, else the unrouted timeout (`review.session_timeout_s`).
+ *
+ * No `review.routes` (or no rule that matches) leaves the config object itself untouched. Pure:
+ * no I/O; the worker (`src/worker/loop.mjs`) reads the bytes, writes the signed `review.route` row
+ * and pins the timeout. This module never imports `src/worker`.
+ */
+
+import { resolveLevel } from '../config/known-ids.mjs';
+
+/** The levels a rule may replace: the reviewers (L2) and the judge (L3). */
+export const ROUTE_LEVELS = Object.freeze(['L2', 'L3']);
+
+/** The level a rule replaces when it names none. */
+export const DEFAULT_ROUTE_LEVEL = 'L2';
+
+/** The keys of a rule that form the routed level entry (`$defs/level`). */
+const ENTRY_KEYS = Object.freeze(['model', 'provider', 'effort', 'fallback']);
+
+/** A route list that cannot be used: the ticket is `unavailable` with this code, never reviewed on another model. */
+export class RouteError extends Error {
+  constructor() {
+    super('review.routes is not a list of valid rules');
+    this.code = 'route-invalid';
+  }
+}
+
+/**
+ * The number of lines of a file's content: its newline bytes, plus one for a last line with no
+ * newline. Counted on the bytes, never on decoded text. `null` (a deleted file) and an empty file
+ * have 0 lines.
+ * @param {Buffer | null} bytes @returns {number}
+ */
+export function countLines(bytes) {
+  if (bytes === null || bytes.length === 0) return 0;
+  let n = 0;
+  for (let at = bytes.indexOf(0x0a); at !== -1; at = bytes.indexOf(0x0a, at + 1)) n += 1;
+  return bytes[bytes.length - 1] === 0x0a ? n : n + 1;
+}
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** @param {unknown} v @returns {boolean} */
+const isPositiveInt = (v) => Number.isInteger(v) && /** @type {number} */ (v) >= 1;
+
+/** @param {unknown} v @returns {boolean} a non-empty string. */
+const isText = (v) => typeof v === 'string' && v.length > 0;
+
+/** @param {unknown} v @returns {boolean} absent, or a string (the schema's `effort`/`provider` types). */
+const optString = (v) => v === undefined || typeof v === 'string';
+
+/**
+ * A fallback item (`$defs/level` fallback): an object with a model and a provider, and an
+ * `effort` string when present.
+ * @param {unknown} v @returns {boolean}
+ */
+const isFallbackItem = (v) => isObject(v) && isText(v.model) && isText(v.provider) && optString(v.effort);
+
+/**
+ * A `$defs/level`-shaped entry: a model string, `provider` and `effort` strings when present, and
+ * `fallback` (when present) a list of fallback items. Used for a rule and for its `second`.
+ * @param {unknown} v @returns {boolean}
+ */
+function isEntry(v) {
+  if (!isObject(v) || !isText(v.model) || !optString(v.provider) || !optString(v.effort)) return false;
+  return v.fallback === undefined || (Array.isArray(v.fallback) && v.fallback.every(isFallbackItem));
+}
+
+/**
+ * Is `rule` usable? The schema and config rule 18 refuse everything else at `run start` and
+ * `run reload`; this guards a snapshot that never went through them.
+ * @param {unknown} rule @returns {boolean}
+ */
+function usable(rule) {
+  if (!isEntry(rule)) return false;
+  const r = /** @type {Record<string, any>} */ (rule);
+  if (!Number.isInteger(r.min_lines) || r.min_lines < 0) return false;
+  if (r.level !== undefined && !ROUTE_LEVELS.includes(r.level)) return false;
+  if (r.session_timeout_s !== undefined && !isPositiveInt(r.session_timeout_s)) return false;
+  if (r.second !== undefined && !isEntry(r.second)) return false;
+  return true;
+}
+
+/** @param {Record<string, any>} rule @returns {Record<string, any>} the level entry a rule routes to. */
+function entryOf(rule) {
+  /** @type {Record<string, any>} */
+  const entry = {};
+  for (const key of ENTRY_KEYS) if (rule[key] !== undefined) entry[key] = rule[key];
+  return entry;
+}
+
+/**
+ * The provider a rule's routed level runs on — the one place it is decided, shared with config
+ * validation (rules 16 and 18) so the two cannot drift: the rule's entry REPLACES
+ * `levels.<level>`, so a rule with no `provider` inherits the top-level `provider` (never the
+ * replaced level's own `provider`), resolved exactly as the spawner resolves any level.
+ * @param {Record<string, any> | null | undefined} cfg @param {Record<string, any>} rule
+ * @returns {string | undefined} undefined when the routed level cannot be resolved.
+ */
+export function ruleProvider(cfg, rule) {
+  const level = rule?.level ?? DEFAULT_ROUTE_LEVEL;
+  const levels = { ...(isObject(cfg?.levels) ? cfg?.levels : {}), [level]: isObject(rule) ? entryOf(rule) : {} };
+  try {
+    return resolveLevel({ ...(cfg ?? {}), levels }, /** @type {any} */ (level)).provider;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The rules of `cfg.review.routes`: `[]` when the key is absent or null.
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {Array<Record<string, any>>}
+ * @throws {RouteError} the key is set but is not a list of usable rules.
+ */
+export function routeRules(cfg) {
+  const routes = cfg?.review?.routes;
+  if (routes === undefined || routes === null) return [];
+  if (!Array.isArray(routes) || !routes.every(usable)) throw new RouteError();
+  // config rule 18 refuses the same level and min_lines twice; a snapshot that skipped it fails
+  // closed here rather than letting list order pick the rule
+  const seen = new Set(routes.map((r) => `${r.level ?? DEFAULT_ROUTE_LEVEL}\0${r.min_lines}`));
+  if (seen.size !== routes.length) throw new RouteError();
+  return routes;
+}
+
+/**
+ * The winning rule per level for a file of `lines` lines: among the rules of a level, the largest
+ * `min_lines` that is at most `lines`. A deleted file (`deleted: true`) is never routed.
+ * @param {Record<string, any> | null | undefined} cfg @param {number} lines - a non-negative integer.
+ * @param {{deleted?: boolean}} [opts]
+ * @returns {Array<{level: string, rule: Record<string, any>}>} in `ROUTE_LEVELS` order; `[]` ⇒ no route.
+ * @throws {RouteError}
+ */
+export function pickRoutes(cfg, lines, { deleted = false } = {}) {
+  const rules = routeRules(cfg);
+  // a count that is not a line count never picks (or skips) a route: fail closed
+  if (!Number.isInteger(lines) || lines < 0) throw new RouteError();
+  if (deleted || rules.length === 0) return [];
+  /** @type {Array<{level: string, rule: Record<string, any>}>} */
+  const out = [];
+  for (const level of ROUTE_LEVELS) {
+    let best = null;
+    for (const rule of rules) {
+      if ((rule.level ?? DEFAULT_ROUTE_LEVEL) !== level || rule.min_lines > lines) continue;
+      if (best === null || rule.min_lines > best.min_lines) best = rule;
+    }
+    if (best !== null) out.push({ level, rule: best });
+  }
+  return out;
+}
+
+/**
+ * @typedef {object} RoutedTicket
+ * @property {Record<string, any>} cfg - the config every session of the ticket runs with; the SAME
+ *   object as the input when nothing is routed.
+ * @property {number} timeoutS - the session timeout of every session of the ticket.
+ * @property {Array<Record<string, any>>} rows - one `review.route` row body per routed level
+ *   (`{event, level, min_lines, lines, provider, model, session_timeout_s, second_model}`), unsigned.
+ */
+
+/**
+ * The ticket's routed config, timeout and `review.route` rows.
+ * @param {Record<string, any>} cfg - the ticket's config snapshot.
+ * @param {{lines: number, deleted?: boolean, timeoutS: number}} file - `timeoutS`: the unrouted timeout.
+ * @returns {RoutedTicket}
+ * @throws {RouteError}
+ */
+export function routeTicket(cfg, { lines, deleted = false, timeoutS }) {
+  const picked = pickRoutes(cfg, lines, { deleted });
+  if (picked.length === 0) return { cfg, timeoutS, rows: [] };
+  const given = picked.map(({ rule }) => rule.session_timeout_s).filter((t) => t !== undefined);
+  const routedTimeout = given.length > 0 ? Math.max(...given) : timeoutS;
+  const levels = { ...(isObject(cfg.levels) ? cfg.levels : {}) };
+  const review = { ...(isObject(cfg.review) ? cfg.review : {}) };
+  /** @type {Record<string, any>} */
+  const seconds = { ...(isObject(review.second_levels) ? review.second_levels : {}) };
+  let secondsChanged = false;
+  /** @type {Array<{level: string, rule: Record<string, any>, second: boolean}>} */
+  const applied = [];
+  for (const { level, rule } of picked) {
+    levels[level] = entryOf(rule);
+    // the consensus second reviewer is `second_levels.L2`: an L2 rule never replaces it then
+    const second = rule.second !== undefined && !(level === 'L2' && review.multimodel === true);
+    if (second) {
+      seconds[level] = rule.second;
+      secondsChanged = true;
+    }
+    applied.push({ level, rule, second });
+  }
+  if (secondsChanged) review.second_levels = seconds;
+  const routed = { ...cfg, levels, review };
+  const rows = applied.map(({ level, rule, second }) => ({
+    event: 'review.route',
+    level,
+    min_lines: rule.min_lines,
+    lines,
+    provider: providerOf(cfg, rule),
+    model: rule.model,
+    session_timeout_s: routedTimeout,
+    second_model: second ? rule.second.model : null,
+  }));
+  return { cfg: routed, timeoutS: routedTimeout, rows };
+}
+
+/**
+ * The provider the routed level resolves to — the one its sessions spawn on (`ruleProvider`).
+ * @param {Record<string, any>} cfg - the unrouted snapshot. @param {Record<string, any>} rule
+ * @returns {string}
+ * @throws {RouteError} the routed level cannot be resolved (e.g. no provider anywhere): the ticket
+ *   is `route-invalid`, never a row with no provider.
+ */
+function providerOf(cfg, rule) {
+  const provider = ruleProvider(cfg, rule);
+  if (provider === undefined) throw new RouteError();
+  return provider;
+}

package/src/review/schema-fallback.mjs

@@ -1,5 +1,6 @@
 /**
- * The second-level retry after repeated `schema` misses on ONE packet (block B55, issue #2).
+ * The second-level retry after two broken results on ONE packet (block B55, issue #2): `schema`
+ * misses and, since B91, timed-out attempts, in any mix.
  *
  * Field data: one L2 reviewer model answered `unavailable: schema` four times in a row on the same
  * packet (round 1, its retry, a patch_check recheck, a fresh review), while the model configured in
@@ -13,8 +14,7 @@
  * `history`, which only counts rows whose MAC verifies) plus the miss in hand. In practice: the
  * round's first session is miss 1; the worker's existing retry of that round (`next: retry`, the
  * next ticket re-runs the SAME packet) is miss 2, and that ticket then tries the second level once.
- * A session that times out is retried first by `session-retry.mjs` and counts once, with its last
- * result; a `needs_file` round or a Markdown section is another packet text, so another count, and
+ * Each timed-out attempt counts too (B91, below); a `needs_file` round or a Markdown section is another packet text, so another count, and
  * so is a recheck whose pending set changed between tries (S1 `resolved` closed another finding,
  * so the open-findings list differs): a different packet starts its own count, by design.
  *
@@ -43,6 +43,19 @@
  * schema-side params, Ajv's message), for non-JSON the kind of parse error and its byte offset.
  * Text a model copies from the packet into a JSON string can never reach the ledger this way.
  *
+ * B91: a timed-out attempt is a broken result too. Every timed-out attempt of the level's own
+ * ladder leaves one signed `review.session_timeout` note with the packet's `packet_hash`
+ * (`session-retry.mjs`), so the count above is `review.schema_invalid` rows plus those notes
+ * (`second_level` not true) plus the miss in hand, schema and timeout in any mix. After each
+ * timed-out attempt `session-retry.mjs` asks {@link afterSchemaMiss} with `trigger: 'timeout'`:
+ * its note is already in the ledger (it IS the miss in hand, so nothing more is written or added),
+ * and at 2 the second level is tried in that same ticket instead of the same-model retry. The mark
+ * says which kind of broken result was the second one: `trigger: schema | timeout`; an old mark
+ * without `trigger` reads as `schema`. A note without `packet_hash` (written before B91), an
+ * unsigned note and a `second_level` note are read but never count. With no second level nothing
+ * is tried and no mark is written: the timeout is retried once on the same model as before, its
+ * note now carrying `packet_hash` and signed.
+ *
  * Concurrency: the worker never runs two tickets for one (block, file) at once (its file lock,
  * `worker/loop.mjs`), and round 1, its retry, every recheck and the patch_check of a file are all
  * tickets for that file, so one packet's history is read and written by one ticket at a time. The
@@ -61,7 +74,7 @@ import { logWarning } from '../util/error-log.mjs';
 import { keyedLock } from '../util/locks.mjs';
 import { schemaErrorsOf } from './validate-review.mjs';
 
-/** Schema misses of the level's own ladder on one packet before the second level is tried. */
+/** Broken results (B91: schema misses and timeouts) of the level's own ladder on one packet before the second level is tried. */
 export const SCHEMA_FAILURES_BEFORE_FALLBACK = 2;
 
 /** At most this many schema errors are kept in a diagnosis (`errors_total` has the full count). */
@@ -78,8 +91,9 @@ const KEPT_PARAMS = Object.freeze(['missingProperty', 'additionalProperty', 'typ
 /**
  * @typedef {(packetHash: string, who: {level: string, role: string}) => Promise<{failures: number, fellBack: boolean}>} SchemaHistory -
  *   the signed history of ONE packet (`packetHash`) at one level and role in this run for this
- *   file at this content hash: `failures` = `review.schema_invalid` rows of the level's own ladder
- *   (`second_level` not true), `fellBack` = a `review.schema_fallback` row exists. Built by the
+ *   file at this content hash: `failures` = `review.schema_invalid` and (B91)
+ *   `review.session_timeout` rows of the level's own ladder (`second_level` not true),
+ *   `fellBack` = a `review.schema_fallback` row exists. Built by the
  *   worker; absent ⇒ no second-level try.
  */
 
@@ -218,8 +232,24 @@ export function secondLevelFor(cfg, level, from, role) {
 }
 
 /**
- * Log a schema miss and, when it is the packet's second (see the module doc), try the second level
- * once. Never throws (see the module doc).
+ * Whether a {@link secondLevelFor} answer says no second level is configured (a `same-model` or
+ * `closed-book` refusal is a configured level that cannot run: its mark is still written).
+ * @param {ReturnType<typeof secondLevelFor>} second @returns {boolean}
+ */
+function noSecondLevel(second) {
+  return second.ok === false && second.reason === 'no-second-level';
+}
+
+/** @param {Record<string, any>} row @returns {'schema' | 'timeout'} what a mark says the second broken result was; an old mark without `trigger` is `schema`. */
+export function fallbackTrigger(row) {
+  return row?.trigger === 'timeout' ? 'timeout' : 'schema';
+}
+
+/**
+ * Log a schema miss and, when it is the packet's second broken result (see the module doc), try the
+ * second level once. B91: `trigger: 'timeout'` is a timed-out attempt whose signed note is already
+ * written (nothing more is logged, and the history already counts it). Never throws (see the
+ * module doc).
  * @param {object} p
  * @param {Record<string, any> | null} p.res - the missed session's result.
  * @param {{lens: string, role: string, level: string}} p.session
@@ -229,21 +259,41 @@ export function secondLevelFor(cfg, level, from, role) {
  * @param {SchemaHistory | undefined} p.history
  * @param {((row: Record<string, any>) => Promise<unknown>) | undefined} p.writeRow - throws on a
  *   failed write; absent ⇒ nothing is logged or tried.
- * @param {(cfg: Record<string, any>) => Promise<{res: Record<string, any> | null, attempts: number}>} p.spawnAt
- *   - the same session on the same packet with another config (timeout retry included).
+ * @param {(cfg: Record<string, any>, to: {level: string, provider: string, model: string}) => Promise<{res: Record<string, any> | null, attempts: number}>} p.spawnAt
+ *   - the same session on the same packet with another config (timeout retry included); `to`
+ *   says which second level it is (called only after the mark row was written).
+ * @param {'schema' | 'timeout'} [p.trigger] - B91: the kind of the miss in hand (default `schema`).
  * @returns {Promise<{res: Record<string, any> | null, attempts: number, to: {level: string, provider: string, model: string}} | null>}
  *   the second level's result, or null when none was spawned.
  */
-export async function afterSchemaMiss({ res, session, packetText, cfg, allowed, history, writeRow, spawnAt }) {
+export async function afterSchemaMiss({ res, session, packetText, cfg, allowed, history, writeRow, spawnAt, trigger = 'schema' }) {
   if (!writeRow) return null;
+  const timedOut = trigger === 'timeout';
+  // a timeout's note is written by the retry helper: where no try can be made there is nothing to
+  // do — no history read, no row (B91: with no second level a timeout runs exactly as before B30)
+  if (timedOut && (!allowed || !history)) return null;
   const write = writeRow;
   const hash = packetHash(packetText);
   const from = { provider: typeof res?.provider === 'string' ? res.provider : null, model: typeof res?.model === 'string' ? res.model : null };
+  if (timedOut && (from.provider === null || from.model === null)) {
+    // B91: a timed-out result may lack its model; it is the level's resolved one (what was spawned)
+    try {
+      const resolved = resolveLevel(cfg, /** @type {any} */ (session.level));
+      from.provider = from.provider ?? resolved.provider;
+      from.model = from.model ?? resolved.model;
+    } catch {
+      // an unresolvable level: the mark keeps null (the spawn itself could not have resolved it)
+    }
+  }
+  // no second level for a timeout: nothing read, nothing written. Asked with the SAME arguments as
+  // the decision below (cfg, level, from, role), so this guard can never disagree with it
+  if (timedOut && noSecondLevel(secondLevelFor(cfg, session.level, from, session.role))) return null;
   /** @type {{cfg: Record<string, any>, to: {level: string, provider: string, model: string}} | null} */
   let go = null;
   try {
     go = await keyedLock(`schema-fallback\0${hash}\0${session.level}\0${session.role}`, async () => {
-      // the history is read BEFORE this miss is logged: failures = signed earlier misses + this one
+      // the history is read BEFORE a schema miss is logged: failures = signed earlier misses + this
+      // one. A timeout's note is already in it (B91): it is the miss in hand, never added twice.
       let seen = null;
       if (allowed && history) {
         try {
@@ -253,18 +303,21 @@ export async function afterSchemaMiss({ res, session, packetText, cfg, allowed,
           await logWarning({ warning: 'review_schema_history', message: 'the schema-miss history could not be read; no second-level try' }).catch(() => null);
         }
       }
-      try {
-        await write({ event: 'review.schema_invalid', lens: session.lens, role: session.role, level: session.level, ...from, fallback_step: res?.fallback_step ?? 0, packet_hash: hash, second_level: false, ...diagnoseAnswer(res) });
-      } catch {
-        // the log is best-effort; the count then misses this one (fewer tries, never more)
+      if (!timedOut) {
+        try {
+          await write({ event: 'review.schema_invalid', lens: session.lens, role: session.role, level: session.level, ...from, fallback_step: res?.fallback_step ?? 0, packet_hash: hash, second_level: false, ...diagnoseAnswer(res) });
+        } catch {
+          // the log is best-effort; the count then misses this one (fewer tries, never more)
+        }
       }
-      if (!seen || seen.fellBack || seen.failures + 1 < SCHEMA_FAILURES_BEFORE_FALLBACK) return null;
+      const broken = seen ? seen.failures + (timedOut ? 0 : 1) : 0;
+      if (!seen || seen.fellBack || broken < SCHEMA_FAILURES_BEFORE_FALLBACK) return null;
       const second = secondLevelFor(cfg, session.level, from, session.role);
       const to = `review.second_levels.${session.level}`;
       /** @type {string | null} */
       let refused = null;
       if (second.ok === false) {
-        if (second.reason === 'no-second-level') return null;
+        if (noSecondLevel(second)) return null;
         refused = second.reason; // `same-model` or `closed-book`: nothing of the level may run
       }
       await write({
@@ -278,7 +331,8 @@ export async function afterSchemaMiss({ res, session, packetText, cfg, allowed,
         to,
         to_provider: second.ok ? second.provider : null,
         to_model: second.ok ? second.model : null,
-        attempts: seen.failures + 1,
+        attempts: broken,
+        trigger,
         ...(refused ? { refused } : {}),
       }); // the once-per-packet mark: a failed write throws ⇒ no try
       return !second.ok ? null : { cfg: second.cfg, to: { level: to, provider: second.provider, model: second.model } };
@@ -287,9 +341,9 @@ export async function afterSchemaMiss({ res, session, packetText, cfg, allowed,
     return null;
   }
   if (!go) return null;
-  await logWarning({ warning: 'review_schema_fallback', message: 'a review answer failed the schema twice on one packet; the second level was tried once' }).catch(() => null);
+  await logWarning({ warning: 'review_schema_fallback', message: 'a review broke twice on one packet (schema or timeout); the second level was tried once' }).catch(() => null);
   try {
-    const out = await spawnAt(go.cfg);
+    const out = await spawnAt(go.cfg, go.to);
     return { res: out.res, attempts: out.attempts, to: go.to };
   } catch {
     // a throwing spawn is a session with no result: `exit` through the stub guard, never approval
@@ -326,6 +380,7 @@ export async function logSecondLevelMiss({ res, session, packetText, writeRow })
  * about, rows of `runId` for `file` at `contentHash` with that `packet_hash`, `level` and `role`
  * whose MAC verifies (`verify`; a row that does not verify, or whose check throws, counts for
  * nothing). A miss on another packet of the same content, or at another level, never counts.
+ * B91: a signed `review.session_timeout` note with that `packet_hash` counts like a schema miss.
  * @param {{readRows: () => Promise<Array<Record<string, any>>>, verify: (row: Record<string, any>) => boolean, runId: string, file: string, contentHash: string}} opts
  * @returns {SchemaHistory}
  */
@@ -335,7 +390,7 @@ export function ledgerSchemaHistory({ readRows, verify, runId, file, contentHash
     let failures = 0;
     let fellBack = false;
     for (const r of rows) {
-      if (r.event !== 'review.schema_invalid' && r.event !== 'review.schema_fallback') continue;
+      if (r.event !== 'review.schema_invalid' && r.event !== 'review.session_timeout' && r.event !== 'review.schema_fallback') continue;
       let ok = false;
       try {
         ok = verify(r);

package/src/review/session-retry.mjs

@@ -9,11 +9,26 @@
  *
  * 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.
+ * model, attempt, retried, duration_ms, stderr_tail, tail_note?, stdout_bytes, stdout_events,
+ * packet_hash?, second_level?}`: 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. A throwing spawn is returned as `res: null` and
+ * a failed note is ignored; the helper throws only when `onBroken` throws (B91: rethrown, never
+ * followed by the same-model retry — the caller turns it into a non-approval). `onAttempt(n)` is told each attempt as it
+ * starts.
+ *
+ * B91: a timed-out attempt is a BROKEN result, like a schema miss. The caller passes the packet's
+ * hash (`packetHash`, sha256 of the packet text): every note then carries `packet_hash`, so the
+ * worker's signed history (`ledgerSchemaHistory`) counts it for that packet, level and role. In the
+ * worker every note goes through its ledger writer, which signs it with the run key. A session of
+ * the second-level try itself passes `secondLevel: true`: its notes say `second_level: true` and
+ * never count. `onBroken(res)` (never used on a second-level try) is asked after each timed-out
+ * attempt's note is written: null ⇒ the B30 flow goes on unchanged (retry once, then give up); a
+ * result ⇒ the packet's second broken result started the B55 second-level try
+ * (`schema-fallback.mjs`, `trigger: timeout`) and its outcome is the session's:
+ * `{res, attempts: n + its attempts, to, broken}` (`broken`: the timed-out result it replaced, for
+ * the token sum). The note's `retried` keeps its B30 meaning (the same-model retry was due); the
+ * `review.schema_fallback` row written after it says the second level ran instead.
  */
 
 import { logWarning } from '../util/error-log.mjs';
@@ -21,15 +36,25 @@ import { logWarning } from '../util/error-log.mjs';
 /** How many times a timed-out session is spawned again. */
 export const TIMEOUT_RETRIES = 1;
 
+/**
+ * @typedef {{res: Record<string, any> | null, attempts: number, to: {level: string, provider: string, model: string}}} BrokenTry -
+ *   the outcome of a second-level try started by a timed-out attempt (`afterSchemaMiss`).
+ * @typedef {{packetHash?: string, secondLevel?: boolean, onBroken?: (res: Record<string, any>) => Promise<BrokenTry | null>}} BrokenOpts -
+ *   B91: the packet hash every note carries, whether this is the second-level try, and the
+ *   broken-result hook (see the module doc).
+ */
+
 /**
  * @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.
+ * @param {BrokenOpts} [broken] - B91 (absent ⇒ the B30 behaviour, notes without `packet_hash`).
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number, to?: BrokenTry['to'], broken?: Record<string, any>}>}
+ *   the last attempt's result (`null` when the spawn threw) and how many attempts ran; with `to`
+ *   (and `broken`) when a timed-out attempt started the second-level try.
  */
-export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () => {}) {
+export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () => {}, broken = {}) {
   let attempts = 0;
   for (;;) {
     attempts += 1;
@@ -58,9 +83,19 @@ export async function spawnWithTimeoutRetry(spawn, opts, note, onAttempt = () =>
         ...(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 : [],
+        ...(typeof broken.packetHash === 'string' ? { packet_hash: broken.packetHash } : {}),
+        ...(broken.secondLevel === true ? { second_level: true } : {}),
       });
     } catch {
-      // a failed note never stops the retry or the result
+      // a failed note never stops the retry or the result (the count then misses it: fewer tries)
+    }
+    if (broken.onBroken && broken.secondLevel !== true) {
+      // Contract: `onBroken` is called AFTER this attempt's note was written (or its write failed),
+      // so the hook's count already holds the attempt in hand and must not add it a second time.
+      // A hook that throws is rethrown, never followed by the B30 same-model retry: a second-level
+      // try may already have started, and the caller turns the throw into a non-approval.
+      const taken = await broken.onBroken(res);
+      if (taken) return { res: taken.res, attempts: attempts + taken.attempts, to: taken.to, broken: res };
     }
     if (!retried) return { res, attempts };
     // B37: the retry is a recoverable problem: one warning line in the local error log