@codedology/code-forge 0.9.0 → 0.11.0

package/src/cli/keys.mjs

@@ -5,43 +5,96 @@
  * message would be masked once the chain registered it.
  *
  *   keys list
- *   keys set <name> [--op <ref>]         hidden prompt, or read once from 1Password and cache 8 h
+ *   keys set <name> [--op <ref> [--cache-hours <n>]]
+ *                                        hidden prompt, or read once from 1Password and cache it
  *   keys test <name> [--ref <ref>]       resolve through the chain (no prompt)
  *   keys remove <name>
  *
+ * Cache time (B84): `--cache-hours` (only with `--op`; a typed key never expires), else
+ * `keys.cache_hours` from the `.code-forge.yml` of the project root of the current directory, else
+ * 8 h — whole hours from 1 to 24. `keys set --op` and `keys test` read that config; a missing file
+ * is the default, a file that cannot be loaded is the default with one WARN line. An invalid
+ * `--cache-hours`, or an invalid `keys.cache_hours` for `set --op`, exits 2 before any 1Password
+ * call; `keys test` warns once and uses 8 h for an invalid `keys.cache_hours` (as `jev ask` does).
+ * A cached entry is never
+ * trusted for longer than those hours (`store.read`).
+ *
+ * Expiry warning (B85): `keys list` keeps its stdout table and writes one stderr line per key with
+ * less than 1 hour left — `WARN <name> expires in <m> min; re-link: code-forge keys set <name> --op
+ * <ref>` — naming the `op://` reference from the index row, or a placeholder for a row written
+ * before the index carried it.
+ *
  * An `--op`/`--ref` value may be a 1Password item ID or item link instead of `op://vault/item/field`:
  * it is resolved to `op://<vaultId>/<itemId>/<fieldId>` first (`op item get`, B25).
  *
  * Every name is validated before any store call, on every subcommand.
  */
 
+import path from 'node:path';
 import { writeSafe } from '../util/redact.mjs';
+import { DEFAULT_CONFIG_FILENAME, loadConfigFile, projectRootFor } from '../config/load.mjs';
 import { describeOpItem, isOpRef, OP_APPROVE_NOTE, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../keys/onepassword.mjs';
-import { assertKeyName, createDefaultKeyStore, parseRef, readOpAndCache, resolveKey } from '../keys/store.mjs';
+import { assertKeyName, CACHE_HOURS_RULE, cacheHoursFrom, createDefaultKeyStore, DEFAULT_CACHE_HOURS, isCacheHours, isTime, parseRef, readOpAndCache, resolveKey, shellWord } from '../keys/store.mjs';
+
+const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref> [--cache-hours <1-24>]] | test <name> [--ref <ref>] | remove <name>\n';
 
-const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref>] | test <name> [--ref <ref>] | remove <name>\n';
+/** The flags each subcommand accepts (list and remove take none); each at most once, any order. */
+const FLAGS = /** @type {Record<string, string[]>} */ ({ list: [], set: ['--op', '--cache-hours'], test: ['--ref'], remove: [] });
+
+/**
+ * @param {string} text
+ * @returns {number | null} the whole number of hours `text` spells (digits only) within the
+ *   bounds, else null.
+ */
+export function parseCacheHours(text) {
+  if (!/^[0-9]{1,3}$/.test(text)) {
+    return null;
+  }
+  const hours = Number(text);
+  return isCacheHours(hours) ? hours : null;
+}
 
-/** The one flag each subcommand accepts (list and remove take none). */
-const FLAGS = /** @type {Record<string, string|null>} */ ({ list: null, set: '--op', test: '--ref', remove: null });
+/** Below this much time left, `keys list` warns (B85). */
+const WARN_BELOW_MS = 3_600_000;
+
+/**
+ * @param {{name: string, exp: number|null, ref?: string}} row
+ * @param {number} now
+ * @returns {string|null} the stderr warning for a key with less than 1 hour left, else null (also
+ *   for an `exp` that is not a valid time).
+ */
+export function expiryWarning(row, now) {
+  if (!isTime(row.exp) || row.exp <= now || row.exp - now >= WARN_BELOW_MS) {
+    return null;
+  }
+  // whole minutes left, never 0 and never 60 (under 1 hour is at most 59 min 59 s)
+  const minutes = Math.max(1, Math.floor((row.exp - now) / 60_000));
+  const ref = typeof row.ref === 'string' ? shellWord(row.ref) : '<your 1Password reference>';
+  return `WARN ${row.name} expires in ${minutes} min; re-link: code-forge keys set ${row.name} --op ${ref}\n`;
+}
 
 /**
  * @param {number|null} exp
  * @param {number} now
- * @returns {string}
+ * @returns {string} `unknown` for an `exp` that is not a valid time (a hand-edited index).
  */
 export function formatExpiry(exp, now) {
   if (exp === null) {
     return 'never';
   }
+  if (!isTime(exp)) {
+    return 'unknown';
+  }
   return exp <= now ? 'expired' : new Date(exp).toISOString();
 }
 
 /**
- * Strict parse: `<sub> [<name>] [<flag> <value>]`, in that order. A flag with no value, a value
- * that looks like a flag, a name that looks like a flag, an unknown flag or an extra argument is
- * a usage error — never silently reinterpreted.
+ * Strict parse: `<sub> [<name>] [<flag> <value>]...` — the name first, then the subcommand's flags,
+ * each at most once, in any order. A flag with no value, a value that looks like a flag, a name
+ * that looks like a flag, an unknown or repeated flag, an extra argument, or `--cache-hours`
+ * without `--op` (a typed key never expires) is a usage error — never silently reinterpreted.
  * @param {string[]} args
- * @returns {{sub: string, name?: string, flagArg?: string} | null}
+ * @returns {{sub: string, name?: string, flagArg?: string, cacheHoursArg?: string} | null}
  */
 export function parseKeysArgs(args) {
   const [sub, ...rest] = args;
@@ -51,17 +104,77 @@ export function parseKeysArgs(args) {
   if (sub === 'list') {
     return rest.length === 0 ? { sub } : null;
   }
-  const [name, flagName, flagArg, ...extra] = rest;
-  if (typeof name !== 'string' || name.startsWith('-') || extra.length > 0) {
+  const [name, ...flags] = rest;
+  if (typeof name !== 'string' || name.startsWith('-') || flags.length % 2 !== 0) {
     return null;
   }
-  if (flagName === undefined) {
-    return { sub, name };
+  /** @type {Record<string, string>} */
+  const values = {};
+  for (let i = 0; i < flags.length; i += 2) {
+    const flagName = flags[i];
+    const value = flags[i + 1];
+    if (!FLAGS[sub].includes(flagName) || Object.hasOwn(values, flagName) || value.length === 0 || value.startsWith('-')) {
+      return null;
+    }
+    values[flagName] = value;
   }
-  if (flagName !== FLAGS[sub] || typeof flagArg !== 'string' || flagArg.length === 0 || flagArg.startsWith('-')) {
+  if (values['--cache-hours'] !== undefined && values['--op'] === undefined) {
     return null;
   }
-  return { sub, name, flagArg };
+  const flagArg = sub === 'set' ? values['--op'] : values['--ref'];
+  return {
+    sub,
+    name,
+    ...(flagArg !== undefined ? { flagArg } : {}),
+    ...(values['--cache-hours'] !== undefined ? { cacheHoursArg: values['--cache-hours'] } : {}),
+  };
+}
+
+/**
+ * The cache time for `keys set --op` / `keys test`: `--cache-hours`, else `keys.cache_hours` from
+ * the project config, else 8. An invalid flag fails closed; an invalid `keys.cache_hours` fails
+ * closed when `strict` (`set --op`) and otherwise (`test`) gives the default with one warning. A
+ * config that cannot be loaded gives the default with one warning (`keys` must keep working beside
+ * an unrelated config error).
+ * @param {string|undefined} cacheHoursArg
+ * @param {string} cwd
+ * @param {typeof loadConfigFile} loadConfig
+ * @param {boolean} strict - true for `set --op`: an invalid `keys.cache_hours` refuses.
+ * @returns {Promise<{ok: true, hours: number, from: string|null, warning: string|null} | {ok: false, message: string}>}
+ *   `from` names where hours other than the default came from.
+ */
+async function cacheHoursFor(cacheHoursArg, cwd, loadConfig, strict) {
+  let fromFlag = null;
+  if (cacheHoursArg !== undefined) {
+    fromFlag = parseCacheHours(cacheHoursArg);
+    if (fromFlag === null) {
+      return { ok: false, message: `keys: --cache-hours must be ${CACHE_HOURS_RULE}\n` };
+    }
+  }
+  const loaded = await loadConfig(path.join(projectRootFor(cwd), DEFAULT_CONFIG_FILENAME));
+  /** @type {string|null} */
+  let warning = null;
+  /** @type {Record<string, any>} */
+  let cfg = {};
+  if (loaded.ok) {
+    cfg = loaded.config ?? {};
+  } else if (loaded.error !== 'not-found') {
+    // the error class only, never the loader's message; the WARN names the hours really used
+    const used = fromFlag !== null ? `${fromFlag} h from --cache-hours` : `the default ${DEFAULT_CACHE_HOURS} h`;
+    warning = `WARN keys: ${DEFAULT_CONFIG_FILENAME} cannot be loaded (${loaded.error}); caching for ${used}\n`;
+  }
+  const fromConfig = cacheHoursFrom(cfg);
+  if (fromConfig.problem !== null) {
+    if (strict) {
+      return { ok: false, message: `keys: ${fromConfig.problem} (${DEFAULT_CONFIG_FILENAME})\n` };
+    }
+    // fromConfig.hours is already the default here
+    warning = `WARN keys: ${fromConfig.problem} (${DEFAULT_CONFIG_FILENAME}); caching for the default ${fromConfig.hours} h\n`;
+  }
+  if (fromFlag !== null) {
+    return { ok: true, hours: fromFlag, from: '--cache-hours', warning };
+  }
+  return { ok: true, hours: fromConfig.hours, from: fromConfig.source === 'config' ? 'keys.cache_hours' : null, warning };
 }
 
 /** @param {string} name */
@@ -82,9 +195,11 @@ async function askHidden(name) {
  * @param {typeof import('../util/exec.mjs').exec} [deps.opExec] - runs `op item get` for an item ID or link.
  * @param {NodeJS.ProcessEnv} [deps.env]
  * @param {number} [deps.now]
+ * @param {string} [deps.cwd] - the project config is read at the project root of this directory.
+ * @param {typeof loadConfigFile} [deps.loadConfig]
  * @returns {Promise<number>}
  */
-export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, opExec, env = process.env, now = Date.now() }) {
+export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, opExec, env = process.env, now = Date.now(), cwd = process.cwd(), loadConfig = loadConfigFile }) {
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
 
@@ -93,7 +208,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(USAGE);
     return 2;
   }
-  const { sub, name } = parsed;
+  const { sub, name, cacheHoursArg } = parsed;
   let { flagArg } = parsed;
   try {
     if (name !== undefined) {
@@ -103,6 +218,21 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(`keys: ${e.message}\n`);
     return 2;
   }
+  // B84: the cache time is settled before any 1Password call (`set --op` and `test` may cache);
+  // only `set --op` refuses an invalid keys.cache_hours, `test` warns once and uses 8 h
+  /** @type {{hours: number, from: string|null}} */
+  let cache = { hours: DEFAULT_CACHE_HOURS, from: null };
+  if (sub === 'test' || (sub === 'set' && flagArg !== undefined)) {
+    const found = await cacheHoursFor(cacheHoursArg, cwd, loadConfig, sub === 'set');
+    if ('message' in found) {
+      err(found.message);
+      return 2;
+    }
+    if (found.warning !== null) {
+      err(found.warning);
+    }
+    cache = found;
+  }
   const fullRef = flagArg !== undefined && isOpRef(flagArg);
   const itemId = flagArg !== undefined && !fullRef ? opItemIdFromInput(flagArg) : null;
   if (sub === 'set' && flagArg !== undefined && !fullRef && itemId === null) {
@@ -147,6 +277,10 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     for (const row of rows) {
       out(`${row.name}\t${row.source}\t${row.backend}\t${formatExpiry(row.exp, now)}\n`);
     }
+    for (const row of rows) {
+      const warning = expiryWarning(row, now);
+      if (warning !== null) err(warning);
+    }
     return 0;
   }
 
@@ -157,7 +291,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
   }
 
   if (sub === 'test') {
-    const res = await resolveKey(name, { store, ref: flagArg, env, opRead, now });
+    const res = await resolveKey(name, { store, ref: flagArg, env, opRead, now, cacheHours: cache.hours });
     for (const e of res.errors) {
       err(`${name}: ${e}\n`);
     }
@@ -170,7 +304,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
   }
 
   if (flagArg !== undefined) {
-    const res = await readOpAndCache(name, flagArg, { store, opRead, now });
+    const res = await readOpAndCache(name, flagArg, { store, opRead, now, cacheHours: cache.hours });
     for (const e of res.errors) {
       err(`${name}: ${e}\n`);
     }
@@ -178,7 +312,8 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     if (res.value === null) {
       return 1;
     }
-    out(`stored ${name} in ${store.writer} (source=op, expires=${formatExpiry(res.exp, now)})\n`);
+    const from = cache.from === null ? '' : ` (cache ${cache.hours} h from ${cache.from})`;
+    out(`stored ${name} in ${store.writer} (source=op, expires=${formatExpiry(res.exp, now)})${from}\n`);
     return 0;
   }
 

package/src/cli/proof.mjs

@@ -16,6 +16,9 @@
  *                             which this block must hold; exit 0 proven, 1 not proven or refused).
  *                             The signed row carries `covers` (B20): the reverted sources, or
  *                             the test file for `assertion-deletion`.
+ *                             B87: a test file a `proof.runners` entry of the run snapshot matches
+ *                             runs with that entry's argv and is read from its JUnit report; the
+ *                             row and the output then carry `runner`, `env_keys` and `failed_tests`.
  *
  * `export` reads `proof.export.{link_dirs,copy_untracked}` from the workspace's `.code-forge.yml`
  * (defaults §1.3) and writes a signed `proof` row `isolation: export`; `lock`/`unlock` write
@@ -35,12 +38,14 @@ import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
 import { validateConfig } from '../config/validate.mjs';
 import { appendRow } from '../ledger/write.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
+import { proofRunners } from '../state/config-snapshot.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { redactJSON, writeSafe } from '../util/redact.mjs';
 import { DEFAULT_COPY_UNTRACKED, DEFAULT_LINK_DIRS, buildExport, exportDirFor, recordProof, removeExport } from '../proof/export.mjs';
 import { acquireProofLock, lockHolder, releaseProofLock } from '../proof/lock.mjs';
 import { MECHANISMS, readJournal, restoreJournal, runRedGreen } from '../proof/red-green.mjs';
+import { adapterPrecheck, runnerCovers, runnerHook, runnerTimeoutMs, selectRunner } from '../proof/runners.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { blockFileSet, repoRelativePath } from '../review/gate-check.mjs';
@@ -83,13 +88,15 @@ async function assertTestFile(dir, file) {
 
 /**
  * The test command filtered to one test: `node --test [--test-name-pattern ^<case>$] <file>`, run
- * with the Node that runs this CLI. Other stacks (Pest, Vitest…) have no filtered command here yet.
+ * with the Node that runs this CLI. Other stacks need a `proof.runners` entry (B87).
  * @param {string} file @param {string | undefined} testCase
  * @returns {string[]}
  * @throws {StateError} `unsupported-test`
  */
 function filteredTestArgv(file, testCase) {
-  if (!NODE_TEST_FILE.test(file)) throw new StateError('unsupported-test', 'only node:test files (.mjs, .cjs, .js) have a filtered test command in this version');
+  if (!NODE_TEST_FILE.test(file)) {
+    throw new StateError('unsupported-test', 'only node:test files (.mjs, .cjs, .js) have a filtered test command in this version — add a proof.runners entry for it (see proof.md §2)');
+  }
   const pattern = testCase === undefined ? [] : ['--test-name-pattern', `^${testCase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`];
   return [process.execPath, '--test', ...pattern, file];
 }
@@ -178,11 +185,14 @@ async function exportAndRecord({ runId, record, blockId, block, place, config, w
 
 /**
  * @param {string[]} args
- * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown},
+ *   precheck?: (entry: import('../proof/runners.mjs').RunnerEntry) => Promise<void>,
+ *   hook?: (entry: import('../proof/runners.mjs').RunnerEntry, test: {file: string, testCase?: string}) => import('../proof/runners.mjs').RunnerHook | null}} [deps] -
+ *   `precheck` and `hook` are test-only seams for the runner adapter's precheck and hook (B87)
  * @returns {Promise<number>}
  */
 export async function runProof(args, deps = {}) {
-  const { stdout = process.stdout, stderr = process.stderr } = deps;
+  const { stdout = process.stdout, stderr = process.stderr, precheck = adapterPrecheck, hook = runnerHook } = deps;
   const out = (/** @type {object} */ value) => writeSafe(stdout, `${redactJSON(value)}\n`);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
   const [sub, ...rest] = args;
@@ -270,9 +280,17 @@ export async function runProof(args, deps = {}) {
       const testCase = sep < 0 ? undefined : flags.test.slice(sep + 2);
       if (testCase === '') throw new StateError('usage', '--test <file>::<case> needs a case name after ::');
       const file = normalizeTestPath(sep < 0 ? flags.test : flags.test.slice(0, sep));
-      const argv = filteredTestArgv(file, testCase);
       const runId = flags.run;
       const record = await readRun(runId);
+      // B87: the runner comes from the run snapshot only, never the live file; no entry matches ⇒
+      // the built-in node:test command, or the refusal
+      const runners = proofRunners(record);
+      const entry = selectRunner(runners, file);
+      const runner = entry === null ? null : (hook(entry, { file, testCase }) ?? null);
+      // a matched entry is run by its hook or not at all: never a node:test fallback (no row, no precheck)
+      if (entry !== null && runner === null) throw new StateError('usage', `the ${entry.adapter} runner for ${file} has no hook; no proof was run`);
+      // exactly one of the two: the built-in argv without a runner, the runner (its own argv) with one
+      const how = runner === null || entry === null ? { argv: filteredTestArgv(file, testCase) } : { runner, timeoutMs: runnerTimeoutMs(entry) };
       const block = record.blocks?.[blockId];
       if (block?.status !== 'open') throw new StateError('no-block', `block ${blockId} is not open in run ${runId}`);
       const place = await proofPlace(runId, record, blockId, block);
@@ -292,17 +310,20 @@ export async function runProof(args, deps = {}) {
         owned: block.owned_files,
         matchOwned: (f) => ownsFile(block.owned_files, f, block.owned_kinds),
       });
-      const sources = mechanism === 'assertion-deletion' ? [] : changed.map((c) => c.file).filter((f) => f !== file && !TEST_PATH.test(f));
+      // B87: a file a configured runner matches is a test too, never a source
+      const sources = mechanism === 'assertion-deletion' ? [] : changed.map((c) => c.file).filter((f) => f !== file && !TEST_PATH.test(f) && !runnerCovers(runners, f));
       if (mechanism === 'revert' && sources.length === 0) {
         throw new StateError('usage', `block ${blockId} changed no non-test source file to revert — use --mechanism assertion-deletion`);
       }
+      // B87: the adapter's precheck runs before the export is built and before any file is reverted
+      if (entry !== null) await precheck(entry);
       const exp = isolation === 'export' ? await exportAndRecord({ runId, record, blockId, block, place, config, writeRow }) : null;
       if (exp) await assertTestFile(exp.dir, file); // the test must also be where it runs (owned, or tracked at base)
       const result = await runRedGreen({
         workDir: exp ? exp.dir : place.dir,
         repoDir: place.dir,
         base: place.base,
-        argv,
+        ...how,
         test: { file, ...(testCase === undefined ? {} : { case: testCase }), characterization: mechanism === 'assertion-deletion' },
         sources,
         isolation,
@@ -317,6 +338,11 @@ export async function runProof(args, deps = {}) {
       // still lands, `proven: false` and `red_kind: null`, and the verb exits 1.
       const red = result.red ?? null;
       const proven = result.proven === true && red !== null;
+      // B87: only when a runner really ran, names only — its adapter, the bounded failed test names
+      // and the env variable names (row and JSON alike); `failed_ids` stays in memory, and env
+      // values are never shown
+      const runnerFields =
+        runner === null ? {} : { runner: runner.adapter, failed_tests: red !== null && 'failed_tests' in red ? red.failed_tests : [], env_keys: [...runner.env_keys] };
       await recordProof({
         runId,
         writeRow,
@@ -332,6 +358,7 @@ export async function runProof(args, deps = {}) {
           proven,
           failed: red?.failed ?? null,
           covers,
+          ...runnerFields,
         },
       });
       out({
@@ -343,6 +370,7 @@ export async function runProof(args, deps = {}) {
         red_kind: red?.red_kind ?? null,
         green: result.green ?? null,
         proven,
+        ...runnerFields,
         ...(exp ? { export: { dir: exp.dir, restored: exp.restored, untracked: exp.untracked } } : {}),
       });
       return proven ? 0 : 1;

package/src/cli/review-file.mjs

@@ -10,8 +10,8 @@
  *                                                  status, kind: answers, file: source, by_file, answers}
  *   review-file <path> --block <id> --fresh        B75: re-run a cached result that never counted
  *
- * The same content enqueued again after an `unavailable` result is a fresh attempt (`retry: true`),
- * not the old result.
+ * The same content enqueued again after an `unavailable` or round-1 `split_required` result is a
+ * fresh attempt (`retry: true`), not the old result.
  * A done result that is not approved and carries open findings adds `fix_list` (what the coder
  * fixes before re-running `review-file <path>`, which is then a round-2 recheck of the fix hunks,
  * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) and (B73)
@@ -28,8 +28,9 @@
  * down on two polls in a row, and a worker whose pid is alive with a fresh heartbeat is never down
  * (`liveWorker`, B30). Output is one JSON line on stdout.
  * B75: `--fresh` drops the cached done marker of the file's current content and queues the ticket
- * again ONLY when that result never counted as a review: `stale`, `unavailable`, or `refused` with
- * `other-run`, `context-unreadable` or a `worktree-*` reason (an allow-list, fail closed). Any
+ * again ONLY when that result never counted as a review: `stale`, `unavailable`, round-1
+ * `split_required`, or `refused` with `other-run`, `context-unreadable` or a `worktree-*` reason
+ * (an allow-list, fail closed). Any
  * other cached result — a round ran (findings, approved, stopped), `review-state-lost`, an answers
  * result, an unknown status or reason, an unreadable marker — is refused `fresh-needs-reopen`
  * (exit 1, `exits: [block reopen, block waive]`, the marker kept byte-for-byte); a
@@ -129,8 +130,9 @@ const FRESH_REFUSED = new Set(['other-run', 'context-unreadable']);
 
 /**
  * B75: may `--fresh` drop this cached result? An allow-list, fail closed: `rerun` only for a
- * result that never counted as a review — `stale`, `unavailable`, or `refused` with a reason that
- * is not a verdict (`other-run`, `context-unreadable`, `worktree-*`) — whose marker names the same
+ * result that never counted as a review — `stale`, `unavailable`, round-1 `split_required`, or
+ * `refused` with a reason that is not a verdict (`other-run`, `context-unreadable`, `worktree-*`)
+ * — whose marker names the same
  * status. `tampered` for `refused review-state-tampered`; `counted` for everything else (a round
  * ran, `review-state-lost`, an answers result, an unknown status or reason, an unreadable marker or
  * result).
@@ -145,7 +147,7 @@ export function freshVerdict(text, result) {
     return 'counted';
   }
   if (result === null || marker === null || typeof marker !== 'object' || marker.status !== result.status) return 'counted';
-  if (result.status === 'stale' || result.status === 'unavailable') return 'rerun';
+  if (result.status === 'stale' || result.status === 'unavailable' || result.status === 'split_required') return 'rerun';
   if (result.status !== 'refused' || typeof result.reason !== 'string') return 'counted';
   if (result.reason === 'review-state-tampered') return 'tampered';
   return FRESH_REFUSED.has(result.reason) || result.reason.startsWith('worktree-') ? 'rerun' : 'counted';
@@ -166,10 +168,11 @@ export const FRESH_EXITS = Object.freeze(['block reopen', 'block waive']);
  * crash between the drop and the enqueue leaves only a re-runnable pending ticket. Anything else is refused and the marker kept byte-for-byte:
  * `fresh-needs-reopen` (names `block reopen` and `block waive`) or `fresh-tampered` (names only
  * the owner's `block close --no-require-reviews`; reopen refuses a tampered state).
- * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf}} opts
+ * B110: a plain cached round-1 `split_required` uses the same claim, with `retry: true`.
+ * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean}} opts
  * @returns {number} the exit code.
  */
-function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf }) {
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false }) {
   const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
   const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
   /** @type {'rerun' | 'tampered' | 'counted'} */
@@ -210,7 +213,7 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
     // dropped: queue it again now (a crash right here leaves a pending ticket with no marker, which
     // the next review-file queues anyway); gone: another caller took the marker, a normal enqueue
     const queued = enqueue({ repoRoot, run, block, file, ...where });
-    say(outcome === 'dropped' ? { ...queued, fresh: true } : queued);
+    say(outcome === 'dropped' ? { ...queued, ...(retry ? { retry: true } : { fresh: true }) } : queued);
     return 0;
   }
   if (verdict === 'tampered') {
@@ -223,7 +226,7 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
     ticket,
     file,
     exits: [...FRESH_EXITS],
-    message: `fresh-needs-reopen: the cached result of ${file} counts as a review (or cannot be read, or kept changing under the claim); --fresh re-runs only stale, unavailable or refused other-run/worktree-*/context-unreadable results; the human's ways out are block reopen and block waive; the cached result was kept`,
+    message: `fresh-needs-reopen: the cached result of ${file} counts as a review (or cannot be read, or kept changing under the claim); --fresh re-runs only stale, unavailable, round-1 split_required or refused other-run/worktree-*/context-unreadable results; the human's ways out are block reopen and block waive; the cached result was kept`,
   });
   return 1;
 }
@@ -410,6 +413,9 @@ export async function runReviewFile(args, deps = {}) {
     const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
     if (flags.fresh === true) return freshTicket({ repoRoot, run: worker.run, block, file, where, say, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     const queued = enqueue({ repoRoot, run: worker.run, block, file, ...where });
+    if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'split_required') {
+      return freshTicket({ repoRoot, run: worker.run, block, file, where, say, retry: true, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
+    }
     if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
       // `unavailable` is never approval AND never final: drop the done marker so the worker runs
       // the ticket again (the fix loop re-runs its pending round); the signed result is replaced.

package/src/cli/spawn.mjs

@@ -6,6 +6,12 @@
  * on stdout; the `level=… provider=… model=… effort=… fallback_step=…` line goes to stderr.
  * Exit codes: 0 ok / started, 1 failed (timeout, bad output, refused), 2 usage, 3 unavailable
  * (every step of the ladder reported unavailability).
+ *
+ * B93: with `--role coder --run <id>` of a recorded run, `coder.sandbox` in the live config must
+ * equal the run-start config snapshot's: a value that differs refuses the session
+ * (`sandbox-changed`, exit 1) before anything is spawned. Other roles never read the key and are
+ * not checked. A record from before snapshots, a run id with no record, or no `--run` uses the
+ * live config. A record that cannot be read is `run-unreadable` (exit 2).
  */
 
 import { readFile } from 'node:fs/promises';
@@ -14,6 +20,8 @@ import { loadProjectConfig, projectRootFor, slugFor } from '../config/load.mjs';
 import { ROLES, runRootFor, SessionError, spawnSession } from '../session/spawn.mjs';
 import { intFlag, parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { canonicalJSON, coderSandbox } from '../state/config-snapshot.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
 /**
@@ -46,6 +54,36 @@ export function exitCodeFor(result) {
   return result.status === 'unavailable' ? 3 : 1;
 }
 
+/** The SessionError codes that are a refusal (exit 1), not a usage error (exit 2). */
+const REFUSED_CODES = new Set(['forbidden', 'sandbox-changed', 'sandbox-dir-refused']);
+
+/**
+ * B93: for `--role coder --run <id>`, the live config, after checking that its `coder.sandbox`
+ * equals the run-start snapshot's (the key is fixed for the run). The value is the same, so the
+ * live config is what the session builds from. A run id with no record, or a record from before
+ * snapshots (no run-start value), uses the live config unchecked.
+ * @param {Record<string, any>} live @param {string} runId
+ * @returns {Promise<Record<string, any>>}
+ * @throws {SessionError} `sandbox-changed` when the live value differs from the snapshot's;
+ *   `run-unreadable` when the run record exists but cannot be read, parsed or understood.
+ * @throws {StateError} `config-snapshot` when the snapshot in force does not match its hash.
+ */
+async function checkRunSandbox(live, runId) {
+  let pinned;
+  try {
+    pinned = coderSandbox(await readRun(runId));
+  } catch (err) {
+    if (err instanceof StateError && err.code === 'no-run') return live; // no recorded run: the live config
+    if (err instanceof StateError) throw err; // e.g. config-snapshot: named, exit 2
+    throw new SessionError('run-unreadable', `run-unreadable: the record of run ${runId} cannot be read, so coder.sandbox cannot be checked against the run start`);
+  }
+  if (!pinned.snapshot) return live; // a run from before snapshots: no run-start value to hold to
+  if (canonicalJSON(pinned.sandbox ?? null) !== canonicalJSON(live?.coder?.sandbox ?? null)) {
+    throw new SessionError('sandbox-changed', `sandbox-changed: coder.sandbox in the live config differs from the run ${runId} snapshot — put it back, or end the run and start a new one`);
+  }
+  return live;
+}
+
 /**
  * @param {string[]} args
  * @param {import('../session/spawn.mjs').SessionDeps & {stdout?: {write: (s: string) => unknown}}} [deps]
@@ -67,9 +105,12 @@ export async function runSpawn(args, deps = {}) {
       writeSafe(stderr, `spawn: ${loaded.message}\n`);
       return 2;
     }
-    const cfg = loaded.config;
     const timeout = intFlag(flags.timeout, 'timeout');
     const schema = typeof flags.schema === 'string' ? await readJSONFlag(flags.schema, 'schema') : undefined;
+    // the run id is checked (and its temp root made) before the run record is read
+    const runRootDir = typeof flags.run === 'string' ? runRootFor(flags.run, loaded.config?.tmp?.root) : undefined;
+    // B93: only a coder reads coder.sandbox, so only a coder session is held to the run-start value
+    const cfg = typeof flags.run === 'string' && flags.role === 'coder' ? await checkRunSandbox(loaded.config, flags.run) : loaded.config;
     const result = await spawnSession(
       {
         cfg,
@@ -80,7 +121,7 @@ export async function runSpawn(args, deps = {}) {
         schema,
         timeoutMs: timeout === undefined ? undefined : timeout * 1000,
         background: flags.background === true,
-        runRoot: typeof flags.run === 'string' ? runRootFor(flags.run, cfg?.tmp?.root) : undefined,
+        runRoot: runRootDir,
         run: typeof flags.run === 'string' ? flags.run : undefined,
         block: typeof flags.block === 'string' ? flags.block : undefined,
         slug: slugFor(cfg, root),
@@ -93,7 +134,7 @@ export async function runSpawn(args, deps = {}) {
   } catch (err) {
     if (err instanceof StateError || err instanceof SessionError) {
       writeSafe(stderr, `spawn: ${/** @type {Error} */ (err).message}\n`);
-      return err instanceof SessionError && err.code === 'forbidden' ? 1 : 2;
+      return err instanceof SessionError && REFUSED_CODES.has(err.code) ? 1 : 2;
     }
     throw err;
   }