@codedology/code-forge 0.8.0 → 0.10.0

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

package/src/review/stop-exits.mjs

@@ -0,0 +1,15 @@
+/**
+ * B73 (issue #12): the ways out of a file the fix loop stopped (`review_cap`,
+ * `l3_patch_exhausted`, `split_required`), in this order — `block reopen` after a fix,
+ * `block waive` for each open finding, `review-file --answers` for a fix made in another owned
+ * file, or re-decompose the block. `review-file`'s `stopped` answer carries them as `exits`; the
+ * gate appends {@link stopExitsLine} to its `review_cap` and `unreviewed` detail for a stopped
+ * file. A `tampered` review state is not a stop (it is refused; the owner's way out is
+ * `block close --no-require-reviews`) and never gets them.
+ */
+
+/** @type {ReadonlyArray<string>} */
+export const STOP_EXITS = Object.freeze(['block reopen', 'block waive', 'review-file --answers', 're-decompose']);
+
+/** The one short line the gate appends to a stopped file's detail. */
+export const stopExitsLine = `exits: ${STOP_EXITS.join(', ')}`;

package/src/review/test-quality.mjs

@@ -0,0 +1,201 @@
+/**
+ * The test-quality note (block B92, issue #10 item 3): a test file that reads a source file and
+ * asserts on its text proves text, not behaviour. Its review packets get a `## test-quality`
+ * section before the diff that names the lines (never their text), so the reviewer looks at them.
+ * The lenses tell the reviewer to raise such a test as a `warning` unless the read file is a
+ * fixture. The note is a hint, never a tool-made finding: no row, no gate change.
+ *
+ * The detector is pure (path and content in, line numbers out; no I/O):
+ *  - it runs only on a test file: `isTestPath` (`test/ tests/ __tests__/ spec/` dirs, `*.test.*`,
+ *    `*.spec.*`, `*Test.php`, `*_test.go`, `test_*.py`) plus a `Tests/` dir and a name ending in
+ *    `Tests.<ext>` or `Test.<ext>` (`FooTests.swift`, `FooTest.kt`). A docs file (`.md`, `.txt`)
+ *    and a file under a fixtures dir are never checked;
+ *  - a READ line holds a read call ({@link READ_CALLS}) and, in the call's span, either a quoted
+ *    path literal that ends in a source extension ({@link SOURCE_EXTENSIONS}), or a name bound on an
+ *    earlier line to such a literal (`const SRC = 'src/a.mjs'` … `readFileSync(SRC)`). A name is
+ *    bound only when its value IS the literal: the whole right-hand side, or the literal passed
+ *    straight to `join`/`path.join`/`resolve`/`path.resolve`; the binding may carry modifiers and a
+ *    type (`private val`, `const val`, `private static let`, `private static final String`,
+ *    `private const string`, `export const`). The span is the call's line, plus up to
+ *    {@link SPAN_LINES} following lines while the read call's own `(` is still open (a formatter
+ *    split); the call's line is the one reported. A span with any string literal that has a
+ *    fixtures dir segment (`fixtures`, `fixture`, `__fixtures__`) — `'test/fixtures/a.mjs'` or
+ *    `join(dir, 'fixtures', 'a.mjs')` — or that names a name bound to such a literal
+ *    (`const FIXTURES = join(dir, 'fixtures')`) is a fixture read, never a source read;
+ *  - a TEXT-ASSERT line holds a contains or match call ({@link ASSERT_CALLS});
+ *  - the file is flagged only when it has at least one of each. The flagged lines are every read
+ *    line and every text-assert line, 1-based, sorted; the section lists at most
+ *    {@link MAX_LINES} of them and counts the rest.
+ */
+
+import { isTestPath } from '../gates/expand.mjs';
+
+/** The section names at most this many line numbers. */
+export const MAX_LINES = 10;
+
+/** The file extensions of source code a test should not read for its text. */
+export const SOURCE_EXTENSIONS = Object.freeze(['swift', 'ts', 'tsx', 'js', 'mjs', 'cjs', 'py', 'go', 'rs', 'kt', 'java', 'rb', 'php', 'cs']);
+
+/** Common read calls, matched as plain text. */
+export const READ_CALLS = Object.freeze(['readFileSync', 'readFile', 'open(', 'read_text', 'String(contentsOf', 'contentsOfFile', 'File.read', 'os.ReadFile', 'fs::read_to_string', 'readText(', 'readString(', 'ReadAllText(']);
+
+/** A read call's path may sit on at most this many lines after the call (a formatter split). */
+export const SPAN_LINES = 3;
+
+/** Contains or match calls on text, matched as plain text (`XCTAssertTrue(x.contains(…))` holds `contains(`). */
+export const ASSERT_CALLS = Object.freeze(['includes(', 'contains(', 'toContain(', 'toMatch(', 'assert.match(', 'assertIn(', 'strings.Contains(']);
+
+const DOCS = /\.(md|txt)$/i;
+const FIXTURE_DIRS = new Set(['fixtures', 'fixture', '__fixtures__']);
+/** A quoted string literal (single, double or back quote) with no quote or newline inside. */
+const LITERAL = /(['"`])([^'"`\n]*)\1/g;
+const SOURCE_END = new RegExp(`\\.(${SOURCE_EXTENSIONS.join('|')})$`);
+/**
+ * A binding at the line start: modifiers (`export`, `private`, `static`, `final`, `const`, …), then
+ * `const|let|var|val X` (JS, Swift, Kotlin) or an optional type and `X` (Java `String X`, Python
+ * `X`, Go `X :=`), an optional `: Type`, and `=` (not `==`). Group 1 or 2 is the name.
+ */
+const BINDING = /^\s*(?:(?:export|public|private|protected|internal|fileprivate|open|static|final|readonly|lazy|const)\s+)*(?:(?:const|let|var|val)\s+([A-Za-z_$][\w$]*)|(?:[A-Za-z_][\w.<>[\],]*\s+)?([A-Za-z_$][\w$]*))\s*(?::[^=]*)?=(?!=)/;
+
+/** @param {string} p @returns {string[]} the `/`-separated segments of a path. */
+const segments = (p) => p.split('/');
+
+/** @param {string} p @returns {boolean} whether `p` has a fixtures dir segment. */
+const underFixtures = (p) => segments(p).some((s) => FIXTURE_DIRS.has(s));
+
+/**
+ * Whether the detector checks `file`: a test file that is not a docs file and not a fixture.
+ * @param {unknown} file - a repo-relative POSIX path.
+ * @returns {boolean}
+ */
+export function isCheckedTestFile(file) {
+  if (typeof file !== 'string' || file.length === 0) return false;
+  if (DOCS.test(file) || underFixtures(file)) return false;
+  if (isTestPath(file)) return true;
+  const parts = segments(file);
+  const name = parts[parts.length - 1];
+  return parts.slice(0, -1).includes('Tests') || /(Tests|Test)\.[^./]+$/.test(name);
+}
+
+/** @param {string} line @returns {boolean} whether the line holds a quoted source-path literal (not a fixture). */
+function hasSourceLiteral(line) {
+  for (const m of line.matchAll(LITERAL)) {
+    const value = m[2];
+    if (SOURCE_END.test(value) && !underFixtures(value)) return true;
+  }
+  return false;
+}
+
+/** @param {string} line @returns {boolean} whether any string literal on the line has a fixtures dir segment. */
+const hasFixtureLiteral = (line) => [...line.matchAll(LITERAL)].some((m) => underFixtures(m[2]));
+
+/** @param {string} line @returns {number} `(` minus `)` outside string literals. */
+const parenDelta = (line) => {
+  const bare = line.replace(LITERAL, '');
+  return (bare.match(/\(/g) ?? []).length - (bare.match(/\)/g) ?? []).length;
+};
+
+/**
+ * The lines of the read call on `lines[i]`: that line, plus up to {@link SPAN_LINES} more while
+ * the read call's own `(` stays open (the depth counts from that `(`, not the whole line).
+ * @param {string[]} lines @param {number} i @returns {string[]}
+ */
+function callSpan(lines, i) {
+  const line = lines[i];
+  const span = [line];
+  const at = Math.min(...READ_CALLS.map((c) => line.indexOf(c)).filter((n) => n >= 0));
+  const open = line.indexOf('(', at);
+  let depth = open === -1 ? 0 : parenDelta(line.slice(open));
+  for (let j = i + 1; depth > 0 && j < lines.length && j <= i + SPAN_LINES; j += 1) {
+    span.push(lines[j]);
+    depth += parenDelta(lines[j]);
+  }
+  return span;
+}
+
+/** A call that passes a path straight on: `join(`, `path.join(`, `resolve(`, `path.resolve(`. */
+const PATH_CALL = /^(?:path\.)?(?:join|resolve)\((.*)\)$/;
+
+/**
+ * Whether a binding's right-hand side IS a source-path literal: the literal alone, or the literal
+ * passed straight to a path call. `spawnSync('node', ['bin/cli.mjs'])` is not.
+ * @param {string} rhs @returns {boolean}
+ */
+function valueIsSourceLiteral(rhs) {
+  const value = rhs.trim().replace(/;$/, '').trim();
+  const whole = /^(['"`])([^'"`\n]*)\1$/.exec(value);
+  if (whole) return hasSourceLiteral(value);
+  const call = PATH_CALL.exec(value);
+  return call !== null && hasSourceLiteral(call[1]);
+}
+
+/** @param {string} line @param {ReadonlyArray<string>} calls @returns {boolean} */
+const holdsAny = (line, calls) => calls.some((c) => line.includes(c));
+
+/**
+ * The flagged line numbers of a test file that reads a source file and asserts on its text.
+ * @param {unknown} file - repo-relative path. @param {unknown} content - the file's current text.
+ * @returns {number[]} 1-based, sorted, no duplicates; [] when the file is not flagged.
+ */
+export function testQualityLines(file, content) {
+  if (!isCheckedTestFile(file) || typeof content !== 'string') return [];
+  const lines = content.split(/\r?\n/);
+  /** @type {Set<string>} names bound to a source-path literal so far */
+  const bound = new Set();
+  /** @type {Set<string>} names bound to a literal with a fixtures segment so far */
+  const fixtureBound = new Set();
+  /** @type {number[]} */
+  const reads = [];
+  /** @type {number[]} */
+  const asserts = [];
+  /** @param {Set<string>} names @returns {(line: string) => boolean} whether a line names one of `names` */
+  const names = (names) => (line) => [...names].some((name) => new RegExp(`(^|[^\\w$])${name.replace(/\$/g, '\\$')}([^\\w$]|$)`).test(line));
+  const namesBound = names(bound);
+  const namesFixture = names(fixtureBound);
+  for (const [i, line] of lines.entries()) {
+    if (holdsAny(line, READ_CALLS)) {
+      const span = callSpan(lines, i);
+      const fixture = span.some((l) => hasFixtureLiteral(l) || namesFixture(l));
+      if (!fixture && span.some((l) => hasSourceLiteral(l) || namesBound(l))) reads.push(i + 1);
+    }
+    if (holdsAny(line, ASSERT_CALLS)) asserts.push(i + 1);
+    const m = BINDING.exec(line);
+    const name = m?.[1] ?? m?.[2];
+    if (name) {
+      if (hasFixtureLiteral(line)) fixtureBound.add(name);
+      else if (valueIsSourceLiteral(line.slice(m[0].length))) bound.add(name);
+    }
+  }
+  if (reads.length === 0 || asserts.length === 0) return [];
+  return [...new Set([...reads, ...asserts])].sort((a, b) => a - b);
+}
+
+/**
+ * The `## test-quality` section for `file`, or '' when no line is flagged. It names line numbers
+ * only — never the file's text.
+ * @param {string} file @param {ReadonlyArray<number>} lines - from {@link testQualityLines}.
+ * @returns {string}
+ */
+export function renderTestQuality(file, lines) {
+  if (lines.length === 0) return '';
+  const shown = lines.slice(0, MAX_LINES);
+  const more = lines.length - shown.length;
+  return [
+    '## test-quality',
+    `file: ${file}`,
+    `lines: ${shown.join(', ')}${more > 0 ? ` (${more} more not listed)` : ''}`,
+    'This test file reads a source file and asserts on its text (a hint from a text match, not a finding): check these lines and apply the lens rule on tests that read source text.',
+  ].join('\n');
+}
+
+/**
+ * The section for one file at its current content ('' for none, a deleted file, or any error).
+ * @param {string} file @param {string | null} content @returns {string}
+ */
+export function testQualityNote(file, content) {
+  try {
+    return content === null ? '' : renderTestQuality(file, testQualityLines(file, content));
+  } catch {
+    return ''; // a hint only: no note, the review goes on
+  }
+}

package/src/review/verb-forms.mjs

@@ -0,0 +1,39 @@
+/**
+ * B80: the argument forms of the human verbs `block waive` and `block reopen`, in ONE place, so the
+ * check that runs before the terminal question (`src/cli/block.mjs`) and the verbs themselves
+ * (`waiveFinding`, `reopenFile`) can never drift apart. Every refusal is `usage` (exit 2).
+ *
+ * A control character (any char below 0x20, or 0x7f) is refused before anything else: such a
+ * value would reach the terminal question and the stderr messages that quote it.
+ */
+import path from 'node:path';
+import { StateError } from '../state/paths.mjs';
+
+/** The finding id form a waive takes. */
+const FINDING_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\x00-\x1f\x7f]/;
+
+/**
+ * @param {unknown} finding
+ * @throws {StateError} `usage` for a value with a control character or not of the finding id form.
+ */
+export function checkFindingId(finding) {
+  if (typeof finding === 'string' && CONTROL.test(finding)) throw new StateError('usage', 'a finding id must not contain control characters');
+  if (typeof finding !== 'string' || !FINDING_ID.test(finding)) throw new StateError('usage', 'a finding id is required (letters, digits, . _ : -)');
+}
+
+/**
+ * The `--file` form: no control character, then a repo-root-relative path (not absolute, no `..`
+ * segment, no leading `./`). `normalized` also refuses a path that `path.posix.normalize` changes
+ * — the rule `block reopen` has always had; `block waive` keeps its own (B80 does not change it).
+ * @param {unknown} file @param {{normalized: boolean}} rule
+ * @throws {StateError} `usage`.
+ */
+export function checkFileForm(file, { normalized }) {
+  if (typeof file !== 'string' || file === '') throw new StateError('usage', '--file is required');
+  if (CONTROL.test(file)) throw new StateError('usage', '--file must not contain control characters');
+  if (path.isAbsolute(file) || file.split('/').includes('..') || file.startsWith('./') || (normalized && path.posix.normalize(file) !== file)) {
+    throw new StateError('usage', '--file must be repo-root-relative');
+  }
+}

package/src/session/spawn.mjs

@@ -54,6 +54,7 @@ import { compileSchema } from '../config/schema-compile.mjs';
 import { buildArgv } from '../engines/builders/index.mjs';
 import { removeCodexHome } from '../engines/codex-home.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
+import { DEFAULT_SANDBOX_PROFILE, SANDBOX_DIR_REFUSED, SandboxDirError } from '../engines/sandbox-dirs.mjs';
 import { parseSentinel } from '../engines/sentinel.mjs';
 import { parseUsage } from '../engines/usage-parse.mjs';
 import { budgetUsdOf, checkBudget, estimateSessionUsd, priceSession, reservedUsd, reserveBudget, SPEND_UNREADABLE_MESSAGE, withBudgetLock } from '../ledger/spend.mjs';
@@ -609,7 +610,7 @@ export async function spawnSession(opts, deps = {}) {
         if (hit) throw new SessionError('forbidden', `coder argv refused before spawn: forbidden entry ${hit.id}`);
       }
       writeSafe(stderr, `level=${level} provider=${step.provider} model=${step.model} effort=${step.effort ?? 'none'} fallback_step=${step.fallback_step}\n`);
-      const base = { role, level, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, run: opts.run ?? null, block: opts.block ?? null, ...(role === 's2' ? { source: step.fallback_step > 0 ? 's2-fallback' : 's2' } : {}), ...(opts.rowExtra ?? {}) };
+      const base = { role, level, provider: step.provider, model: step.model, effort: step.effort ?? null, fallback_step: step.fallback_step, run: opts.run ?? null, block: opts.block ?? null, ...(role === 's2' ? { source: step.fallback_step > 0 ? 's2-fallback' : 's2' } : {}), ...sandboxRowField(opts, cli), ...(opts.rowExtra ?? {}) };
 
       if (opts.background) {
         keep = true;
@@ -829,6 +830,12 @@ function buildStep(opts, step, sessionDir, openBook) {
   if (cli === 'codex') params.outPath = path.join(sessionDir, 'out.json');
   // B32 opt-in: only a no-tools role needs it; coder and facts build exactly as without it
   if (cli === 'codex' && openBook && isNoToolRole(opts.role)) params.allowOpenBook = true;
+  // B93: the Codex coder's sandbox profile; no `coder.sandbox` key builds exactly today's argv
+  const sandbox = coderSandboxFor(opts, cli);
+  if (sandbox !== null) {
+    params.sandbox = sandbox;
+    params.runRoot = opts.runRoot ?? currentRunRoot();
+  }
   /** @type {Record<string, any> | null} */
   let compiled = null;
   const strict = variantFor(step.provider) === 'strict';
@@ -841,10 +848,40 @@ function buildStep(opts, step, sessionDir, openBook) {
       params.schema = compiled;
     }
   }
-  const built = buildArgv(/** @type {any} */ (params));
+  let built;
+  try {
+    built = buildArgv(/** @type {any} */ (params));
+  } catch (err) {
+    // B93: a refused `add_dirs` entry; the message names the key path, never the value
+    if (err instanceof SandboxDirError) throw new SessionError(SANDBOX_DIR_REFUSED, err.message);
+    throw err;
+  }
   return { ...built, argv: [...built.argv], compiled, strict };
 }
 
+/**
+ * B93: `{sandbox: <profile>}` for a Codex coder session row when `coder.sandbox` is set; `{}`
+ * otherwise, so a row without the key is byte-equal to the row before B93.
+ * @param {SessionOpts} opts @param {string} cli @returns {{sandbox?: string}}
+ */
+function sandboxRowField(opts, cli) {
+  const sandbox = coderSandboxFor(opts, cli);
+  if (sandbox === null) return {};
+  return { sandbox: typeof sandbox.profile === 'string' ? sandbox.profile : DEFAULT_SANDBOX_PROFILE };
+}
+
+/**
+ * B93: the `coder.sandbox` value a Codex coder session builds with, or null (no key, another
+ * role, or another CLI — the Claude and Grok coders do not read it).
+ * @param {SessionOpts} opts @param {string} cli
+ * @returns {Record<string, any> | null}
+ */
+function coderSandboxFor(opts, cli) {
+  if (cli !== 'codex' || opts.role !== 'coder') return null;
+  const sandbox = /** @type {Record<string, any> | undefined} */ (opts.cfg)?.coder?.sandbox;
+  return sandbox === undefined || sandbox === null ? null : sandbox;
+}
+
 /**
  * @param {{cli: string, argv: string[], cwd: string, stdinFile?: string, outPath?: string, env?: Record<string, string>, compiled: Record<string, any> | null, strict: boolean}} built
  * @param {SessionOpts} opts

package/src/state/block.mjs

@@ -18,7 +18,7 @@ import path from 'node:path';
 import { BLOCK_KINDS, blockKind, dispatchLevel } from '../decide/escalation.mjs';
 import { exec } from '../util/exec.mjs';
 import { DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
-import { blockEndHook, externalReviewer } from './config-snapshot.mjs';
+import { blockEndHook, configInForce, externalReviewer } from './config-snapshot.mjs';
 import { ownedKinds, pathKind } from './owned-kinds.mjs';
 import { isAncestorArgv, revParseArgv } from '../util/git.mjs';
 import { StateError } from './paths.mjs';
@@ -263,12 +263,22 @@ function activeBlocks(record) {
  * subdirectory, relative to the repository top level (the close gate matches both, `ownsAt`).
  * Empty when the key is not set. B64b: `hooks.on_block_end` in the snapshot guards it the same way
  * — the file names a command the orchestrator runs at every block end — and `why` names the key
- * that guards it (`review.external.required` first, so its message is unchanged).
+ * that guards it (`review.external.required` first, so its message is unchanged). B87:
+ * `proof.runners` in the snapshot guards it too — the file names the commands that prove a block;
+ * any stored value guards it (fail closed: `validate` refuses an empty or malformed list anyway).
  * @param {Record<string, any>} record @returns {Promise<{paths: string[], why: string}>}
  * @throws {StateError} `config-snapshot`, `git-failed`
  */
 async function guardedConfigPaths(record) {
-  const why = externalReviewer(record) !== null ? 'review.external.required is true' : blockEndHook(record) !== null ? 'hooks.on_block_end is set' : null;
+  const runners = configInForce(record)?.proof?.runners;
+  const why =
+    externalReviewer(record) !== null
+      ? 'review.external.required is true'
+      : blockEndHook(record) !== null
+        ? 'hooks.on_block_end is set'
+        : runners !== undefined && runners !== null
+          ? 'proof.runners is set'
+          : null;
   if (why === null) return { paths: [], why: '' };
   const top = await repoTop(record.workspace);
   // the repo-top spelling `<prefix>/.code-forge.yml` may also match a different file of the same