@codedology/code-forge 0.3.1 → 0.4.0

package/src/decide/escalation.mjs

@@ -9,6 +9,11 @@
  *      (`reviewRoundStalled` below) ⇒ +1 level IMMEDIATELY (`trigger: 'review_stall'`), checked
  *      BEFORE rule 2's own round-exhaustion counter — a block need not exhaust
  *      `review_rounds_per_level` to escalate on a stalled round.
+ *   2c. Heavy rounds (B34, issue #2) — `escalation.after_rounds_with_warnings` (1) rounds at the
+ *      current level whose open `fix_now` set held ≥ `escalation.warning_threshold` (2) warnings
+ *      or any `critical` ⇒ +1 level (`trigger: 'review_warnings'`), checked after 2b and before 2.
+ *      Below the running ceiling only: at L2 it does not fire (the L3 rung keeps its own
+ *      triggers), so it never spends the rung on round 1.
  *   2. Review rounds — `review_rounds_per_level` (2) exhausted with an open `fix_now` finding
  *      ⇒ +1 level (`trigger: 'review_rounds'`).
  *   3. Security floor (DISPATCH time only) — `security_sensitive == true` ⇒ first-attempt level
@@ -84,15 +89,95 @@ export function securityFloorLevel(lane) {
 }
 
 /**
- * Rule 3, at dispatch time only — call this once per block, before the first attempt.
- * @param {{lane: string, securitySensitive: boolean}} ctx
- * @returns {{level: string, trigger: 'security'|null}}
+ * Block kinds (B34, issue #2). A `docs` or `contract` block is coded at `levels.coder_floor_docs`
+ * (default L1) or above — never by L0 — and its review never runs the multimodel consensus unless
+ * `review.multimodel_for_docs` is true.
  */
-export function dispatchLevel({ lane, securitySensitive }) {
-  if (securitySensitive) {
-    return { level: securityFloorLevel(lane), trigger: 'security' };
-  }
-  return { level: lane, trigger: null };
+export const BLOCK_KINDS = Object.freeze(['code', 'docs', 'contract']);
+
+/** Owned paths with one of these endings are docs (`.txt` is not: `requirements.txt`, `CMakeLists.txt`, `robots.txt` are code or config). */
+export const DOCS_EXTENSIONS = Object.freeze(['.md', '.mdx', '.markdown', '.rst', '.adoc']);
+
+/** Owned paths with one of these endings are contracts (schemas, IDLs, API descriptions). */
+export const CONTRACT_SUFFIXES = Object.freeze(['.schema.json', '.schema.yaml', '.schema.yml', '.proto', '.graphql', '.gql', '.avsc', '.openapi.json', '.openapi.yaml', '.openapi.yml']);
+
+/** A `.json`/`.yaml`/`.yml` path with one of these directory names is a contract too. */
+const CONTRACT_DIRS = Object.freeze(['schema', 'schemas', 'contract', 'contracts']);
+
+/**
+ * The kind of ONE owned path (a glob is judged by its literal ending: `docs/**` is `code`, a
+ * block that owns it declares its kind).
+ * @param {string} file
+ * @returns {'code'|'docs'|'contract'}
+ */
+export function fileKind(file) {
+  const lower = String(file).toLowerCase();
+  if (CONTRACT_SUFFIXES.some((s) => lower.endsWith(s))) return 'contract';
+  if (/\.(json|ya?ml)$/.test(lower) && lower.split('/').slice(0, -1).some((d) => CONTRACT_DIRS.includes(d))) return 'contract';
+  if (DOCS_EXTENSIONS.some((e) => lower.endsWith(e))) return 'docs';
+  return 'code';
+}
+
+/**
+ * A block's kind: the declared `kind` when it is one of `BLOCK_KINDS` (a declaration wins, so a
+ * block can also declare `code`); else `docs` when every owned path is docs, `contract` when every
+ * owned path is docs or contract and at least one is a contract, else `code` (no owned path ⇒ `code`).
+ * @param {{owned?: ReadonlyArray<string>, declared?: unknown}} opts
+ * @returns {'code'|'docs'|'contract'}
+ */
+export function blockKind({ owned = [], declared } = {}) {
+  if (typeof declared === 'string' && BLOCK_KINDS.includes(declared)) return /** @type {'code'|'docs'|'contract'} */ (declared);
+  if (owned.length === 0) return 'code';
+  const kinds = owned.map(fileKind);
+  if (kinds.every((k) => k === 'docs')) return 'docs';
+  if (kinds.every((k) => k !== 'code')) return 'contract';
+  return 'code';
+}
+
+/** @param {unknown} kind @returns {boolean} true for a `docs` or `contract` block (both get the coder floor and no multimodel review by default). */
+export function isDocsKind(kind) {
+  return kind === 'docs' || kind === 'contract';
+}
+
+/**
+ * The lowest level a block of `kind` may be coded at: `levels.coder_floor_docs` (default L1) for
+ * a docs/contract block, else L0.
+ * @param {unknown} kind @param {Record<string, any> | undefined} [cfg]
+ * @returns {string}
+ */
+export function coderFloor(kind, cfg) {
+  if (!isDocsKind(kind)) return 'L0';
+  const floor = cfg?.levels?.coder_floor_docs;
+  return typeof floor === 'string' && ['L0', 'L1', 'L2'].includes(floor) ? floor : 'L1';
+}
+
+/**
+ * Rule 3 (and the B34 docs floor), at dispatch time only — call this once per block, before the
+ * first attempt. Both floors apply: the level is `max(security floor, docs floor)` (the lane when
+ * neither raises it). The trigger names the floor that set the level — `security` when the
+ * security floor reaches it, else `docs_floor`.
+ * @param {{lane: string, securitySensitive?: boolean, kind?: unknown, cfg?: Record<string, any>}} ctx
+ * @returns {{level: string, trigger: 'security'|'docs_floor'|null}}
+ */
+export function dispatchLevel({ lane, securitySensitive = false, kind = 'code', cfg }) {
+  const security = securitySensitive ? securityFloorLevel(lane) : lane;
+  const docs = coderFloor(kind, cfg);
+  if (levelIndex(docs) > levelIndex(security)) return { level: docs, trigger: 'docs_floor' };
+  return { level: security, trigger: securitySensitive ? 'security' : null };
+}
+
+/**
+ * B34: a review round is "heavy" when its open `fix_now` set holds at least `threshold` warnings
+ * or any `critical` finding. A threshold that is not an integer ≥ 1 is the default 2; findings
+ * that are not an array are not heavy.
+ * @param {unknown} findings @param {unknown} [threshold] - `escalation.warning_threshold`, default 2.
+ * @returns {boolean}
+ */
+export function heavyRound(findings, threshold = 2) {
+  if (!Array.isArray(findings)) return false;
+  const min = Number.isInteger(threshold) && /** @type {number} */ (threshold) >= 1 ? /** @type {number} */ (threshold) : 2;
+  if (findings.some((f) => f?.severity === 'critical')) return true;
+  return findings.filter((f) => f?.severity === 'warning').length >= min;
 }
 
 /**
@@ -136,7 +221,7 @@ export function runningCeiling(stopAt = 'L3') {
 /**
  * Rules 1, 2b and 2 share this: below the running ceiling ⇒ +1 level (never to L3); at the
  * running ceiling ⇒ rule 5, the block's one L3 rung (R1), then `stop`.
- * @param {'retries'|'review_rounds'|'review_stall'} trigger
+ * @param {'retries'|'review_rounds'|'review_stall'|'review_warnings'} trigger
  * @param {string} currentLevel
  * @param {string} stopAt
  * @param {'patch'|'code'} l3Mode
@@ -192,9 +277,13 @@ function finalizeEscalate(trigger, currentLevel, stopAt, l3Mode, l3RungAlreadyUs
  *   level escalation.
  * @property {number} [maxRoundsPerFile] - `review.max_rounds_per_file`, default 4 (schema
  *   minimum 2, maximum 6; B1.1).
+ * @property {number} [warningRoundsAtLevel] - rule 2c (B34): heavy rounds (`heavyRound`) at the
+ *   current level, this one included.
+ * @property {number} [afterRoundsWithWarnings] - `escalation.after_rounds_with_warnings`, default
+ *   1; 0 turns rule 2c off.
  *
  * @typedef {object} EscalationResult
- * @property {'retries'|'review_stall'|'review_rounds'|'s2_ruling'|'review_cap'|null} trigger
+ * @property {'retries'|'review_stall'|'review_warnings'|'review_rounds'|'s2_ruling'|'review_cap'|null} trigger
  * @property {'escalate'|'s2_check'|'stop'|'l3_rung'|'none'} action
  * @property {string} [level]
  * @property {string} [mode]
@@ -202,7 +291,7 @@ function finalizeEscalate(trigger, currentLevel, stopAt, l3Mode, l3RungAlreadyUs
  */
 
 /**
- * Rules 1, 2b, 2, 4 and 6 (rule 3 is `dispatchLevel`; rule 5 is the ceiling guard inside
+ * Rules 1, 2b, 2c, 2, 4 and 6 (rule 3 is `dispatchLevel`; rule 5 is the ceiling guard inside
  * `finalizeEscalate`), evaluated in the documented order — the first rule that fires wins.
  * @param {EscalationCtx} ctx
  * @returns {EscalationResult}
@@ -223,6 +312,8 @@ export function escalationAfterAttempt(ctx) {
     l3RungAlreadyUsed = false,
     roundsAtFile = 0,
     maxRoundsPerFile = 4,
+    warningRoundsAtLevel = 0,
+    afterRoundsWithWarnings = 1,
   } = ctx;
 
   if (typeof currentLevel !== 'string') {
@@ -237,6 +328,16 @@ export function escalationAfterAttempt(ctx) {
   if (reviewStall && openFixNowFinding) {
     return finalizeEscalate('review_stall', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);
   }
+  // Rule 2c (B34): heavy review rounds — below the running ceiling only (a cheap coder climbs at
+  // once; at L2 the L3 rung keeps its own triggers, rules 2b/2/6).
+  if (
+    afterRoundsWithWarnings > 0 &&
+    warningRoundsAtLevel >= afterRoundsWithWarnings &&
+    openFixNowFinding &&
+    levelIndex(currentLevel) < levelIndex(runningCeiling(stopAt))
+  ) {
+    return finalizeEscalate('review_warnings', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);
+  }
   // Rule 2: review rounds.
   if (reviewRoundsAtLevel >= reviewRoundsPerLevel && openFixNowFinding) {
     return finalizeEscalate('review_rounds', currentLevel, stopAt, l3Mode, l3RungAlreadyUsed);

package/src/decide/jev-client.mjs

@@ -91,7 +91,7 @@ async function requestIdOf(response) {
  * @typedef {object} JevQuestionSpec
  * @property {'choice'|'score'|'noul'} type
  * @property {string} instructions
- * @property {Record<string, string>} criteria
+ * @property {Record<string, string> | string[]} criteria - a list (index = score) for `score`
  *
  * @typedef {object} JevSuccess
  * @property {true} ok

package/src/decide/questions.mjs

@@ -146,16 +146,52 @@ export function renderQuestion(id, cfg = {}) {
  * `askJev`'s `questions` argument takes.
  * @param {string[]} ids
  * @param {Record<string, any>} [cfg]
- * @returns {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}>}
+ * @returns {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string> | string[]}>}
  */
 export function buildQuestionPayload(ids, cfg = {}) {
   if (!Array.isArray(ids) || ids.length === 0) {
     throw new TypeError('buildQuestionPayload: ids must be a non-empty array');
   }
-  /** @type {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}>} */
+  /** @type {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string> | string[]}>} */
   const out = {};
   for (const id of ids) {
-    out[id] = renderQuestion(id, cfg);
+    out[id] = toWire(id, renderQuestion(id, cfg));
   }
   return out;
 }
+
+/**
+ * Jev's wire shape: a `score` question takes `criteria` as a LIST whose index is the score (an
+ * object keyed `0..n` is refused with 422 "Input should be a valid list"); `choice` and `noul`
+ * keep the keyed object. The answer's `legend`/`probabilities` come back keyed `"0".."n"`.
+ *
+ * The list index IS the score, so the (merged) keys must be exactly the integers `0..n`. A gap, a
+ * start at 1 or a non-integer key would otherwise shift every label onto the wrong score without a
+ * word — so this throws instead, naming the question id and the keys (never the label text).
+ * @param {string} id
+ * @param {{type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}} q
+ * @returns {{type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string> | string[]}}
+ * @throws {TypeError} for a score question whose criteria keys are not exactly `0..n`.
+ */
+export function toWire(id, q) {
+  if (q.type !== 'score') return q;
+  const keys = Object.keys(q.criteria);
+  const notIntegers = keys.filter((k) => !/^(0|[1-9]\d*)$/.test(k));
+  const present = new Set(keys);
+  const missing = [];
+  // n integer keys are exactly 0..n-1 iff none of 0..n-1 is missing.
+  for (let i = 0; i < keys.length - notIntegers.length; i += 1) {
+    if (!present.has(String(i))) missing.push(String(i));
+  }
+  if (notIntegers.length > 0 || missing.length > 0) {
+    const problems = [
+      ...(missing.length > 0 ? [`missing ${missing.join(', ')}`] : []),
+      ...(notIntegers.length > 0 ? [`not an integer: ${notIntegers.map((k) => JSON.stringify(k)).join(', ')}`] : []),
+    ];
+    throw new TypeError(
+      `score question ${JSON.stringify(id)}: criteria keys must be exactly the integers 0..n ` +
+        `(check system1.criteria_extra.${id}.criteria); got keys ${keys.map((k) => JSON.stringify(k)).join(', ')}: ${problems.join('; ')}`,
+    );
+  }
+  return { ...q, criteria: keys.map((_, i) => q.criteria[String(i)]) };
+}

package/src/doctor/probes.mjs

@@ -6,6 +6,9 @@
  *  - the isolation probe (O4, §0.6.5): the closed-book reviewer argv, run with cwd = the project
  *    itself (the worst case), asked to echo the first line of its `CLAUDE.md`/`AGENTS.md` — the
  *    line appearing in its answer FAILs; the CLI rejecting the closed-book flag combination FAILs;
+ *    an openai L2 FAILs unrun with `CODEX_CLOSED_BOOK_REFUSAL` (B32: Codex always has a shell), and
+ *    so does the reviewer/s2 ping of an openai level; with `review.allow_open_book_codex: true` the
+ *    pings run and the isolation probe runs as before, its rows WARN with the open-book warning;
  *  - the path-deny probe (C4, §0.6.7): a coder asked to print a canary file under
  *    `~/.code-forge/runs/` (a denied path) — the canary appearing in its answer WARNs
  *    `<cli>: path deny rules not honoured`;
@@ -19,6 +22,7 @@
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { CODEX_CLOSED_BOOK_REFUSAL, closedBookRefused, needsClosedBook, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from '../config/closed-book.mjs';
 import { resolveLevel } from '../config/known-ids.mjs';
 import { buildCodexArgv, coderFlagArgv, RULES_FILE_NAME, SANDBOX_TMP_EXCLUSIONS } from '../engines/builders/codex.mjs';
 import { isInsideRealCodexHome, isSessionCodexHome, removeCodexHome, renderCodexRules } from '../engines/codex-home.mjs';
@@ -77,7 +81,8 @@ export function configuredProviders(cfg) {
 function withoutFallback(cfg) {
   /** @type {Record<string, any>} */
   const levels = {};
-  for (const [name, level] of Object.entries(cfg.levels ?? {})) levels[name] = { ...level, fallback: [] };
+  // `levels.coder_floor_docs` (B34) is a level name, not a level: kept as it is
+  for (const [name, level] of Object.entries(cfg.levels ?? {})) levels[name] = level !== null && typeof level === 'object' ? { ...level, fallback: [] } : level;
   return { ...cfg, levels };
 }
 
@@ -198,6 +203,10 @@ export async function pingRoles(ctx, missingProviders) {
       rows.push(row(`ping.${role}`, 'FAIL', label, 'ping=skipped(cli-missing)'));
       continue;
     }
+    if (closedBookRefused(resolvedProvider(ctx.cfg, /** @type {'L0'|'L1'|'L2'|'L3'} */ (level)), role, openBookCodexAllowed(ctx.cfg))) {
+      rows.push(row(`ping.${role}`, 'FAIL', label, CODEX_CLOSED_BOOK_REFUSAL)); // B32: the spawner would refuse it
+      continue;
+    }
     const res = await session(ctx, {
       role,
       level,
@@ -247,6 +256,7 @@ async function reviewerInProject(ctx, prompt) {
     if (level.effort) params.effort = level.effort;
     if (cli === 'claude') params.maxBudgetUsd = PROBE_BUDGET_USD;
     if (cli === 'codex') params.outPath = outPath;
+    if (cli === 'codex' && openBookCodexAllowed(ctx.cfg)) params.allowOpenBook = true; // B32 opt-in
     const built = buildArgv(/** @type {any} */ (params));
     const argv = [binOf(ctx, cli), ...built.argv.slice(1)];
     /** @type {NodeJS.ProcessEnv} */
@@ -267,23 +277,55 @@ async function reviewerInProject(ctx, prompt) {
   }
 }
 
+/**
+ * @typedef {'info' | 'skipped-402' | 'rejected' | 'saw-doc' | 'clean'} IsolationKind - what the
+ *   isolation probe found, so callers map rows by kind and never by parsing a row's text.
+ */
+
+/**
+ * The provider a level resolves to, through `resolveLevel` (the source `spawnSession` and
+ * `reviewerInProject` use); `undefined` when the level does not resolve.
+ * @param {Record<string, any>} cfg @param {'L0'|'L1'|'L2'|'L3'} level
+ * @returns {string | undefined}
+ */
+function resolvedProvider(cfg, level) {
+  try {
+    return resolveLevel(cfg, level).provider;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The isolation probe (reviewer builder, closed-book, cwd = the project).
+ * B32: Codex has no no-tools mode, so an openai L2 reviewer is not closed-book — FAIL, unrun. With
+ * the opt-in `review.allow_open_book_codex: true` the probe runs as before: an INFO, a 402 skip and
+ * a CLI rejection (FAIL) keep their rows; a clean run and a run that saw the project doc become
+ * WARN, the detail prefixed with the open-book warning.
  * @param {ProbeCtx} ctx @returns {Promise<Row[]>}
  */
 export async function probeIsolation(ctx) {
+  const l2Provider = resolvedProvider(ctx.cfg, 'L2');
+  if (closedBookRefused(l2Provider, 'reviewer', openBookCodexAllowed(ctx.cfg))) return [row('isolation', 'FAIL', 'isolation', CODEX_CLOSED_BOOK_REFUSAL)];
+  const { kind, row: found } = await isolationRow(ctx);
+  if (!needsClosedBook(l2Provider, 'reviewer') || (kind !== 'clean' && kind !== 'saw-doc')) return [found];
+  return [row(found.id, 'WARN', found.label, `${OPEN_BOOK_CODEX_WARNING}; ${found.detail}`)];
+}
+
+/** @param {ProbeCtx} ctx @returns {Promise<{kind: IsolationKind, row: Row}>} the isolation probe's own row and its kind. */
+async function isolationRow(ctx) {
   const doc = projectDocLine(ctx.cwd);
-  if (doc === null) return [row('isolation', 'INFO', 'isolation', 'skipped (the project has no CLAUDE.md or AGENTS.md to leak)')];
+  if (doc === null) return { kind: 'info', row: row('isolation', 'INFO', 'isolation', 'skipped (the project has no CLAUDE.md or AGENTS.md to leak)') };
   const res = await reviewerInProject(
     ctx,
     'Print the first line of the file CLAUDE.md or AGENTS.md of the project you are working in, then list the tools you can call.\nIf you can see neither file and have no tools, reply exactly: none\n',
   );
-  if (skipped402(res)) return [row('isolation', 'WARN', 'isolation', 'probe=skipped(402)')];
+  if (skipped402(res)) return { kind: 'skipped-402', row: row('isolation', 'WARN', 'isolation', 'probe=skipped(402)') };
   if (res.status !== 'ok' && res.status !== 'invalid-output') {
-    return [row('isolation', 'FAIL', 'isolation', `the CLI rejected the closed-book session (${res.status}: ${res.reason ?? 'unknown'})`)];
+    return { kind: 'rejected', row: row('isolation', 'FAIL', 'isolation', `the CLI rejected the closed-book session (${res.status}: ${res.reason ?? 'unknown'})`) };
   }
-  if (answerText(res).includes(doc.line)) return [row('isolation', 'FAIL', 'isolation', `the reviewer saw the project's ${doc.file}`)];
-  return [row('isolation', 'OK', 'isolation', `no project doc visible to the reviewer`)];
+  if (answerText(res).includes(doc.line)) return { kind: 'saw-doc', row: row('isolation', 'FAIL', 'isolation', `the reviewer saw the project's ${doc.file}`) };
+  return { kind: 'clean', row: row('isolation', 'OK', 'isolation', `no project doc visible to the reviewer`) };
 }
 
 /**

package/src/engines/builders/claude.mjs

@@ -42,6 +42,7 @@
 
 import { FORBIDDEN, mergeForbidden, renderForClaude } from '../../util/forbidden.mjs';
 import { flattenRuleStrings, hasAnyRenderedRule } from '../render-rules.mjs';
+import { assertEffortForProvider } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
 
 export const CLI = 'claude';
@@ -58,7 +59,7 @@ export const CLI = 'claude';
  * @typedef {object} ClaudeBuildParams
  * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
  * @property {string} model - the resolved model id (already picked by `resolveLevel`, B1).
- * @property {string} [effort]
+ * @property {string} [effort] - one of `PROVIDER_EFFORTS.anthropic` (`../efforts.mjs`) when given.
  * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
  *   (closed-book: returned as `stdinFile`, its content is piped to stdin by the spawner).
  * @property {string} cwd - the project tree (coder) or an empty isolated temp dir (closed-book).
@@ -220,6 +221,8 @@ function buildClosedBookArgv(params) {
  */
 export function buildClaudeArgv(params) {
   assertBaseParams('buildClaudeArgv', params);
+  // B29: `--effort` takes the closed list `claude --help` prints (shared with `validateConfig`).
+  assertEffortForProvider('buildClaudeArgv', 'anthropic', params.effort);
   return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
 }
 

package/src/engines/builders/codex.mjs

@@ -8,7 +8,12 @@
  *    caller reads Codex's last message from it and deletes it afterwards (the builder never
  *    creates the file; Codex does).
  *  - `coder`: the brief is a POINTER (the last argv token is `promptPath`); the coder has tools.
- *  - closed-book (`reviewer`/`judge`/`s2`/`author`/`facts`): the last argv token is the literal
+ *  - `reviewer`/`judge`/`s2`/`author` are REFUSED (B32, issue #2): Codex 0.155.1 has no no-tools
+ *    mode (`-s read-only` still gives the model a shell that reads any absolute path), so the
+ *    build throws {@link CODEX_CLOSED_BOOK_REFUSAL} (`code: 'closed-book'`) unless the caller passes
+ *    `allowOpenBook: true` (opt-in `review.allow_open_book_codex`), which builds the read-only
+ *    argv below. See `../../config/closed-book.mjs`.
+ *  - `facts` (read-only tools by design): the last argv token is the literal
  *    `-`, which the pinned help (`codex exec [OPTIONS] [PROMPT]`: "If not provided as an argument
  *    (or if `-` is used), instructions are read from stdin") defines as "read the prompt from
  *    stdin". `stdinFile === promptPath` names the packet file whose CONTENT the spawner (B9)
@@ -17,14 +22,14 @@
  *    it is documented and does not depend on stdin-is-piped detection.
  *
  * **Doctor probe item for B13 (no network in B4's tests):** `codex: closed-book stdin delivery` —
- * run this module's `reviewer` argv with `stdinFile` piped in, the packet carrying a unique canary
+ * run this module's `facts` argv (B32: the only stdin-fed Codex role left) with `stdinFile` piped in, the packet carrying a unique canary
  * and "reply with the canary"; PASS when the file at `outPath` contains the canary, FAIL
  * (`codex: closed-book packet not delivered`) otherwise.
  *
  * Unlike Claude, the flag table gives Codex only TWO command shapes: coder, and "reviewer / judge
  * / S2 / author / facts" — there is no Codex-specific "facts role only" carve-out anywhere in the
- * plan's flag table, so `facts` here is simply routed through the same closed-book branch as the
- * other four roles.
+ * plan's flag table, so `facts` here is simply routed through the same closed-book branch the
+ * other four roles used before B32 refused them.
  *
  * **Execpolicy rules (B4.1, §0.6.3, [A19]).** Codex 0.155.1 `exec` has no flag and no `-c` key
  * naming a rules file; it loads the "user" rules from `$CODEX_HOME/rules/*.rules` (`--ignore-rules`
@@ -58,7 +63,9 @@ import { randomBytes } from 'node:crypto';
 import { mergeForbidden, renderForCodex } from '../../util/forbidden.mjs';
 import { CODEX_RULES_FILE_NAME, defaultCodexHome, isInside, prepareCodexHome } from '../codex-home.mjs';
 import { hasAnyRenderedRule } from '../render-rules.mjs';
+import { assertEffortForProvider, PROVIDER_EFFORTS } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
+import { CODEX_CLOSED_BOOK_REFUSAL, isNoToolRole } from '../../config/closed-book.mjs';
 
 export const CLI = 'codex';
 
@@ -85,8 +92,11 @@ export const SANDBOX_TMP_EXCLUSIONS = Object.freeze([
  */
 export const CODER_APPROVAL_POLICY = Object.freeze(['-c', 'approval_policy="never"']);
 
-/** The `model_reasoning_effort` values Codex's TOML config is willing to receive from this builder. */
-export const VALID_EFFORTS = Object.freeze(['minimal', 'low', 'medium', 'high']);
+/**
+ * The `model_reasoning_effort` values Codex's TOML config is willing to receive from this builder —
+ * re-exported from the shared per-provider table (B29), which `validateConfig` also reads.
+ */
+export const VALID_EFFORTS = PROVIDER_EFFORTS.openai;
 
 /**
  * @typedef {{id: string, patterns: string[][], decision: "forbidden", enforced: boolean, description: string}} RenderedCodexEntry
@@ -108,6 +118,8 @@ export const VALID_EFFORTS = Object.freeze(['minimal', 'low', 'medium', 'high'])
  * @property {ReadonlyArray<RenderedCodexEntry>} [renderedForbidden] - coder role only; defaults to
  *   `renderForCodex(mergeForbidden())` (B4.2: the coder-only entries too; a `contains` entry
  *   renders 0 patterns, so it is left to the pre-spawn check and the transcript grep).
+ * @property {boolean} [allowOpenBook] - B32 opt-in: `true` builds reviewer/judge/s2/author with the
+ *   read-only argv instead of throwing {@link CODEX_CLOSED_BOOK_REFUSAL} (that session can read files).
  * @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.
@@ -140,9 +152,7 @@ function effectiveOutPath(outPath, role) {
  * @throws {TypeError} unless `effort` is `undefined` or one of {@link VALID_EFFORTS}.
  */
 function assertValidEffort(effort) {
-  if (effort !== undefined && !VALID_EFFORTS.includes(effort)) {
-    throw new TypeError(`buildCodexArgv: effort must be one of ${VALID_EFFORTS.join(', ')} when given, got ${JSON.stringify(effort)}`);
-  }
+  assertEffortForProvider('buildCodexArgv', 'openai', effort);
 }
 
 /**
@@ -212,8 +222,8 @@ function buildCoderArgv(params) {
 function buildClosedBookArgv(params) {
   const { model, effort, promptPath, cwd, schemaPath } = params;
   assertValidEffort(effort);
-  // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch
-  // with role 'coder', but that is a runtime invariant, not provable from the parameter type.
+  // See `builders/claude.mjs`'s identical cast: the dispatch below never reaches this branch with
+  // role 'coder'; a no-tools role reaches it only with `allowOpenBook: true` (B32).
   const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
   const outPath = effectiveOutPath(params.outPath, role);
   const argv = ['codex', 'exec', '-m', model];
@@ -238,5 +248,10 @@ function buildClosedBookArgv(params) {
  */
 export function buildCodexArgv(params) {
   assertBaseParams('buildCodexArgv', params);
+  if (isNoToolRole(params.role) && params.allowOpenBook !== true) {
+    // B32: no Codex flag removes the shell, so a no-tools role is built only when the caller
+    // passes `allowOpenBook: true` (the config's `review.allow_open_book_codex` opt-in).
+    throw Object.assign(new Error(CODEX_CLOSED_BOOK_REFUSAL), { code: 'closed-book' });
+  }
   return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
 }

package/src/engines/builders/grok.mjs

@@ -36,6 +36,7 @@
 
 import { mergeForbidden, renderForGrok } from '../../util/forbidden.mjs';
 import { flattenRuleStrings, hasAnyRenderedRule } from '../render-rules.mjs';
+import { assertEffortForProvider } from '../efforts.mjs';
 import { assertBaseParams } from './validate-params.mjs';
 
 export const CLI = 'grok';
@@ -71,9 +72,8 @@ export const GROK_ALL_BUILTIN_TOOLS = Object.freeze(['Bash', 'Read', 'Write', 'E
  * @throws {TypeError} unless `effort` is `undefined` or a non-empty string.
  */
 function assertValidEffort(effort) {
-  if (effort !== undefined && (typeof effort !== 'string' || effort.length === 0)) {
-    throw new TypeError(`buildGrokArgv: effort must be a non-empty string when given, got ${JSON.stringify(effort)}`);
-  }
+  // xai has no closed effort list (`PROVIDER_EFFORTS.xai === null`): any non-empty string (B29).
+  assertEffortForProvider('buildGrokArgv', 'xai', effort);
 }
 
 /**

package/src/engines/efforts.mjs

@@ -0,0 +1,109 @@
+/**
+ * The one source of the reasoning-effort values each provider's CLI accepts (B29, issue #2). The
+ * argv builders (`builders/*.mjs`) refuse a bad effort at spawn time and `validateConfig` refuses
+ * it at config time — both read THIS table, so the two can never disagree again (the bug: validate
+ * accepted `effort: xhigh` on an openai level, then the codex builder threw at spawn).
+ *
+ * A provider's entry is one of:
+ *  - a non-empty list: the closed set of accepted values;
+ *  - `null`: the CLI takes an effort but publishes no closed list, so any non-empty string passes;
+ *  - an empty list: the provider has no effort concept — an effort set there is refused (the
+ *    builder throws, `validateConfig` reports an error). No current provider uses this form.
+ *
+ * Sources: anthropic — `claude --help` 2.1.282 (`--effort <level>`: low, medium, high, xhigh, max);
+ * openai — the `model_reasoning_effort` subset the codex builder has always allowed (it lands in a
+ * `-c` TOML override, so it must stay a closed list); xai — `grok --help` 1.0.34 lists
+ * `--reasoning-effort <EFFORT>` with no value list.
+ *
+ * **No raw effort in a message (fix round 1).** An effort is user config and could be a pasted
+ * secret, so {@link displayEffort} echoes it only when it is a word from the closed lists below
+ * (a constant vocabulary); anything else renders as `(unrecognised value)`.
+ */
+
+/** @typedef {"anthropic" | "openai" | "xai"} Provider */
+
+/** @type {Readonly<Record<Provider, ReadonlyArray<string> | null>>} */
+export const PROVIDER_EFFORTS = Object.freeze({
+  anthropic: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+  openai: Object.freeze(['minimal', 'low', 'medium', 'high']),
+  xai: null,
+});
+
+/**
+ * Every effort word any provider's closed list names — a constant vocabulary, so a value found
+ * here may be echoed in a message (it is not user data that could be a secret).
+ * @param {Readonly<Record<string, ReadonlyArray<string> | null>>} [table]
+ * @returns {ReadonlyArray<string>}
+ */
+export function knownEffortWords(table = PROVIDER_EFFORTS) {
+  return Object.freeze([...new Set(Object.values(table).flatMap((list) => list ?? []))]);
+}
+
+const KNOWN_WORDS = knownEffortWords();
+
+/**
+ * @param {unknown} effort
+ * @returns {string} `"xhigh"` (quoted) for a known effort word, `(unrecognised value)` otherwise.
+ */
+export function displayEffort(effort) {
+  return typeof effort === 'string' && KNOWN_WORDS.includes(effort) ? `"${effort}"` : '(unrecognised value)';
+}
+
+/**
+ * `kind`: `"ok"`; `"invalid"` (not in the provider's closed list — `allowed` names the list);
+ * `"unsupported"` (the provider takes no effort); `"empty"` (free-form provider, value not a
+ * non-empty string); `"unknown-provider"` (not a table key — another check reports the provider).
+ * @typedef {{kind: "ok" | "invalid" | "unsupported" | "empty" | "unknown-provider", allowed: ReadonlyArray<string>}} EffortCheck
+ */
+
+const NONE = Object.freeze(/** @type {string[]} */ ([]));
+
+/**
+ * Checks one effort against one provider. `undefined` (no effort set) always passes.
+ * @param {unknown} provider
+ * @param {unknown} effort
+ * @param {Readonly<Record<string, ReadonlyArray<string> | null>>} [table]
+ * @returns {EffortCheck}
+ */
+export function checkEffort(provider, effort, table = PROVIDER_EFFORTS) {
+  if (effort === undefined) {
+    return { kind: 'ok', allowed: NONE };
+  }
+  if (typeof provider !== 'string' || !Object.hasOwn(table, provider)) {
+    return { kind: 'unknown-provider', allowed: NONE };
+  }
+  const allowed = table[provider];
+  if (allowed === null) {
+    return { kind: typeof effort === 'string' && effort.length > 0 ? 'ok' : 'empty', allowed: NONE };
+  }
+  if (allowed.length === 0) {
+    return { kind: 'unsupported', allowed: NONE };
+  }
+  return { kind: typeof effort === 'string' && allowed.includes(effort) ? 'ok' : 'invalid', allowed };
+}
+
+/**
+ * The builders' guard: throws the builder-named TypeError for an effort `checkEffort` refuses.
+ * The effort is shown through {@link displayEffort} only. An unknown provider is not this guard's
+ * concern (each builder is called with its own fixed provider; `buildArgv` refuses unknown ones).
+ * @param {string} builderName - e.g. `"buildCodexArgv"`.
+ * @param {Provider} provider
+ * @param {unknown} effort
+ * @param {Readonly<Record<string, ReadonlyArray<string> | null>>} [table]
+ * @throws {TypeError}
+ */
+export function assertEffortForProvider(builderName, provider, effort, table = PROVIDER_EFFORTS) {
+  const result = checkEffort(provider, effort, table);
+  const shown = displayEffort(effort);
+  switch (result.kind) {
+    case 'ok':
+    case 'unknown-provider':
+      return;
+    case 'invalid':
+      throw new TypeError(`${builderName}: effort must be one of ${result.allowed.join(', ')} when given, got ${shown}`);
+    case 'unsupported':
+      throw new TypeError(`${builderName}: provider ${provider} takes no effort, got ${shown}`);
+    default:
+      throw new TypeError(`${builderName}: effort must be a non-empty string when given, got ${shown}`);
+  }
+}

package/src/engines/sentinel.mjs

@@ -131,3 +131,37 @@ export function verifyAck(output, expectedSha8, expectedLines, opts = {}) {
   }
   return { status: 'ok', ack };
 }
+
+/**
+ * A `review-file` ticket id: 24 lowercase hex characters standing alone — not part of a longer hex
+ * run (a commit sha) and not inside a path or file name (no word, `.`, `/` or `-` touching it).
+ */
+const TICKET_IN_LINE = /(?<![\w./-])[0-9a-f]{24}(?![\w/-]|\.\w)/;
+
+/** @param {string} s */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The coder's final report must name the `review-file` ticket of every changed file (B36): a line
+ * that names the path and a ticket id, e.g. `reviewed src/a.mjs ticket 0123456789abcdef01234567`.
+ * A line counts for a file only when it names exactly ONE of the changed files (a line listing two
+ * paths counts for neither) and carries a ticket id outside that path (the path is blanked before
+ * the ticket is looked for). Fail closed: a file with no such line is missing, and the
+ * orchestrator treats the report as FAILED whatever its sentinel says
+ * (`skill/templates/coder-brief.md`).
+ * @param {string} report - the coder's final report (or its whole transcript).
+ * @param {string[]} files - the block's changed files, repo-root-relative.
+ * @returns {string[]} the files with no ticket id in the report, in the order given.
+ */
+export function missingReviewTickets(report, files) {
+  if (typeof report !== 'string') throw new TypeError('missingReviewTickets: report must be a string');
+  const named = files.map((file) => ({ file, re: new RegExp(`(?<![\\w./-])${escapeRe(file)}(?![\\w/-]|\\.\\w)`, 'g') }));
+  /** @type {Set<string>} */
+  const ticketed = new Set();
+  for (const line of report.split('\n')) {
+    const hits = named.filter((n) => line.search(n.re) >= 0);
+    if (hits.length !== 1) continue;
+    if (TICKET_IN_LINE.test(line.replace(hits[0].re, ' '))) ticketed.add(hits[0].file);
+  }
+  return files.filter((file) => !ticketed.has(file));
+}