@codedology/code-forge 0.1.0

package/src/doctor/worker-probe.mjs

@@ -0,0 +1,125 @@
+/**
+ * Worker start/stop and signer rows (plan §2.3, §4.8, §8.6; block B13b).
+ *
+ * The probe makes a throwaway run in a throwaway git repo (the project's `.code-forge.yml` copied
+ * in): B8 `startRun` generates the run key, B8 `signer` signs a row and verifies it (and refuses
+ * a byte-flipped copy), B11 `launchWorker` starts `code-forge worker` detached and waits for its
+ * queue announcement, then the worker is stopped (SIGTERM, SIGKILL of its group after 5 s). The
+ * run's record, key, lock and temp root are removed afterwards: doctor leaves no run behind.
+ *
+ * The `signer` row is printed on every full run: `signer: same-user boundary only` (§8.6) — the
+ * MAC is tamper evidence within ordinary tool use, never a boundary against a same-user process.
+ */
+
+import { copyFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { runsDir } from '../state/paths.mjs';
+import { startRun } from '../state/run.mjs';
+import { loadKey, signRow, verifyRow } from '../state/signer.mjs';
+import { exec } from '../util/exec.mjs';
+import { isAlive, registerPid, unregisterPid } from '../util/reaper.mjs';
+import { pidsDir, tmpBase } from '../util/tmp.mjs';
+import { launchWorker } from '../worker/loop.mjs';
+import { liveWorker } from '../worker/queue.mjs';
+import { gitChildEnv } from '../worker/ticket.mjs';
+import { row } from './rows.mjs';
+
+/** @typedef {import('./rows.mjs').Row} Row */
+
+export const SIGNER_ROW = Object.freeze(row('signer', 'INFO', 'signer', 'same-user boundary only'));
+
+const STOP_WAIT_MS = 5000;
+
+/** @param {() => boolean} cond @param {number} ms */
+async function waitFor(cond, ms) {
+  const until = Date.now() + ms;
+  while (Date.now() < until) {
+    if (cond()) return true;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  return cond();
+}
+
+/**
+ * SIGTERM the worker, then SIGKILL its group when it is still alive after `STOP_WAIT_MS`.
+ * @param {number} pid @returns {Promise<boolean>} true when it stopped on SIGTERM.
+ */
+async function stopWorker(pid) {
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    return true; // already gone
+  }
+  if (await waitFor(() => !isAlive(pid), STOP_WAIT_MS)) return true;
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    // gone meanwhile
+  }
+  await waitFor(() => !isAlive(pid), 2000);
+  return false;
+}
+
+/** @param {string} runId remove the probe run's record, key, lock and anything else it left in the runs dir. */
+function removeRun(runId) {
+  let names = [];
+  try {
+    names = readdirSync(runsDir());
+  } catch {
+    return;
+  }
+  for (const name of names) if (name === `${runId}.json` || name === `${runId}.key` || name === `${runId}.lock` || name.startsWith(`${runId}.json.`)) rmSync(path.join(runsDir(), name), { recursive: true, force: true });
+}
+
+/**
+ * @param {{cfg: Record<string, any>, configFile: string, workDir: string, runRootDir: string, env: NodeJS.ProcessEnv, runId: string}} ctx
+ * @returns {Promise<Row[]>} the `signer key` row, the `worker` row and the `signer` line.
+ */
+export async function probeWorkerAndSigner(ctx) {
+  const { runId, env } = ctx;
+  const repo = path.join(ctx.workDir, 'worker-repo');
+  const rows = [];
+  /** @type {number | null} */
+  let pid = null;
+  try {
+    mkdirSync(repo, { recursive: true, mode: 0o700 });
+    const init = await exec(['git', 'init', '-q'], { cwd: repo, env: gitChildEnv(env), timeoutMs: 20000 });
+    if (init.result !== 'ok') throw Object.assign(new Error('git init failed'), { code: 'git-init' });
+    copyFileSync(ctx.configFile, path.join(repo, '.code-forge.yml'));
+    await startRun({ workspace: repo, project: 'doctor-probe', config: ctx.cfg, runId, writeRow: async () => {} });
+
+    const key = await loadKey(runId);
+    const signed = signRow({ event: 'doctor.probe', run: runId }, key);
+    const flipped = { ...signed, event: 'doctor.probf' };
+    const signerOk = verifyRow(signed, key).ok && verifyRow(flipped, key).reason === 'mismatch';
+    rows.push(row('signer-key', signerOk ? 'OK' : 'FAIL', 'signer key', signerOk ? 'generated; a signed row verifies, a changed one is refused' : 'sign/verify round trip failed'));
+
+    const started = await launchWorker({ runId, workspace: repo, env });
+    pid = started.pid;
+    registerPid(pidsDir(ctx.runRootDir), pid, 'code-forge worker'); // a killed doctor's worker is reaped by the next sweep
+    const announced = liveWorker(started.repoRoot)?.pid === pid;
+    const clean = await stopWorker(pid);
+    unregisterPid(pidsDir(ctx.runRootDir), pid);
+    const workerPid = pid;
+    pid = null;
+    const gone = liveWorker(started.repoRoot) === null;
+    rows.push(announced && clean && gone
+      ? row('worker', 'OK', 'worker', `pid ${workerPid} started, announced itself and stopped on SIGTERM`)
+      : row('worker', 'FAIL', 'worker', `pid ${workerPid} start/stop incomplete (announced=${announced}, stopped on SIGTERM=${clean}, retracted=${gone})`));
+  } catch (err) {
+    if (!rows.some((r) => r.id === 'signer-key')) rows.push(row('signer-key', 'FAIL', 'signer key', `run key could not be generated (${err?.code ?? err?.name ?? 'error'})`));
+    rows.push(row('worker', 'FAIL', 'worker', `could not start (${err?.code ?? err?.name ?? 'error'})`));
+  } finally {
+    if (pid !== null) await stopWorker(pid);
+    removeRun(runId);
+    const cfgRoot = typeof ctx.cfg?.tmp?.root === 'string' ? ctx.cfg.tmp.root : undefined;
+    try {
+      rmSync(path.join(tmpBase(cfgRoot), runId), { recursive: true, force: true }); // the worker's own run root
+    } catch {
+      // tmp.root invalid: the tmp row reports it
+    }
+    rmSync(repo, { recursive: true, force: true });
+  }
+  rows.push(SIGNER_ROW);
+  return rows;
+}

package/src/engines/alias-map.mjs

@@ -0,0 +1,78 @@
+/**
+ * The Claude Agent-tool alias map (plan §5.2): under `engine: harness` (no Solo, R2 default) the
+ * orchestrator calls `Agent(subagent_type: general-purpose, model: <alias>, prompt: <pointer>)` —
+ * the Agent tool takes a FAMILY ALIAS (`sonnet|opus|haiku|fable`, per the pinned Claude `--model`
+ * help text: "Provide an alias for the latest model (e.g. 'fable', 'opus', or 'sonnet')"), never a
+ * full model id, and it has no `effort` parameter at all. So this module does two things: (1) maps
+ * a configured model id to its family alias by prefix, and (2) always reports
+ * `effort_effective: null` for an Agent-tool dispatch, so the ledger and `doctor` can show that an
+ * effort setting silently had no effect there (plan §5.2: "the ledger records `effort_effective:
+ * null` and `doctor` prints it" — note the plan's own field name is snake_case; fix round 1
+ * corrected this module's key from `effortEffective` to match it exactly).
+ *
+ * **Fix round 1 (isolated per-file review):**
+ *  - The prefix check now requires a WORD boundary: `model === prefix` or `model.startsWith(prefix
+ *    + '-')`. A bare `model.startsWith(prefix)` accepted typos like `claude-opusx` or
+ *    `claude-sonnetfoo`, which goes against this module's own stated rule ("refuse rather than
+ *    guess when an id is mistyped").
+ *  - `toAgentToolDispatch` destructures with a default so `undefined`/`null` params produce the
+ *    same clear `TypeError` `resolveClaudeAlias` gives for a bad `model`, instead of a generic
+ *    property-access crash before that check ever runs.
+ *  - The dispatch object's key is now `effort_effective` (was `effortEffective`).
+ */
+
+/**
+ * Model-id prefix -> Agent-tool alias, matched longest-prefix-first so a future 2-word family name
+ * cannot be shadowed by a shorter one that happens to be a prefix of it.
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const FAMILY_ALIASES = Object.freeze(
+  /** @type {[string, string][]} */ ([
+    ['claude-haiku', 'haiku'],
+    ['claude-sonnet', 'sonnet'],
+    ['claude-opus', 'opus'],
+    ['claude-fable', 'fable'],
+  ]).sort((a, b) => b[0].length - a[0].length),
+);
+
+/**
+ * @param {string} model
+ * @param {string} prefix
+ * @returns {boolean} true only for an EXACT family match or `prefix` followed by `-` — never a
+ *   bare substring prefix (fix round 1, MINOR: refuses `claude-opusx`, `claude-sonnetfoo`, …).
+ */
+function matchesFamily(model, prefix) {
+  return model === prefix || model.startsWith(`${prefix}-`);
+}
+
+/**
+ * @param {string} model - a resolved Claude model id, e.g. `"claude-opus-5-5"`.
+ * @returns {string} the Agent-tool alias for `model`'s family.
+ * @throws {Error} when `model` matches no known family prefix — refusing rather than guessing
+ *   keeps a typo'd or brand-new id from silently dispatching to the wrong family.
+ */
+export function resolveClaudeAlias(model) {
+  if (typeof model !== 'string' || model.length === 0) {
+    throw new TypeError('resolveClaudeAlias: model must be a non-empty string');
+  }
+  const match = FAMILY_ALIASES.find(([prefix]) => matchesFamily(model, prefix));
+  if (!match) {
+    throw new Error(`resolveClaudeAlias: no known family alias for model "${model}"`);
+  }
+  return match[1];
+}
+
+/** @typedef {{subagentType: "general-purpose", model: string, effort_effective: null}} AgentToolDispatch */
+
+/**
+ * @param {{model?: string, effort?: string}} [params] - `effort` is accepted (a caller may pass the
+ *   resolved level's effort through unconditionally) but is never reflected in the Agent-tool
+ *   call — see the module doc. Defaults to `{}` so a missing/`undefined` `params` still reaches
+ *   {@link resolveClaudeAlias}'s own clear `model` error, instead of crashing on `params.model`
+ *   here first.
+ * @returns {AgentToolDispatch}
+ * @throws {Error} propagated from {@link resolveClaudeAlias} for an unknown/missing family.
+ */
+export function toAgentToolDispatch({ model } = {}) {
+  return { subagentType: 'general-purpose', model: resolveClaudeAlias(/** @type {string} */ (model)), effort_effective: null };
+}

package/src/engines/builders/claude.mjs

@@ -0,0 +1,224 @@
+/**
+ * Claude Code 2.1.282 argv builder (plan §5.2, pinned against `test/fixtures/help/claude-2.1.282.txt`
+ * — B0's byte copy of `claude --help` on this Mac, 2026-09-24). Pure: no I/O, no CLI spawning
+ * (`src/util/exec.mjs` is the one place that spawns; B9's `spawn.mjs` calls it with this argv).
+ *
+ * Six roles collapse to two shapes: `coder` (writes files, cwd = the project tree) and everything
+ * else — `reviewer`/`judge`/`s2`/`author`/`facts` (closed-book, cwd = an empty temp dir with the
+ * packet). `facts` is the one role Claude treats specially even within the closed-book shape
+ * (§0.6.7, §8.4): `--tools ""` becomes `--tools "Bash"`, and `--disallowedTools` + `--restricted`
+ * are added so the facts delegate can run read-only shell commands but nothing that writes.
+ *
+ * **Return contract (fix round 3, root ruling — corrects plan §5.2's "<brief pointer>" for the
+ * closed-book shape):** `{cli, role, argv, cwd, stdinFile?, forbiddenRendered?}`.
+ *  - `coder`: the brief is a POINTER — the coder has tools and opens it itself. argv ends with a
+ *    literal `--` then `promptPath`, so no variadic flag (`--disallowedTools <tools...>`) can ever
+ *    swallow it. No `stdinFile`.
+ *  - closed-book (`reviewer`/`judge`/`s2`/`author`/`facts`): a role built with `--tools ""` cannot
+ *    open a path, so a pointer would leave the model reviewing nothing. The argv carries NO prompt
+ *    positional (and no `--`); `stdinFile === promptPath` names the packet file whose CONTENT the
+ *    spawner (B9) must pipe to the child's stdin. `claude -p` with no prompt argument reads the
+ *    prompt from stdin (`--input-format` default "text", help fixture line "--input-format <format>
+ *    Input format (only works with --print)"); the root verified the stdin form against the real
+ *    `claude -p --safe-mode --tools ""` on this Mac (2026-09-24). `facts` has `Bash` and could
+ *    read the file, but it takes the same stdin path so every closed-book role has ONE delivery
+ *    mechanism.
+ *
+ * **Doctor probe item for B13 (no network in B4's tests):** `claude: closed-book stdin delivery` —
+ * spawn this module's `reviewer` argv with `stdinFile` piped in, the packet containing a unique
+ * canary token and the instruction "reply with the canary"; PASS when the JSON `result` contains
+ * the canary, FAIL (`claude: closed-book packet not delivered`) otherwise.
+ *
+ * **Forbidden-list rendering is a PARAMETER** (`renderedForbidden`, default
+ * `renderForClaude(FORBIDDEN)` from B8's landed `src/util/forbidden.mjs`): this module only
+ * flattens whatever render it is given, so it never hard-codes a rule-string shape (seam C17).
+ * Both `coder` and `facts` refuse an empty render (0 usable rules) — a renderer regression must
+ * be a thrown error, never a silently weaker deny list.
+ *
+ * `--fallback-model <model>` takes exactly ONE model id in the pinned help. Only the first
+ * same-provider (`anthropic`) fallback whose model DIFFERS from the main `--model` is used —
+ * Claude Code refuses to start when the two are equal.
+ */
+
+import { FORBIDDEN, mergeForbidden, renderForClaude } from '../../util/forbidden.mjs';
+import { flattenRuleStrings, hasAnyRenderedRule } from '../render-rules.mjs';
+import { assertBaseParams } from './validate-params.mjs';
+
+export const CLI = 'claude';
+
+/**
+ * @typedef {{id: string, rules: ReadonlyArray<string>, enforced: boolean}} RenderedForbiddenEntry
+ */
+
+/**
+ * @typedef {{provider: string, model: string, effort?: string}} FallbackEntry
+ */
+
+/**
+ * @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} 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).
+ * @property {ReadonlyArray<RenderedForbiddenEntry>} [renderedForbidden] - used by the coder role
+ *   (default `renderForClaude(mergeForbidden())`, B4.2) and the `facts` role (default
+ *   `renderForClaude(FORBIDDEN)`, unchanged).
+ * @property {ReadonlyArray<FallbackEntry>} [fallback] - coder role only; see the module doc.
+ * @property {number} [maxBudgetUsd] - must be a finite number > 0 when given.
+ * @property {Record<string, any>} [schema] - compiled JSON Schema object; closed-book roles only,
+ *   sent inline (`--json-schema`, help text example is an inline JSON string, not a file path).
+ * @property {string} [systemPromptText] - the lens preamble; closed-book roles only.
+ */
+
+/**
+ * @typedef {object} BuiltCoder
+ * @property {"claude"} cli
+ * @property {"coder"} role
+ * @property {string[]} argv - ends with `--`, promptPath.
+ * @property {string} cwd
+ * @property {ReadonlyArray<RenderedForbiddenEntry>} forbiddenRendered
+ * @property {undefined} [stdinFile] - never set: the coder opens its brief itself.
+ */
+
+/**
+ * @typedef {object} BuiltClosedBook
+ * @property {"claude"} cli
+ * @property {"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {string[]} argv - no prompt positional.
+ * @property {string} cwd
+ * @property {string} stdinFile - the packet file the spawner pipes to stdin.
+ * @property {ReadonlyArray<RenderedForbiddenEntry>} [forbiddenRendered] - present only for `facts`.
+ */
+
+/**
+ * Extra `--disallowedTools` rules the `facts` role adds on top of the forbidden list (plan §5.2
+ * "Facts role only"): the two literal examples the plan names (`Bash(rm*)`, `Bash(git push*)`)
+ * plus the handful of other ordinary write verbs a read-only facts delegate never needs.
+ * @type {ReadonlyArray<string>}
+ */
+export const FACTS_EXTRA_WRITE_VERB_RULES = Object.freeze([
+  'Bash(rm*)',
+  'Bash(git push*)',
+  'Bash(git commit*)',
+  'Bash(git merge*)',
+  'Bash(mv*)',
+  'Bash(cp*)',
+]);
+
+/**
+ * @param {unknown} fallback
+ * @throws {TypeError} unless `fallback` is `undefined` or an array of objects whose `provider` and
+ *   `model` are non-empty strings. The message names the index only, never the entry's values.
+ */
+function assertValidFallback(fallback) {
+  if (fallback === undefined) return;
+  if (!Array.isArray(fallback)) {
+    throw new TypeError('buildClaudeArgv: fallback must be an array when given');
+  }
+  fallback.forEach((entry, index) => {
+    const valid =
+      entry !== null &&
+      typeof entry === 'object' &&
+      typeof entry.provider === 'string' &&
+      entry.provider.length > 0 &&
+      typeof entry.model === 'string' &&
+      entry.model.length > 0;
+    if (!valid) {
+      throw new TypeError(`buildClaudeArgv: fallback[${index}] must be an object with non-empty string provider and model`);
+    }
+  });
+}
+
+/**
+ * @param {ReadonlyArray<FallbackEntry> | undefined} fallback
+ * @param {string} provider
+ * @param {string} model - the main `--model`; a fallback equal to it is skipped.
+ * @returns {string | undefined} the FIRST same-provider fallback model id that differs from `model`.
+ */
+function firstSameProviderFallbackId(fallback, provider, model) {
+  return (fallback ?? []).find((f) => f.provider === provider && f.model !== model)?.model;
+}
+
+/**
+ * @param {unknown} maxBudgetUsd
+ * @param {string} builderName
+ * @throws {TypeError} unless `maxBudgetUsd` is `undefined` or a finite number > 0.
+ */
+function assertValidBudget(maxBudgetUsd, builderName) {
+  if (maxBudgetUsd !== undefined && !(typeof maxBudgetUsd === 'number' && Number.isFinite(maxBudgetUsd) && maxBudgetUsd > 0)) {
+    throw new TypeError(`${builderName}: maxBudgetUsd must be a finite number > 0 when given, got ${JSON.stringify(maxBudgetUsd)}`);
+  }
+}
+
+/**
+ * @param {ClaudeBuildParams} params
+ * @returns {BuiltCoder}
+ */
+function buildCoderArgv(params) {
+  // B4.2: a coder's deny list is `mergeForbidden()` — FORBIDDEN plus the coder-only entries
+  // (`code-forge block waive`, `--no-require-reviews`). A `contains` entry (`--no-require-reviews`)
+  // renders 0 rules (no pinned CLI has a match-anywhere rule), so it stays with the pre-spawn
+  // `isForbidden` check and the transcript grep, as before.
+  const { model, effort, promptPath, cwd, fallback, maxBudgetUsd, renderedForbidden = renderForClaude(mergeForbidden()) } = params;
+  assertValidBudget(maxBudgetUsd, 'buildClaudeArgv');
+  assertValidFallback(fallback);
+  if (!hasAnyRenderedRule(renderedForbidden)) {
+    throw new Error('buildClaudeArgv: coder role requires a non-empty forbidden-list render (got 0 usable rules)');
+  }
+  const argv = ['claude', '-p', '--model', model];
+  if (effort) argv.push('--effort', effort);
+  argv.push('--permission-mode', 'bypassPermissions');
+  argv.push('--output-format', 'json');
+  argv.push('--no-session-persistence');
+  if (maxBudgetUsd !== undefined) argv.push('--max-budget-usd', String(maxBudgetUsd));
+  argv.push('--disallowedTools', ...flattenRuleStrings(renderedForbidden));
+  const sameProviderId = firstSameProviderFallbackId(fallback, 'anthropic', model);
+  if (sameProviderId !== undefined) argv.push('--fallback-model', sameProviderId);
+  argv.push('--', promptPath);
+  return { cli: CLI, role: 'coder', argv, cwd, forbiddenRendered: renderedForbidden };
+}
+
+/**
+ * @param {ClaudeBuildParams} params
+ * @returns {BuiltClosedBook}
+ */
+function buildClosedBookArgv(params) {
+  const { model, effort, promptPath, cwd, schema, systemPromptText, maxBudgetUsd, renderedForbidden = renderForClaude(FORBIDDEN) } = params;
+  assertValidBudget(maxBudgetUsd, 'buildClaudeArgv');
+  // The dispatch in `buildClaudeArgv` never reaches this branch with role 'coder' — a runtime
+  // invariant the parameter type alone cannot prove, so the narrowing is explicit.
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const isFacts = role === 'facts';
+  if (isFacts && !hasAnyRenderedRule(renderedForbidden)) {
+    throw new Error('buildClaudeArgv: facts role requires a non-empty forbidden-list render (got 0 usable rules)');
+  }
+  const argv = ['claude', '-p', '--model', model];
+  if (effort) argv.push('--effort', effort);
+  argv.push('--safe-mode');
+  argv.push('--tools', isFacts ? 'Bash' : '');
+  argv.push('--strict-mcp-config');
+  argv.push('--no-session-persistence');
+  if (systemPromptText !== undefined) argv.push('--system-prompt', systemPromptText);
+  argv.push('--output-format', 'json');
+  if (schema !== undefined) argv.push('--json-schema', JSON.stringify(schema));
+  if (maxBudgetUsd !== undefined) argv.push('--max-budget-usd', String(maxBudgetUsd));
+  argv.push('--permission-mode', 'dontAsk');
+  if (!isFacts) {
+    return { cli: CLI, role, argv, cwd, stdinFile: promptPath };
+  }
+  argv.push('--disallowedTools', ...flattenRuleStrings(renderedForbidden), ...FACTS_EXTRA_WRITE_VERB_RULES);
+  // `--restricted` is boolean and last: it also terminates the variadic list above.
+  argv.push('--restricted');
+  return { cli: CLI, role, argv, cwd, stdinFile: promptPath, forbiddenRendered: renderedForbidden };
+}
+
+/**
+ * @param {ClaudeBuildParams} params
+ * @returns {BuiltCoder | BuiltClosedBook}
+ */
+export function buildClaudeArgv(params) {
+  assertBaseParams('buildClaudeArgv', params);
+  return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
+}

package/src/engines/builders/codex.mjs

@@ -0,0 +1,242 @@
+/**
+ * Codex 0.155.1 argv builder (plan §5.2, pinned against `test/fixtures/help/codex-0.155.1.txt`).
+ * No spawning; the coder role writes its per-session rules file (see "Execpolicy rules" below). NOT fully deterministic: when `outPath` is omitted, a default is drawn from
+ * `os.tmpdir()` + `randomBytes` — pass `outPath` for a reproducible argv (every snapshot test does).
+ *
+ * **Return contract (fix round 3):** `{cli, role, argv, cwd, outPath, stdinFile?, ...}`.
+ *  - `outPath` is ALWAYS returned — the effective `-o` target, worked out once per call, so the
+ *    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
+ *    `-`, 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)
+ *    pipes to stdin — a closed-book reviewer must receive the packet itself, never a path it may
+ *    not be able to open. The explicit `-` form was chosen over omitting the positional because
+ *    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
+ * 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.
+ *
+ * **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`
+ * help: "Do not load user or project execpolicy `.rules` files"). So the coder build creates a
+ * per-session Codex home under the run temp root (`../codex-home.mjs`, `codexHome` param or
+ * `defaultCodexHome()`), writes `rules/code-forge.rules` there (execpolicy Starlark, one
+ * `prefix_rule(..., decision="forbidden")` per `renderForCodex` pattern) and returns
+ * `env: {CODEX_HOME}` — the spawner MUST merge `env` into the child's environment. The home is
+ * never the user's real `~/.codex` (a `codexHome` there throws). This is the one builder that
+ * writes a file: the rules must exist before Codex starts, and the builder is the one place that
+ * holds the render.
+ *
+ * **Fix round 1 (isolated per-file review):**
+ *  - Unknown `role` now throws (was silently routed to closed-book) — `assertBaseParams`.
+ *  - `cwd` is now required and validated, same as `model`/`promptPath` — `assertBaseParams`.
+ *  - A coder-role render with 0 usable patterns now throws (see `claude.mjs`'s identical guard).
+ *  - The default `-o`/output-last-message path no longer lands INSIDE `cwd`: for the coder that
+ *    put a stray file in the project tree (picked up by later diffs); for a closed-book role it
+ *    silently broke the "isolation dir lists exactly 1 file" invariant. It now defaults to a path
+ *    under `os.tmpdir()`, keyed by role and a random suffix, always outside `cwd`.
+ *  - `effort` is now checked against the same four values the alias map / Claude `--effort` help
+ *    text documents (`low|medium|high|xhigh|max` minus `xhigh`/`max`, which Codex's own
+ *    `model_reasoning_effort` TOML values don't claim — kept to the portable subset
+ *    `minimal|low|medium|high`) before being written into a `-c` config override; Codex parses
+ *    that value as TOML, so an unchecked string could smuggle a quote or a nested key.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+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 { assertBaseParams } from './validate-params.mjs';
+
+export const CLI = 'codex';
+
+/** The rules file Codex loads from `<CODEX_HOME>/rules/` (B4.1). */
+export const RULES_FILE_NAME = CODEX_RULES_FILE_NAME;
+
+/** `-c` overrides that keep `$TMPDIR` and `/tmp` out of the coder's writable roots (B4.1). */
+export const SANDBOX_TMP_EXCLUSIONS = Object.freeze([
+  '-c',
+  'sandbox_workspace_write.exclude_tmpdir_env_var=true',
+  '-c',
+  'sandbox_workspace_write.exclude_slash_tmp=true',
+]);
+
+/**
+ * The coder's approval policy (B4.2). Codex 0.155.1 rejects `-s workspace-write` together with
+ * `--approve-for-me` (clap: "the argument '--sandbox <SANDBOX_MODE>' cannot be used with
+ * '--approve-for-me'"), so the coder drops `--approve-for-me` and keeps the sandbox. `codex exec`
+ * has no `-a/--ask-for-approval` flag (that one is on the interactive `codex` only), so the
+ * policy is set through the `approval_policy` config key, whose valid values the 0.155.1 config
+ * loader lists as `untrusted`, `on-failure`, `on-request`, `granular`, `never`. `never` = "Never
+ * ask for user approval. Execution failures are immediately returned to the model" (`codex
+ * --help`): a sandbox-denied command simply fails, nothing escalates out of the sandbox.
+ */
+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']);
+
+/**
+ * @typedef {{id: string, patterns: string[][], decision: "forbidden", enforced: boolean, description: string}} RenderedCodexEntry
+ */
+
+/**
+ * @typedef {object} CodexBuildParams
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {string} model
+ * @property {string} [effort] - one of {@link VALID_EFFORTS} when given.
+ * @property {string} promptPath - the brief file (coder: passed as a pointer) or the packet file
+ *   (closed-book: returned as `stdinFile`, piped to stdin by the spawner).
+ * @property {string} cwd - the project tree (coder) or an empty isolated temp dir (closed-book).
+ * @property {string} [outPath] - `-o` target; defaults to a fresh path under `os.tmpdir()`, NEVER
+ *   inside `cwd` (fix round 1).
+ * @property {string} [schemaPath] - closed-book only: a FILE PATH (`--output-schema <FILE>` takes
+ *   a path, unlike Claude/Grok's inline `--json-schema` string — see `test/fixtures/help/
+ *   codex-0.155.1.txt`).
+ * @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 {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.
+ */
+
+/**
+ * @param {string} role
+ * @returns {string} a fresh path under `os.tmpdir()`, never inside the caller's `cwd`.
+ */
+function defaultOutPath(role) {
+  return path.join(os.tmpdir(), `code-forge-${role}-output-${randomBytes(6).toString('hex')}.json`);
+}
+
+/**
+ * @param {unknown} outPath
+ * @param {string} role
+ * @returns {string} the effective `-o` target: the caller's `outPath`, or one fresh default.
+ * @throws {TypeError} unless `outPath` is `undefined` or a non-empty string.
+ */
+function effectiveOutPath(outPath, role) {
+  if (outPath === undefined) return defaultOutPath(role);
+  if (typeof outPath !== 'string' || outPath.length === 0) {
+    throw new TypeError('buildCodexArgv: outPath must be a non-empty string when given');
+  }
+  return outPath;
+}
+
+/**
+ * @param {string | undefined} effort
+ * @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)}`);
+  }
+}
+
+/**
+ * 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
+ * @returns {string[]}
+ */
+export function coderFlagArgv({ model, effort, cwd, outPath, promptPath }) {
+  const argv = ['codex', 'exec', '-m', model];
+  if (effort) argv.push('-c', `model_reasoning_effort=${effort}`);
+  argv.push('-s', 'workspace-write');
+  // 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`.
+  argv.push(...SANDBOX_TMP_EXCLUSIONS);
+  // B4.2: NO `--approve-for-me` (Codex 0.155.1 refuses it next to `-s`); see CODER_APPROVAL_POLICY.
+  argv.push(...CODER_APPROVAL_POLICY);
+  argv.push('-C', cwd);
+  argv.push('--json');
+  argv.push('-o', outPath);
+  argv.push(promptPath);
+  return argv;
+}
+
+/**
+ * @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}}}
+ */
+function buildCoderArgv(params) {
+  const { model, effort, promptPath, cwd, renderedForbidden = renderForCodex(mergeForbidden()) } = params;
+  assertValidEffort(effort);
+  const outPath = effectiveOutPath(params.outPath, 'coder');
+  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).
+  if (typeof codexHome !== 'string' || !path.isAbsolute(codexHome)) {
+    throw new TypeError('buildCodexArgv: codexHome must be an absolute path');
+  }
+  // `isInside` realpaths BOTH sides through their nearest existing ancestor (fix round 3): a
+  // `/var/...` cwd and a `/private/var/...` home are the same tree on macOS, and a symlinked cwd
+  // is compared by its target, so a string-different alias cannot slip a home into the cwd.
+  if (isInside(codexHome, cwd)) {
+    throw new Error('buildCodexArgv: the session CODEX_HOME must not be inside the coder cwd (the sandbox can write there)');
+  }
+  const home = prepareCodexHome(codexHome, renderedForbidden);
+  return {
+    cli: CLI,
+    role: 'coder',
+    argv,
+    cwd,
+    outPath,
+    env: { CODEX_HOME: home.codexHome },
+    forbiddenRendered: renderedForbidden,
+    rulesFile: { fileName: RULES_FILE_NAME, path: home.rulesPath, content: home.content, count: home.count },
+  };
+}
+
+/**
+ * @param {CodexBuildParams} params
+ * @returns {{cli: "codex", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string, outPath: string, stdinFile: string}}
+ */
+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.
+  const role = /** @type {"reviewer"|"judge"|"s2"|"author"|"facts"} */ (params.role);
+  const outPath = effectiveOutPath(params.outPath, role);
+  const argv = ['codex', 'exec', '-m', model];
+  if (effort) argv.push('-c', `model_reasoning_effort=${effort}`);
+  argv.push('-s', 'read-only');
+  argv.push('--ephemeral');
+  argv.push('--ignore-rules');
+  argv.push('--ignore-user-config');
+  argv.push('-C', cwd);
+  argv.push('--skip-git-repo-check');
+  if (schemaPath !== undefined) argv.push('--output-schema', schemaPath);
+  argv.push('-o', outPath);
+  argv.push('--json');
+  // `-` = "read the prompt from stdin" (pinned help); the packet CONTENT arrives there.
+  argv.push('-');
+  return { cli: CLI, role, argv, cwd, outPath, stdinFile: promptPath };
+}
+
+/**
+ * @param {CodexBuildParams} params
+ * @returns {ReturnType<typeof buildCoderArgv> | ReturnType<typeof buildClosedBookArgv>}
+ */
+export function buildCodexArgv(params) {
+  assertBaseParams('buildCodexArgv', params);
+  return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
+}