@codedology/code-forge 0.9.0 → 0.11.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,14 +19,18 @@
  *     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` /
  *     `tokens_out` summed over both sessions;
- *  7. a diff alone over the packet budget is `split_required` (with `tokens_in` and `budget`) —
+ *  7. a non-Markdown quick packet over budget first steps up to one full L2 session (B109).
+ *     A diff alone still over the packet budget is `split_required` (with `tokens_in` and `budget`) —
  *     except a Markdown file (B54), which is reviewed SECTION BY SECTION (`sections.mjs`): every
  *     section packet runs the whole plan above (its own sessions, judge and stub guard, its own
  *     `review.plan` row with `section`), in file order, stopping at the first one that is not
@@ -43,6 +47,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.
@@ -56,14 +65,17 @@ import { blockKind, isDocsKind } from '../decide/escalation.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
 import { isMigrationPath, isPolicyPath } from '../decide/lane-facts.mjs';
 import { tierFor } from '../proof/tiers.mjs';
-import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
+import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, isSecretLike, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
 import { deletionNote, renderDeletionNote } from './deletion.mjs';
+import { testQualityNote } from './test-quality.mjs';
+import { pairsFor, summarize } from './paired.mjs';
+import { redact } from '../util/redact.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 { assertRowPath } from '../worker/ticket.mjs';
+import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallback.mjs';
+import { assertRowPath, readRegularFileNoFollow } from '../worker/ticket.mjs';
 
 /**
  * @typedef {{lens: 'quick' | 'full' | 'A' | 'B' | 'judge', role: 'reviewer' | 'judge', level: 'L2' | 'L3', slot: 'A' | 'B' | null, cfg?: Record<string, any>}} SessionSpec -
@@ -176,6 +188,9 @@ export function rulesRisk({ file, plusCount, cfg }) {
  *   code moved between this file and one of them is named in every packet (`## moved code`).
  * @property {() => Promise<import('./moved.mjs').PeerDiff[]>} [peerDiffs] - B56: a memoised reader
  *   of those files' diffs (`peerDiffReader`), shared by the caller across the round; wins over `peers`.
+ * @property {ReadonlyArray<string>} [ownedFiles] - concrete paths owned by this block.
+ * @property {ReadonlyArray<string>} [changedFiles] - concrete changed paths of the same block.
+ * @property {ReadonlyArray<string>} [testFiles] - the block's explicit test_files, regardless of stem.
  */
 
 /**
@@ -215,6 +230,31 @@ function safeNeeds(needs) {
   }
 }
 
+/**
+ * B98: names only, from owned changed peers and explicit tests in the reviewed tree.
+ * Missing, unsafe or unreadable pairs give no hint, never a failed review.
+ * @param {{repoRoot: string, file: string, peers?: ReadonlyArray<string>, ownedFiles?: ReadonlyArray<string>, changedFiles?: ReadonlyArray<string>, testFiles?: ReadonlyArray<string>}} input
+ * @returns {string}
+ */
+export function pairedContext({ repoRoot, file, peers = [], ownedFiles = [], changedFiles = peers, testFiles = [] }) {
+  if (ownedFiles.length === 0) return '';
+  const owned = new Set(ownedFiles);
+  const candidates = [...new Set([...pairsFor(file, changedFiles), ...testFiles])].filter((p) => p !== file && owned.has(p));
+  const lines = [];
+  for (const candidate of candidates) {
+    try {
+      const rel = assertRowPath(candidate);
+      if (isSecretLike(rel)) continue;
+      const bytes = readRegularFileNoFollow(repoRoot, rel);
+      if (bytes === null) continue;
+      lines.push(`- ${redact(rel)}`, ...summarize(bytes.toString('utf8'), rel).map((name) => `  - ${name}`));
+    } catch {
+      // The summary is optional; never follow a symlink or substitute another file.
+    }
+  }
+  return lines.join('\n');
+}
+
 /**
  * @param {ReviewInput} input @param {ReviewDeps} deps
  * @returns {Promise<{status: string, approved: boolean, engine: string, sessions: Array<Record<string, any>>} & Record<string, any>>}
@@ -225,8 +265,8 @@ export async function reviewFile(input, deps) {
   const risk = input.risk ?? rulesRisk({ file: diff.file, plusCount: diff.plusCount, 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 };
+  let plan = planSessions({ risk, cfg, kind });
+  let 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: [] };
   mkdirSync(workDir, { recursive: true, mode: 0o700 });
@@ -253,8 +293,12 @@ 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);
+  const paired = pairedContext(input);
   /** @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';
@@ -268,7 +312,7 @@ export async function reviewFile(input, deps) {
       const paths = safeNeeds(needs);
       let extra = null;
       try {
-        extra = paths ? await attachFiles({ repoRoot, paths, budgetTokens: budgetFor(cfg, 'full_in') }) : null;
+        extra = paths ? await attachFiles({ repoRoot, paths, budgetTokens: budgetFor(cfg, 'full_in'), ownedFiles: input.ownedFiles, changedFiles: input.changedFiles ?? input.peers ?? [] }) : null;
       } catch {
         extra = null;
       }
@@ -278,10 +322,10 @@ export async function reviewFile(input, deps) {
     return summary;
   };
 
-  const reviewers = plan.sessions.filter((s) => s.role === 'reviewer');
-  const judgeSpec = plan.sessions.find((s) => s.role === 'judge');
+  let reviewers = plan.sessions.filter((s) => s.role === 'reviewer');
+  let judgeSpec = plan.sessions.find((s) => s.role === 'judge');
   /** @param {import('./packet.mjs').FileDiff} part @param {ReadonlyArray<number> | null} [keys] */
-  const packetsFor = (part, keys = null) => reviewers.map((spec) => assemblePacket({ diff: part, lens: spec.lens, rulesDigest: input.rulesDigest, factsExcerpt: input.factsExcerpt, cfg, moved: movedOf(keys) }));
+  const packetsFor = (part, keys = null) => reviewers.map((spec) => assemblePacket({ diff: part, lens: spec.lens, rulesDigest: input.rulesDigest, factsExcerpt: input.factsExcerpt, cfg, moved: movedOf(keys), paired }));
 
   /**
    * The plan on one packet set (the whole file, or one Markdown section): reviewers, then the judge.
@@ -315,10 +359,25 @@ export async function reviewFile(input, deps) {
     return { status: 'reviewed', approved, summary: final.review.summary, findings, sessions };
   };
 
-  const packets = packetsFor(diff);
-  const split = /** @type {{status: 'split_required', tokensIn: number, budget: number} | undefined} */ (packets.find((p) => p.status === 'split_required'));
+  let packets = packetsFor(diff);
+  let split = /** @type {{status: 'split_required', tokensIn: number, budget: number} | undefined} */ (packets.find((p) => p.status === 'split_required'));
+  /** @type {Record<string, any>} */
+  let stepUp = {};
+  if (split && plan.depth === 'quick' && !isMarkdownFile(diff.file)) {
+    const full = planSessions({ risk: 1, cfg, kind });
+    // A configured consensus/refusal is not the single full session this step permits.
+    if (full.depth === 'full') {
+      stepUp = { step_up: { from: 'quick', tokens_in: split.tokensIn, budget: split.budget } };
+      plan = full;
+      head = { ...head, engine: plan.mode, depth: plan.depth };
+      reviewers = plan.sessions.filter((s) => s.role === 'reviewer');
+      judgeSpec = plan.sessions.find((s) => s.role === 'judge');
+      packets = packetsFor(diff);
+      split = /** @type {typeof split} */ (packets.find((p) => p.status === 'split_required'));
+    }
+  }
   if (!split) {
-    const { status, reason, approved, summary, findings, sessions } = await reviewPart(diff, packets);
+    const { status, reason, approved, summary, findings, sessions } = await reviewPart(diff, packets, stepUp);
     if (status !== 'reviewed') return { status, reason, approved: false, ...head, sessions };
     return { status, approved, ...head, summary, findings, sessions };
   }
@@ -383,8 +442,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 +461,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 +508,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 +516,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 +565,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 {