@codedology/code-forge 0.1.0

package/src/engines/builders/grok.mjs

@@ -0,0 +1,132 @@
+/**
+ * Grok 1.0.34 argv builder (plan §5.2, pinned against `test/fixtures/help/grok-1.0.34.txt`). Pure:
+ * no I/O, no CLI spawning.
+ *
+ * Like Codex, Grok's flag table has only two command shapes — coder, and "reviewer / judge / S2 /
+ * author / facts" — so `facts` routes through the same closed-book branch as the other four roles
+ * (Claude is the only provider with a facts-specific carve-out).
+ *
+ * The coder command has **no `-p`**: Grok's `-p`/`--single` flag is a different, single-turn mode
+ * the coder role must not use (the plan calls this out explicitly). The forbidden list arrives the
+ * same way Claude's does — as a `renderedForbidden` parameter, defaulting to
+ * `renderForGrok(FORBIDDEN)` from B8's landed extensions, never a hard dependency baked in.
+ *
+ * Grok's `--deny <RULE>` fixture help shows a single value, not a variadic `<RULE...>` — unlike
+ * Claude's documented `<tools...>` for `--disallowedTools`. This builder repeats `--deny <rule>`
+ * once per rendered rule string — a scalar (single-value) flag repeated, never a variadic-list
+ * swallow risk the way `claude.mjs`'s BLOCKER fix had to guard against, since each `--deny`
+ * occurrence's value slot is exactly one token wide.
+ *
+ * **Return contract (fix round 3):** `{cli, role, argv, cwd, forbiddenRendered?}` — never a
+ * `stdinFile`. Unlike Claude/Codex closed-book runs, Grok's `--prompt-file <PATH>` ("Single-turn
+ * prompt from a file", pinned help) makes the CLI itself read the packet and send its CONTENT as
+ * the prompt, so even a closed-book run with every tool denied receives the packet text; the
+ * spawner pipes nothing to stdin.
+ *
+ * Effort is sent as the canonical `--reasoning-effort <EFFORT>` (the pinned help lists `--effort`
+ * only as an alias), so the flag the builder emits is the exact one `probe.mjs` checks (fix round 3,
+ * found by the widened all-roles probe-coverage test).
+ *
+ * **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 rules now throws (see `claude.mjs`'s identical guard).
+ *  - `effort`, when given, must be a non-empty string (was pushed into argv unchecked).
+ */
+
+import { mergeForbidden, renderForGrok } from '../../util/forbidden.mjs';
+import { flattenRuleStrings, hasAnyRenderedRule } from '../render-rules.mjs';
+import { assertBaseParams } from './validate-params.mjs';
+
+export const CLI = 'grok';
+
+/**
+ * Built-in tool names the closed-book command denies wholesale via `--disallowed-tools` (in
+ * addition to the wildcard `--deny "*"`, per plan §5.2). Not independently verified against a
+ * machine-readable Grok tool list (none is documented in the pinned `--help`) — a reasonable,
+ * conservative superset, flagged in the facts diff.
+ * @type {ReadonlyArray<string>}
+ */
+export const GROK_ALL_BUILTIN_TOOLS = Object.freeze(['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'WebFetch', 'WebSearch']);
+
+/**
+ * @typedef {{id: string, rules: ReadonlyArray<string>, enforced: boolean}} RenderedGrokEntry
+ */
+
+/**
+ * @typedef {object} GrokBuildParams
+ * @property {"coder"|"reviewer"|"judge"|"s2"|"author"|"facts"} role
+ * @property {string} model
+ * @property {string} [effort] - a non-empty string when given.
+ * @property {string} promptPath - `--prompt-file` value (brief for coder, packet for closed-book).
+ * @property {string} cwd
+ * @property {ReadonlyArray<RenderedGrokEntry>} [renderedForbidden] - coder role only; defaults to
+ *   `renderForGrok(mergeForbidden())` (B4.2).
+ * @property {Record<string, any>} [schema] - closed-book only; sent inline like Claude's.
+ * @property {string} [systemPromptText] - closed-book only (`--system-prompt-override`).
+ */
+
+/**
+ * @param {unknown} effort
+ * @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)}`);
+  }
+}
+
+/**
+ * @param {GrokBuildParams} params
+ * @returns {{cli: "grok", role: "coder", argv: string[], cwd: string, forbiddenRendered: ReadonlyArray<RenderedGrokEntry>}}
+ */
+function buildCoderArgv(params) {
+  // B4.2: the coder's deny list is `mergeForbidden()` (FORBIDDEN + the coder-only entries). A
+  // `contains` entry renders 0 `--deny` rules; the pre-spawn check and the transcript grep keep it.
+  const { model, effort, promptPath, cwd, renderedForbidden = renderForGrok(mergeForbidden()) } = params;
+  assertValidEffort(effort);
+  if (!hasAnyRenderedRule(renderedForbidden)) {
+    throw new Error('buildGrokArgv: coder role requires a non-empty forbidden-list render (got 0 usable rules)');
+  }
+  const argv = ['grok', '--prompt-file', promptPath, '-m', model];
+  if (effort) argv.push('--reasoning-effort', effort);
+  argv.push('--permission-mode', 'bypassPermissions');
+  argv.push('--cwd', cwd);
+  for (const rule of flattenRuleStrings(renderedForbidden)) {
+    argv.push('--deny', rule);
+  }
+  return { cli: CLI, role: 'coder', argv, cwd, forbiddenRendered: renderedForbidden };
+}
+
+/**
+ * @param {GrokBuildParams} params
+ * @returns {{cli: "grok", role: "reviewer"|"judge"|"s2"|"author"|"facts", argv: string[], cwd: string}}
+ */
+function buildClosedBookArgv(params) {
+  const { model, effort, promptPath, cwd, schema, systemPromptText } = 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 argv = ['grok', '--prompt-file', promptPath, '-m', model];
+  if (effort) argv.push('--reasoning-effort', effort);
+  if (schema !== undefined) argv.push('--json-schema', JSON.stringify(schema));
+  argv.push('--disallowed-tools', GROK_ALL_BUILTIN_TOOLS.join(','));
+  argv.push('--deny', '*');
+  argv.push('--no-plan');
+  argv.push('--no-subagents');
+  argv.push('--max-turns', '1');
+  argv.push('--permission-mode', 'dontAsk');
+  argv.push('--cwd', cwd);
+  if (systemPromptText !== undefined) argv.push('--system-prompt-override', systemPromptText);
+  return { cli: CLI, role, argv, cwd };
+}
+
+/**
+ * @param {GrokBuildParams} params
+ * @returns {ReturnType<typeof buildCoderArgv> | ReturnType<typeof buildClosedBookArgv>}
+ */
+export function buildGrokArgv(params) {
+  assertBaseParams('buildGrokArgv', params);
+  return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
+}

package/src/engines/builders/index.mjs

@@ -0,0 +1,35 @@
+/**
+ * Generic per-provider argv-builder dispatch (plan §5.2). A later block (B9's `spawn.mjs`) calls
+ * `buildArgv({provider, ...})` rather than importing all three provider builders and branching
+ * itself.
+ *
+ * Every builder returns `{cli, role, argv, cwd, stdinFile?, outPath?, ...}` (fix round 3). The
+ * spawner MUST honour two fields: when `stdinFile` is set, pipe that file's CONTENT to the child's
+ * stdin (Claude and Codex closed-book roles — their argv carries no prompt pointer); when
+ * `outPath` is set (Codex, always), read the result from it and delete it afterwards.
+ */
+
+import { buildClaudeArgv } from './claude.mjs';
+import { buildCodexArgv } from './codex.mjs';
+import { buildGrokArgv } from './grok.mjs';
+
+export { buildClaudeArgv } from './claude.mjs';
+export { buildCodexArgv } from './codex.mjs';
+export { buildGrokArgv } from './grok.mjs';
+
+/** @type {Readonly<Record<"anthropic"|"openai"|"xai", (params: any) => any>>} */
+const BUILDERS = Object.freeze({ anthropic: buildClaudeArgv, openai: buildCodexArgv, xai: buildGrokArgv });
+
+/**
+ * @param {{provider: "anthropic"|"openai"|"xai"} & Record<string, any>} params
+ * @returns {any} whichever provider builder's return shape (`{cli, role, argv, cwd, stdinFile?, outPath?, ...}`).
+ */
+export function buildArgv(params) {
+  if (!params || !Object.hasOwn(BUILDERS, params.provider ?? '')) {
+    // Fix round 1 (MINOR): the message is now built from BUILDERS itself — the same object the
+    // check above uses — so it can never name a provider the check doesn't actually accept (the
+    // old version imported a SEPARATE `PROVIDER_CLI_NAMES` map for the message, which could drift).
+    throw new TypeError(`buildArgv: unknown provider "${params?.provider}" (expected one of ${Object.keys(BUILDERS).join(', ')})`);
+  }
+  return BUILDERS[/** @type {"anthropic"|"openai"|"xai"} */ (params.provider)](params);
+}

package/src/engines/builders/validate-params.mjs

@@ -0,0 +1,34 @@
+/**
+ * Shared parameter validation for the three provider builders (fix round 1, findings #2 MAJOR ×2
+ * + cwd MAJOR). Written once so `claude.mjs`/`codex.mjs`/`grok.mjs` cannot drift from each other on
+ * what counts as a valid `role`/`model`/`promptPath`/`cwd` — the review found `codex.mjs` and
+ * `grok.mjs` silently routed ANY non-'coder' string (a typo, `undefined`, a stray level name like
+ * `'L2'`) into the closed-book branch instead of refusing it.
+ */
+
+/**
+ * The six roles the plan's engine adapters section (§5.2) declares.
+ * @type {ReadonlyArray<"coder"|"reviewer"|"judge"|"s2"|"author"|"facts">}
+ */
+export const VALID_ROLES = Object.freeze(/** @type {const} */ (['coder', 'reviewer', 'judge', 's2', 'author', 'facts']));
+
+/**
+ * @param {string} builderName - for the thrown message, e.g. `"buildClaudeArgv"`.
+ * @param {unknown} params
+ * @throws {TypeError} for a missing/invalid `role`, `model`, `promptPath` or `cwd`.
+ */
+export function assertBaseParams(builderName, params) {
+  const p = /** @type {Record<string, unknown> | null | undefined} */ (params);
+  if (!p || typeof p !== 'object' || !VALID_ROLES.includes(/** @type {any} */ (p.role))) {
+    throw new TypeError(`${builderName}: params.role must be one of ${VALID_ROLES.join(', ')}, got ${JSON.stringify(p?.role)}`);
+  }
+  if (typeof p.model !== 'string' || p.model.length === 0) {
+    throw new TypeError(`${builderName}: params.model is required (non-empty string)`);
+  }
+  if (typeof p.promptPath !== 'string' || p.promptPath.length === 0) {
+    throw new TypeError(`${builderName}: params.promptPath is required (non-empty string)`);
+  }
+  if (typeof p.cwd !== 'string' || p.cwd.length === 0) {
+    throw new TypeError(`${builderName}: params.cwd is required (non-empty string)`);
+  }
+}

package/src/engines/codex-home.mjs

@@ -0,0 +1,230 @@
+/**
+ * Per-session `CODEX_HOME` for the Codex coder (block B4.1, plan §5.2 Codex row, §8.4, [A19]).
+ *
+ * Facts (Codex 0.155.1, read-only checks on this Mac):
+ *  - `codex exec --help`: `--ignore-rules  Do not load user or project execpolicy \`.rules\` files`
+ *    — `exec` loads execpolicy rules, but has NO flag naming a rules file, and `ConfigToml` has no
+ *    rules-path key, so `-c` cannot name one either.
+ *  - The "user" rules are `$CODEX_HOME/rules/*.rules` (`~/.codex/rules/default.rules` on this Mac;
+ *    the binary logs "loaded … .rules files in …"). `CODEX_HOME` is therefore the one per-run
+ *    handle: the coder runs with `CODEX_HOME=<run temp root>/…/codex-home`, whose
+ *    `rules/code-forge.rules` holds the rendered forbidden list. The user's real `~/.codex` (and
+ *    its own `rules/`) is never written.
+ *  - The file format is execpolicy Starlark, one `prefix_rule(pattern=[…], decision="forbidden",
+ *    justification="…")` per token-array prefix (`codex execpolicy check --rules <PATH> <COMMAND>…`
+ *    parses the same files; the doctor/facts evidence ran it against a rendered file).
+ *  - `--ignore-user-config`'s help says "auth still uses `CODEX_HOME`", so a fresh home has no
+ *    login. The real home's `auth.json` is COPIED in (0600; the bytes pass through one Buffer that
+ *    is never decoded, logged or kept), never symlinked: a symlink would let a write inside the
+ *    session home reach the real file. Both files the session home receives (the rules file and
+ *    the auth copy) are written with `writeFreshFile`: the destination is `lstat`ed and refused
+ *    when ANYTHING already exists there (a planted symlink included), then created with
+ *    `O_CREAT|O_EXCL|O_NOFOLLOW`, so a token can never be written through a link (L3 patch).
+ *    Tradeoff: a token refresh inside the session is NOT written back to the real
+ *    `auth.json`; if Codex rotates the refresh token, the user's own Codex may have to log in
+ *    again. With no `auth.json` present, Codex uses its env auth (`CODEX_API_KEY` /
+ *    `OPENAI_API_KEY`). The user's Codex TOML config is NOT linked: the coder argv carries every
+ *    setting it needs, and the user's own allow-rules stay out of a coder session.
+ *
+ * INVARIANT (fix round 1): the coder's sandbox can never write the session home. The home lives
+ * under the run temp root; the builder runs the coder with `-s workspace-write` PLUS
+ * `-c sandbox_workspace_write.exclude_tmpdir_env_var=true` and
+ * `-c sandbox_workspace_write.exclude_slash_tmp=true` (both keys are in the 0.155.1 binary), so the
+ * only writable root is the project `-C <cwd>` — and a home inside that cwd is refused. On top, the
+ * rules file is 0444. The directories stay 0700, not 0555: a 0555 directory makes the run-root
+ * sweep's `rmSync(…, {recursive, force})` fail (ENOTEMPTY, checked on this Mac), which would leave
+ * the whole run root — the auth copy included — behind. Tradeoff of the tmp exclusion: the coder's
+ * own commands cannot write `$TMPDIR` or `/tmp` either.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { currentRunRoot } from '../util/tmp.mjs';
+
+/** The rules file name inside `<codexHome>/rules/`. Codex loads every `*.rules` file there. */
+export const CODEX_RULES_FILE_NAME = 'code-forge.rules';
+
+/**
+ * @typedef {{id: string, patterns: ReadonlyArray<ReadonlyArray<string>>, enforced: boolean, description?: string}} CodexRenderedEntry
+ */
+
+/**
+ * The user's real Codex home: `$CODEX_HOME` when set, else `$HOME/.codex` (`os.homedir()` without `HOME`).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} an absolute path.
+ */
+export function realCodexHome(env = process.env) {
+  const fromEnv = env.CODEX_HOME;
+  const home = typeof env.HOME === 'string' && env.HOME.length > 0 ? env.HOME : os.homedir();
+  return path.resolve(typeof fromEnv === 'string' && fromEnv.length > 0 ? fromEnv : path.join(home, '.codex'));
+}
+
+/** @param {string} p @returns {string} the realpath of the longest existing ancestor + the rest. */
+function resolveExisting(p) {
+  let head = path.resolve(p);
+  const tail = [];
+  while (!existsSync(head)) {
+    const parent = path.dirname(head);
+    if (parent === head) break;
+    tail.unshift(path.basename(head));
+    head = parent;
+  }
+  return path.join(realpathSync(head), ...tail);
+}
+
+/**
+ * Whether `candidate` is `dir` or inside it (both sides symlink-resolved).
+ * @param {string} candidate @param {string} dir @returns {boolean}
+ */
+export function isInside(candidate, dir) {
+  const rel = path.relative(resolveExisting(dir), resolveExisting(candidate));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Whether `candidate` is the real Codex home or inside it (both sides symlink-resolved).
+ * @param {string} candidate @param {NodeJS.ProcessEnv} [env] @returns {boolean}
+ */
+export function isInsideRealCodexHome(candidate, env = process.env) {
+  return isInside(candidate, realCodexHome(env));
+}
+
+/**
+ * Execpolicy Starlark for a `renderForCodex` render: one `prefix_rule` per pattern, in entry
+ * order. `JSON.stringify` of a string is a valid Starlark string literal for these ASCII tokens.
+ * @param {ReadonlyArray<CodexRenderedEntry>} rendered
+ * @returns {{content: string, count: number}}
+ */
+export function renderCodexRules(rendered) {
+  const lines = ['# code-forge forbidden list (src/util/forbidden.mjs). Generated per session; do not edit.'];
+  let count = 0;
+  for (const entry of rendered) {
+    for (const pattern of entry.patterns) {
+      const tokens = pattern.map((t) => JSON.stringify(String(t))).join(', ');
+      lines.push(`prefix_rule(pattern=[${tokens}], decision="forbidden", justification=${JSON.stringify(`code-forge: ${entry.id}`)})`);
+      count += 1;
+    }
+  }
+  return { content: `${lines.join('\n')}\n`, count };
+}
+
+/** The name of the run-root directory every session home lives in. */
+export const CODEX_HOMES_DIR_NAME = 'codex-homes';
+
+/** @returns {string} `<currentRunRoot()>/codex-homes`, the one parent of every session home. */
+export function sessionCodexHomesDir() {
+  return path.join(currentRunRoot(), CODEX_HOMES_DIR_NAME);
+}
+
+/**
+ * Whether `candidate` is STRICTLY inside `<currentRunRoot()>/codex-homes/` (both sides
+ * symlink-resolved through their nearest existing ancestor). The directory itself, the run root,
+ * the real Codex home, `$HOME` and any sibling are all outside.
+ * @param {string} candidate @returns {boolean}
+ */
+export function isSessionCodexHome(candidate) {
+  if (typeof candidate !== 'string' || !path.isAbsolute(candidate)) return false;
+  const rel = path.relative(resolveExisting(sessionCodexHomesDir()), resolveExisting(candidate));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * A fresh per-session Codex home path under the run temp root.
+ * @returns {string}
+ */
+export function defaultCodexHome() {
+  return path.join(sessionCodexHomesDir(), `coder-${randomBytes(6).toString('hex')}`);
+}
+
+/**
+ * Create `<codexHome>/rules/code-forge.rules` (dirs 0700, file 0444) and copy the real home's
+ * `auth.json` (0600) when it exists.
+ * @param {string} codexHome - absolute; never the real Codex home or inside it.
+ * @param {ReadonlyArray<CodexRenderedEntry>} rendered
+ * @param {{env?: NodeJS.ProcessEnv}} [opts]
+ * @returns {{codexHome: string, rulesPath: string, count: number, content: string}}
+ * @throws {Error} when `codexHome` is relative, is (or is inside) the real Codex home, or the
+ *   render yields 0 rules.
+ */
+export function prepareCodexHome(codexHome, rendered, opts = {}) {
+  const env = opts.env ?? process.env;
+  if (typeof codexHome !== 'string' || !path.isAbsolute(codexHome)) {
+    throw new TypeError('prepareCodexHome: codexHome must be an absolute path');
+  }
+  if (isInsideRealCodexHome(codexHome, env)) {
+    throw new Error('prepareCodexHome: codexHome must not be the real Codex home or inside it');
+  }
+  // Fix round 4: an ANCESTOR of the real home (`$HOME`, `/`) is not "inside" it, yet a home there
+  // would put `rules/` and an auth copy where the user lives. The only place a session home may be
+  // is strictly inside `<run root>/codex-homes/` — the same confinement `removeCodexHome` enforces.
+  if (!isSessionCodexHome(codexHome)) {
+    throw new Error(`prepareCodexHome: codexHome must be strictly inside <run root>/${CODEX_HOMES_DIR_NAME}/`);
+  }
+  const { content, count } = renderCodexRules(rendered);
+  if (count === 0) throw new Error('prepareCodexHome: the forbidden-list render has 0 rules');
+  const rulesDir = path.join(codexHome, 'rules');
+  const rulesPath = path.join(rulesDir, CODEX_RULES_FILE_NAME);
+  const auth = path.join(realCodexHome(env), 'auth.json');
+  const copy = path.join(codexHome, 'auth.json');
+  // L3 patch: both destinations are checked BEFORE anything is written, so a planted entry (a
+  // symlink at either path) makes this throw with the home left exactly as found.
+  refuseExisting(rulesPath);
+  refuseExisting(copy);
+  mkdirSync(rulesDir, { recursive: true, mode: 0o700 });
+  if (lstatSync(rulesDir).isSymbolicLink()) throw new Error('prepareCodexHome: refusing a symlinked rules directory');
+  writeFreshFile(rulesPath, Buffer.from(content, 'utf8'), 0o444);
+  if (existsSync(auth)) {
+    writeFreshFile(copy, readFileSync(auth), 0o600);
+  }
+  return { codexHome, rulesPath, count, content };
+}
+
+/**
+ * Throw when anything at all (file, directory, symlink — dangling or not) already exists at `dest`.
+ * @param {string} dest
+ */
+function refuseExisting(dest) {
+  try {
+    lstatSync(dest);
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return;
+    throw err;
+  }
+  throw new Error(`prepareCodexHome: refusing to write ${path.basename(dest)}: something already exists at the destination`);
+}
+
+/**
+ * Create `dest` exclusively, never following a link (`O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW`, mode
+ * 0600), write `bytes`, set the final `mode` on the open descriptor, close. A path that gained an
+ * entry between `refuseExisting` and this open fails on `O_EXCL` — nothing is ever written through it.
+ * @param {string} dest @param {Buffer} bytes @param {number} mode
+ */
+function writeFreshFile(dest, bytes, mode) {
+  const { O_WRONLY, O_CREAT, O_EXCL, O_NOFOLLOW } = constants;
+  const fd = openSync(dest, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o600);
+  try {
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset);
+    fchmodSync(fd, mode);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Remove a session home (the auth copy with it). The ONLY recursive delete of this module, and it
+ * is confined (fix round 3): `codexHome` must be strictly inside `<currentRunRoot()>/codex-homes/`
+ * after realpath resolution, or this throws and deletes nothing — the real `~/.codex`, `$HOME`,
+ * the run root itself and any sibling directory are refused. No-op when the (confined) path does
+ * not exist.
+ * @param {string} codexHome
+ * @throws {Error} when `codexHome` is not strictly inside the run root's `codex-homes/`.
+ */
+export function removeCodexHome(codexHome) {
+  if (!isSessionCodexHome(codexHome)) {
+    throw new Error(`removeCodexHome: refusing to delete a path outside <run root>/${CODEX_HOMES_DIR_NAME}/`);
+  }
+  rmSync(resolveExisting(codexHome), { recursive: true, force: true });
+}

package/src/engines/isolation.mjs

@@ -0,0 +1,84 @@
+/**
+ * The empty-cwd temp dir every closed-book session (reviewer, judge, S2, author, facts) runs in
+ * (plan §4.3, §5.2). A fresh `os.tmpdir()`-rooted directory holding EXACTLY the packet/brief file
+ * a caller writes into it — no project source, no `CLAUDE.md`/`AGENTS.md`, nothing a closed-book
+ * session could read besides what it was explicitly handed. `doctor`'s isolation probe (B13, §2.3)
+ * asks a closed-book session to echo the first line of the project's `CLAUDE.md` — this module is
+ * why that should come back empty: the session's cwd never contained one.
+ *
+ * **Fix round 1 (isolated per-file review):**
+ *  - `fileName` now also refuses `.` and `..` (previously only a `/`/`\` check — `path.join(dir,
+ *    '..')` points OUTSIDE the fresh dir; the old code didn't escape, since `writeFile` on a
+ *    directory path fails with `EISDIR`, but the caller got a vague filesystem error instead of
+ *    the documented `TypeError`).
+ *  - A `writeFile` failure (bad content type, disk full, …) after `mkdtemp` no longer leaks an
+ *    empty `code-forge-isolated-*` directory: the dir is removed before rethrowing.
+ *  - `cleanupIsolatedWorkspace` now also requires `dir`'s PARENT to be the temp root (or the
+ *    `baseDir` the caller passes, matching `createIsolatedWorkspace`'s own override) — the old
+ *    basename-prefix-only check would recursively delete ANY directory anywhere on disk that
+ *    happened to be named `code-forge-isolated-*`, not only ones this module actually created.
+ */
+
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Directory name prefix for every isolated workspace this module creates. */
+const DIR_PREFIX = 'code-forge-isolated-';
+
+/**
+ * @param {string} fileName - a plain basename, e.g. `"packet.json"` — never a path (a caller
+ *   trying to escape the fresh temp dir is a bug in the caller, not something to silently "fix").
+ * @param {string} content
+ * @param {{baseDir?: string}} [opts] - `baseDir` overrides `os.tmpdir()` (tests only).
+ * @returns {Promise<{dir: string, filePath: string}>}
+ * @throws {TypeError} if `fileName` contains a path separator, is empty, or is `.`/`..`.
+ */
+export async function createIsolatedWorkspace(fileName, content, opts = {}) {
+  if (
+    typeof fileName !== 'string' ||
+    fileName.length === 0 ||
+    fileName.includes('/') ||
+    fileName.includes('\\') ||
+    fileName === '.' ||
+    fileName === '..'
+  ) {
+    throw new TypeError(`createIsolatedWorkspace: fileName must be a plain basename, got ${JSON.stringify(fileName)}`);
+  }
+  const dir = await mkdtemp(path.join(opts.baseDir ?? os.tmpdir(), DIR_PREFIX));
+  const filePath = path.join(dir, fileName);
+  try {
+    await writeFile(filePath, content, 'utf8');
+  } catch (err) {
+    await rm(dir, { recursive: true, force: true });
+    throw err;
+  }
+  return { dir, filePath };
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<number>} how many entries `dir` currently holds (doctor / tests use this to
+ *   prove isolation: a freshly created workspace must list exactly 1).
+ */
+export async function countWorkspaceEntries(dir) {
+  const entries = await readdir(dir);
+  return entries.length;
+}
+
+/**
+ * @param {string} dir - MUST be one this module created: its basename must start with
+ *   {@link DIR_PREFIX} AND its parent directory must be `baseDir` (default `os.tmpdir()`).
+ * @param {{baseDir?: string}} [opts] - MUST match whatever `baseDir` `createIsolatedWorkspace` was
+ *   called with, when it was overridden.
+ * @returns {Promise<void>}
+ * @throws {TypeError} if `dir` does not satisfy both checks above.
+ */
+export async function cleanupIsolatedWorkspace(dir, opts = {}) {
+  const expectedParent = path.resolve(opts.baseDir ?? os.tmpdir());
+  const actualParent = path.dirname(path.resolve(dir));
+  if (!path.basename(dir).startsWith(DIR_PREFIX) || actualParent !== expectedParent) {
+    throw new TypeError(`cleanupIsolatedWorkspace: refusing to remove a directory this module did not create: ${dir}`);
+  }
+  await rm(dir, { recursive: true, force: true });
+}

package/src/engines/probe.mjs

@@ -0,0 +1,116 @@
+/**
+ * The flag probe (plan §5.2, §2.3): the literal flags every builder in `builders/{claude,codex,
+ * grok}.mjs` depends on, checked as literal substrings of a `--help` text, WITH a word-boundary
+ * check so a shorter required flag can never be satisfied by a longer one that merely starts with
+ * it. No pinned CLI documents a machine-readable `--help` format, so this is a substring probe,
+ * not a parser — the same standard B0's own header check used ("the Claude fixture contains
+ * `--safe-mode` and does not contain `--max-turns`", plan header, B0 acceptance (7)).
+ *
+ * `doctor` (B13, §2.3) re-runs this probe against the REAL installed CLI's live `--help` output at
+ * runtime — this module is what it calls; this block only proves the probe itself works, against
+ * the pinned fixtures (which must all pass) and against a deliberately mutilated copy of one
+ * (which must fail, naming exactly the flag that was removed).
+ *
+ * **Fix round 1 (isolated per-file review, MINOR ×2):**
+ *  - `REQUIRED_FLAGS[provider]` is now `Object.hasOwn`-guarded — `probeHelpText('constructor', …)`
+ *    used to fall through to `Object.prototype.constructor` (truthy) instead of the documented
+ *    "unknown provider" `Error`, then crash on `.filter` not being a function.
+ *  - A match is only counted when the character immediately before and after it is NOT part of an
+ *    identifier or another flag token (`[A-Za-z0-9-]`) — previously `--json` was satisfied by the
+ *    unrelated, LONGER `--json-schema`/`--jsonl`, so removing the real `--json` flag while a longer
+ *    one remained went undetected.
+ */
+
+/**
+ * The flags each builder actually emits, one literal phrase per flag as it appears in the pinned
+ * `--help` fixture (the exact spelling `probeHelpText` checks with a boundary-aware substring
+ * search).
+ * @type {Readonly<Record<"claude"|"codex"|"grok", ReadonlyArray<string>>>}
+ */
+export const REQUIRED_FLAGS = Object.freeze({
+  claude: Object.freeze([
+    '-p, --print',
+    '--model <model>',
+    '--effort <level>',
+    '--permission-mode <mode>',
+    '--output-format <format>',
+    '--no-session-persistence',
+    '--max-budget-usd <amount>',
+    '--disallowedTools, --disallowed-tools <tools...>',
+    '--fallback-model <model>',
+    '--safe-mode',
+    '--tools <tools...>',
+    '--strict-mcp-config',
+    '--json-schema <schema>',
+    '--system-prompt <prompt>',
+    '--restricted',
+  ]),
+  codex: Object.freeze([
+    '-m, --model <MODEL>',
+    '-c, --config <key=value>',
+    '-s, --sandbox <SANDBOX_MODE>',
+    '-C, --cd <DIR>',
+    '--json',
+    '-o, --output-last-message <FILE>',
+    '--ephemeral',
+    '--ignore-rules',
+    '--ignore-user-config',
+    '--skip-git-repo-check',
+    '--output-schema <FILE>',
+  ]),
+  grok: Object.freeze([
+    '--prompt-file <PATH>',
+    '-m, --model <MODEL>',
+    '--reasoning-effort <EFFORT>',
+    '--permission-mode <MODE>',
+    '--cwd <CWD>',
+    '--deny <RULE>',
+    '--json-schema <SCHEMA>',
+    '--disallowed-tools <TOOLS>',
+    '--no-plan',
+    '--no-subagents',
+    '--max-turns <N>',
+    '--system-prompt-override <PROMPT>',
+  ]),
+});
+
+/** @typedef {{ok: boolean, missing: string[]}} ProbeResult */
+
+/** A char that would extend an identifier/flag token if it sat right next to a match. */
+const WORD_CHAR_RE = /[A-Za-z0-9-]/;
+
+/**
+ * @param {string} haystack
+ * @param {string} needle
+ * @returns {boolean} true only if `needle` occurs in `haystack` with a non-word character (or
+ *   string start/end) on BOTH sides — so `--json` does not match inside `--json-schema`.
+ */
+function containsAsWholeToken(haystack, needle) {
+  let fromIndex = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, fromIndex);
+    if (at === -1) return false;
+    const before = at > 0 ? haystack[at - 1] : '';
+    const after = at + needle.length < haystack.length ? haystack[at + needle.length] : '';
+    if (!WORD_CHAR_RE.test(before) && !WORD_CHAR_RE.test(after)) return true;
+    fromIndex = at + 1;
+  }
+}
+
+/**
+ * @param {"claude"|"codex"|"grok"} provider
+ * @param {string} helpText - the CLI's own `--help` output (or a pinned fixture's contents).
+ * @returns {ProbeResult}
+ * @throws {Error} for an unknown provider.
+ */
+export function probeHelpText(provider, helpText) {
+  if (typeof provider !== 'string' || !Object.hasOwn(REQUIRED_FLAGS, provider)) {
+    throw new Error(`probeHelpText: unknown provider "${provider}"`);
+  }
+  if (typeof helpText !== 'string') {
+    throw new TypeError('probeHelpText: helpText must be a string');
+  }
+  const required = REQUIRED_FLAGS[/** @type {"claude"|"codex"|"grok"} */ (provider)];
+  const missing = required.filter((flag) => !containsAsWholeToken(helpText, flag));
+  return { ok: missing.length === 0, missing };
+}

package/src/engines/provider-cli.mjs

@@ -0,0 +1,24 @@
+/**
+ * The one place that maps a config `provider` to the CLI binary `engine: subprocess` spawns for
+ * it (plan §5.2). `src/cli/validate.mjs` (B1) keeps its own private copy for `hasCliOnPath` — this
+ * module is the shared, exported version every `src/engines/**` builder and `src/cli/resolve.mjs`
+ * use, so the mapping is written once on this side of the seam (B1 landed first; B4 does not edit
+ * B1's file to add an export it didn't already have).
+ */
+
+/** @typedef {"anthropic" | "openai" | "xai"} Provider */
+
+/** @type {Readonly<Record<Provider, string>>} */
+export const PROVIDER_CLI_NAMES = Object.freeze({ anthropic: 'claude', openai: 'codex', xai: 'grok' });
+
+/**
+ * `Object.hasOwn`-guarded (see `known-ids.mjs`'s `knownIdsForProvider` for why a bare index lookup
+ * is unsafe for a string that might be `"constructor"` or another `Object.prototype` member).
+ * @param {string} provider
+ * @returns {string | undefined} the CLI binary name, or `undefined` for an unknown provider.
+ */
+export function cliNameForProvider(provider) {
+  return typeof provider === 'string' && Object.hasOwn(PROVIDER_CLI_NAMES, provider)
+    ? PROVIDER_CLI_NAMES[/** @type {Provider} */ (provider)]
+    : undefined;
+}