@codedology/code-forge 0.9.0 → 0.10.0

package/src/proof/xcresult.mjs

@@ -0,0 +1,285 @@
+/**
+ * `xcresult` (red-green plan §1.6, B102): read the result bundle of an `xcodebuild test` run and
+ * classify the RED and GREEN steps of the `xcodebuild` runner adapter from it.
+ *
+ * The bundle is read with `xcrun xcresulttool get test-results tests --path <bundle>` (argv only,
+ * 60 s timeout, output capped at 8 MiB), and its JSON is mapped to the common `{tests}` shape of
+ * `junit.mjs`. The node shape is pinned by real captured output (Xcode 26.6, `test/fixtures/xcresult/`):
+ *
+ *   {testNodes: [Test Plan → Unit test bundle | UI test bundle → Test Suite (→ Test Suite)…
+ *                → Test Case → Failure Message]}
+ *
+ * A Test Case carries `nodeIdentifier` (`ClampXCTests/testCapsHigh()` for XCTest,
+ * `ClampSwiftTests/capsHigh()` for Swift Testing) and `result` (`Passed`, `Failed`, `Skipped`). Its
+ * id is `<bundle name>/<nodeIdentifier>`, e.g. `KitTests/ClampXCTests/testCapsHigh()`. A Test Plan
+ * with no children (a filter that selected nothing) is zero tests.
+ *
+ * Fail closed: no bundle, a bundle that is not a real directory, a failed or timed-out
+ * `xcresulttool`, output over 8 MiB, JSON that does not parse, two tests with the same id, and a
+ * failed check of what this reader uses make the result unreadable. It checks every node's
+ * `nodeType` (a known type) and its parent type (a known place), a Test Case's `result` (a known
+ * result) and `nodeIdentifier` (a non-empty string), a bundle's `name` (non-empty, no `/`), a
+ * Failure Message's `name` (a string, no children) and every `children` (a list). Any other key of a
+ * node or of the document (`devices`, `testPlanConfigurations`, `duration`, …) is not read and is
+ * ignored. An unreadable result never proves anything (RED is `RED_INVALID error`, GREEN is
+ * `NOT_GREEN`). Today
+ * that includes these xcresulttool node types: a parameterized Swift Testing test (`Arguments`),
+ * repetitions (`Repetition`, `Test Case Run`), a multi-destination or multi-configuration run
+ * (`Device`, `Test Plan Configuration`), `Runtime Warning`, `Source Code Reference`, `Attachment`,
+ * `Expression`, `Test Value`, and the result `Expected Failure`.
+ *
+ * A Failure Message (`<file>.swift:<line>: <text>`, the prefix optional) is an assertion only for
+ * these texts, as captured: `XCTAssert… failed` (but not `XCTAssert… failed: threw error`, a thrown
+ * error inside the assertion), XCTFail's `failed` and `failed - <message>`, and Swift Testing's
+ * `Expectation failed: …`. Every other text is an error: a thrown error (`failed: caught error: …`,
+ * `Caught error: …`), `Issue recorded: …`, a crash. A failed test is an assertion only when every
+ * one of its messages is one.
+ */
+
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+import { MAX_REPORT_BYTES, NO_REPORT, classifyGreen, classifyReport, swiftCompileError } from './junit.mjs';
+
+/** `xcresulttool` may run this long before it is stopped. */
+export const XCRESULTTOOL_TIMEOUT_MS = 60_000;
+
+/** Which parent node type each known node type may have (`null` = the `testNodes` list). */
+const NODE_PARENTS = Object.freeze({
+  'Test Plan': [null],
+  'Unit test bundle': ['Test Plan'],
+  'UI test bundle': ['Test Plan'],
+  'Test Suite': ['Unit test bundle', 'UI test bundle', 'Test Suite'],
+  'Test Case': ['Test Suite'],
+  'Failure Message': ['Test Case'],
+});
+
+/** A Test Case `result` this reader knows, and its common status. */
+const RESULT_STATUS = Object.freeze({ Passed: 'passed', Failed: 'failed', Skipped: 'skipped' });
+
+/** The optional `<file>.swift:<line>: ` prefix of a Failure Message. */
+const MESSAGE_PREFIX = /^[^\n:]+\.swift:\d+: /;
+/** The assertion texts, after the prefix (see the header). */
+const ASSERTION_MESSAGES = Object.freeze([/^XCTAssert\w* failed(?!: threw error)/, /^failed - /, /^failed$/, /^Expectation failed: /]);
+
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+/** `xcodebuild`'s own build-failure lines (`** BUILD FAILED **`, `** TEST BUILD FAILED **`). */
+const BUILD_FAILED_LINE = /^\*\* (?:TEST )?BUILD FAILED \*\*[ \t\r]*$/m;
+/** `xcodebuild test` (Xcode 26.6) on a test that does not compile prints this line, tab-indented, then `** TEST FAILED **`. */
+const BUILD_CANCELLED_LINE = /^[ \t]*Testing cancelled because the build failed\.[ \t\r]*$/m;
+
+/** @param {string} reason @returns {never} */
+function unreadable(reason) {
+  const err = new Error(`report-unreadable: ${reason}`);
+  /** @type {any} */ (err).code = 'report-unreadable';
+  throw err;
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Is a Failure Message text an assertion failure?
+ * @param {string} text @returns {'assertion' | 'error'}
+ */
+export function failureMessageKind(text) {
+  const rest = String(text).replace(MESSAGE_PREFIX, '');
+  return ASSERTION_MESSAGES.some((p) => p.test(rest)) ? 'assertion' : 'error';
+}
+
+/**
+ * Read `xcresulttool get test-results tests` JSON.
+ * @param {string} text
+ * @returns {{tests: import('./junit.mjs').ReportTest[]}}
+ * @throws {Error} `code: 'report-unreadable'`; the message names the reason only, never content.
+ */
+export function readXcresult(text) {
+  if (typeof text !== 'string') unreadable('the xcresulttool output is not text');
+  if (Buffer.byteLength(text, 'utf8') > MAX_REPORT_BYTES) unreadable('the xcresulttool output is over 8 MiB');
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    unreadable('the xcresulttool output is not JSON');
+  }
+  if (!isObject(doc) || !Array.isArray(doc.testNodes)) unreadable('the xcresulttool output has no testNodes list');
+
+  /** @type {import('./junit.mjs').ReportTest[]} */
+  const tests = [];
+  const seen = new Set();
+  /** @param {unknown} node @param {string | null} parent @param {string | null} bundle */
+  const walk = (node, parent, bundle) => {
+    if (!isObject(node)) unreadable('a test node that is not an object');
+    const type = node.nodeType;
+    if (typeof type !== 'string' || !Object.hasOwn(NODE_PARENTS, type)) unreadable('a node type this reader does not know');
+    if (!NODE_PARENTS[/** @type {keyof typeof NODE_PARENTS} */ (type)].includes(/** @type {any} */ (parent))) unreadable('a test node in the wrong place');
+    const children = node.children ?? [];
+    if (!Array.isArray(children)) unreadable('test node children that are not a list');
+    if (type === 'Failure Message') {
+      if (typeof node.name !== 'string') unreadable('a failure message without a text');
+      if (children.length > 0) unreadable('a failure message with children');
+      return;
+    }
+    let inBundle = bundle;
+    if (type === 'Unit test bundle' || type === 'UI test bundle') {
+      if (typeof node.name !== 'string' || node.name === '' || node.name.includes('/')) unreadable('a test bundle without a name');
+      inBundle = node.name;
+    }
+    if (type === 'Test Case') {
+      const ident = node.nodeIdentifier;
+      if (typeof ident !== 'string' || ident === '') unreadable('a test case without a nodeIdentifier');
+      const result = node.result;
+      if (typeof result !== 'string' || !Object.hasOwn(RESULT_STATUS, result)) unreadable('a test result this reader does not know');
+      const status = RESULT_STATUS[/** @type {keyof typeof RESULT_STATUS} */ (result)];
+      const kinds = children.map((child) => {
+        walk(child, 'Test Case', inBundle);
+        return failureMessageKind(/** @type {any} */ (child).name);
+      });
+      const id = `${inBundle}/${ident}`;
+      // one id twice (two bundles of one name, a repeated node) would let one result hide the other
+      if (seen.has(id)) unreadable('two test cases with the same id');
+      seen.add(id);
+      if (status === 'failed') tests.push({ id, status, kind: kinds.length > 0 && kinds.every((k) => k === 'assertion') ? 'assertion' : 'error' });
+      else if (kinds.length > 0) unreadable('a failure message on a test that did not fail');
+      else tests.push({ id, status });
+      return;
+    }
+    for (const child of children) walk(child, type, inBundle);
+  };
+  for (const node of doc.testNodes) walk(node, null, null);
+  return { tests };
+}
+
+/**
+ * `readXcresult` that never throws.
+ * @param {string} text @returns {import('./junit.mjs').ReportResult}
+ */
+export function parseXcresult(text) {
+  try {
+    return readXcresult(text);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : '';
+    return { unreadable: message.startsWith('report-unreadable: ') ? message.slice('report-unreadable: '.length) : 'the result bundle could not be read' };
+  }
+}
+
+/**
+ * Read a result bundle with `xcresulttool`. Never throws. No bundle at the path is `NO_REPORT`; a
+ * symlink or any other non-directory is unreadable. A relative `bundle` is resolved against `cwd`
+ * once, and that one absolute path is both checked and read.
+ * @param {string} bundle @param {{cwd: string, env: NodeJS.ProcessEnv, timeoutMs?: number}} opts
+ * @returns {Promise<import('./junit.mjs').ReportResult>}
+ */
+export async function loadXcresult(bundle, { cwd, env, timeoutMs = XCRESULTTOOL_TIMEOUT_MS }) {
+  const target = path.resolve(cwd, bundle);
+  let st;
+  try {
+    st = await lstat(target);
+  } catch (err) {
+    return /** @type {any} */ (err)?.code === 'ENOENT' ? NO_REPORT : { unreadable: 'the result bundle could not be opened' };
+  }
+  if (!st.isDirectory()) return { unreadable: 'the result bundle is not a directory' };
+  try {
+    const res = await exec(['xcrun', 'xcresulttool', 'get', 'test-results', 'tests', '--path', target], { cwd, env, timeoutMs, maxBufferBytes: MAX_REPORT_BYTES + 1 });
+    if (res.result !== 'ok' || res.code !== 0 || res.signal || res.timedOut) return { unreadable: 'xcresulttool failed' };
+    return parseXcresult(res.stdout);
+  } catch {
+    return { unreadable: 'xcresulttool failed' };
+  }
+}
+
+/**
+ * Does the console text show that the test build failed? Colours are stripped first.
+ * @param {string} text @returns {boolean}
+ */
+export function xcodeBuildFailed(text) {
+  const plain = String(text).replace(ANSI, '');
+  return BUILD_FAILED_LINE.test(plain) || BUILD_CANCELLED_LINE.test(plain);
+}
+
+/** @param {import('./junit.mjs').RunResult} run @returns {boolean} */
+const exitedClean = (run) => run.code === 0 && !run.signal && !run.timedOut;
+
+/**
+ * A scope is `<test_target>/<Suite>/`: two non-empty parts and the closing `/`. Without the `/`,
+ * `KitTests/Clamp` would also admit `KitTests/ClampMore/…`, so any other scope throws (the callers
+ * then classify fail closed).
+ * @param {unknown} scope @returns {asserts scope is string}
+ */
+function checkScope(scope) {
+  if (typeof scope !== 'string' || !/^[^/]+\/[^/]+\/$/.test(scope)) throw new Error('an xcodebuild scope is <test_target>/<Suite>/');
+}
+
+/**
+ * Is any test of a readable result outside `scope` (`<test_target>/<Suite>/`)?
+ * @param {import('./junit.mjs').ReportResult} report @param {string} scope @returns {boolean}
+ * @throws {Error} a scope that is not `<test_target>/<Suite>/`
+ */
+const ranOtherTests = (report, scope) => {
+  checkScope(scope);
+  return 'tests' in report && report.tests.some((t) => !t.id.startsWith(scope));
+};
+
+/**
+ * Classify the RED step of an `xcodebuild` run. Never throws. A `scope` that is not
+ * `<test_target>/<Suite>/` is `RED_INVALID error`. Then the first row that applies wins:
+ *   - exit 0 and no readable result (no bundle, or an unreadable one) ⇒ `RED_INVALID error`: a clean
+ *     exit with nothing to read says nothing about the test;
+ *   - exit 0 and a readable result with a test outside `scope` (or only such tests) ⇒
+ *     `RED_INVALID error` (the filter ran other tests): the test under proof did not run cleanly
+ *     in scope, so a passing run is not `NOT_RED`;
+ *   - exit 0 and a readable result with no test that ran ⇒ `RED_INVALID error` (the filter ran no
+ *     test). This differs from `junit` and `swift`, where `classifyReport` reads any exit 0 as
+ *     `NOT_RED`: `xcodebuild test` exits 0 when `-only-testing` selects nothing (a Swift Testing id
+ *     without its `()`), so an empty run says nothing about the test and must not read as "it passed";
+ *   - exit 0 otherwise ⇒ `NOT_RED`; a timeout or a signal ⇒ `RED_INVALID fatal`;
+ *   - a failed run whose console shows a build failure, or that has no tests and a `swiftc` error
+ *     ⇒ `RED_INVALID compile`;
+ *   - a test outside `scope` ⇒ `RED_INVALID error` (the filter ran other tests);
+ *   - else `classifyReport` (§1.1).
+ * Every invalid row this adds carries no failed data.
+ * @param {{run: import('./junit.mjs').RunResult, report: import('./junit.mjs').ReportResult, scope: string}} input
+ * @returns {import('./junit.mjs').JUnitRedParse}
+ */
+export function classifyXcodeRed({ run, report, scope }) {
+  try {
+    checkScope(scope);
+    const base = classifyReport({ run, reports: [report], compileError: swiftCompileError });
+    /** @param {'compile' | 'error'} red_kind @param {string} reason @returns {import('./junit.mjs').JUnitRedParse} */
+    const invalid = (red_kind, reason) => ({ ...base, verdict: 'RED_INVALID', red_kind, failed: null, failed_tests: [], failed_ids: [], reason });
+    const readable = isObject(report) && Array.isArray(/** @type {any} */ (report).tests);
+    if (exitedClean(run)) {
+      if (!readable) return invalid('error', 'no readable test result');
+      if (readable && ranOtherTests(report, scope)) return invalid('error', 'the filter ran other tests');
+      if (readable && !(/** @type {any} */ (report).tests.some((/** @type {any} */ t) => t.status !== 'skipped'))) return invalid('error', 'the filter ran no test');
+      return base;
+    }
+    if (run.timedOut || run.signal) return base;
+    const output = `${run.stdout ?? ''}\n${run.stderr ?? ''}`;
+    if (xcodeBuildFailed(output)) return invalid('compile', 'the test did not build');
+    const noTests = report === NO_REPORT || (readable && /** @type {any} */ (report).tests.length === 0);
+    if (noTests && swiftCompileError(output)) return invalid('compile', 'the test did not compile');
+    if (readable && ranOtherTests(report, scope)) return invalid('error', 'the filter ran other tests');
+    return base;
+  } catch {
+    return { verdict: 'RED_INVALID', red_kind: 'error', framework: 'junit', failed: null, failed_tests: [], failed_ids: [], reason: 'no readable test result' };
+  }
+}
+
+/**
+ * Classify the GREEN step of an `xcodebuild` run: `classifyGreen`, and `NOT_GREEN` when the result
+ * has a test outside `scope`. Never throws.
+ * @param {{run: import('./junit.mjs').RunResult, report: import('./junit.mjs').ReportResult, redFailed: string[], scope: string}} input
+ * @returns {import('./junit.mjs').JUnitGreenParse}
+ */
+export function classifyXcodeGreen({ run, report, redFailed, scope }) {
+  try {
+    checkScope(scope);
+    const base = classifyGreen({ run, reports: [report], redFailed });
+    if (base.verdict === 'GREEN' && ranOtherTests(report, scope)) return { ...base, verdict: 'NOT_GREEN', reason: 'the filter ran other tests' };
+    return base;
+  } catch {
+    return { verdict: 'NOT_GREEN', failed: null, failed_tests: [], reason: 'no readable test result' };
+  }
+}

package/src/review/engine.mjs

@@ -19,9 +19,12 @@
  *     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;
+ *     `attempts` says how many ran. B91: a timed-out attempt is a broken result like a schema
+ *     miss: its signed `review.session_timeout` note carries the packet's `packet_hash`, and when
+ *     it is the packet's second broken result (schema or timeout, in any mix) the second level
+ *     (6b) is tried in the same session instead of the same-model retry (`trigger: timeout`);
  *  6b. a session whose answer fails the schema logs it (`review.schema_invalid`, the raw answer
- *     redacted); at the packet's second such miss it is tried ONCE on `review.second_levels.<level>`
+ *     redacted); at the packet's second broken result it is tried ONCE on `review.second_levels.<level>`
  *     when the owner configured one (`schema-fallback.mjs`, B55; never in consensus mode).
  *     The summary then carries `schema_fallback: {level, provider, model}` (`level`:
  *     `review.second_levels.<level>`), the second level's own provider/model, and `tokens_in` /
@@ -43,6 +46,11 @@
  *  9. a pure deletion (the file is gone from the reviewed tree) gets a `## deleted file` note in
  *     every packet — reviewers and judge — naming up to 20 tree paths that still name its basename
  *     (`deletion.mjs`, B74). It is a hint, never an exemption: the deletion still needs approval.
+ * 10. a test file that reads a source file and asserts on its text gets a `## test-quality` note in
+ *     every packet — reviewers and judge — naming up to 10 line numbers, never the file's text
+ *     (`test-quality.mjs`, B92). It is a hint, never a finding: the lens tells the reviewer to
+ *     raise it as a `warning` unless the read file is a fixture. It is extra text like the
+ *     moved code (after it), counted in the same measure; no flag ⇒ no section, no row.
  * 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.
@@ -59,10 +67,11 @@ import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
 import { deletionNote, renderDeletionNote } from './deletion.mjs';
+import { testQualityNote } from './test-quality.mjs';
 import { isMarkdownFile, packSections, sectionFindings, sectionGroups } from './sections.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
-import { afterSchemaMiss, logSecondLevelMiss } from './schema-fallback.mjs';
+import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallback.mjs';
 import { assertRowPath } from '../worker/ticket.mjs';
 
 /**
@@ -253,8 +262,11 @@ export async function reviewFile(input, deps) {
       deleted = renderDeletionNote(diff.file, { status: 'not_checked', paths: [], more: 0 }); // the review goes on
     }
   }
+  // B92: a test that reads a source file and asserts on its text gets the `## test-quality` hint
+  // (line numbers only), read once from the current content; '' for none
+  const quality = testQualityNote(diff.file, diff.content);
   /** @param {ReadonlyArray<number> | null} keys - a Markdown section's group keys; null ⇒ the whole file. */
-  const movedOf = (keys) => [deleted, movedText(moves, diff.content, keys)].filter((t) => typeof t === 'string' && t.length > 0).join('\n');
+  const movedOf = (keys) => [deleted, movedText(moves, diff.content, keys), quality].filter((t) => typeof t === 'string' && t.length > 0).join('\n');
   const min = minTokensOut(cfg);
   // B55: never in consensus mode — its providers (two reviewers, the judge) are the check itself
   const schemaFallback = plan.mode !== 'consensus';
@@ -383,8 +395,9 @@ export async function reviewFile(input, deps) {
 }
 
 /**
- * One session: packet file (0600, removed after), spawn, stub guard — and, on a `schema` miss, the
- * B55 second-level try (`schema-fallback.mjs`) on the same packet file before it is removed.
+ * One session: packet file (0600, removed after), spawn, stub guard — and, on a `schema` miss or
+ * (B91) a timed-out attempt, the B55 second-level try (`schema-fallback.mjs`) on the same packet
+ * file before it is removed.
  * @param {SessionSpec} spec @param {string} text
  * @param {{hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet
  * @param {{deps: ReviewDeps, workDir: string, min: number, cfg: Record<string, any>, schemaFallback?: boolean}} env -
@@ -401,10 +414,39 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
   let verdict = { ok: false, reason: 'exit', detail: 'no session result' };
   /** @type {{level: string, provider: string, model: string} | null} */
   let fellBackTo = null;
-  /** @param {Record<string, any> | undefined} sessionCfg @param {number} done - attempts before this call. */
-  const attempt = (sessionCfg, done) =>
+  const session = { lens: spec.lens, role: spec.role, level: spec.level };
+  // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
+  // (each helper handles its own failed write)
+  const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<ReviewDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
+  const hash = packetHash(text);
+  /** @type {{level: string, provider: string, model: string} | null} the second level once its try started */
+  let tried = null;
+  /** @param {Record<string, any> | null} missed @param {'schema' | 'timeout'} trigger */
+  const tryNext = (missed, trigger) =>
+    afterSchemaMiss({
+      res: missed,
+      session,
+      packetText: text,
+      cfg: spec.cfg ?? cfg,
+      allowed: schemaFallback && !spec.cfg,
+      history: deps.schemaHistory,
+      writeRow: write,
+      // the second level's attempts follow the ones already run in this session
+      spawnAt: (c, to) => {
+        tried = to; // the try started: whatever happens next, the session fell back
+        return attempt(c, attempts, true);
+      },
+      trigger,
+    });
+  /**
+   * @param {Record<string, any> | undefined} sessionCfg @param {number} done - attempts before this call.
+   * @param {boolean} [secondLevel] - B91: the second-level try (its timeouts never count, never try again).
+   * @returns {ReturnType<typeof spawnWithTimeoutRetry>}
+   */
+  const attempt = (sessionCfg, done, secondLevel = false) =>
     // 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
+    // (bad config, refused argv) is an `exit` failure, never approval. B91: each timed-out attempt
+    // is a broken result of this packet; the second one tries the second level instead
     spawnWithTimeoutRetry(
       deps.spawn,
       {
@@ -419,6 +461,7 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
       (n) => {
         attempts = done + n;
       },
+      { packetHash: hash, secondLevel, ...(secondLevel ? {} : { onBroken: (/** @type {Record<string, any>} */ r) => tryNext(r, 'timeout') }) },
     );
   /** @type {number | null} the session's tokens: the first spawn's, plus a second-level try's */
   let tokensIn = null;
@@ -426,34 +469,42 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
   let tokensOut = null;
   // the packet file is removed on every path, and only after the second-level try (which reads it)
   try {
+    /** @type {Awaited<ReturnType<typeof spawnWithTimeoutRetry>> | null} */
+    let first = null;
     try {
-      ({ res, attempts } = await attempt(spec.cfg, 0));
+      first = await attempt(spec.cfg, 0);
+      ({ res, attempts } = first);
     } catch {
-      // 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).
+      // defensive only: the helpers never throw. If they ever did, it is still an `exit` failure,
+      // never approval, with the attempts reported so far (at least 1; a second-level try's spawns
+      // included) and, once that try started, its second level (never a same-model spawn after it).
       res = null;
       attempts = Math.max(attempts, 1);
+      fellBackTo = tried;
+    }
+    if (first?.to) {
+      // B91: a timed-out attempt was the packet's second broken result; the second level ran and
+      // `attempts` already counts its spawns. The verdict is set first: whatever throws after it
+      // leaves that verdict (a failed one stays a non-approval), never an exception
+      fellBackTo = first.to;
+      verdict = { ok: false, reason: 'exit', detail: 'second-level result not checked' };
+      try {
+        verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+        tokensIn = addTokens(first.broken?.usage?.tokens_in ?? null, res?.usage?.tokens_in);
+        tokensOut = addTokens(first.broken?.usage?.tokens_out ?? null, res?.usage?.tokens_out);
+        if (!verdict.ok && verdict.reason === 'schema') await logSecondLevelMiss({ res, session, packetText: text, writeRow: write });
+      } catch {
+        // defensive only, as on the schema path below
+      }
+    } else {
+      tokensIn = res?.usage?.tokens_in ?? null;
+      tokensOut = res?.usage?.tokens_out ?? null;
+      verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
     }
-    tokensIn = res?.usage?.tokens_in ?? null;
-    tokensOut = res?.usage?.tokens_out ?? null;
-    verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
-    if (!verdict.ok && verdict.reason === 'schema') {
+    if (!fellBackTo && !verdict.ok && verdict.reason === 'schema') {
       try {
-        const session = { lens: spec.lens, role: spec.role, level: spec.level };
         const done = attempts;
-        // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
-        // (each helper handles its own failed write)
-        const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<ReviewDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
-        const second = await afterSchemaMiss({
-          res,
-          session,
-          packetText: text,
-          cfg: spec.cfg ?? cfg,
-          allowed: schemaFallback && !spec.cfg,
-          history: deps.schemaHistory,
-          writeRow: write,
-          spawnAt: (c) => attempt(c, done),
-        });
+        const second = await tryNext(res, 'schema');
         if (second) {
           const secondVerdict = validateReview(second.res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
           res = second.res;
@@ -467,6 +518,7 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
       } catch {
         // defensive only: the helpers never throw. If they ever did, the first session's result
         // and its `schema` verdict stand (never turned into `exit`, never approval)
+        fellBackTo = fellBackTo ?? tried;
       }
     }
   } finally {

package/src/review/fixloop.mjs

@@ -97,7 +97,7 @@ import { isMarkdownFile, packSections, sectionFindings, sectionGroups, sectionOf
 import { cameFromJudge, resolvedBand, triageFindings } from './triage.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
-import { afterSchemaMiss, logSecondLevelMiss } from './schema-fallback.mjs';
+import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallback.mjs';
 
 /** @typedef {import('./triage.mjs').Finding} Finding */
 /** @typedef {import('./context.mjs').Hunk} Hunk */
@@ -431,8 +431,9 @@ export function insideHunks(f, hunks) {
 }
 
 /**
- * One recheck session through the stub guard — and, on a `schema` miss, the B55 second-level try
- * on the same packet (`schema-fallback.mjs`; rechecks and the patch_check alike).
+ * One recheck session through the stub guard — and, on a `schema` miss or (B91) a timed-out
+ * attempt that is the packet's second broken result, the B55 second-level try on the same packet
+ * (`schema-fallback.mjs`; rechecks and the patch_check alike).
  * @param {{text: string, hunkHeaders: string[], tokensIn: number, contextMode: string}} packet
  * @param {LoopDeps} deps
  */
@@ -442,14 +443,28 @@ async function recheckSession(packet, deps) {
   writeFileSync(promptPath, packet.text, { mode: 0o600 });
   const min = minTokensOut(deps.cfg);
   const session = { lens: 'recheck', role: 'reviewer', level: 'L2' };
-  /** @param {Record<string, any> | undefined} cfg */
+  // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
+  // (each helper handles its own failed write)
+  const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<LoopDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
+  const hash = packetHash(packet.text);
+  /** @param {Record<string, any> | null} missed @param {'schema' | 'timeout'} trigger */
+  const tryNext = (missed, trigger) =>
+    afterSchemaMiss({ res: missed, session, packetText: packet.text, cfg: deps.cfg ?? {}, allowed: true /* rechecks are never consensus; the budget gate is inside the spawn */, history: deps.schemaHistory, writeRow: write, spawnAt: attempt, trigger });
+  /**
+   * @param {Record<string, any> | undefined} cfg - set only for the second-level try (B91: its
+   *   timeouts never count and never try again).
+   * @returns {Promise<{res: Record<string, any> | null, attempts: number, to?: Record<string, any>, broken?: Record<string, any>}>}
+   */
   const attempt = async (cfg) =>
     deps.spawn
-      ? // a `timeout` is spawned once more on the same packet and level (B30)
+      ? // a `timeout` is spawned once more on the same packet and level (B30); B91: the packet's
+        // second broken result tries the second level instead
         spawnWithTimeoutRetry(
           deps.spawn,
           { level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn }, ...(cfg ? { cfg } : {}) },
           (row) => note(deps, row),
+          undefined,
+          cfg ? { packetHash: hash, secondLevel: true } : { packetHash: hash, onBroken: (r) => tryNext(r, 'timeout') },
         )
       : { res: null, attempts: 0 };
   /** @type {Record<string, any> | null} */
@@ -462,20 +477,37 @@ async function recheckSession(packet, deps) {
   let tokensOut = null;
   // the packet file is removed on every path, and only after the second-level try (which reads it)
   try {
+    /** @type {{res: Record<string, any> | null, attempts: number, to?: Record<string, any>, broken?: Record<string, any>} | null} */
+    let first = null;
     try {
-      res = (await attempt(undefined)).res;
+      first = await attempt(undefined);
+      res = first.res;
     } catch {
       res = null; // the helper never throws; if it ever did, it is still an `exit` failure
     }
-    tokensIn = res?.usage?.tokens_in ?? null;
-    tokensOut = res?.usage?.tokens_out ?? null;
     verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
-    if (!verdict.ok && verdict.reason === 'schema') {
+    if (first?.to) {
+      // B91: a timed-out attempt was the packet's second broken result; the second level ran. The
+      // verdict is already set: whatever throws after it leaves that verdict, never an exception
+      // the second level's miss is logged first, in its own try, so no sum error can skip it
       try {
-        // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
-        // (each helper handles its own failed write)
-        const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<LoopDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
-        const second = await afterSchemaMiss({ res, session, packetText: packet.text, cfg: deps.cfg ?? {}, allowed: true /* rechecks are never consensus; the budget gate is inside the spawn */, history: deps.schemaHistory, writeRow: write, spawnAt: attempt });
+        if (!verdict.ok && verdict.reason === 'schema') await logSecondLevelMiss({ res, session, packetText: packet.text, writeRow: write });
+      } catch {
+        // defensive only: the helper never throws; the verdict above stands (never approval)
+      }
+      try {
+        tokensIn = sum(first.broken?.usage?.tokens_in ?? null, res?.usage?.tokens_in);
+        tokensOut = sum(first.broken?.usage?.tokens_out ?? null, res?.usage?.tokens_out);
+      } catch {
+        // defensive only, as on the schema path below
+      }
+    } else {
+      tokensIn = res?.usage?.tokens_in ?? null;
+      tokensOut = res?.usage?.tokens_out ?? null;
+    }
+    if (!first?.to && !verdict.ok && verdict.reason === 'schema') {
+      try {
+        const second = await tryNext(res, 'schema');
         if (second) {
           // compute everything first, then assign together, so a throw never leaves a mixed state
           const secondVerdict = validateReview(second.res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });

package/src/review/gate-check.mjs

@@ -93,6 +93,7 @@ import { tierFor } from '../proof/tiers.mjs';
 import { DELETED_HASH, contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { verifyResult } from '../worker/queue.mjs';
 import { stopExitsLine } from './stop-exits.mjs';
+import { checkFileForm, checkFindingId } from './verb-forms.mjs';
 
 /**
  * @typedef {{file: string, content_hash: string, status: 'reviewed_by_waiver', findings: string[], by: 'human' | 'autopilot' | null, answered?: string[]}} WaivedAll
@@ -1055,10 +1056,10 @@ export function reviewGateCheck(load, { onWaivedAll } = {}) {
  * @returns {Promise<Record<string, any>>} the signed row.
  */
 export async function waiveFinding({ runId, id, finding, reason, file, writeRow }) {
-  if (typeof finding !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.test(finding)) throw new StateError('usage', 'a finding id is required (letters, digits, . _ : -)');
+  checkFindingId(finding);
   if (typeof reason !== 'string' || reason.trim().length === 0) throw new StateError('usage', 'block waive needs --reason');
   if (typeof file !== 'string' || file.length === 0) throw new StateError('usage', 'block waive needs --file <path>');
-  if (path.isAbsolute(file) || file.split('/').includes('..') || file.startsWith('./')) throw new StateError('usage', '--file must be repo-root-relative');
+  checkFileForm(file, { normalized: false });
   const record = await readRun(runId);
   if (!record.blocks?.[id]) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
   const row = { event: 'review.waived', block: id, file, finding, reason: reason.trim(), by: 'human' };

package/src/review/lenses/A.md

@@ -20,3 +20,4 @@ You work blind: you do not see the other reviewer's answer.
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/B.md

@@ -21,3 +21,4 @@ You work blind: you do not see the other reviewer's answer.
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/full.md

@@ -21,3 +21,4 @@ Report each real defect once, at the lines where it lives.
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/quick.md

@@ -19,3 +19,4 @@ Skip style, naming and structure unless it hides a bug. Keep `findings` short.
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/recheck.md

@@ -21,3 +21,4 @@ that changed since that round, each with a window of the current file around it.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order.
 - Answer with ONE JSON object that matches the answer schema.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.