@codedology/code-forge 0.9.0 → 0.10.0

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

package/src/state/config-snapshot.mjs

@@ -44,6 +44,11 @@ export const IMMUTABLE_KEYS = Object.freeze({
   // B64b: the block-end hook runs a command on the owner's machine at every block end, so only
   // the owner sets it, before the run starts
   'hooks.on_block_end': 'it runs a command on the owner\'s machine at every block end; fixed by the owner before the run starts',
+  // B87: the runner argv proves the coder's own work, so only the owner sets it, before the run starts
+  'proof.runners': 'the commands that prove a block are fixed by the owner before the run starts',
+  // B93: the coder sandbox profile widens what the coder may write, so only the owner sets it,
+  // before the run starts (a coder can never own `.code-forge.yml`)
+  'coder.sandbox': 'the coder sandbox widens what the coder may write; fixed by the owner before the run starts',
 });
 
 /** @param {unknown} v @returns {boolean} what `JSON.stringify` drops from an object. */
@@ -235,3 +240,37 @@ export function blockEndHook(record) {
   if (!Number.isInteger(timeoutS) || timeoutS < HOOK_TIMEOUT_MIN_S || timeoutS > HOOK_TIMEOUT_MAX_S) return null;
   return { argv: [...argv], timeoutS };
 }
+
+/**
+ * B87: `proof.runners` of the run-start config snapshot (never the live config), as a deep copy
+ * (entries and argv arrays), or null when the key is absent or the record is from before
+ * snapshots. `proof/runners.mjs` checks each entry again before it runs one (fail closed).
+ * @param {Record<string, any>} record
+ * @returns {unknown[] | null}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash;
+ *   `runner-invalid` when the stored value is not a list, or is an empty one.
+ */
+export function proofRunners(record) {
+  const runners = configInForce(record)?.proof?.runners;
+  if (runners === undefined || runners === null) return null;
+  if (!Array.isArray(runners)) throw new StateError('runner-invalid', `run ${record.run_id}: proof.runners in the run snapshot is not a list`);
+  // `validate` refuses an empty list (minItems 1); a record that holds one anyway is refused too
+  if (runners.length === 0) throw new StateError('runner-invalid', `run ${record.run_id}: proof.runners in the run snapshot is an empty list`);
+  // a deep copy: a caller that changes an entry or an argv array never changes the snapshot
+  return structuredClone(runners);
+}
+
+/**
+ * B93: `coder.sandbox` of the run-start config snapshot (never the live config). A record from
+ * before snapshots has no run-start value: `{snapshot: false}`. Otherwise `{snapshot: true,
+ * sandbox}`, where `sandbox` is a deep copy of the value, or null when the snapshot has no key.
+ * @param {Record<string, any>} record
+ * @returns {{snapshot: false} | {snapshot: true, sandbox: Record<string, any> | null}}
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+export function coderSandbox(record) {
+  const config = configInForce(record);
+  if (config === null) return { snapshot: false };
+  const sandbox = config.coder?.sandbox;
+  return { snapshot: true, sandbox: sandbox === undefined || sandbox === null ? null : structuredClone(sandbox) };
+}

package/src/state/run.mjs

@@ -269,6 +269,10 @@ export async function reloadRun({ runId, config, readPending = () => [], effecti
       if (config.context?.require_coder_tests === true) frozen.push('context.require_coder_tests');
       // B64b: and never had a block-end hook
       if (config.hooks?.on_block_end !== undefined) frozen.push('hooks.on_block_end');
+      // B87: and never had a proof runner
+      if (config.proof?.runners !== undefined) frozen.push('proof.runners');
+      // B93: and never had a coder sandbox profile
+      if (config.coder?.sandbox !== undefined) frozen.push('coder.sandbox');
     }
     if (frozen.length > 0) {
       const why = frozen.map((key) => `${key} cannot change mid-run (${IMMUTABLE_KEYS[/** @type {keyof typeof IMMUTABLE_KEYS} */ (key)]})`);

package/src/util/forbidden.mjs

@@ -292,7 +292,7 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
         ['code-forge', 'block', 'waive'],
         ['forge', 'block', 'waive'],
       ],
-      description: 'Waive a review finding (forge block waive) — human-only, run by the orchestrator after the human said so (§4.9)',
+      description: 'Waive a review finding (forge block waive) — human-only, typed by the human in their own terminal (§4.9, B80)',
     },
     {
       id: 'code-forge-block-reopen-from-coder',
@@ -301,7 +301,7 @@ export const CODER_ONLY_FORBIDDEN = Object.freeze(
         ['code-forge', 'block', 'reopen'],
         ['forge', 'block', 'reopen'],
       ],
-      description: 'Reopen the review of a stopped or lost file (forge block reopen) — human-only, run by the orchestrator after the human said so (B72)',
+      description: 'Reopen the review of a stopped or lost file (forge block reopen) — human-only, typed by the human in their own terminal (B72, B80)',
     },
     {
       id: 'code-forge-autopilot-from-coder',

package/src/worker/loop.mjs

@@ -39,7 +39,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { expiryChecks } from '../autopilot/limits.mjs';
 import { loadProjectConfig } from '../config/load.mjs';
-import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
+import { cacheHoursFrom, createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { appendRow, readAllRows } from '../ledger/write.mjs';
 import { spawnSession } from '../session/spawn.mjs';
 import { snapshotFor } from '../state/config-snapshot.mjs';
@@ -47,12 +47,13 @@ import { readRun, reattachWorker } from '../state/run.mjs';
 import { loadKey, signRow } from '../state/signer.mjs';
 import { logWarning } from '../util/error-log.mjs';
 import { keyedLock } from '../util/locks.mjs';
-import { writeSafe } from '../util/redact.mjs';
+import { redact, writeSafe } from '../util/redact.mjs';
 import { runRoot, setRunRoot } from '../util/tmp.mjs';
 import { openFindings } from '../review/gate-check.mjs';
+import { countLines, RouteError, routeTicket } from '../review/route.mjs';
 import { canonicalPath, contentRootFor, reviewTicket } from './engine.mjs';
 import { announceWorker, beatWorker, HEARTBEAT_MS, liveWorker, pendingTickets, readTicket, retractWorker, writeResult } from './queue.mjs';
-import { contentHash, DELETED_HASH, repoRootOf, WorkerError } from './ticket.mjs';
+import { DELETED_HASH, hashBytes, readRegularFileNoFollow, repoRootOf, WorkerError } from './ticket.mjs';
 
 /** Name of the key the worker resolves for System 1 (`keys.jev` / `system1.key` reference). */
 export const JEV_KEY_NAME = 'jev';
@@ -136,16 +137,37 @@ export function sessionEnv(env, secrets) {
 /**
  * Resolve the Jev key through B2's chain (env → store → 1Password). A missing key is not an error:
  * System 1 then falls back (`system1.fallback`, B3). The value is registered for redaction by B2.
+ * A refresh from 1Password is cached for the config's `keys.cache_hours` (B84: the run's snapshot;
+ * a snapshot from before the key has none ⇒ 8 h).
  * @param {Record<string, any>} cfg
- * @param {{store: import('../keys/store.mjs').KeyStore, env: NodeJS.ProcessEnv, opRead?: any}} deps
+ * @param {{store: import('../keys/store.mjs').KeyStore, env: NodeJS.ProcessEnv, opRead?: any, now?: number}} deps
  * @returns {Promise<string | null>}
  */
-export async function resolveJevKey(cfg, { store, env, opRead }) {
+export async function resolveJevKey(cfg, { store, env, opRead, now }) {
   const ref = cfg?.system1?.key ?? cfg?.keys?.[JEV_KEY_NAME];
-  const res = await resolveKey(JEV_KEY_NAME, { store, env, ref: typeof ref === 'string' ? ref : undefined, ...(opRead ? { opRead } : {}) });
+  const res = await resolveKey(JEV_KEY_NAME, {
+    store,
+    env,
+    ref: typeof ref === 'string' ? ref : undefined,
+    cacheHours: cacheHoursFrom(cfg).hours,
+    ...(opRead ? { opRead } : {}),
+    ...(now !== undefined ? { now } : {}),
+  });
   return res.value;
 }
 
+/**
+ * B90: an unexpected failure inside a named worker step (today: `routing`). The ticket still ends
+ * `worker-error`; its result's `detail` says `<step>: <original error text>` (redacted).
+ */
+class StepError extends Error {
+  /** @param {string} step @param {unknown} cause */
+  constructor(step, cause) {
+    super(`${step}: ${cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)}`, { cause });
+    this.step = step;
+  }
+}
+
 /** The fix-loop fields of an engine outcome the result carries (B12c, §4.11). */
 const LOOP_FIELDS = Object.freeze(['round', 'kind', 'level', 'next', 'trigger', 'stopped', 'late']);
 
@@ -282,14 +304,51 @@ export async function createWorker(opts, deps = {}) {
   }
 
   /**
-   * One ticket through the engine hook with `tcfg` (the ticket's config snapshot): the unsigned result.
+   * One ticket through the engine hook with the ticket's config snapshot, routed by size (B90): the unsigned result.
+   * @param {string} id - the ticket id (B90: a retried ticket never writes its route rows twice).
    * @param {import('./queue.mjs').Ticket} ticket @param {Record<string, any>} base
-   * @param {Record<string, any>} tcfg
+   * @param {Record<string, any>} snapshotCfg - the ticket's config snapshot, before B90 routing.
    * @param {string} contentRoot - B62b: the tree the content was hashed in, and is reviewed in.
+   * @param {{lines: number, deleted: boolean}} size - B90: the line count of the hashed bytes.
    * @returns {Promise<Record<string, any>>}
    */
-  async function reviewWith(ticket, base, tcfg, contentRoot) {
-    const timeoutS = Number.isInteger(tcfg?.review?.session_timeout_s) && tcfg.review.session_timeout_s > 0 ? tcfg.review.session_timeout_s : DEFAULT_SESSION_TIMEOUT_S;
+  async function reviewWith(id, ticket, base, snapshotCfg, contentRoot, size) {
+    const baseTimeoutS = Number.isInteger(snapshotCfg?.review?.session_timeout_s) && snapshotCfg.review.session_timeout_s > 0 ? snapshotCfg.review.session_timeout_s : DEFAULT_SESSION_TIMEOUT_S;
+    // B90: `review.routes` picks the model, second level and timeout of every session of this
+    // ticket from its size, once, before the first session. No route ⇒ the snapshot object itself.
+    // A route list that cannot be used is `unavailable` — never a review on a model it did not name.
+    let routed;
+    try {
+      routed = routeTicket(snapshotCfg, { lines: size.lines, deleted: size.deleted, timeoutS: baseTimeoutS });
+    } catch (err) {
+      // only a route list that cannot be used is `route-invalid`; anything else is a real failure
+      // and goes to runOne (`worker-error`), named as a routing-step failure with its own text
+      if (!(err instanceof RouteError)) throw new StepError('routing', err);
+      return { ...base, status: 'unavailable', reason: 'route-invalid', approved: false };
+    }
+    const tcfg = routed.cfg;
+    const timeoutS = routed.timeoutS;
+    // the signed `review.route` row comes before the first session; a row that cannot be written
+    // is `unavailable` (a routed review the ledger cannot explain never runs). One row per routed
+    // level per ticket: a retried ticket (same id) skips the levels whose row the ledger already has.
+    // `runId` is the run this ticket belongs to (reviewOne refuses `ticket.run !== runId` as
+    // other-run), and a restarted worker serves the same run id (startWorker: `opts.runId`), so the
+    // check holds across workers of that run.
+    if (routed.rows.length > 0) {
+      try {
+        const have = new Set(
+          (await readRows())
+            .filter((r) => r?.event === 'review.route' && r.run === runId && r.ticket === id)
+            .map((r) => r.level),
+        );
+        for (const row of routed.rows) {
+          if (have.has(row.level)) continue;
+          await ledger({ ...row, ticket: id, block: ticket.block, file: ticket.file, content_hash: ticket.content_hash });
+        }
+      } catch {
+        return { ...base, status: 'unavailable', reason: 'route-row', approved: false };
+      }
+    }
     /** @type {import('./engine.mjs').ReviewContext} */
     const ctx = {
       repoRoot,
@@ -382,8 +441,12 @@ export async function createWorker(opts, deps = {}) {
     if (canonicalPath(hashedIn) !== canonicalPath(contentRoot)) return { ...base, status: 'unavailable', reason: 'worktree-mismatch', approved: false };
     /** @type {string} */
     let current;
+    /** @type {Buffer | null} */
+    let bytes;
     try {
-      current = contentHash(contentRoot, ticket.file);
+      // B90: one read — the bytes hashed are the bytes whose lines route the review
+      bytes = readRegularFileNoFollow(contentRoot, ticket.file);
+      current = hashBytes(bytes);
     } catch (err) {
       // the path no longer passes the on-disk check, or the file cannot be read
       const reason = err instanceof WorkerError ? err.code : 'unreadable';
@@ -398,7 +461,7 @@ export async function createWorker(opts, deps = {}) {
     } catch {
       return { ...base, status: 'unavailable', reason: 'config-snapshot', approved: false };
     }
-    return reviewWith(ticket, base, ticketCfg, contentRoot);
+    return reviewWith(id, ticket, base, ticketCfg, contentRoot, { lines: countLines(bytes), deleted: bytes === null });
   }
 
   /**
@@ -445,9 +508,11 @@ export async function createWorker(opts, deps = {}) {
   async function runOne(id) {
     try {
       return (await processTicket(id)) !== null ? 1 : 0;
-    } catch {
+    } catch (err) {
+      // B90: a failure a step names (StepError) keeps its step and original text, redacted
+      const detail = err instanceof StepError ? { detail: redact(err.message) } : {};
       try {
-        await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', approved: false });
+        await complete(id, { event: 'review.result', status: 'unavailable', reason: 'worker-error', ...detail, approved: false });
         return 1;
       } catch {
         poisoned.add(id);

package/src/worker/ticket.mjs

@@ -185,7 +185,15 @@ function realOrSelf(p) {
  * @returns {string}
  */
 export function contentHash(repoRoot, file) {
-  const bytes = readRegularFileNoFollow(repoRoot, file);
+  return hashBytes(readRegularFileNoFollow(repoRoot, file));
+}
+
+/**
+ * The one content-hash rule (B90: the worker hashes the bytes it also counts lines on): sha256 of
+ * the bytes, or `DELETED_HASH` for `null` (no file).
+ * @param {Buffer | null} bytes @returns {string}
+ */
+export function hashBytes(bytes) {
   if (bytes === null) return DELETED_HASH;
   return createHash('sha256').update(bytes).digest('hex');
 }