@lyupro/codex-bridge 0.5.2 → 0.5.4

package/src/home/hooks/worktree-lock.mjs

@@ -1,77 +1,109 @@
-#!/usr/bin/env node
-/**
- * PreToolUse lock for file-writing tools in the Claude Code host.
- *
- * A live codex-build runner snapshots its repository before and after editing. Letting the
- * orchestrator write during that window folds unrelated work into the runner's result, exactly
- * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
- * build run's repository; every malformed or unreadable input passes so diagnostics never break
- * unrelated host work.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
-import { WRITE_TOOLS } from '../lib/hook-definitions.mjs';
-import { runsRoot } from '../lib/runner/runs-root.mjs';
-import { allLiveRuns, normalizePath } from './live-runs.mjs';
-
-const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
-const pass = () => process.exit(0);
-
-let input;
-try {
-  input = JSON.parse(fs.readFileSync(0, 'utf8'));
-} catch {
-  pass();
-}
-
-if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
-if (!WRITE_TOOL_NAMES.has(input.tool_name)) pass();
-
-const toolInput = input.tool_input;
-if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
-const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
-const rawPath = toolInput[pathField];
-if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
-
-let targetPath;
-try {
-  if (path.isAbsolute(rawPath)) targetPath = rawPath;
-  else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
-  else pass();
-} catch {
-  pass();
-}
-
-const target = normalizePath(targetPath);
-if (!target) pass();
-
-let liveRuns;
-try {
-  liveRuns = allLiveRuns(runsRoot());
-} catch {
-  pass();
-}
-const owner = liveRuns.find(({ status }) => {
-  if (status.agent !== 'codex-build') return false;
-  const repository = normalizePath(status.repo);
-  return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
-});
-if (!owner) pass();
-
-const { status, dir } = owner;
-process.stdout.write(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: 'PreToolUse',
-    permissionDecision: 'deny',
-    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${targetPath} is inside repository `
-      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
-      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
-      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
-      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
-      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
-      // work they meant to keep.
-      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
-      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
-  },
-}));
+#!/usr/bin/env node
+/**
+ * PreToolUse lock for file tools and plainly recognisable shell writes in the Claude Code host.
+ *
+ * A live codex-build runner snapshots its repository before and after editing. Letting the
+ * orchestrator write during that window folds unrelated work into the runner's result, exactly
+ * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
+ * build run's repository; every malformed or unreadable input passes so diagnostics never break
+ * unrelated host work.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
+import { SHELL_TOOLS, WRITE_TOOLS } from '../lib/hook-definitions.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+import { shellWriteIntent } from './shell-write-intent.mjs';
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!WRITE_TOOL_NAMES.has(input.tool_name) && !SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+let rawPaths;
+if (WRITE_TOOL_NAMES.has(input.tool_name)) {
+  const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+  const rawPath = toolInput[pathField];
+  if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
+  rawPaths = [rawPath];
+} else {
+  const intent = shellWriteIntent(toolInput.command);
+  if (!intent.writes || !intent.paths.length) pass();
+  rawPaths = intent.paths;
+}
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+let match;
+for (const rawPath of rawPaths) {
+  let targetPath;
+  try {
+    if (path.isAbsolute(rawPath)) targetPath = rawPath;
+    else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
+    else continue;
+  } catch {
+    continue;
+  }
+  const target = normalizePath(targetPath);
+  if (!target) continue;
+  const owner = liveRuns.find(({ status }) => {
+    if (status.agent !== 'codex-build') return false;
+    const repository = normalizePath(status.repo);
+    return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
+  });
+  if (owner) {
+    match = { owner, targetPath };
+    break;
+  }
+}
+if (!match) pass();
+
+const { status, dir } = match.owner;
+// A run is only ever failed for what `git status --porcelain` reports, and an ignored path never
+// appears there — the witness that grades a run does not see it either. Meanwhile the working
+// order for a live run is to touch exactly those files: plans and checklists live in ignored
+// folders. On 2026-08-23 this guard refused four such edits in five minutes, which is worse than
+// a miss: a miss has the witness behind it, a false refusal has nothing and reads as a broken
+// tool. Only a proven `ignored` passes — anything else (not a repository, git absent, any other
+// error) keeps the refusal, because "no proof it is ignored" is not "proof it is harmless".
+const repository = normalizePath(status.repo);
+const target = normalizePath(match.targetPath);
+const gitMetadata = target === `${repository}/.git` || target.startsWith(`${repository}/.git/`);
+if (!gitMetadata) {
+  const ignored = spawnSync('git', ['-C', status.repo, 'check-ignore', '--quiet', '--', match.targetPath], {
+    stdio: 'ignore',
+  });
+  if (ignored.status === 0) pass();
+}
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${match.targetPath} is inside repository `
+      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
+      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
+      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
+      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
+      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
+      // work they meant to keep.
+      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
+      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
+  },
+}));

package/src/home/hooks/worktree-witness.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse witness for shell writes into a live codex-build repository.
+ *
+ * A shell can write through Python, redirection, or any other command while bypassing the
+ * file-tool lock. That is how the orchestrator changed CHANGELOG.md during the 2026-08-16
+ * split-guard run and made an honest build appear out of scope. This hook compares the live
+ * run's recorded git state with the repository after every shell tool and directs the
+ * orchestrator to undo any change outside the run's declared scope.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SHELL_TOOLS } from '../lib/hook-definitions.mjs';
+import { parseJsonText } from '../lib/json-file.mjs';
+import { globToRegExp } from '../lib/meta/paths.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+const pass = () => process.exit(0);
+
+function readRequired(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function statusMap(text) {
+  if (typeof text !== 'string') return null;
+  const result = new Map();
+  for (const line of text.split(/\r?\n/).filter(Boolean)) {
+    if (!/^.. /.test(line)) return null;
+    const rawPath = line.slice(3);
+    const file = rawPath.includes(' -> ') ? rawPath.slice(rawPath.lastIndexOf(' -> ') + 4) : rawPath;
+    if (!file.trim()) return null;
+    result.set(file, line.slice(0, 2));
+  }
+  return result;
+}
+
+let input;
+try {
+  input = parseJsonText('stdin', fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+const cwd = normalizePath(input.cwd);
+if (!cwd) pass();
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+const owner = liveRuns.find(({ status }) => {
+  if (status.agent !== 'codex-build') return false;
+  const repository = normalizePath(status.repo);
+  return Boolean(repository) && (cwd === repository || cwd.startsWith(`${repository}/`));
+});
+if (!owner) pass();
+
+const { dir, status } = owner;
+const beforeText = readRequired(path.join(dir, 'git-before.txt'));
+const scopeText = readRequired(path.join(dir, 'scope.txt'));
+if (beforeText === null || scopeText === null) pass();
+
+const before = statusMap(beforeText);
+let allowed;
+try {
+  const patterns = scopeText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (!patterns.length) pass();
+  allowed = patterns.map(globToRegExp);
+} catch {
+  pass();
+}
+if (!before) pass();
+
+let currentResult;
+try {
+  currentResult = spawnSync('git', ['-C', status.repo, 'status', '--porcelain'], {
+    encoding: 'utf8',
+  });
+} catch {
+  pass();
+}
+if (currentResult.error || currentResult.status !== 0 || typeof currentResult.stdout !== 'string') pass();
+const current = statusMap(currentResult.stdout);
+if (!current) pass();
+
+const changed = [];
+for (const [file, state] of current) if (before.get(file) !== state) changed.push(file);
+for (const file of before.keys()) if (!current.has(file)) changed.push(file);
+const outside = [...new Set(changed)].filter((file) => !allowed.some((pattern) => pattern.test(file)));
+if (!outside.length) pass();
+
+const folder = path.basename(dir);
+const paths = outside.join(', ');
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PostToolUse',
+    additionalContext: `WORKTREE WITNESS — act now: the shell changed paths outside the scope of `
+      + `live run folder ${dir} (agent ${status.agent}, slug ${status.slug}): ${paths}. `
+      + `Revert those paths now, or run codex-bridge stop ${folder} to take the repository back `
+      + `before making further changes.`,
+  },
+}));

package/src/home/lib/brand-home.mjs

@@ -0,0 +1,39 @@
+/**
+ * Resolves where the package's host-side files live: the brand home and the files seeded into it.
+ *
+ * One resolver, because the rule existed twice and the two copies disagreed. Until 2026-08-26 the
+ * runtime built the path to config.json from its own module directory, so `codex-bridge run` read
+ * the seed shipped inside the package while the operator edited `~/.lyupro/.codex-bridge/config.json`.
+ * A model and an effort pinned there on 5 August never reached a single run — every run silently
+ * used defaults, `env.json` recorded `"models": {}`, three releases shipped with it, and `doctor`
+ * kept confirming the setting because the CLI resolved the path correctly.
+ *
+ * The environment and the home directory are injectable so no test needs the operator's real home;
+ * `source` is reported because a path chosen by an override and one chosen by default must be
+ * distinguishable wherever the setting is shown.
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+export function resolveBrandHome({ homedir = os.homedir(), env = process.env } = {}) {
+  const overridden = Boolean(env.CODEX_BRIDGE_HOME);
+  const root = path.resolve(
+    overridden ? env.CODEX_BRIDGE_HOME : path.join(homedir, '.lyupro', '.codex-bridge'),
+  );
+  return {
+    root,
+    source: overridden ? 'CODEX_BRIDGE_HOME' : 'default',
+    configPath: path.join(root, 'config.json'),
+    conventionsPath: path.join(root, 'conventions.md'),
+  };
+}
+
+/**
+ * Resolved once per process, deliberately: a run reads its configuration in the launcher and must
+ * not see the answer change underneath it. Code that needs the answer for another home — a test, an
+ * installer targeting `--host` — calls resolveBrandHome() with that home instead of editing the
+ * environment after import, which would not be seen here.
+ */
+export const BRAND_HOME = resolveBrandHome();
+export const BRAND_CONFIG_PATH = BRAND_HOME.configPath;
+export const BRAND_CONVENTIONS_PATH = BRAND_HOME.conventionsPath;

package/src/home/lib/heartbeat.mjs

@@ -2,7 +2,10 @@
  * The one definition of run progress: a heartbeat file in the run folder, its age, and the
  * stale threshold. On 2026-08-06 run 2026-08-06_204007_build left a live worker waiting on
  * Codex's grandchild; a worker timer alone would have kept that dead run looking alive, so
- * the timer stops at exit.
+ * the timer stops at exit. The file's modification time is the run's best-effort sign of recent
+ * progress. A failed stamp is swallowed so this hint cannot prevent the run's normal verdict and
+ * artifacts. For an old record, a missing file is a legacy state that keeps its lock until its pid
+ * dies.
  */
 import fs from 'node:fs';
 import path from 'node:path';

package/src/home/lib/hook-definitions.mjs

@@ -46,6 +46,14 @@ export const STOP_TOOLS = Object.freeze(['TaskStop']);
 /** A PreToolUse matcher is a regular expression over tool names, so the list remains authoritative. */
 export const STOP_TOOL_MATCHER = STOP_TOOLS.join('|');
 
+/**
+ * The lock listens to file tools and shells through one registration, not two. A second definition
+ * naming the same file lands twice in the installation record, and that record forbids duplicate
+ * files — 33 tests failed on it the day the shell side was added. One hook, one entry, one matcher
+ * wide enough for both.
+ */
+export const LOCKED_TOOL_MATCHER = [...WRITE_TOOLS, ...SHELL_TOOLS].join('|');
+
 /**
  * Stable CLI names live beside each event and file because the Plan_19 drift incident left
  * registration, diagnostics, and the guard itself carrying different hook identities. The
@@ -54,7 +62,8 @@ export const STOP_TOOL_MATCHER = STOP_TOOLS.join('|');
 export const HOOK_DEFINITIONS = Object.freeze([
   Object.freeze({ name: 'reply-guard', event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
   Object.freeze({ name: 'order-gate', event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
-  Object.freeze({ name: 'worktree-lock', event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
+  Object.freeze({ name: 'worktree-lock', event: 'PreToolUse', matcher: LOCKED_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
   Object.freeze({ name: 'prune-guard', event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
+  Object.freeze({ name: 'worktree-witness', event: 'PostToolUse', matcher: SHELL_TOOL_MATCHER, file: 'worktree-witness.mjs' }),
   Object.freeze({ name: 'stop-guard', event: 'PreToolUse', matcher: STOP_TOOL_MATCHER, file: 'stop-guard.mjs' }),
 ]);

package/src/home/lib/meta/reply.mjs

@@ -139,6 +139,33 @@ function reviewReply(ctx) {
   ];
 }
 
+/**
+ * Which worker actually ran, printed next to the log link.
+ *
+ * A dispatcher reads these rows and nothing else, so a run on the wrong model was invisible here
+ * for three releases: the configured profile never reached the command line, and no reply said
+ * which model had answered (2026-08-26). The row names the depth's origin too — a `fallback`
+ * depth on a mode configured for `max` is the same silence one level down.
+ */
+export function profileRow(meta) {
+  const profile = meta?.profile;
+  if (!profile?.effort) return null;
+  const model = profile.model || 'codex default';
+  return `Model: ${model} at ${profile.effort} effort (${profile.effort_source})`;
+}
+
+/**
+ * Inserted before the row carrying the log link, or appended when a reply has none. The link is
+ * matched anywhere in the row, not at its start: scout and review put it after the report path,
+ * and the profile belongs beside it in every reply rather than only in two of them.
+ */
+export function withProfileRow(rows, meta) {
+  const row = profileRow(meta);
+  if (!row) return rows;
+  const at = rows.findIndex((r) => r.includes('Log: '));
+  return at === -1 ? [...rows, row] : [...rows.slice(0, at), row, ...rows.slice(at)];
+}
+
 export function failReply(ctx, meta) {
   const retention = retentionReply(ctx.runDir);
   return [

package/src/home/lib/run-config.mjs

@@ -19,10 +19,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { BRAND_CONFIG_PATH, BRAND_HOME } from './brand-home.mjs';
 import { readJsonFileSync } from './json-file.mjs';
 
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-export const CONFIG_PATH = path.join(HERE, '..', 'config.json');
+export const CONFIG_PATH = BRAND_CONFIG_PATH;
+
+/**
+ * Every print of the state says which file was read AND why that one. The defect this replaced was
+ * invisible precisely because the path was never shown beside its origin: two files named
+ * config.json, and no way to tell from the output which of them the run had just used.
+ */
+const ORIGIN =
+  BRAND_HOME.source === 'CODEX_BRIDGE_HOME' ? 'from CODEX_BRIDGE_HOME' : 'default location';
 
 const BUDGET_KEY = 'budgets';
 const BUDGET_MODES = ['scout', 'build', 'review'];
@@ -73,7 +81,11 @@ const MODEL_KEYS = ['scout', 'build', 'review'];
  * fallback depth the dispatcher happens to pass.
  */
 const PROFILE_KEYS = ['model', 'effort'];
-export const ALLOWED_EFFORTS = Object.freeze(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+// Exactly the values the service enumerates, and no more. `minimal` sat here until 2026-08-26,
+// passed validation and was rejected by the model itself after the run had started
+// ("Unsupported value: 'minimal' is not supported with the … model"), so an order died four
+// seconds in on quota already spent. A validator that admits a known-dead value is worse than none.
+export const ALLOWED_EFFORTS = Object.freeze(['none', 'low', 'medium', 'high', 'xhigh', 'max']);
 /**
  * The language a run answers in. Left to the model it followed the task, the surrounding docs or
  * its own default: an English order came back in Russian, and artifacts of one project ended up in
@@ -308,13 +320,13 @@ function main(argv) {
 
   if (!key) {
     const config = readRunConfig();
-    console.log([...state(config), `File: ${CONFIG_PATH}`].join('\n'));
+    console.log([...state(config), `File: ${CONFIG_PATH} (${ORIGIN})`].join('\n'));
     return 0;
   }
 
   if (key === 'reset') {
     writeRunConfig({ ...DEFAULTS });
-    console.log([...state(DEFAULTS), `Reset to defaults · ${CONFIG_PATH}`].join('\n'));
+    console.log([...state(DEFAULTS), `Reset to defaults · ${CONFIG_PATH} (${ORIGIN})`].join('\n'));
     return 0;
   }
 
@@ -334,7 +346,7 @@ function main(argv) {
 
   const config = { ...readRunConfig(), [key]: value === 'on' };
   writeRunConfig(config);
-  console.log([...state(config), `File: ${CONFIG_PATH}`].join('\n'));
+  console.log([...state(config), `File: ${CONFIG_PATH} (${ORIGIN})`].join('\n'));
   return 0;
 }
 

package/src/home/lib/runner/codex-args.mjs

@@ -0,0 +1,154 @@
+/**
+ * What a run asks Codex to do: the model, the reasoning depth and the flag set per agent.
+ *
+ * Split out of codex-cmd.mjs when that file outgrew the size limit; the seam is deliberate, not
+ * arithmetic — starting a process and deciding what it is asked to do are different jobs, and
+ * only this half needs to know the run's configuration.
+ *
+ * The flag sets are the ones the three agent files carried before, verbatim. Sandboxes especially
+ * must not drift: codex-scout and codex-review are read-only through an explicit --sandbox
+ * read-only, and codex-build needs workspace-write and must NOT get --ignore-user-config. What
+ * --ignore-user-config buys the two read-only agents is isolation from the operator's config,
+ * never the sandbox itself — reading it as the read-only guarantee is how the 2026-08-23 breakage
+ * stayed misdiagnosed as "read-only is broken" (see sandbox-flags.mjs for what actually stops a
+ * run from starting a process on Windows).
+ */
+import path from 'node:path';
+import { CLEAN_ENV, RUN_ENV } from './run-env.mjs';
+import { platformSandboxArgs } from './sandbox-flags.mjs';
+
+/**
+ * Which model runs a mode, and how deep it reasons.
+ *
+ * Three sources, in this order: what the dispatcher asked for this one task, the mode's
+ * configured profile, and finally a depth to fall back on. The order is the whole point —
+ * pinning a model without its depth leaves every run at the fallback, which is how a mode
+ * configured for maximum reasoning would quietly keep working at the shallowest setting.
+ */
+const FALLBACK_EFFORT = 'medium';
+
+/**
+ * A run is one worker, not a team it recruits for itself.
+ *
+ * Codex can spawn subagents when a prompt asks it to, and their edits land in the same
+ * worktree — so they arrive in the snapshot as the run's own work, outside the scope check
+ * that grades it, on quota nobody budgeted. The prompts say not to; this is why they cannot.
+ */
+const NO_SUBAGENTS = ['-c', 'agents.enabled=false'];
+
+/**
+ * Which configured mode an agent is. One table, because the launcher needs the same answer to
+ * pick a run's time budget: a second copy of this mapping is a second place to forget a mode.
+ */
+export const runMode = (agent) =>
+  ({
+    'codex-scout': 'scout',
+    'codex-build': 'build',
+    'codex-review': 'review',
+  })[agent];
+
+/**
+ * Which model and depth this run gets, and — as part of the same answer — where each came from.
+ *
+ * The provenance is not decoration. A configured profile failed to reach any run for three
+ * releases (2026-08-26) and nothing said so: the reply named no model, meta.json recorded none,
+ * and a depth silently served by the fallback is indistinguishable from one the operator chose.
+ * `model_source` is `config` or `codex default`; `effort_source` is `request`, `config` or
+ * `fallback`, in the order the values are consulted above.
+ */
+export function runProfile(opts) {
+  const mode = runMode(opts.agent);
+  // opts.models is how tests state a configuration; a real run reads the one loaded for it.
+  const configured = (opts.models || RUN_ENV?.models || {})[mode] || {};
+  return {
+    model: configured.model || '',
+    model_source: configured.model ? 'config' : 'codex default',
+    effort: opts.effort || configured.effort || FALLBACK_EFFORT,
+    effort_source: opts.effort ? 'request' : configured.effort ? 'config' : 'fallback',
+  };
+}
+
+export function codexArgs(opts, runDir, isGitRepo) {
+  const schema = path.join(runDir, 'schema.json');
+  const profile = runProfile(opts);
+  const effort = `model_reasoning_effort=${profile.effort}`;
+  const modelArgs = profile.model ? ['-m', profile.model] : [];
+  if (opts.agent === 'codex-scout') {
+    return [
+      'exec',
+      '--json',
+      ...CLEAN_ENV,
+      '--ignore-user-config',
+      '-c',
+      effort,
+      ...NO_SUBAGENTS,
+      ...platformSandboxArgs(),
+      ...modelArgs,
+      '--sandbox',
+      'read-only',
+      '--skip-git-repo-check',
+      '-C',
+      opts.repo,
+      '--output-schema',
+      schema,
+      '-o',
+      path.join(runDir, 'result.json'),
+      '-',
+    ];
+  }
+  if (opts.agent === 'codex-build') {
+    // --ignore-user-config is deliberately absent: with it Codex forces read-only and
+    // every edit is rejected ("writing is blocked by read-only sandbox").
+    return [
+      'exec',
+      '--json',
+      ...CLEAN_ENV,
+      '-c',
+      effort,
+      ...NO_SUBAGENTS,
+      ...platformSandboxArgs(),
+      ...modelArgs,
+      '--sandbox',
+      'workspace-write',
+      '-C',
+      opts.repo,
+      ...(isGitRepo ? [] : ['--skip-git-repo-check']),
+      '--output-schema',
+      schema,
+      '-o',
+      path.join(runDir, 'result.json'),
+      '-',
+    ];
+  }
+  // codex-review deliberately does NOT use the `review` subcommand. Two of its traits
+  // break the contract this design rests on: it rejects a scope flag together with a
+  // prompt ("the argument '--uncommitted' cannot be used with '[PROMPT]'"), so task.md
+  // was silently discarded and the review rules never arrived; and it ignores
+  // --output-schema, writing prose into -o, so the old JSON parsing of review.json could
+  // only ever fail — which is what pushed a dispatcher into reviewing the diff itself.
+  //
+  // Plain `codex exec` honours the schema (proven by codex-scout), so the review comes
+  // back as machine-checkable JSON. Scope lives in the prompt as a file list plus the
+  // exact diff command computed by reviewScope(). Read-only through
+  // --ignore-user-config, same as scout: review never needs write access.
+  return [
+    'exec',
+    '--json',
+    ...CLEAN_ENV,
+    '--ignore-user-config',
+    '-c',
+    effort,
+    ...NO_SUBAGENTS,
+    ...platformSandboxArgs(),
+    ...modelArgs,
+    '--sandbox',
+    'read-only',
+    '-C',
+    opts.repo,
+    '--output-schema',
+    schema,
+    '-o',
+    path.join(runDir, 'review.json'),
+    '-',
+  ];
+}