@codedology/code-forge 0.8.0 → 0.10.0

package/src/config/validate.mjs

@@ -4,7 +4,7 @@
  *
  *  1. **Schema validation** (Ajv, draft 2020-12, `additionalProperties: false` almost everywhere)
  *     catches shape errors: unknown keys, wrong types, missing required fields.
- *  2. **Domain rules** (`DOMAIN_RULES` below, 16 of them as of B32) catch things no JSON Schema can express:
+ *  2. **Domain rules** (`DOMAIN_RULES` below, 20 of them as of B93) catch things no JSON Schema can express:
  *     cross-field comparisons (two levels resolving to the same tuple), a value that needs a
  *     second config value to be reachable (`second_levels.L2.provider` vs. the effective L2
  *     provider) and rules that reach outside the config object entirely (is a CLI on PATH, is a
@@ -36,6 +36,10 @@
  *  14  caps-coders-exceeds-cap               WARN   (v1.3/R10/B1.1: caps.coders > 2)
  *  15  effort-not-valid-for-provider         ERROR  (B29: a level's / fallback's effort vs. its provider)
  *  16  closed-book-on-openai                 WARN   (B32: Codex has no no-tools mode)
+ *  17  proof-runners-invalid                 ERROR  (B87: a proof.runners entry: adapter, match, argv tokens, env, timeout_s)
+ *  18  review-routes-invalid                 ERROR  (B90: a review.routes rule: level, duplicate level+min_lines, provider vs. the second reviewer)
+ *  19  sandbox-dir-refused                   ERROR  (B93: a coder.sandbox.add_dirs entry opens /, the home dir, a secret dir or the run temp tree)
+ *  20  sandbox-dirs-unused                   WARN   (B93: coder.sandbox.add_dirs set under a profile other than toolchain)
  *
  * **B1.2 (v1.3, Q16 cut) removed rule:** `proof-tool-absent-for-high-tier` (formerly #13) — the
  * key it warned about (`proof.tiers.high.tool`) left the schema in the same amendment, along with
@@ -66,6 +70,11 @@ import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
+// B90: the routing module's own level list and provider resolution, so rules 16 and 18 check a
+// route with exactly the provider the worker spawns it on (they cannot drift)
+import { ROUTE_LEVELS, ruleProvider } from '../review/route.mjs';
+import { DEFAULT_SANDBOX_PROFILE, SANDBOX_PROFILES, sandboxDirRefusals, SANDBOX_DIR_REFUSED } from '../engines/sandbox-dirs.mjs';
+import { tmpBase } from '../util/tmp.mjs';
 import { looksLikeSecret, maskSecretTokens, SECRET_MASK, secretTokensIn } from './secret-patterns.mjs';
 
 /**
@@ -781,6 +790,21 @@ function checkClosedBookOnOpenai(cfg) {
   if (cfg?.review?.multimodel === true && isNoClosedBookProvider(effectiveSecondL2Provider(cfg))) {
     where.push('review.second_levels.L2 (else review.second_provider)');
   }
+  // B90: a review.routes rule replaces an L2/L3 level for a big file — the same closed-book limit
+  routeRulesOf(cfg).forEach((rule, i) => {
+    if (!isPlainObject(rule)) return;
+    if (isNoClosedBookProvider(ruleProvider(cfg, rule))) where.push(`review.routes[${i}]`);
+    if (Array.isArray(rule.fallback)) {
+      rule.fallback.forEach((fb, j) => {
+        if (isNoClosedBookProvider(fb?.provider)) where.push(`review.routes[${i}].fallback[${j}]`);
+      });
+    }
+    // like the second reviewer's own check above: only with multimodel on, and with the same
+    // effective second provider (the rule's own, else second_levels.L2, else second_provider)
+    if (cfg?.review?.multimodel === true && isPlainObject(rule.second) && isNoClosedBookProvider(rule.second.provider ?? effectiveSecondL2Provider(cfg))) {
+      where.push(`review.routes[${i}].second`);
+    }
+  });
   // B32 opt-in: the same places, but the text says what the opt-in costs instead of "refused".
   const text = openBookCodexAllowed(cfg) ? OPEN_BOOK_CODEX_WARNING : CODEX_CLOSED_BOOK_REFUSAL;
   return where.map((key) => ({
@@ -790,11 +814,298 @@ function checkClosedBookOnOpenai(cfg) {
   }));
 }
 
+// ── 17. proof-runners-invalid (ERROR, B87) ──────────────────────────────────
+
+/**
+ * B87: the argv tokens each `proof.runners` adapter expands. A token is a whole argv item, never
+ * the command. `proof/runners.mjs` expands exactly these (proof may import config; config may not
+ * import proof).
+ */
+export const RUNNER_ADAPTER_TOKENS = Object.freeze({
+  junit: Object.freeze(['{test_file}', '{test_id}', '{test_filter}', '{report}']),
+  swift: Object.freeze(['{test_file}', '{test_id}', '{test_filter}', '{report}']),
+  // B102: the values come from the entry's `xcode` object; `{only_testing}` names the test and
+  // `{result_bundle}` is the fresh result bundle path code-forge reads
+  xcodebuild: Object.freeze(['{workspace}', '{project}', '{scheme}', '{destination}', '{only_testing}', '{result_bundle}']),
+});
+/** B87: the tokens that name the test; a `junit` or `swift` runner needs at least one (a proof must name its test). */
+export const RUNNER_TEST_TOKENS = Object.freeze(['{test_file}', '{test_id}', '{test_filter}']);
+/** B87: every token any adapter knows. */
+const ALL_RUNNER_TOKENS = Object.freeze(['{test_file}', '{test_id}', '{test_filter}', '{report}', '{workspace}', '{project}', '{scheme}', '{destination}', '{only_testing}', '{result_bundle}']);
+/** B102: the keys of an `xcodebuild` entry's `xcode` object, and the ones it must have. */
+export const XCODE_KEYS = Object.freeze(['workspace', 'project', 'scheme', 'destination', 'test_target']);
+const XCODE_REQUIRED = Object.freeze(['scheme', 'destination', 'test_target']);
+/** B102: the tokens an `xcodebuild` argv must have, and why. */
+const XCODE_REQUIRED_TOKENS = Object.freeze([
+  ['{scheme}', 'the xcodebuild adapter fills it from xcode.scheme'],
+  ['{destination}', 'the xcodebuild adapter fills it from xcode.destination, the one the precheck checks'],
+  ['{only_testing}', 'a proof must name its test'],
+  ['{result_bundle}', 'the xcodebuild adapter reads the result bundle code-forge places there'],
+]);
+/** B87: an item that is a whole `{word}` is read as a token. */
+const TOKEN_SHAPE = /^\{[a-z_]+\}$/;
+/** B87: the bounds of `proof.runners[].timeout_s`, in seconds. */
+const RUNNER_TIMEOUT_MIN_S = 60;
+const RUNNER_TIMEOUT_MAX_S = 7200;
+/** B87: the keys a runner entry may have (the schema's `additionalProperties: false`, as a rule). */
+const RUNNER_KEYS = Object.freeze(['match', 'adapter', 'argv', 'env', 'timeout_s', 'xcode']);
+/** B87: every token some adapter lists; with a bad adapter, an item outside it is still refused. */
+const ANY_ADAPTER_TOKENS = Object.freeze([...new Set(Object.values(RUNNER_ADAPTER_TOKENS).flat())]);
+/** B102: the report items and the test tokens of every adapter; a bad adapter's argv needs one of each. */
+const ANY_REPORT_TOKENS = Object.freeze(['{report}', '{result_bundle}']);
+const ANY_TEST_TOKENS = Object.freeze([...RUNNER_TEST_TOKENS, '{only_testing}']);
+
+/**
+ * Rule 17's messages for one runner entry. A message names the key path and the rule; it may name
+ * an env variable NAME or an unknown entry key (key paths), never a value (argv items, env values) — only the adapter's
+ * own token words, which are code-forge's. The argv checks run even when the adapter is bad, so
+ * one pass shows every error. `proof/runners.mjs` checks the snapshot's entries with it again
+ * before it runs one.
+ * @param {unknown} entry @param {number} i @returns {string[]}
+ */
+export function runnerMessages(entry, i) {
+  const at = `proof.runners[${i}]`;
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return [`${at} must be an object with match, adapter and argv`];
+  const runner = /** @type {Record<string, unknown>} */ (entry);
+  const messages = [];
+  const adapter = typeof runner.adapter === 'string' && Object.hasOwn(RUNNER_ADAPTER_TOKENS, runner.adapter) ? runner.adapter : null;
+  if (adapter === null) messages.push(`${at}.adapter must be one of: ${Object.keys(RUNNER_ADAPTER_TOKENS).join(', ')}`);
+  for (const key of Object.keys(runner)) {
+    if (!RUNNER_KEYS.includes(key)) messages.push(`${at}: ${JSON.stringify(key)} is not a runner key (${RUNNER_KEYS.join(', ')})`);
+  }
+  const match = runner.match;
+  if (!Array.isArray(match) || match.length === 0 || !match.every((glob) => typeof glob === 'string' && glob.length > 0)) {
+    messages.push(`${at}.match must be a non-empty list of globs`);
+  }
+  if (!isArgvArray(runner.argv)) {
+    messages.push(`${at}.argv must be a non-empty argv array of strings`);
+  } else {
+    const argv = /** @type {string[]} */ (runner.argv);
+    if (TOKEN_SHAPE.test(argv[0])) messages.push(`${at}.argv[0]: a token cannot be the command`);
+    // with a bad adapter, a token-shaped item is checked against every adapter's tokens instead;
+    // every other argv check still runs
+    const known = adapter === null ? null : RUNNER_ADAPTER_TOKENS[/** @type {keyof typeof RUNNER_ADAPTER_TOKENS} */ (adapter)];
+    argv.forEach((item, j) => {
+      if (item.includes('\0')) {
+        messages.push(`${at}.argv[${j}] contains a NUL character`);
+      } else if (j > 0 && TOKEN_SHAPE.test(item) && known !== null && !known.includes(item)) {
+        messages.push(`${at}.argv[${j}] is not a token of the ${adapter} adapter (${known.join(', ')})`);
+      } else if (j > 0 && TOKEN_SHAPE.test(item) && known === null && !ANY_ADAPTER_TOKENS.includes(item)) {
+        messages.push(`${at}.argv[${j}] is not a token of any adapter (${ANY_ADAPTER_TOKENS.join(', ')})`);
+      } else if (!TOKEN_SHAPE.test(item) && ALL_RUNNER_TOKENS.some((token) => item.includes(token))) {
+        messages.push(`${at}.argv[${j}]: a token must be a whole argv item (give it as its own item)`);
+      }
+    });
+    // the required tokens depend on the adapter; with a bad adapter, every adapter's report items
+    // and test tokens count, so an argv that names no report or no test is still refused
+    const items = argv.slice(1);
+    if (adapter === 'junit' || adapter === 'swift') {
+      if (!items.includes('{report}')) messages.push(`${at}.argv needs a {report} item (the ${adapter} adapter reads the report code-forge places there)`);
+      if (!items.some((item) => RUNNER_TEST_TOKENS.includes(item))) messages.push(`${at}.argv needs a test token (${RUNNER_TEST_TOKENS.join(', ')}): a proof must name its test`);
+    } else if (adapter === 'xcodebuild') {
+      for (const [token, why] of XCODE_REQUIRED_TOKENS) if (!items.includes(token)) messages.push(`${at}.argv needs a ${token} item (${why})`);
+    } else {
+      if (!items.some((item) => ANY_REPORT_TOKENS.includes(item))) messages.push(`${at}.argv needs a report item (${ANY_REPORT_TOKENS.join(', ')}): every adapter reads the report code-forge places there`);
+      if (!items.some((item) => ANY_TEST_TOKENS.includes(item))) messages.push(`${at}.argv needs a test token (${ANY_TEST_TOKENS.join(', ')}): a proof must name its test`);
+    }
+  }
+  messages.push(...xcodeMessages(runner, adapter, at));
+  if (runner.env !== undefined) {
+    if (runner.env === null || typeof runner.env !== 'object' || Array.isArray(runner.env)) {
+      messages.push(`${at}.env must be a map of variable names to string values`);
+    } else {
+      for (const [name, envValue] of Object.entries(runner.env)) {
+        if (!ENV_NAME.test(name)) messages.push(`${at}.env: ${JSON.stringify(name)} is not a variable name (letters, digits and _, not starting with a digit)`);
+        else if (typeof envValue !== 'string') messages.push(`${at}.env.${name} must be a string`);
+        else if (envValue.includes('\0')) messages.push(`${at}.env.${name} contains a NUL character`);
+      }
+    }
+  }
+  if (runner.timeout_s !== undefined) {
+    const t = runner.timeout_s;
+    if (typeof t !== 'number' || !Number.isInteger(t) || t < RUNNER_TIMEOUT_MIN_S || t > RUNNER_TIMEOUT_MAX_S) {
+      messages.push(`${at}.timeout_s must be a whole number of seconds from ${RUNNER_TIMEOUT_MIN_S} to ${RUNNER_TIMEOUT_MAX_S}`);
+    }
+  }
+  return messages;
+}
+
+/** @param {unknown} value @returns {boolean} */
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * B102: rule 17's messages for an entry's `xcode` object. An `xcodebuild` entry needs one; any other
+ * adapter refuses one. Its values are argv items of `xcodebuild`, so each is a non-empty string with
+ * no NUL that does not start with `-` (it would be read as an option). Messages name key paths only.
+ * @param {Record<string, unknown>} runner @param {string | null} adapter @param {string} at
+ * @returns {string[]}
+ */
+function xcodeMessages(runner, adapter, at) {
+  const xcode = runner.xcode;
+  if (xcode === undefined) return adapter === 'xcodebuild' ? [`${at}.xcode is required for the xcodebuild adapter (${XCODE_REQUIRED.join(', ')})`] : [];
+  if (adapter !== null && adapter !== 'xcodebuild') return [`${at}.xcode is only for the xcodebuild adapter`];
+  if (!isPlainObject(xcode)) return [`${at}.xcode must be an object with ${XCODE_REQUIRED.join(', ')}`];
+  const values = /** @type {Record<string, unknown>} */ (xcode);
+  const messages = [];
+  for (const key of Object.keys(values)) {
+    if (!XCODE_KEYS.includes(key)) messages.push(`${at}.xcode: ${JSON.stringify(key)} is not an xcode key (${XCODE_KEYS.join(', ')})`);
+  }
+  for (const key of XCODE_KEYS) {
+    const value = values[key];
+    if (value === undefined) {
+      if (XCODE_REQUIRED.includes(key)) messages.push(`${at}.xcode.${key} is required`);
+    } else if (typeof value !== 'string' || value.length === 0 || value.startsWith('-')) {
+      messages.push(`${at}.xcode.${key} must be a non-empty string that does not start with "-"`);
+    } else if (value.includes('\0')) {
+      messages.push(`${at}.xcode.${key} contains a NUL character`);
+    } else if (key === 'test_target' && value.includes('/')) {
+      messages.push(`${at}.xcode.test_target must be one target name, without "/"`);
+    }
+  }
+  if (values.workspace !== undefined && values.project !== undefined) messages.push(`${at}.xcode: give workspace or project, not both`);
+  // a {workspace} / {project} item and its xcode key come together: one without the other is a
+  // value xcodebuild would never see, or an argv item with no value
+  const argv = isArgvArray(runner.argv) ? /** @type {string[]} */ (runner.argv).slice(1) : null;
+  if (argv !== null) {
+    for (const key of ['workspace', 'project']) {
+      const token = `{${key}}`;
+      if (argv.includes(token) && values[key] === undefined) messages.push(`${at}.argv has ${token} but ${at}.xcode.${key} is not set`);
+      if (!argv.includes(token) && values[key] !== undefined) messages.push(`${at}.xcode.${key} is set but ${at}.argv has no ${token} item`);
+    }
+  }
+  return messages;
+}
+
+function checkProofRunnersInvalid(cfg) {
+  const runners = cfg?.proof?.runners;
+  if (runners === undefined) return [];
+  const messages = !Array.isArray(runners)
+    ? ['proof.runners must be a list of runner entries']
+    : runners.length === 0
+      ? ['proof.runners must list at least one runner (leave the key out for none)']
+      : runners.flatMap((entry, i) => runnerMessages(entry, i));
+  return messages.map((message) => ({ rule: 'proof-runners-invalid', severity: /** @type {const} */ ('error'), message }));
+}
+
+// ── 18. review-routes-invalid (ERROR, B90) ──────────────────────────────────
+
+/** @param {Record<string, any>} cfg @returns {any[]} the `review.routes` list, `[]` when it is not one. */
+function routeRulesOf(cfg) {
+  const routes = cfg?.review?.routes;
+  return Array.isArray(routes) ? routes : [];
+}
+
+/**
+ * B90: what the schema cannot say about `review.routes` — a level other than L2 or L3, two rules
+ * for the same level and `min_lines` (which one wins would be order-dependent), and, with
+ * `review.multimodel` on, an L2 rule whose provider (its own, else the top-level one) equals its
+ * own `second.provider`, or the second reviewer's effective L2 provider — the consensus slot B a
+ * routed ticket really runs with — (the consensus needs two providers on a big file too).
+ * Messages name key paths only, never a value.
+ * @param {Record<string, any>} cfg
+ */
+function checkReviewRoutesInvalid(cfg) {
+  const routes = cfg?.review?.routes;
+  if (routes === undefined || routes === null) return [];
+  /** @type {string[]} */
+  const messages = [];
+  if (!Array.isArray(routes)) {
+    messages.push('review.routes must be a list of rules');
+  } else {
+    /** @type {Map<string, number>} */
+    const seen = new Map();
+    const second = effectiveSecondL2Provider(cfg);
+    routes.forEach((rule, i) => {
+      const at = `review.routes[${i}]`;
+      if (!isPlainObject(rule)) {
+        messages.push(`${at} must be a rule object`);
+        return;
+      }
+      const level = rule.level ?? 'L2';
+      if (!ROUTE_LEVELS.includes(level)) {
+        messages.push(`${at}.level must be L2 or L3`);
+        return;
+      }
+      if (Number.isInteger(rule.min_lines)) {
+        const k = `${level}\0${rule.min_lines}`;
+        const first = seen.get(k);
+        if (first === undefined) seen.set(k, i);
+        else messages.push(`${at} has the same level and min_lines as review.routes[${first}]`);
+      }
+      if (cfg?.review?.multimodel === true && level === 'L2') {
+        // the provider the worker spawns this rule on: its own, else the top-level one (the rule
+        // REPLACES levels.L2, so levels.L2.provider is never inherited)
+        const first = ruleProvider(cfg, rule);
+        const own = isPlainObject(rule.second) ? rule.second.provider : undefined;
+        if (own !== undefined && first === own) {
+          // the rule's own second reviewer
+          messages.push(`${at}.provider (else provider) equals ${at}.second.provider — multimodel needs two different providers`);
+        } else if (second !== undefined && first === second) {
+          // the consensus slot B a routed ticket runs with (it keeps review.second_levels.L2)
+          messages.push(`${at}.provider (else provider) equals the second reviewer's effective L2 provider (review.second_levels.L2.provider, else review.second_provider) — multimodel needs two different providers`);
+        }
+      }
+    });
+  }
+  return messages.map((message) => ({ rule: 'review-routes-invalid', severity: /** @type {const} */ ('error'), message }));
+}
+
+// ── 19. sandbox-dir-refused (ERROR, B93) ────────────────────────────────────
+/**
+ * A `coder.sandbox.add_dirs` entry that is not absolute / `~/`, or that is `/`, the home dir, or
+ * is, holds or sits inside a secret dir (`~/.code-forge`, `~/.codex`, `~/.ssh`, …) or the run
+ * temp base (every run temp root and session CODEX_HOME live under it). One issue per refused
+ * entry; the message names the key path, never the value. The builder checks again at spawn.
+ * @param {Record<string, any>} cfg
+ * @returns {ValidationIssue[]}
+ */
+function checkSandboxDirRefused(cfg) {
+  const sandbox = isPlainObject(cfg.coder) ? cfg.coder.sandbox : undefined;
+  // a non-list add_dirs, or a non-string entry, is the schema layer's issue (fix round 1)
+  if (!isPlainObject(sandbox) || !Array.isArray(sandbox.add_dirs)) return [];
+  const dirs = /** @type {unknown[]} */ (sandbox.add_dirs);
+  /** @type {string[]} */
+  const extra = [];
+  try {
+    extra.push(tmpBase(isPlainObject(cfg.tmp) ? cfg.tmp.root ?? undefined : undefined));
+  } catch {
+    extra.push(tmpBase()); // a bad tmp.root is the schema's issue; the default base still counts
+  }
+  const nonStrings = new Set(dirs.flatMap((entry, i) => (typeof entry === 'string' ? [] : [`coder.sandbox.add_dirs[${i}]`])));
+  return sandboxDirRefusals(dirs, { extra })
+    .filter((r) => !nonStrings.has(r.keyPath))
+    .map((r) => ({
+      rule: SANDBOX_DIR_REFUSED,
+      severity: /** @type {const} */ ('error'),
+      message: `${r.keyPath} is refused — ${r.why}`,
+    }));
+}
+
+// ── 20. sandbox-dirs-unused (WARN, B93 fix round 1) ─────────────────────────
+/**
+ * `coder.sandbox.add_dirs` is set (a non-empty list) but the profile is not `toolchain`: only
+ * `toolchain` adds `--add-dir`, so the entries change nothing (rule 19 still refuses a bad one).
+ * The message names the key path and the profile, never a dir.
+ * @param {Record<string, any>} cfg
+ * @returns {ValidationIssue[]}
+ */
+function checkSandboxDirsUnused(cfg) {
+  const sandbox = isPlainObject(cfg.coder) ? cfg.coder.sandbox : undefined;
+  if (!isPlainObject(sandbox) || !Array.isArray(sandbox.add_dirs) || sandbox.add_dirs.length === 0) return [];
+  const profile = sandbox.profile ?? DEFAULT_SANDBOX_PROFILE;
+  if (profile === 'toolchain' || !SANDBOX_PROFILES.includes(profile)) return [];
+  return [{
+    rule: 'sandbox-dirs-unused',
+    severity: /** @type {const} */ ('warning'),
+    message: `coder.sandbox.add_dirs is set but coder.sandbox.profile is ${profile}, which does not use it — only toolchain adds --add-dir`,
+  }];
+}
+
 /**
- * The 16 domain rules paired with the exact `rule` id string each one emits — the single source
+ * The 20 domain rules paired with the exact `rule` id string each one emits — the single source
  * of truth both `DOMAIN_RULES` (below, what `validateConfig` runs) and the exported
  * `DOMAIN_RULE_IDS` are built from. `'schema'` (the ajv layer's own issues) is deliberately not
- * one of these 16 (B29 added rule 15, B32 rule 16). (B1.2/v1.3, Q16 cut: `proof-tool-absent-for-high-tier` removed, 15 -> 14.)
+ * one of these 20 (B29 added rule 15, B32 rule 16, B87 rule 17, B90 rule 18, B93 rules 19 and 20). (B1.2/v1.3, Q16 cut: `proof-tool-absent-for-high-tier` removed, 15 -> 14.)
  * @type {ReadonlyArray<{fn: (cfg: Record<string, any>, opts?: object) => ValidationIssue[], id: string}>}
  */
 const RULE_TABLE = Object.freeze([
@@ -814,12 +1125,16 @@ const RULE_TABLE = Object.freeze([
   { fn: checkCapsCodersExceedsCap, id: 'caps-coders-exceeds-cap' },
   { fn: checkEffortNotValidForProvider, id: 'effort-not-valid-for-provider' },
   { fn: checkClosedBookOnOpenai, id: 'closed-book-on-openai' },
+  { fn: checkProofRunnersInvalid, id: 'proof-runners-invalid' },
+  { fn: checkReviewRoutesInvalid, id: 'review-routes-invalid' },
+  { fn: checkSandboxDirRefused, id: 'sandbox-dir-refused' },
+  { fn: checkSandboxDirsUnused, id: 'sandbox-dirs-unused' },
 ]);
 
-/** The 16 domain rules, in the order documented above. */
+/** The 20 domain rules, in the order documented above. */
 const DOMAIN_RULES = Object.freeze(RULE_TABLE.map((entry) => entry.fn));
 
-/** The 16 rule ids `validateConfig` can emit, in `DOMAIN_RULES` order (see `RULE_TABLE`). */
+/** The 20 rule ids `validateConfig` can emit, in `DOMAIN_RULES` order (see `RULE_TABLE`). */
 export const DOMAIN_RULE_IDS = Object.freeze(RULE_TABLE.map((entry) => entry.id));
 
 /**

package/src/doctor/index.mjs

@@ -1,9 +1,9 @@
 /**
  * `code-forge doctor` (plan §2.3; block B13b): every row, in print order. `--quick` = the three
  * rows the skill's preflight needs (config, harness links, Jev key resolution); the full run adds
- * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, the provider CLI probes (presence,
- * version, flags, one call per role builder, isolation, path deny, Codex rules), the worker
- * start/stop, the signer key and the `signer: same-user boundary only` line.
+ * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, `review state` (B69), the provider
+ * CLI probes (presence, version, flags, one call per role builder, isolation, path deny, Codex
+ * rules), the worker start/stop, the signer key and the `signer: same-user boundary only` line.
  */
 
 import { randomBytes } from 'node:crypto';
@@ -13,8 +13,8 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkTmp, checkTools } from './local.mjs';
-import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
+import { checkCoderSandbox, configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
 
@@ -68,7 +68,9 @@ export async function runDoctor(opts = {}, deps = {}) {
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
   rows.push(...checkTmp(cfg));
+  rows.push(...(await checkReviewState(cfg)));
   rows.push(checkReviewConcurrency(cfg));
+  rows.push(...checkCoderSandbox(cfg)); // B93: no rows without coder.sandbox
   if (!cfg) {
     rows.push(row('probes', 'FAIL', 'probes', 'skipped: no valid config'));
     rows.push(SIGNER_ROW);

package/src/doctor/local.mjs

@@ -1,7 +1,8 @@
 /**
  * Doctor rows that need no provider CLI (plan §2.3; block B13b): config, harness links, Jev key
  * resolution (the three `--quick` rows), `code-forge` on PATH, Solo, gate commands, the live Jev
- * call, ledger writability and the `tmp` row. Every check returns rows; none throws.
+ * call, ledger writability, the `tmp` row and (B69) the `review state` row. Every check returns
+ * rows; none throws.
  */
 
 import { constants, readdirSync } from 'node:fs';
@@ -15,12 +16,18 @@ import { commandOnPath } from '../install/detect.mjs';
 import { installsPath, readInstalls, targetResolves } from '../install/link.mjs';
 import { missingTools } from '../install/tools.mjs';
 import { OP_MESSAGES } from '../keys/onepassword.mjs';
-import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
+import { cacheHoursFrom, createDefaultKeyStore, isTime, resolveKey } from '../keys/store.mjs';
 import { ledgerDir } from '../ledger/paths.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { DEFAULT_PROVIDER_CONCURRENCY, providerLimit } from '../session/spawn.mjs';
+import { snapshotFor } from '../state/config-snapshot.mjs';
+import { assertRunId, runsDir } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { loadKey } from '../state/signer.mjs';
 import { listEntries } from '../util/reaper.mjs';
-import { ownerState, tmpBase } from '../util/tmp.mjs';
+import { ownerState, runRootPath, tmpBase } from '../util/tmp.mjs';
 import { parallelTickets } from '../worker/loop.mjs';
+import { missingStateFiles } from '../worker/review-state.mjs';
 import { row } from './rows.mjs';
 
 /** @typedef {import('./rows.mjs').Row} Row */
@@ -65,16 +72,28 @@ export async function checkLinks(home) {
 
 /**
  * Resolve the Jev key through B2's chain (env → keychain/file → 1Password). The value never
- * leaves this function except to the caller that makes the live call.
+ * leaves this function except to the caller that makes the live call. A refresh from 1Password is
+ * cached for `keys.cache_hours` (B84); a config that failed validation arrives as null ⇒ 8 h.
+ * B85: under 1 hour left the row is WARN with a fixed re-link text (never the reference); when
+ * `keys.cache_hours` is set the OK text ends `(cache <n> h)`.
  * @param {Record<string, any> | null} cfg
- * @param {{env: NodeJS.ProcessEnv, store?: any, opRead?: any}} deps
+ * @param {{env: NodeJS.ProcessEnv, store?: any, opRead?: any, now?: number}} deps
  * @returns {Promise<{rows: Row[], key: string | null}>}
  */
 export async function checkKeys(cfg, deps) {
   try {
     const store = deps.store ?? (await createDefaultKeyStore(deps.env));
     const ref = cfg?.system1?.key ?? cfg?.keys?.jev;
-    const res = await resolveKey('jev', { store, env: deps.env, ref: typeof ref === 'string' ? ref : undefined, ...(deps.opRead ? { opRead: deps.opRead } : {}) });
+    const cache = cacheHoursFrom(cfg);
+    const now = deps.now ?? Date.now();
+    const res = await resolveKey('jev', {
+      store,
+      env: deps.env,
+      ref: typeof ref === 'string' ? ref : undefined,
+      cacheHours: cache.hours,
+      now,
+      ...(deps.opRead ? { opRead: deps.opRead } : {}),
+    });
     if (res.value === null) {
       // only fixed texts are shown: a 1Password failure by its classified message (B25), any other
       // reason as a fixed "key store error" — never a reference, a path or tool output
@@ -85,8 +104,17 @@ export async function checkKeys(cfg, deps) {
       const why = reasons.length > 0 ? ` (${reasons.join('; ')})` : '';
       return { rows: [row('keys', 'WARN', 'keys', `jev key not resolved${why}; System 1 falls back to rules`)], key: null };
     }
-    const exp = res.exp === null ? 'no expiry' : `expires ${new Date(res.exp).toISOString()}`;
-    return { rows: [row('keys', 'OK', 'keys', `jev key from ${res.source}, ${exp}`)], key: res.value };
+    if (isTime(res.exp) && res.exp - now < 3_600_000) {
+      // whole minutes left, never 0 and never 60 (as keys list)
+      const minutes = Math.max(1, Math.floor((res.exp - now) / 60_000));
+      return {
+        rows: [row('keys', 'WARN', 'keys', `jev key from ${res.source} expires in ${minutes} min; re-link with code-forge keys set jev --op <ref from keys.jev>`)],
+        key: res.value,
+      };
+    }
+    const exp = res.exp === null ? 'no expiry' : isTime(res.exp) ? `expires ${new Date(res.exp).toISOString()}` : 'expiry unknown';
+    const hours = cache.source === 'config' ? ` (cache ${cache.hours} h)` : '';
+    return { rows: [row('keys', 'OK', 'keys', `jev key from ${res.source}, ${exp}${hours}`)], key: res.value };
   } catch (err) {
     return { rows: [row('keys', 'FAIL', 'keys', `jev key resolution failed (${err?.code ?? err?.name ?? 'error'})`)], key: null };
   }
@@ -192,6 +220,86 @@ export function checkTmp(cfg) {
   return [row('tmp', roots + pids > 0 ? 'WARN' : 'OK', 'tmp', roots + pids > 0 ? `${detail} (the next code-forge run start removes them)` : detail)];
 }
 
+/** B69: the most missing state files the `review state` row names. */
+export const LISTED_MAX = 10;
+
+/**
+ * B69: one WARN row per ACTIVE run (its record's `status` is `active`, as `run end` and the worker
+ * decide it) whose ledger has `review.state` anchors whose latest state file is missing — neither
+ * at `<code-forge home>/runs/<run>/review-state/` nor at the old temp-root path. The row counts the
+ * files the ledger can rebuild (the latest anchor carries `state_body`) and the lost ones (no body:
+ * the next ticket is refused `review-state-lost`; the owner needs `code-forge block reopen`), and
+ * names the first {@link LISTED_MAX} blocks and files (then `… and K more`). No row when nothing
+ * is missing. When the old temp location cannot be named (`tmp.root` not absolute), nothing is
+ * counted and the row says so; when an anchor of the run does not verify, the row says the review
+ * state was not checked. Each project's ledger is read once. Never throws: a run whose record, key
+ * or ledger cannot be read is skipped. No file content is read or printed.
+ * @param {Record<string, any> | null} cfg
+ * @returns {Promise<Row[]>}
+ */
+export async function checkReviewState(cfg) {
+  let names = [];
+  try {
+    names = readdirSync(runsDir()).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  /** @type {Row[]} */
+  const rows = [];
+  /** @type {Map<string, Array<Record<string, any>>>} the ledger rows per project, read once */
+  const ledgers = new Map();
+  for (const name of names.sort()) {
+    const runId = name.slice(0, -'.json'.length);
+    try {
+      assertRunId(runId);
+      const record = await readRun(runId);
+      if (record?.status !== 'active' || typeof record.project !== 'string') continue;
+      const key = await loadKey(runId);
+      let ledger = ledgers.get(record.project);
+      if (ledger === undefined) {
+        ledger = await readAllRows(record.project);
+        ledgers.set(record.project, ledger);
+      }
+      const atNew = missingStateFiles({ runId, key, rows: ledger });
+      if (atNew === null) {
+        rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: review.state anchors do not verify; review state not checked`));
+        continue;
+      }
+      let root;
+      try {
+        root = snapshotFor(record, '')?.config?.tmp?.root;
+      } catch {
+        root = undefined;
+      }
+      if (typeof root !== 'string') root = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
+      let runRootDir;
+      try {
+        runRootDir = runRootPath(runId, root === undefined ? {} : { root });
+      } catch {
+        runRootDir = undefined;
+      }
+      if (runRootDir === undefined) {
+        // the old place cannot be named: nothing is counted as missing, the row says why
+        if (atNew.length > 0) {
+          rows.push(row('review-state', 'WARN', 'review state', `run ${runId}: the old temp location could not be checked (tmp.root is not an absolute path); review state files are not counted`));
+        }
+        continue;
+      }
+      const missing = missingStateFiles({ runId, key, rows: ledger, runRootDir });
+      if (missing === null || missing.length === 0) continue;
+      const rebuildable = missing.filter((m) => m.rebuildable).length;
+      const lost = missing.length - rebuildable;
+      const shown = missing.slice(0, LISTED_MAX).map((m) => `${m.block} ${m.file} (${m.rebuildable ? 'rebuildable' : 'lost'})`).join(', ');
+      const more = missing.length > LISTED_MAX ? ` … and ${missing.length - LISTED_MAX} more` : '';
+      rows.push(row('review-state', 'WARN', 'review state',
+        `run ${runId}: ${missing.length} state file(s) missing — ${rebuildable} rebuildable from the ledger, ${lost} lost (needs code-forge block reopen): ${shown}${more}`));
+    } catch {
+      // an unreadable record, key or ledger: not this row's business
+    }
+  }
+  return rows;
+}
+
 /**
  * B44: the `review concurrency` INFO row — how many review tickets run at once and each provider's
  * session slots, from the effective config (defaults when a key is unset). Never throws.

package/src/doctor/probes.mjs

@@ -32,6 +32,7 @@ import { mergeForbidden, renderForCodex } from '../util/forbidden.mjs';
 import { buildArgv } from '../engines/builders/index.mjs';
 import { probeHelpText } from '../engines/probe.mjs';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
+import { DEFAULT_SANDBOX_PROFILE, SANDBOX_PROFILES } from '../engines/sandbox-dirs.mjs';
 import { commandOnPath } from '../install/detect.mjs';
 import { classifyUnavailable, readAnswer, spawnSession } from '../session/spawn.mjs';
 import { S2_SCHEMA } from '../session/s2.mjs';
@@ -98,6 +99,43 @@ export function configuredProviders(cfg) {
   return [...out];
 }
 
+/** B93: the coders `coder.sandbox` never changes, by provider, in the order doctor names them. */
+const SANDBOX_NO_EFFECT = Object.freeze([
+  ['anthropic', 'Claude (anthropic)'],
+  ['xai', 'Grok (xai)'],
+]);
+
+/**
+ * B93: the `coder.sandbox` rows. None without the key, for a null config, or for a value the
+ * schema refuses (a non-mapping, an unknown profile: config validation reports those). With it:
+ *  - one INFO row `coder-sandbox` naming the profile (and, for `toolchain`, how many extra dirs);
+ *  - one INFO row `coder-sandbox-no-effect` only when a Claude (anthropic) or Grok (xai) coder is
+ *    configured (any level or fallback): the key has no effect on it, its argv does not change;
+ *  - one WARN row `coder-sandbox-full` when the profile is `full` (`-s danger-full-access`).
+ * Rows name the profile and a count, never a directory.
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {import('./rows.mjs').Row[]}
+ */
+export function checkCoderSandbox(cfg) {
+  const sandbox = cfg?.coder?.sandbox;
+  if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return [];
+  const profile = sandbox.profile ?? DEFAULT_SANDBOX_PROFILE;
+  if (!SANDBOX_PROFILES.includes(profile)) return [];
+  const dirs = Array.isArray(sandbox.add_dirs) ? sandbox.add_dirs.length : 0;
+  const extra = profile === 'toolchain' ? `, ${dirs} extra writable ${dirs === 1 ? 'dir' : 'dirs'}` : '';
+  const rows = [row('coder-sandbox', 'INFO', 'coder sandbox', `profile ${profile}${extra}; applies to the Codex (openai) coder only`)];
+  const providers = configuredProviders(cfg);
+  const others = SANDBOX_NO_EFFECT.filter(([id]) => providers.includes(id)).map(([, name]) => name);
+  if (others.length > 0) {
+    const who = others.length === 1 ? `the ${others[0]} coder` : `the ${others.join(' and ')} coders`;
+    rows.push(row('coder-sandbox-no-effect', 'INFO', 'coder sandbox', `coder.sandbox has no effect on ${who}: the argv does not change`));
+  }
+  if (profile === 'full') {
+    rows.push(row('coder-sandbox-full', 'WARN', 'coder sandbox', 'profile full runs the Codex coder with -s danger-full-access: it can write anywhere you can; only the forbidden list, the transcript grep and the gates limit it'));
+  }
+  return rows;
+}
+
 /** @param {Record<string, any>} cfg @returns {Record<string, any>} the config with every level's fallback removed. */
 function withoutFallback(cfg) {
   /** @type {Record<string, any>} */