@lyupro/codex-bridge 0.1.0

package/src/runner/launcher.mjs

@@ -0,0 +1,374 @@
+/**
+ * The half the caller can kill: every preparation and every refusal that costs no quota,
+ * then the spawn of the worker and the immediate return; a repeated call waits for the reply.
+ *
+ * The order it leaves for the worker is worker.json in the run folder — after the split
+ * that file is the only connection between the two halves. It is written here with
+ * `agent`, `slug`, `order_id`, `repo`, `is_git_repo`, `launcher_pid`, `budget_minutes` and `args`;
+ * worker.mjs reads `repo`, `agent`, `args`, `is_git_repo` and `budget_minutes`. The three extra fields are deliberate: `slug`,
+ * `order_id` and `launcher_pid` are what a run folder read back months later needs in order to
+ * explain itself — which order it belonged to included. Nothing may be dropped from this shape
+ * without changing worker.mjs and saying so out loud.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  writeFailure,
+  writeStatus,
+  markAbandoned,
+  abandonedBranchDrift,
+  activeRun,
+  chainRuns,
+  taskFingerprint,
+  readJson,
+} from '../write-meta.mjs';
+import { attach } from './attach.mjs';
+import { setRun } from './run-context.mjs';
+import { loadRunEnv, RUN_ENV } from './run-env.mjs';
+import { parseArgs, die } from './args.mjs';
+import { SCHEMAS } from './schemas.mjs';
+import { INSTRUCTIONS } from './prompts.mjs';
+import { git, headSha, branchName, worktreeSnapshot, reviewScope } from './git-state.mjs';
+import { codexArgs, requireCodex, runMode, unsafeForCmd } from './codex-cmd.mjs';
+import { runsRoot } from './runs-root.mjs';
+import { resolveProjectRunsDir } from './project-dir.mjs';
+
+/**
+ * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
+ * below is the CLI entry one level up — not this module, which has no command line of its own.
+ */
+const RUNNER_ENTRY = fileURLToPath(new URL('../run-codex.mjs', import.meta.url));
+
+export const questionsFromFlags = (questionTexts = []) =>
+  questionTexts.map((text, i) => ({ id: `Q${i + 1}`, text }));
+
+const stamp = () => {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}_${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+};
+
+/**
+ * Never reuse a run folder. Two runs with the same slug inside the same second would
+ * otherwise overwrite each other's task.md, log and result — and a status could then be
+ * computed from another run's artifacts.
+ */
+function makeRunDir(base) {
+  fs.mkdirSync(path.dirname(base), { recursive: true });
+  for (let n = 2, dir = base; ; n += 1) {
+    try {
+      fs.mkdirSync(dir);
+      return dir;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      dir = `${base}-${n}`;
+    }
+  }
+}
+
+/**
+ * Everything a run needs before a single token of someone else's quota is spent, and every
+ * refusal that costs nothing: bad arguments, an open chain without --continue, a busy
+ * worktree, a missing Codex CLI. All of it happens here, in the process the caller is free
+ * to kill — so a killed caller can only ever interrupt a run that was already paid for.
+ */
+export async function launcher() {
+  loadRunEnv();
+
+  const opts = parseArgs(process.argv.slice(2));
+  const taskText = fs.readFileSync(0, 'utf8').trim();
+  if (!taskText) die('task text on stdin is empty');
+
+  const topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
+  const isGitRepo = topLevel.status === 0;
+  const repoRoot = isGitRepo ? topLevel.stdout.trim() : opts.repo;
+  const projectRunsRoot = resolveProjectRunsDir(runsRoot(), repoRoot).dir;
+
+  // Folders left behind by a runner that was killed mid-run get an explicit state before
+  // anything else happens. One order produced four of them, and without this pass an
+  // abandoned folder is indistinguishable from a run still working: neither has meta.json.
+  // The snapshot is passed in because meta/ makes no git calls of its own: it is the only way an
+  // abandoned run can be closed with the files it left behind rather than with a bare label.
+  markAbandoned(projectRunsRoot, isGitRepo ? worktreeSnapshot(repoRoot) : undefined);
+
+  if (isGitRepo) {
+    const drift = abandonedBranchDrift(projectRunsRoot, repoRoot, branchName(repoRoot));
+    if (drift) {
+      die(
+        `repository is detached after abandoned run ${drift.run}, which recorded branch ${drift.branch}. ` +
+          `Return with: git checkout ${drift.branch}. No run folder was created and no quota was spent.`,
+      );
+    }
+  }
+
+  // A second pass at the same task is a real need — after a timeout or a LIMIT the work has
+  // to be finished — so it is allowed and made visible rather than forbidden. What is
+  // forbidden is repeating by accident: the orchestrator saw the previous reply, the runner
+  // did not, so only the orchestrator can decide there is something left to finish.
+  //
+  // The task is identified by its text as well as by its slug, because the slug is chosen by
+  // whoever repeats the run: on 2026-08-02 a dispatcher whose launcher was killed restarted
+  // the identical order as `<slug>-v2` and spent 46k on it. Refused before the folder exists,
+  // like --scope.
+  const taskHash = taskFingerprint(taskText);
+  const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
+
+  // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
+  // restart the synchronous launcher. A live same-order run is now the repeat target: attach
+  // before creating a folder, probing Codex or spending another token.
+  const attachedExitCode = await attach({
+    runsRoot: projectRunsRoot,
+    repo: repoRoot,
+    slug: opts.slug,
+    taskHash,
+    orderId: opts.orderId,
+    chain,
+    isContinue: opts.continue,
+  });
+  if (attachedExitCode !== null) process.exit(attachedExitCode);
+
+  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
+  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
+  // attach(), while --continue must refuse to overlap that live work.
+  const continuationError = continuationRefusal(projectRunsRoot, chain, opts.continue, opts.orderId);
+  if (continuationError) die(continuationError);
+
+  if (chain.length && !opts.continue) {
+    const last = chain[chain.length - 1];
+    const lastSlug = String(readJson(path.join(projectRunsRoot, last, 'status.json'))?.slug || '');
+    const renamed = lastSlug && lastSlug.toLowerCase() !== String(opts.slug).toLowerCase();
+    die(
+      `--continue is required: ${
+        renamed
+          ? `this task already ran in this repository under the name “${lastSlug}”`
+          : `runs for task “${opts.slug}” already exist in this repository`
+      } (${chain.length}), latest: ${path.join(projectRunsRoot, last)}. ` +
+        'A repeat run is allowed, but the orchestrator decides, not the runner: it read the ' +
+        'previous response and knows whether work remains. Add --continue if you are finishing ' +
+        'the same task; changing --slug with the same task text does not stop it being a repeat. ' +
+        'The run folder was not created; quota was not spent.',
+    );
+  }
+
+  // Asked before this run registers itself, so it cannot find itself. Two writing runs share
+  // one worktree with no isolation: the second one's before/after snapshot picks up the
+  // first one's edits, and an honest run gets failed for work it never did.
+  const busy = opts.agent === 'codex-build' ? activeRun(projectRunsRoot, repoRoot) : null;
+
+  const runDir = makeRunDir(path.join(projectRunsRoot, `${stamp()}_${opts.slug}`));
+  setRun(runDir, opts.agent);
+
+  // Written before Codex is even probed. From here on a killed runner leaves a folder that
+  // says what it was and whose pid to check, instead of a folder that says nothing — the run
+  // itself takes 20-25 minutes, far longer than the caller's default timeout, so being killed
+  // mid-run is the normal way for this to end, not the exotic one.
+  //
+  // `pid` is the launcher's only until the worker exists, and the worker's from then on:
+  // activeRun(), markAbandoned() and the reply guard all read `pid` as "the process whose
+  // death means this run is abandoned", and after the spawn that process is the worker.
+  writeStatus(runDir, {
+    state: 'running',
+    pid: process.pid,
+    launcher_pid: process.pid,
+    agent: opts.agent,
+    slug: opts.slug,
+    order_id: opts.orderId,
+    // Fingerprint of the order, so a later run of the same task finds this one whatever it
+    // calls itself. Written here, before Codex is probed, like everything the chain reads.
+    task_hash: taskHash,
+    repo: repoRoot,
+    started_at: new Date().toISOString(),
+    // Which run of this task started the chain — the base every later pass is measured
+    // against. Absent means this is the first pass.
+    ...(chain.length ? { continues: chain[0] } : {}),
+  });
+
+  // Printed before anything can go wrong: even a dispatcher that dies mid-run leaves the
+  // orchestrator with a folder to look into.
+  console.log(`RUN=${runDir}`);
+
+  // Before requireCodex, so a blocked run costs nothing at all.
+  if (busy) {
+    const { reply } = writeFailure(
+      runDir,
+      opts.agent,
+      `run ${busy} is already active for this repository; two writing runs in one tree are prohibited`,
+      [`Active run: ${path.join(projectRunsRoot, busy)}`, 'Codex was not started; quota was not spent'],
+    );
+    console.log(reply);
+    process.exit(1);
+  }
+
+  requireCodex(runDir, opts.agent);
+
+  const scope = opts.agent === 'codex-review' ? reviewScope(repoRoot, opts.mode) : null;
+  if (scope) {
+    fs.writeFileSync(
+      path.join(runDir, 'scope.txt'),
+      `${scope.label}\n${scope.diffCommand}\n${scope.files.join('\n')}\n`,
+    );
+  }
+
+  // The sub-questions this run will be graded against come only from the orchestrator's
+  // repeatable flags. They are written before the task is assembled so the prompt and verdict
+  // read the same ordered list, including a valid one-question order.
+  const questions = opts.agent === 'codex-scout' ? questionsFromFlags(opts.questions) : [];
+  if (opts.agent === 'codex-scout') {
+    fs.writeFileSync(path.join(runDir, 'questions.json'), `${JSON.stringify(questions, null, 2)}\n`);
+  }
+
+  if (opts.agent === 'codex-build') {
+    fs.writeFileSync(path.join(runDir, 'scope.txt'), `${opts.scopePatterns.join('\n')}\n`);
+  }
+
+  // Which environment this run actually got. Without it a replay months later cannot tell
+  // whether the operator's hooks were in play, and that is the first question a run that
+  // wandered off task raises.
+  fs.writeFileSync(path.join(runDir, 'env.json'), `${JSON.stringify(RUN_ENV, null, 2)}\n`);
+
+  // The extra sections carry the two things prose could not enforce: what has to be answered,
+  // and what may be edited. Both also go to disk as questions.json / scope.txt, so the verdict
+  // is computed from the same list Codex was handed, not from a second reading of the wording.
+  const sections = [`## Operator task (verbatim)\n\n${taskText}`];
+  if (questions.length) {
+    sections.push(
+      [
+        '## Sub-questions, each requires a separate response',
+        '',
+        questions.map((q) => `${q.id}: ${q.text}`).join('\n'),
+        '',
+        'A missed sub-question fails the run; a response containing only coordinates counts as missed.',
+      ].join('\n'),
+    );
+  }
+  if (opts.agent === 'codex-build') {
+    sections.push(
+      [
+        '## Scope (hard boundary)',
+        '',
+        'Only these may be changed:',
+        opts.scopePatterns.map((p) => `- ${p}`).join('\n'),
+        '',
+        'Do not touch any file outside this list — even if it blocks the work or looks broken.',
+        'Put the obstacle in leftovers instead of changing the file. The touched worktree is',
+        'checked against this list after the run.',
+      ].join('\n'),
+    );
+  }
+  sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
+  fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
+  fs.writeFileSync(
+    path.join(runDir, 'schema.json'),
+    `${JSON.stringify(SCHEMAS[opts.agent], null, 2)}\n`,
+  );
+
+  if (opts.agent === 'codex-build') {
+    fs.writeFileSync(path.join(runDir, 'head-before.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
+    fs.writeFileSync(path.join(runDir, 'branch-before.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
+    fs.writeFileSync(path.join(runDir, 'git-before.txt'), git(repoRoot, ['status', '--porcelain']).stdout || '');
+    fs.writeFileSync(path.join(runDir, 'state-before.txt'), `${worktreeSnapshot(repoRoot)}\n`);
+  }
+
+  // The worker's entire order, on disk. Not passed as arguments: the launcher may be gone
+  // when the worker needs to know what it is doing, and a folder that explains itself is
+  // also the only way to read a run back months later.
+  const codexArgv = codexArgs({ ...opts, repo: repoRoot }, runDir, isGitRepo);
+  const unsafe = process.platform === 'win32' ? unsafeForCmd(codexArgv) : undefined;
+  if (unsafe) {
+    const { reply } = writeFailure(
+      runDir,
+      opts.agent,
+      `argument cannot be passed through cmd.exe (contains % or "): ${unsafe}`,
+      ['Codex was not started; quota was not spent'],
+    );
+    console.log(reply);
+    process.exit(1);
+  }
+  fs.writeFileSync(
+    path.join(runDir, 'worker.json'),
+    `${JSON.stringify(
+      {
+        agent: opts.agent,
+        slug: opts.slug,
+        order_id: opts.orderId,
+        repo: repoRoot,
+        is_git_repo: isGitRepo,
+        launcher_pid: process.pid,
+        // The mode's wall-clock budget, resolved here and never re-read by the worker: a run
+        // that consulted run-config.json twice could end up honouring two different limits.
+        budget_minutes: RUN_ENV?.budgets?.[runMode(opts.agent)],
+        args: codexArgv,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  // detached + unref + no stdio: the worker leaves the caller's process group, so a Ctrl+C
+  // or a timeout kill aimed at the dispatcher's shell does not reach it, and it holds no
+  // pipe that could fill up and stall once nobody is reading.
+  const worker = spawn(process.execPath, [RUNNER_ENTRY, '--worker', runDir], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    cwd: repoRoot,
+  });
+  worker.on('error', (err) => {
+    const { reply } = writeFailure(runDir, opts.agent, `run worker process failed to start: ${err.message}`, [
+      'Codex was not started; quota was not spent',
+    ]);
+    console.log(reply);
+    process.exit(1);
+  });
+  worker.unref();
+  writeStatus(runDir, { pid: worker.pid, runner_pid: worker.pid });
+
+  console.log(
+    `STARTED agent=${opts.agent} slug=${opts.slug} order-id=${opts.orderId} worker-pid=${worker.pid}`,
+  );
+  console.log(
+    'To get the verdict, repeat the identical command with the same --order-id; it will attach to this run and will not start a second run.',
+  );
+  process.exit(0);
+}
+
+/**
+ * Applies the one-continuation limit and the in-flight safety gate before a folder is created.
+ *
+ * The limit is counted over the runs carrying THIS order id, not over the whole chain. The chain
+ * also ties runs together by slug and by the fingerprint of the task text, which is what catches a
+ * repeat that renamed itself — but counting continuations that way makes the escape hatch
+ * unreachable: the operator's rule is "more passes than one need a new order id", and a new order
+ * id lands in the same chain through the task hash. A task would then be refused with --continue
+ * for having spent its continuation and refused without it for already having runs — permanently
+ * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
+ */
+export function continuationRefusal(runsRootPath, chain, isContinue, orderId) {
+  if (!isContinue || chain.length === 0) return null;
+  const wanted = String(orderId ?? '').trim();
+  const ofThisOrder = chain.filter(
+    (run) => String(readJson(path.join(runsRootPath, run, 'status.json'))?.order_id ?? '').trim() === wanted,
+  );
+  if (ofThisOrder.length === 0) return null;
+  if (ofThisOrder.length > 1) {
+    const spent = ofThisOrder.map((run) => path.join(runsRootPath, run)).join(', ');
+    return (
+      `--continue is refused: order “${wanted}” already spent its allowed continuation on ${spent}. ` +
+      'A further pass needs a new order id from the orchestrator. The run folder was not ' +
+      'created; quota was not spent.'
+    );
+  }
+  const previous = path.join(runsRootPath, ofThisOrder[0]);
+  const status = readJson(path.join(previous, 'status.json'));
+  const meta = readJson(path.join(previous, 'meta.json'));
+  if (!meta?.status || status?.state === 'running') {
+    return (
+      `--continue is refused: previous run ${previous} has no finished verdict and may still ` +
+      'be editing the worktree. Repeat without --continue to attach to it. The run folder was ' +
+      'not created; quota was not spent.'
+    );
+  }
+  return null;
+}

package/src/runner/project-dir.mjs

@@ -0,0 +1,92 @@
+/** Assigns a stable runs directory to one repository. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectFolder } from '../write-meta.mjs';
+
+export const PROJECT_MARKER = '.project.json';
+
+const MAX_CANDIDATES = 100;
+
+export function normalizeRepoPath(repoPath) {
+  let normalized = path.resolve(repoPath).replaceAll('\\', '/').replace(/\/$/, '');
+  if (process.platform === 'win32') normalized = normalized.toLowerCase();
+  return normalized;
+}
+
+function readMarker(dir) {
+  const markerPath = path.join(dir, PROJECT_MARKER);
+  if (!fs.existsSync(markerPath)) return null;
+  let marker;
+  try {
+    marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Cannot read project marker ${markerPath}: ${err.message}`);
+  }
+  if (!marker || typeof marker.repo !== 'string' || !marker.repo) {
+    throw new Error(`Project marker ${markerPath} must contain a non-empty repo path`);
+  }
+  return marker;
+}
+
+function writeMarker(dir, repo) {
+  const marker = { repo, created: new Date().toISOString() };
+  fs.writeFileSync(path.join(dir, PROJECT_MARKER), `${JSON.stringify(marker, null, 2)}\n`, { flag: 'wx' });
+}
+
+function legacyOwner(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const statuses = entries.map((entry) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, entry.name, 'status.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+  });
+  return statuses.find((status) => typeof status?.repo === 'string' && status.repo)?.repo ?? null;
+}
+
+function candidateName(base, index) {
+  return index === 1 ? base : `${base}-${index}`;
+}
+
+export function resolveProjectRunsDir(runsRootPath, repoRoot, { create = true } = {}) {
+  const base = projectFolder(repoRoot);
+  const wantedRepo = normalizeRepoPath(repoRoot);
+  if (create) fs.mkdirSync(runsRootPath, { recursive: true });
+
+  for (let index = 1; index <= MAX_CANDIDATES; index += 1) {
+    const name = candidateName(base, index);
+    const dir = path.join(runsRootPath, name);
+    if (!fs.existsSync(dir)) {
+      if (create) {
+        fs.mkdirSync(dir);
+        writeMarker(dir, repoRoot);
+      }
+      return { dir, name, reason: 'created' };
+    }
+    if (!fs.statSync(dir).isDirectory()) {
+      throw new Error(`Project runs candidate is not a directory: ${dir}`);
+    }
+
+    const marker = readMarker(dir);
+    if (marker) {
+      if (normalizeRepoPath(marker.repo) === wantedRepo) return { dir, name, reason: 'marker' };
+      continue;
+    }
+
+    const owner = legacyOwner(dir);
+    if (!owner || normalizeRepoPath(owner) === wantedRepo) {
+      if (create) writeMarker(dir, repoRoot);
+      return { dir, name, reason: 'adopted' };
+    }
+    // Recording the discovered owner prevents later runs from reinterpreting mixed history.
+    if (create) writeMarker(dir, owner);
+  }
+
+  throw new Error(
+    `No project runs directory is available for ${repoRoot} after ${MAX_CANDIDATES} candidates. ` +
+      `Remove or relocate an obsolete ${base} directory, or choose a different CODEX_RUNS_ROOT.`,
+  );
+}

package/src/runner/prompts.mjs

@@ -0,0 +1,97 @@
+/**
+ * What each agent is told to do, one instruction text per agent.
+ *
+ * These are data, not comments: the wording IS the contract a run is graded against, and
+ * every rule in it was added by an incident. Keyed by agent name, next to the matching
+ * schema in schemas.mjs — one lookup picks both halves of an agent's strategy.
+ */
+import { DEFAULTS } from '../run-config.mjs';
+import { RUN_ENV } from './run-env.mjs';
+const BODIES = {
+  'codex-scout': (opts, scope, questions = []) => `Response rules:
+- You are working in read-only mode: do not try to write or edit anything.
+- Answer from your own reading: do not spawn or delegate to other agents.
+- The response is an analysis, not a map. Explain in prose: how it works, which fields,
+  signatures, and contracts are involved, how the areas differ, and what follows from this.
+  A list of coordinates instead of an analysis does NOT count and will be rejected as empty.
+- Coordinates in \`path:line\` form belong in evidence, not in place of the response: each
+  response needs at least one reference. If removing paths and coordinates leaves no several
+  sentences of coherent text, there is no response.
+${
+  questions.length
+    ? `- The sub-questions are listed above. Each Q1..Q${questions.length} needs its own object in
+  answers: question_id, a separate analysis in answer, and its own references in evidence.
+  One common response to all sub-questions is not acceptable — a missed sub-question fails the run.
+- The top-level answer is a 2-4 sentence summary of the whole task, on top of the analyses.`
+    : `- Put one object in answers with question_id "Q1": analysis in answer, references in evidence.
+- The top-level answer is the same response summarized in 2-4 sentences.`
+}
+- Base the response on what you read; support every fact with a \`path:line\` reference in where.
+- If facts are missing, list them in unknowns; do not make them up.
+- report_markdown is a full markdown report with sections: “Response” (2-4 sentences),
+  “How it works” (required: prose analysis ${questions.length ? 'for each sub-question' : 'of the mechanism'},
+  grounded in the code), “Findings” (fact / location / confidence table), “Missing information”.`,
+  'codex-build': (opts) => `Definition of done: exactly as stated in the task above.
+
+Working rules:
+- Change only what the task requires. Do not refactor adjacent code or reformat files.
+- Prefer the smallest correct change and the patterns this project already uses over new
+  abstractions of your own.
+- Do this work yourself: do not spawn or delegate to other agents. Their edits would land in
+  this worktree as yours, outside the scope you are graded against. If the task needs authority
+  you do not have, or a file is being changed by someone else, put that in leftovers.
+- Work strictly within the scope from the section above. Do not touch a file outside the list
+  under any circumstances — even if it blocks you, looks broken, or is a “one-line fix”. Put the
+  obstacle in leftovers. Touched files are checked against the worktree scope after the run,
+  and an out-of-scope change fails the entire run.
+- Do not commit or prepare a commit: \`git commit\`, \`git add\`, \`git stash\`, new branches and
+  tags, and any changes inside \`.git/\` are prohibited. The orchestrator performs acceptance
+  and commits; it must see your changes uncommitted. If a commit seems unavoidable, put that
+  in leftovers instead of running a command. A changed HEAD fails the run.
+- Do not leave stubs, TODOs, \`test.skip\`/\`.only\`, or unimplemented branches. If something
+  cannot be done, do not pretend it is done; list it in leftovers.
+- After making changes, run verification: ${opts.verify || 'determine the command from the project'}.
+  Put the command actually run in verify_command and whether it passed in verify_passed.
+- summary and changes describe only changes in this repository for this task. Do not include
+  anything unrelated in them.
+- Each change is a separate changes[] entry, exactly one file per entry. The file field contains
+  one repository-root-relative path exactly as git prints it. Globs (\`*\`, \`?\`), brace expansion
+  (\`dir/{a,b}.ts\`), and lists separated by \`;\` or \`,\` are prohibited: a collapsed entry will
+  match no file when the report is checked against the worktree and will fail the run even if
+  the work was done honestly.
+- Do not fix the environment. Service directories (\`.omx/\`, \`.claude/\`, \`.codex/\`, \`.git/\`,
+  \`node_modules/\`) and other sessions are not your task, even if they prevent you from working
+  or finishing. Put the obstacle in leftovers instead of changing them.
+- report_markdown is a full markdown report with sections: “What was done”, “Changes”
+  (file / what changed / why table), “Verification” (command and its actual output),
+  “Remaining work / risks”.`,
+  'codex-review': (opts, scope) => `Review the changes as an independent second opinion. The author is another AI model.
+
+Review scope: ${scope.label}
+Get the exact diff with: ${scope.diffCommand}
+Affected files:
+${scope.files.length ? scope.files.map((f) => `- ${f}`).join('\n') : '- (empty: git showed no changes in this scope)'}
+
+Priorities, in order: correctness bugs, security holes, data loss, broken error handling,
+race conditions, silently swallowed failures, unimplemented branches left as stubs.
+
+Rules:
+- Review it yourself: do not spawn or delegate to other agents.
+- Report only defects you can point at with file and line numbers.
+- Do not report style preferences, formatting, or naming unless they change meaning.
+- Do not invent problems to look useful. An empty findings list is a valid answer.
+- Set confidence honestly: "low" when you are guessing about intent or missing context.`,
+};
+
+/**
+ * The language of the answer, appended to every agent rather than repeated in three places.
+ * Left unsaid, the model picked it from the task, the surrounding docs or its own default: an
+ * English order once came back in Russian, and one project's artifacts ended up in two languages.
+ */
+const languageRule = () =>
+  `- Write the answer, report_markdown and every text field of result.json in ` +
+  `${RUN_ENV?.answerLanguage || DEFAULTS.answerLanguage}, whatever language the task is written in.`;
+
+export const INSTRUCTIONS = Object.fromEntries(
+  Object.entries(BODIES).map(([agent, body]) => [agent, (...args) => `${body(...args)}\n${languageRule()}`]),
+);

package/src/runner/run-context.mjs

@@ -0,0 +1,52 @@
+/**
+ * Holds the state of the run in progress and is the only way to answer whoever asked for it.
+ *
+ * Both halves of the program write here — launcher() and worker() each announce the run they
+ * took over — and the crash handler in run-codex.mjs reads it to name the run that just died.
+ * The state lives behind functions rather than exported variables because an ES module cannot
+ * reassign a binding it imported: as a plain `let` shared across files the crash handler would
+ * always have read null and lost the one report a crash is supposed to leave behind.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+let workerDir = null;
+let currentRun = null;
+let currentAgent = null;
+
+/**
+ * Marks this process as the worker half and points it at its run folder. Called once from the
+ * CLI entry, before anything else runs: from here on emitReply() answers into reply.txt rather
+ * than to a console the worker does not have.
+ */
+export function setWorkerDir(dir) {
+  workerDir = dir;
+  currentRun = dir;
+}
+
+/** The run this process is working on, for anything that has to report it. */
+export function setRun(dir, agent) {
+  currentRun = dir;
+  currentAgent = agent;
+}
+
+export const getRun = () => ({ dir: currentRun, agent: currentAgent });
+
+/**
+ * Where the reply goes. The launcher prints it, because its stdout IS the dispatcher's
+ * contract. The worker has no stdout at all — it is spawned with stdio 'ignore', since a
+ * pipe nobody drains fills up and stalls the run it was supposed to outlive — so it leaves
+ * the same text in reply.txt and the launcher prints that. Identical bytes either way.
+ */
+export function emitReply(text) {
+  if (!workerDir) {
+    console.log(text);
+    return;
+  }
+  try {
+    fs.writeFileSync(path.join(workerDir, 'reply.txt'), `${text}\n`);
+  } catch {
+    // Disk gone: status.json and meta.json already carry the verdict, and the launcher
+    // falls back to them when reply.txt never appears.
+  }
+}

package/src/runner/run-env.mjs

@@ -0,0 +1,38 @@
+/**
+ * Decides which environment a delegated run gets, and freezes that answer for the whole run.
+ *
+ * The operator's hooks and plugins belong to interactive work; by default a delegated run
+ * does not inherit them. A failing oh-my-codex `Stop` hook would not let Codex end its
+ * session, so it quarantined `.omx/state/session.json` to get out — and reported that as
+ * the job. It happened twice in production and reproduced on a sterile fixture, 44k tokens
+ * of someone else's quota spent on work nobody asked for; with both disabled the same
+ * fixture ran the task and cost 23k.
+ *
+ * Not hardcoded, because "never" is the wrong contract: `node run-config.mjs hooks on`
+ * turns either of them back on. A broken run-config.json stops the run instead of quietly
+ * falling back — a typo must not decide what environment a run gets.
+ */
+import { readRunConfig, disableFlags } from '../run-config.mjs';
+
+/**
+ * The switches as read (they go to env.json) and the flags they turn into (they go to
+ * `codex exec`). Assigned only by loadRunEnv() below, in this module: importers read them
+ * through the live binding, which is the only way they could see the loaded value at all.
+ */
+export let RUN_ENV;
+export let CLEAN_ENV;
+
+/**
+ * Launcher-only: the worker gets the finished argument list in worker.json and never reads
+ * the config again, so a config edited mid-run cannot change the environment of a run that
+ * is already going.
+ */
+export function loadRunEnv() {
+  try {
+    RUN_ENV = readRunConfig();
+    CLEAN_ENV = disableFlags(RUN_ENV);
+  } catch (err) {
+    console.log(`FAIL — ${err.message}\nRun was not started; quota was not spent`);
+    process.exit(1);
+  }
+}

package/src/runner/runs-root.mjs

@@ -0,0 +1,16 @@
+/**
+ * Says where run artifacts live.
+ *
+ * The path used to be built from os.homedir() in two places, which taught the package that it
+ * lives inside ~/.claude — outside that folder it had nowhere to write. The value is read on
+ * every call, not frozen into a constant, because tests override the variable per case.
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+export function runsRoot() {
+  const configured = process.env.CODEX_RUNS_ROOT;
+  // Trimmed, not taken literally: a path with a leading or trailing space creates a folder
+  // Windows tooling cannot address, and the value usually arrives from a shell or an .env line.
+  return configured?.trim() ? configured.trim() : path.join(os.homedir(), '.claude', 'codex-runs');
+}