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

@@ -14,7 +14,7 @@ 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, checkReviewState, checkTmp, checkTools } from './local.mjs';
-import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.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';
 
@@ -70,6 +70,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   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

@@ -16,7 +16,7 @@ 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';
@@ -72,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
@@ -92,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 };
   }

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>} */

package/src/engines/builders/codex.mjs

@@ -65,6 +65,8 @@ import { CODEX_RULES_FILE_NAME, defaultCodexHome, isInside, prepareCodexHome } f
 import { hasAnyRenderedRule } from '../render-rules.mjs';
 import { assertEffortForProvider, PROVIDER_EFFORTS } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
+import { checkSandboxDirs, DEFAULT_SANDBOX_PROFILE, SandboxDirError, sandboxRefusalMessage, SANDBOX_PROFILES } from '../sandbox-dirs.mjs';
+import { tmpBase } from '../../util/tmp.mjs';
 import { CODEX_CLOSED_BOOK_REFUSAL, isNeverOpenBookRole, isNoToolRole } from '../../config/closed-book.mjs';
 
 export const CLI = 'codex';
@@ -123,6 +125,11 @@ export const VALID_EFFORTS = PROVIDER_EFFORTS.openai;
  * @property {string} [codexHome] - coder role only: the per-session Codex home to create (absolute,
  *   must not exist as the real `~/.codex` or inside it); defaults to `defaultCodexHome()` under the
  *   run temp root.
+ * @property {{profile?: string, add_dirs?: string[]}} [sandbox] - B93, coder role only: the
+ *   `coder.sandbox` config value. Absent ⇒ today's argv. `toolchain` adds one `--add-dir <abs>`
+ *   per checked `add_dirs` entry; `full` builds `-s danger-full-access`. A refused entry throws
+ *   a `SandboxDirError` (code `sandbox-dir-refused`) naming the key path, never the value.
+ * @property {string} [runRoot] - B93, coder role only: the run temp root, refused as an `add_dirs` tree.
  */
 
 /**
@@ -158,13 +165,23 @@ function assertValidEffort(effort) {
 /**
  * The Codex coder argv itself — pure, no I/O, no rules file (B4.2). `buildCoderArgv` uses it, and
  * the doctor's flags probe builds it with placeholder values for its static conflict check.
- * @param {{model: string, effort?: string, cwd: string, outPath: string, promptPath: string}} p
+ * B93: `profile` `full` swaps `-s workspace-write` for `-s danger-full-access`; `addDirs` (already
+ * checked and resolved, `toolchain` only) follow `-s workspace-write` as `--add-dir <abs>` pairs.
+ * The tmp exclusions stay in every profile: under `danger-full-access` Codex ignores the
+ * `sandbox_workspace_write.*` keys, and one argv shape keeps the forbidden-list check the same.
+ * @param {{model: string, effort?: string, cwd: string, outPath: string, promptPath: string, profile?: string, addDirs?: ReadonlyArray<string>}} p
  * @returns {string[]}
  */
-export function coderFlagArgv({ model, effort, cwd, outPath, promptPath }) {
+export function coderFlagArgv({ model, effort, cwd, outPath, promptPath, profile = DEFAULT_SANDBOX_PROFILE, addDirs = [] }) {
+  if (!SANDBOX_PROFILES.includes(profile)) throw new TypeError(`coderFlagArgv: profile must be one of ${SANDBOX_PROFILES.join(', ')}`);
   const argv = ['codex', 'exec', '-m', model];
   if (effort) argv.push('-c', `model_reasoning_effort=${effort}`);
-  argv.push('-s', 'workspace-write');
+  if (profile === 'full') {
+    argv.push('-s', 'danger-full-access');
+  } else {
+    argv.push('-s', 'workspace-write');
+    if (profile === 'toolchain') for (const dir of addDirs) argv.push('--add-dir', dir);
+  }
   // INVARIANT (B4.1 fix round 1): the session CODEX_HOME lives under the run temp root, so the
   // sandbox must not make $TMPDIR or /tmp writable — the project cwd is then the only writable
   // root, and a home inside the cwd is refused below. See `../codex-home.mjs`.
@@ -178,6 +195,26 @@ export function coderFlagArgv({ model, effort, cwd, outPath, promptPath }) {
   return argv;
 }
 
+/**
+ * B93: the checked sandbox of one coder build. Absent ⇒ the default profile with no extra dir.
+ * The `add_dirs` are checked here too (defence in depth: validation checks them first), against
+ * the protected home dirs plus `extra` (the session CODEX_HOME, the run temp root and base).
+ * @param {unknown} sandbox @param {ReadonlyArray<string | undefined>} extra
+ * @returns {{profile: string, addDirs: string[]}}
+ */
+function coderSandbox(sandbox, extra) {
+  if (sandbox === undefined || sandbox === null) return { profile: DEFAULT_SANDBOX_PROFILE, addDirs: [] };
+  if (typeof sandbox !== 'object' || Array.isArray(sandbox)) throw new TypeError('buildCodexArgv: coder.sandbox must be a mapping');
+  const s = /** @type {{profile?: unknown, add_dirs?: unknown}} */ (sandbox);
+  const profile = s.profile ?? DEFAULT_SANDBOX_PROFILE;
+  if (typeof profile !== 'string' || !SANDBOX_PROFILES.includes(profile)) {
+    throw new TypeError(`buildCodexArgv: coder.sandbox.profile must be one of ${SANDBOX_PROFILES.join(', ')}`);
+  }
+  const checked = checkSandboxDirs(s.add_dirs, { extra });
+  if ('keyPath' in checked) throw new SandboxDirError(sandboxRefusalMessage(checked));
+  return { profile, addDirs: profile === 'toolchain' ? checked.dirs : [] };
+}
+
 /**
  * @param {CodexBuildParams} params
  * @returns {{cli: "codex", role: "coder", argv: string[], cwd: string, outPath: string, env: {CODEX_HOME: string}, forbiddenRendered: ReadonlyArray<RenderedCodexEntry>, rulesFile: {fileName: string, path: string, content: string, count: number}}}
@@ -189,7 +226,6 @@ function buildCoderArgv(params) {
   if (!hasAnyRenderedRule(renderedForbidden)) {
     throw new Error('buildCodexArgv: coder role requires a non-empty forbidden-list render (got 0 usable patterns)');
   }
-  const argv = coderFlagArgv({ model, effort, cwd, outPath, promptPath });
   const codexHome = params.codexHome ?? defaultCodexHome();
   // Fix round 4: a non-absolute home is refused here, before any I/O, and the containment check
   // below then runs EVERY time (no `isAbsolute` short-circuit that could skip it).
@@ -202,6 +238,10 @@ function buildCoderArgv(params) {
   if (isInside(codexHome, cwd)) {
     throw new Error('buildCodexArgv: the session CODEX_HOME must not be inside the coder cwd (the sandbox can write there)');
   }
+  // B93 (fix round 1): the sandbox dirs are checked only after the home is known to be absolute
+  // and outside the cwd, so the home they are checked against is the one the session will use.
+  const sandbox = coderSandbox(params.sandbox, [codexHome, params.runRoot, tmpBase()]);
+  const argv = coderFlagArgv({ model, effort, cwd, outPath, promptPath, ...sandbox });
   const home = prepareCodexHome(codexHome, renderedForbidden);
   return {
     cli: CLI,