@codedology/code-forge 0.8.0 → 0.10.0

package/src/cli/review-file.mjs

@@ -5,12 +5,17 @@
  *   review-file --wait <ticket> [--max <90s>]      poll; prints {ticket, status: done, result} or
  *                                                  {ticket, status: pending, reason: wait_timeout}
  *                                                  when --max elapses (the review is still running)
+ *   review-file <answering file> --block <id> --answers <ids> --of <source> [--run <id>]
+ *                                                  B71: enqueue an answers ticket; prints {ticket,
+ *                                                  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.
  * 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`, …) — the coder
+ * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) and (B73)
+ * `exits: ["block reopen", "block waive", "review-file --answers", "re-decompose"]` — the coder
  * stops and reports; only the orchestrator and the human act on it. A `split_required` result
  * (the packet is over `review.budgets.full_in`) adds `stop: split_required` with `tokens_in` and
  * `budget` (always; null when unknown) and a Markdown `section` — never for another result (B54); a Markdown file gets there only when one of its sections alone is too large.
@@ -22,6 +27,15 @@
  * `===BLOCK <id> FAILED: worker down===`. While waiting, `worker_down` needs the worker to look
  * 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
+ * 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
+ * `review-state-tampered` one is refused `fresh-tampered` (names only `block close
+ * --no-require-reviews`). No cached result: a normal enqueue. A coder may run it; it never
+ * re-rolls a counted round and writes no ledger row.
  * Exit codes: 0 queued/done/pending, 1 bad-path or another refusal, 2 usage, 3 worker_down.
  *
  * B62b: the queue and the worker are always the MAIN tree's (`mainRootOf`), also when the coder
@@ -35,19 +49,38 @@
  * from, which is the block's tree when the coder works there. A record naming a worktree that is
  * gone or malformed is refused (exit 1, `reason: worktree-missing|worktree-malformed|…`), and
  * nothing is queued.
+ *
+ * B71: `--answers <id,id,…> --of <source>` (1 to 10 finding ids, comma-separated) asks the worker
+ * whether the change in the positional file (the answering file) resolves those open findings of
+ * `<source>`. It is refused before anything is queued — exit 2 `usage` for a missing `--of`, no
+ * ids, more than 10 ids or a malformed id; exit 1 `answers-same-file` when both name one file,
+ * `answers-not-owned` when the run record says the block does not own both, `answers-not-open`
+ * when an id is not open on the source at its current hash (not named by the latest refusal or
+ * cap row there, or already waived or answered; these two pre-checks read what this process can read, unverified, and are skipped when the run
+ * record cannot be opened here). The worker checks all of it again with the signed rows; that check
+ * is the one that counts. Its done result has `status: answers` and the coder-facing `answers:
+ * [{id, verdict: resolved|not_resolved, reason}]` instead of a fix list; a resolved id is a signed
+ * `review.answered` row the close counts until either file changes. The answering file still
+ * needs its own review.
  */
 
 import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { enqueue, isDone, liveWorker, queueDir } from '../worker/queue.mjs';
-import { assertBlockId, assertInsideRoot, assertTicketId, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { answersTicketId, assertAnswers, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { namedOnHash } from '../review/gate-check.mjs';
+import { STOP_EXITS } from '../review/stop-exits.mjs';
+import { ownsFile } from '../state/registry.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
-const USAGE = 'usage: code-forge review-file <path> --block <id> [--run <id>] | review-file --wait <ticket> [--max <seconds>s]\n';
+const USAGE =
+  'usage: code-forge review-file <path> --block <id> [--run <id>] [--fresh] | review-file --wait <ticket> [--max <seconds>s]\n' +
+  '       code-forge review-file <answering file> --block <id> --answers <id,id,…> --of <source> [--run <id>]\n';
 
 export const DEFAULT_WAIT_MS = 90_000;
 const POLL_MS = 200;
@@ -69,15 +102,132 @@ export function parseMax(raw) {
  */
 function doneResult(repoRoot, ticket) {
   try {
-    const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
-    const rel = typeof marker.result === 'string' ? marker.result : '';
+    return resultOfMarker(repoRoot, readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} repoRoot @param {string} text - a done marker's text
+ * @returns {Record<string, any> | null} the worker's result it names (unverified), or null.
+ */
+function resultOfMarker(repoRoot, text) {
+  try {
+    const marker = JSON.parse(text);
+    const rel = typeof marker?.result === 'string' ? marker.result : '';
     if (!rel.startsWith(`.code-forge${path.sep}reviews${path.sep}`) || rel.split(path.sep).includes('..')) return null;
-    return JSON.parse(readFileSync(path.join(repoRoot, rel), 'utf8'));
+    const result = JSON.parse(readFileSync(path.join(repoRoot, rel), 'utf8'));
+    return result !== null && typeof result === 'object' && !Array.isArray(result) ? result : null;
   } catch {
     return null;
   }
 }
 
+/** B75: the refused reasons that are not a verdict on the content (`--fresh` re-runs them). */
+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
+ * 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).
+ * @param {string} text - the done marker's text @param {Record<string, any> | null} result
+ * @returns {'rerun' | 'tampered' | 'counted'}
+ */
+export function freshVerdict(text, result) {
+  let marker;
+  try {
+    marker = JSON.parse(text);
+  } catch {
+    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 !== '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';
+}
+
+/** B75: how many times --fresh classifies a marker that changed under its claim. */
+const FRESH_ATTEMPTS = 3;
+
+/** B75: the ways out a counted result names (human-only; a coder stops and reports). */
+export const FRESH_EXITS = Object.freeze(['block reopen', 'block waive']);
+
+/**
+ * B75: `review-file <path> --block <id> --fresh`. No done marker: a normal enqueue. The marker is
+ * read and classified IN PLACE; only a cached result that never counted is then claimed by
+ * `dropDoneIf` (rename, then a byte compare with what was classified) and the ticket queued again.
+ * A marker that changed under the claim is restored (link only) and classified again, at most
+ * {@link FRESH_ATTEMPTS} times. The queue has no lock: the rename claim is the exclusion, and a
+ * 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
+ * @returns {number} the exit code.
+ */
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf }) {
+  const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
+  const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
+  /** @type {'rerun' | 'tampered' | 'counted'} */
+  let verdict = 'counted';
+  // a marker that changed under the claim is classified again; bounded, then refused (fail closed)
+  for (let attempt = 0; attempt < FRESH_ATTEMPTS; attempt += 1) {
+    /** @type {Buffer | null} */
+    let bytes;
+    try {
+      bytes = readFileSync(markerPath);
+    } catch (err) {
+      // no marker: a normal enqueue; a marker that exists but cannot be read is never dropped
+      bytes = /** @type {{code?: unknown}} */ (err)?.code === 'ENOENT' ? null : Buffer.alloc(0);
+    }
+    if (bytes === null) {
+      say(enqueue({ repoRoot, run, block, file, ...where }));
+      return 0;
+    }
+    // classified IN PLACE: a refusal never moves, renames or touches the marker
+    const text = bytes.toString('utf8');
+    verdict = freshVerdict(text, resultOfMarker(repoRoot, text));
+    if (verdict !== 'rerun') break;
+    /** @type {unknown} */
+    let outcome;
+    try {
+      outcome = dropDone(repoRoot, ticket, bytes);
+    } catch (err) {
+      // a named refusal passes through; any other throw is named here, never echoed
+      if (err instanceof WorkerError) throw err;
+      throw new WorkerError('fresh-claim-failed', `the claim of the cached result of ${file} failed; nothing was queued`);
+    }
+    if (outcome === 'changed') {
+      verdict = 'counted';
+      continue;
+    }
+    // an allow-list of outcomes: anything else is refused and nothing is queued
+    if (outcome !== 'dropped' && outcome !== 'gone') throw new WorkerError('fresh-claim-unknown', `the claim of the cached result of ${file} gave an unknown outcome; nothing was queued`);
+    // 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);
+    return 0;
+  }
+  if (verdict === 'tampered') {
+    say({ status: 'refused', reason: 'fresh-tampered', ticket, file, exits: ['block close --no-require-reviews'], message: `fresh-tampered: the cached result of ${file} is review-state-tampered (a security event, not a stop); only the owner's block close --no-require-reviews gets past it; the cached result was kept` });
+    return 1;
+  }
+  say({
+    status: 'refused',
+    reason: 'fresh-needs-reopen',
+    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`,
+  });
+  return 1;
+}
+
 /**
  * B62b: where the block `block` of run `runId` keeps its content, from the run record (read from
  * the user's state dir, `~/.code-forge/runs`, whatever the current directory): `{top}` with the
@@ -112,7 +262,63 @@ async function blockTreeOf(runId, block) {
 }
 
 /**
- * The coder-facing summary of a done result: the fix list and the stop reason, when any.
+ * B71: the coder-side pre-checks of an answers ticket (fast refusal only): with a run record this
+ * process can open, the block must own both files and every id must be open on the source's
+ * current hash — named by the latest refusal or cap row there, not waived or answered yet — read by
+ * the close's rules over unverified rows ({@link namedOnHash}). A record or ledger that
+ * cannot be read here skips the check it needs: the worker re-checks everything with signed rows.
+ * The rows of the ticket this request gets do not close an id (the retry of an attempt whose
+ * ledger write failed part way). `treeName`: the ticket's tree (null in the main tree).
+ * @param {{runId: string, block: string, file: string, byFile: string, tree: string, answers: string[], treeName: string | null}} opts
+ * @throws {WorkerError} `answers-not-owned`, `answers-not-open`
+ */
+async function answersPrecheck({ runId, block, file, byFile, tree, answers, treeName }) {
+  let record;
+  try {
+    record = await readRun(runId);
+  } catch {
+    return;
+  }
+  const entry = record?.blocks?.[block];
+  if (!entry || typeof entry !== 'object') return;
+  const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
+  if (!ownsFile(owned, file, entry.owned_kinds) || !ownsFile(owned, byFile, entry.owned_kinds)) {
+    throw new WorkerError('answers-not-owned', `block ${block} does not own both ${byFile} and ${file}; nothing was queued`);
+  }
+  let rows;
+  try {
+    rows = await readAllRows(record.project);
+  } catch {
+    return;
+  }
+  const hash = contentHash(tree, file);
+  const current = new Map([
+    [file, hash],
+    [byFile, contentHash(tree, byFile)],
+  ]);
+  const by_hash = /** @type {string} */ (current.get(byFile));
+  const ticket = answersTicketId({ run: runId, block, file, content_hash: hash, by_file: byFile, by_hash, answers, tree: treeName });
+  const named = namedOnHash({ block, runId, rows, file, hash, current, ticket });
+  const missing = answers.filter((id) => !named.has(id));
+  if (missing.length > 0) throw new WorkerError('answers-not-open', `${missing.join(', ')} is not an open finding of ${file} at its current content; nothing was queued`);
+}
+
+/**
+ * B71: the `--answers` list: comma-separated finding ids, 1 to {@link MAX_ANSWERS}.
+ * @param {unknown} raw @returns {string[]}
+ * @throws {WorkerError} `usage`
+ */
+function answersOf(raw) {
+  if (typeof raw !== 'string') throw new WorkerError('usage', '--answers needs finding ids');
+  const ids = raw.split(',');
+  if (ids.length > MAX_ANSWERS) throw new WorkerError('usage', `--answers takes at most ${MAX_ANSWERS} finding ids`);
+  if (new Set(ids).size !== ids.length) throw new WorkerError('usage', '--answers names a finding id twice');
+  return assertAnswers(ids);
+}
+
+/**
+ * The coder-facing summary of a done result: the fix list and the stop reason, when any. B71: an
+ * answers result gives `answers: [{id, verdict, reason}]` instead.
  * @param {Record<string, any> | null} result
  * @returns {Record<string, any>}
  */
@@ -120,6 +326,10 @@ export function fixList(result) {
   if (!result || result.approved === true) return {};
   /** @type {Record<string, any>} */
   const out = {};
+  if (result.kind === 'answers' || result.status === 'answers') {
+    if (Array.isArray(result.findings)) out.answers = result.findings.map((/** @type {Record<string, any>} */ f) => ({ id: f?.id ?? null, verdict: f?.verdict ?? 'not_resolved', reason: f?.reason ?? '' }));
+    return out;
+  }
   if (Array.isArray(result.findings) && result.findings.length > 0) {
     out.fix_list = result.findings.map((/** @type {Record<string, any>} */ f) => ({
       id: f?.id ?? null,
@@ -129,8 +339,11 @@ export function fixList(result) {
       fix: f?.fix ?? '',
     }));
   }
-  if (typeof result.stopped === 'string') out.stop = result.stopped;
-  else if (result.status === 'split_required') out.stop = 'split_required';
+  if (typeof result.stopped === 'string') {
+    out.stop = result.stopped;
+    // B73: a stopped file names its ways out (never a refused or tampered state: no `stopped`)
+    out.exits = [...STOP_EXITS];
+  } else if (result.status === 'split_required') out.stop = 'split_required';
   // B54: a split_required stop (only) says how large the packet was, the budget, and the section
   if (out.stop === 'split_required') {
     const fin = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
@@ -141,7 +354,7 @@ export function fixList(result) {
 
 /**
  * @param {string[]} args
- * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number}} [deps]
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number, dropDone?: typeof dropDoneIf}} [deps] - `dropDone`: B75's claim, for tests.
  * @returns {Promise<number>}
  */
 export async function runReviewFile(args, deps = {}) {
@@ -150,12 +363,12 @@ export async function runReviewFile(args, deps = {}) {
   const say = (/** @type {Record<string, any>} */ obj) => writeSafe(stdout, `${JSON.stringify(obj)}\n`);
   const cwd = deps.cwd ?? process.cwd();
   try {
-    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max'] });
+    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max', 'answers', 'of'], booleans: ['fresh'] });
     // the queue and the worker: the main tree, also from inside a block's worktree
     const repoRoot = await mainRootOf(cwd);
 
     if (typeof flags.wait === 'string') {
-      if (positionals.length > 0 || flags.block !== undefined) throw new WorkerError('usage', '--wait takes only a ticket and --max');
+      if (positionals.length > 0 || flags.block !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true) throw new WorkerError('usage', '--wait takes only a ticket and --max');
       const ticket = assertTicketId(flags.wait);
       const maxMs = flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max);
       const deadline = Date.now() + maxMs;
@@ -181,6 +394,8 @@ export async function runReviewFile(args, deps = {}) {
 
     if (positionals.length !== 1 || typeof flags.block !== 'string' || flags.max !== undefined) throw new WorkerError('usage', 'give one path and --block');
     const block = assertBlockId(flags.block);
+    if (flags.fresh === true && (flags.answers !== undefined || flags.of !== undefined)) throw new WorkerError('usage', '--fresh takes no --answers or --of');
+    if (flags.answers !== undefined || flags.of !== undefined) return await enqueueAnswersTicket({ flags, answering: positionals[0], block, cwd, repoRoot, say });
     const file = normalizeRequestPath(positionals[0], cwd, await repoRootOf(cwd));
     const worker = liveWorker(repoRoot);
     if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
@@ -193,6 +408,7 @@ export async function runReviewFile(args, deps = {}) {
     const tree = recorded === null ? await repoRootOf(cwd) : (recorded.top ?? repoRoot);
     assertInsideRoot(tree, file); // the path, re-checked in the tree its content is read from
     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 === 'unavailable') {
       // `unavailable` is never approval AND never final: drop the done marker so the worker runs
@@ -214,6 +430,41 @@ export async function runReviewFile(args, deps = {}) {
   }
 }
 
+/**
+ * B71: `review-file <answering file> --block <id> --answers <ids> --of <source>`.
+ * @param {{flags: Record<string, any>, answering: string, block: string, cwd: string, repoRoot: string, say: (obj: Record<string, any>) => unknown}} opts
+ * @returns {Promise<number>}
+ * @throws {WorkerError}
+ */
+async function enqueueAnswersTicket({ flags, answering, block, cwd, repoRoot, say }) {
+  if (typeof flags.of !== 'string' || flags.of.length === 0) throw new WorkerError('usage', '--answers needs --of <source>');
+  const answers = answersOf(flags.answers);
+  const top = await repoRootOf(cwd);
+  const byFile = normalizeRequestPath(answering, cwd, top);
+  const file = normalizeRequestPath(flags.of, cwd, top);
+  if (byFile === file) throw new WorkerError('answers-same-file', `${file} cannot answer its own findings: give the file that resolves them`);
+  const worker = liveWorker(repoRoot);
+  if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
+    say({ status: 'worker_down', file });
+    return 3;
+  }
+  const recorded = await blockTreeOf(worker.run, block);
+  const tree = recorded === null ? top : (recorded.top ?? repoRoot);
+  assertInsideRoot(tree, file);
+  assertInsideRoot(tree, byFile);
+  const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
+  await answersPrecheck({ runId: worker.run, block, file, byFile, tree, answers, treeName: where.tree === undefined ? null : realpathSync(tree) });
+  const opts = { repoRoot, run: worker.run, block, file, byFile, answers, ...where };
+  const queued = enqueueAnswers(opts);
+  if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
+    rmSync(path.join(queueDir(repoRoot), `${queued.ticket}.done`), { force: true });
+    say({ ...enqueueAnswers(opts), kind: 'answers', retry: true });
+    return 0;
+  }
+  say({ ...queued, kind: 'answers' });
+  return 0;
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function run(args) {
   return runReviewFile(args);

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;
   }