@codedology/code-forge 0.9.0 → 0.11.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-end.mjs

@@ -54,11 +54,13 @@ function safeId(id) {
  * @param {{
  *   block: string, runId: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
  *   commit: string | null, spend: {usd: number, unknown: number} | null, findings: number | null, at: Date,
- * }} facts
+ *   reviewed?: ReadonlyArray<{file: string, ticket: string, via: string}>,
+ * }} facts `reviewed` (B96): the close's reviewed lines, sorted by file; the key is added last, and only when given.
  * @returns {{block: string, run_id: string, status: string, event: string, reason: string | null, commit: string | null,
- *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string}}
+ *   spent_usd: number | null, unknown_usd_sessions: number | null, findings: number | null, at: string,
+ *   reviewed?: Array<{file: string, ticket: string, via: string}>}}
  */
-export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at }) {
+export function doneFileContent({ block, runId, status, event, reason = null, commit, spend, findings, at, reviewed }) {
   return {
     block,
     run_id: runId,
@@ -71,6 +73,7 @@ export function doneFileContent({ block, runId, status, event, reason = null, co
     unknown_usd_sessions: spend && Number.isInteger(spend.unknown) ? spend.unknown : null,
     findings: Number.isInteger(findings) ? findings : null,
     at: at.toISOString(),
+    ...(Array.isArray(reviewed) ? { reviewed: reviewed.map((r) => ({ file: r.file, ticket: r.ticket, via: r.via })).sort((x, y) => (x.file < y.file ? -1 : x.file > y.file ? 1 : 0)) } : {}),
   };
 }
 
@@ -97,12 +100,13 @@ async function headCommit(cwd) {
  * @param {{
  *   record: Record<string, any>, id: string, status: 'closed' | 'stopped', event: string, reason?: string | null,
  *   openFindings: (rows: Record<string, any>[]) => Promise<number>, err: (s: string) => unknown, now?: Date,
+ *   reviewed?: ReadonlyArray<{file: string, ticket: string, via: string}>,
  * }} opts - `record` is the run record read before the end (its `workspace` and the block's
  *   `worktree` do not change at an end); `openFindings` counts the block's open findings exactly
- *   as `code-forge status` does.
+ *   as `code-forge status` does. `reviewed` (B96): the close's reviewed lines, kept as the last key.
  * @returns {Promise<string | null>} the done file's absolute path, or null when it was not written.
  */
-export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date() }) {
+export async function writeDoneFile({ record, id, status, event, reason = null, openFindings, err, now = new Date(), reviewed }) {
   const runId = String(record?.run_id);
   try {
     const file = doneFilePath(runId, id);
@@ -127,7 +131,7 @@ export async function writeDoneFile({ record, id, status, event, reason = null,
     }
     const tree = record.blocks?.[id]?.worktree?.path;
     const commit = await headCommit(typeof tree === 'string' && tree.length > 0 ? tree : record.workspace);
-    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now });
+    const content = doneFileContent({ block: id, runId, status, event, reason, commit, spend, findings, at: now, ...(reviewed === undefined ? {} : { reviewed }) });
     const dir = path.dirname(file);
     await mkdir(dir, { recursive: true, mode: 0o700 });
     const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);

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',