@lyupro/codex-bridge 0.1.0

package/src/meta/verdict.mjs

@@ -0,0 +1,362 @@
+/**
+ * Derives a run's status from what its artifacts prove, never from what the run claims.
+ *
+ * Exit code, log size, result file, the worktree either side of the run, HEAD either side
+ * of it, and the sub-questions the order asked — a dispatcher agent therefore cannot report
+ * an outcome its own run does not support. Every branch in resolveStatus() exists because
+ * a real run satisfied every schema while doing something other than the job.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  SERVICE_RE,
+  changedPaths,
+  declaredHits,
+  displayPath,
+  expandDeclared,
+  globToRegExp,
+  line,
+  normalizePath,
+  readJson,
+  readText,
+} from './paths.mjs';
+import { chainBaseline } from './chain.mjs';
+import { splitRunChanges } from './environment.mjs';
+
+/**
+ * Quota exhaustion is a transport error, not a word. Both markers must sit on the same
+ * line: a run whose review text merely discusses "quota exhaustion" is not a run that
+ * hit the quota, and reporting LIMIT there tells the orchestrator not to retry when it
+ * should. "try again later" is deliberately absent — it is a transient-failure phrase,
+ * not a quota one.
+ */
+const LIMIT_RE = /rate.?limit|usage limit|usage_limit|quota exceeded|quota exhausted|too many requests|\b429\b/i;
+const ERROR_RE = /\bERROR\b|error[:=]|stream error|"status"\s*:\s*429|rejected|refused|failed/i;
+
+// How much prose an answer must carry once coordinates and paths are subtracted. Measured
+// on the scout run of 2026-07-30 that replied with a table of `file.ts:60-79` rows: every
+// one of its six sub-answers scored under 30, while the shortest honest explanation of a
+// single mechanism in the same report scored above 120. 80 is one full sentence; 200 is
+// the single-question mode, where one question means the whole answer is the essay.
+const MIN_SUBSTANCE_CHARS = 80;
+const MIN_SINGLE_SUBSTANCE_CHARS = 200;
+
+/**
+ * The honest reason for a failure. Codex prints API errors as pretty-printed JSON, so
+ * the literally-last line is often just `}` — useless in a one-line reply. Prefer the
+ * error message field, then any error line, then the last line that carries text.
+ */
+const reasonFrom = (log) => {
+  const messages = [...log.matchAll(/"message"\s*:\s*"((?:[^"\\]|\\.)*)"/g)];
+  if (messages.length) return line(messages[messages.length - 1][1].replace(/\\"/g, '"'));
+  const lines = log.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const errorLine = [...lines].reverse().find((l) => /error|failed|denied|refused/i.test(l));
+  return line(errorLine || lines[lines.length - 1] || '');
+};
+
+const limitSignal = (log) => {
+  const hit = log.split(/\r?\n/).find((l) => LIMIT_RE.test(l) && ERROR_RE.test(l));
+  return hit ? line(hit) : null;
+};
+
+/**
+ * Which touched paths the task never authorised. The scope exists because prose does not
+ * bind: one build run was told in words to keep away from `!Plans/*.md` and edited them
+ * anyway, and nothing in the artifacts objected — reportVersusWork() only needs a single
+ * declared path to match the tree, so extra files were never looked at.
+ *
+ * Service directories are outside every scope by construction: no task grants a delegated
+ * run the right to edit `.git/` or `.claude/`, so no pattern can whitelist them.
+ */
+export function outOfScope(touchedPaths, patterns) {
+  const allowed = (patterns || []).filter(Boolean).map(globToRegExp);
+  const bad = [];
+  for (const raw of touchedPaths || []) {
+    const file = displayPath(raw);
+    const comparison = normalizePath(file);
+    if (!comparison) continue;
+    if (SERVICE_RE.test(comparison)) {
+      bad.push(file);
+      continue;
+    }
+    if (allowed.length && !allowed.some((re) => re.test(file))) bad.push(file);
+  }
+  return bad;
+}
+
+/** Reserved for verdicts where the work really was the wrong work, not for check artefacts. */
+const WRONG_WORK = 'wrong work was done: ';
+
+/**
+ * Does the report describe the work that actually happened? A schema cannot answer this:
+ * a well-formed report about unrelated work is indistinguishable from a well-formed
+ * report about the job. The worktree can — it was snapshotted either side of the run.
+ *
+ * The report describes the state of the TASK, so it is matched against the run's own delta
+ * first and against the whole chain's accumulated work second (baseline of the first run ->
+ * this run's "after"). A second pass that legitimately changed little is carried, not
+ * failed. Both sides empty stays agreement: "there was nothing to change" is a legitimate
+ * outcome, and failing it would punish the one honest way to say so.
+ */
+export function reportVersusWork(runDir, result, ctx) {
+  const declared = (result?.changes || []).flatMap((c) => expandDeclared(c?.file));
+  const after = readText(path.join(runDir, 'state-after.txt'));
+  // Only the run's own work is compared: a report that names nothing is honest when the sole
+  // change in the tree was written by the tooling around the run.
+  const touched = splitRunChanges(
+    runDir,
+    changedPaths(readText(path.join(runDir, 'state-before.txt')), after),
+  ).work;
+  const show = (list) => list.slice(0, 3).join(', ');
+  const agreed = (carried = false) => ({ ok: true, carried, reason: null });
+  const broken = (reason) => ({ ok: false, carried: false, reason });
+
+  if (!declared.length && !touched.length) return agreed();
+  if (!declared.length) {
+    return broken(
+      `${WRONG_WORK}tree changed (${touched.length}: ${show(touched)}), but the report names no changes`,
+    );
+  }
+  if (declared.some((d) => declaredHits(d, touched))) return agreed();
+
+  // Ahead of the chain lookup: no earlier pass of any task grants the right to edit `.git/`
+  // or `.claude/`, so finding such a path in the chain would excuse the one thing that is
+  // never excusable.
+  const service = declared.filter((f) => SERVICE_RE.test(f));
+  if (service.length) {
+    return broken(
+      `${WRONG_WORK}report describes work in service directories (${show(service)}), not task files`,
+    );
+  }
+
+  const baseline = chainBaseline(ctx?.runsRoot, ctx?.repo, ctx?.slug, ctx?.taskHash, ctx?.orderId);
+  if (baseline !== null) {
+    const accumulated = splitRunChanges(runDir, changedPaths(baseline, after)).work;
+    if (declared.some((d) => declaredHits(d, accumulated))) return agreed(true);
+  }
+
+  return broken(
+    touched.length
+      ? `${WRONG_WORK}report names ${show(declared)}, but ${show(touched)} changed`
+      : 'run did not change the tree, and earlier runs of this task do not contain the declared files',
+  );
+}
+
+/**
+ * Which task a run belongs to, for the chain lookup. status.json is written before Codex is
+ * even probed, so repo and slug are on disk by the time a verdict is computed; a run from
+ * before status.json existed yields an empty context, and the chain is then not guessed.
+ */
+const chainContextOf = (runDir) => {
+  const status = readJson(path.join(runDir, 'status.json')) || {};
+  return {
+    runsRoot: path.dirname(runDir),
+    repo: status.repo || '',
+    slug: status.slug || '',
+    // Runs from before the fingerprint existed carry no hash; they chain by slug as they did.
+    taskHash: status.task_hash || '',
+    orderId: status.order_id || '',
+  };
+};
+
+/**
+ * How much of an answer is prose rather than a map. Coordinates (`path/to/file.ts:12-40`,
+ * `foo.ts:88`) and bare paths are subtracted first, then punctuation and spacing, because a
+ * "scout" that returns nothing but a coordinate table is the exact failure this measures
+ * — and by character count that table is long.
+ */
+function substanceLength(text) {
+  return String(text ?? '')
+    .replace(/`+/g, ' ')
+    .replace(/\S*\.[A-Za-z0-9]+:\d+(?:\s*[-– — ]\s*\d+)?/g, ' ')
+    .replace(/\S*[\\/]\S*/g, ' ')
+    .replace(/[^\p{L}\p{N}]+/gu, '').length;
+}
+
+const questionsOf = (runDir) => {
+  const parsed = readJson(path.join(runDir, 'questions.json'));
+  return Array.isArray(parsed) ? parsed.filter((q) => q && q.id) : [];
+};
+
+/** Answers indexed by question id, first one wins; ids come back in whatever case Codex used. */
+const answersById = (result) => {
+  const map = new Map();
+  for (const answer of Array.isArray(result?.answers) ? result.answers : []) {
+    const id = String(answer?.question_id || '').trim().toUpperCase();
+    if (id && !map.has(id)) map.set(id, answer);
+  }
+  return map;
+};
+
+/**
+ * Why a scout run is not done. Coverage is checked against the orchestrator's questions.json,
+ * including a one-question order. Runs from before that artifact existed retain the legacy
+ * single-answer check. Every branch here exists because a schema alone accepted the run that
+ * answered in coordinates.
+ */
+function scoutCoverageGap(runDir, result) {
+  const questions = questionsOf(runDir);
+  const show = (list) => list.slice(0, 8).join(', ');
+
+  if (!questions.length) {
+    const chars = substanceLength(result?.answer);
+    if (chars < MIN_SINGLE_SUBSTANCE_CHARS) {
+      return `response without analysis: ${chars} substantive characters, minimum ` +
+        `${MIN_SINGLE_SUBSTANCE_CHARS} (coordinates and paths excluded)`;
+    }
+    return null;
+  }
+
+  const byId = answersById(result);
+  const missing = questions
+    .filter((q) => !String(byId.get(q.id)?.answer || '').trim())
+    .map((q) => q.id);
+  if (missing.length) {
+    return `scout did not answer ${missing.length} sub-questions: ${show(missing)}`;
+  }
+
+  const thin = questions
+    .filter((q) => substanceLength(byId.get(q.id).answer) < MIN_SUBSTANCE_CHARS)
+    .map((q) => q.id);
+  if (thin.length) return `response to ${show(thin)} contains coordinates without analysis`;
+
+  const unsourced = questions
+    .filter((q) => !(byId.get(q.id).evidence || []).some((e) => String(e || '').trim()))
+    .map((q) => q.id);
+  if (unsourced.length) return `responses without a single code reference: ${show(unsourced)}`;
+
+  return null;
+}
+
+/** `1/1 sub-questions`, or null for legacy runs with no questions.json artifact. */
+export function scoutCoverage(runDir, result) {
+  const questions = questionsOf(runDir);
+  if (!questions.length) return null;
+  const byId = answersById(result);
+  const answered = questions.filter((q) => String(byId.get(q.id)?.answer || '').trim()).length;
+  return `${answered}/${questions.length} sub-questions`;
+}
+
+/**
+ * A commit made under an explicit ban. HEAD is snapshotted either side of the run, so this
+ * is a fact rather than an interpretation: one build run went to commit while the task said
+ * not to, and only the sandbox (a read-only `.git`) stopped it — the contract said nothing.
+ */
+function commitDuringRun(runDir) {
+  const before = readText(path.join(runDir, 'head-before.txt')).trim();
+  const after = readText(path.join(runDir, 'head-after.txt')).trim();
+  if (!before || !after || before === after) return null;
+  return `commit made despite prohibition: ${before.slice(0, 12)} → ${after.slice(0, 12)}`;
+}
+
+/**
+ * A branch moved under an explicit ban. Branch names are snapshotted either side of the run,
+ * so the artifacts prove whether it stayed on the same ref or left the repository detached.
+ *
+ * Existence is checked rather than emptiness, because here an empty file is data — detached
+ * HEAD — and a missing one is silence. Both snapshots have to be present for the comparison
+ * to mean anything: a run whose launcher predates this check, or whose worker died before
+ * writing its half, would otherwise be accused of detaching a branch it never touched.
+ */
+function branchDuringRun(runDir) {
+  const beforeFile = path.join(runDir, 'branch-before.txt');
+  const afterFile = path.join(runDir, 'branch-after.txt');
+  if (!fs.existsSync(beforeFile) || !fs.existsSync(afterFile)) return null;
+  const before = readText(beforeFile).trim();
+  const after = readText(afterFile).trim();
+  if (before === after) return null;
+  if (before && !after) return `branch moved despite prohibition: ${before} → detached HEAD`;
+  return `branch moved despite prohibition: ${before || 'detached HEAD'} → ${after}`;
+}
+
+/**
+ * Status comes from artifacts, never from intent. An abandoned run leaves raw.log at
+ * zero bytes, and that is a FAIL with its own reason — not a retry hint. An empty
+ * result with a quota signal in the log is LIMIT; without one it is FAIL.
+ */
+export function resolveStatus({ log, logBytes, resultOk, exit, agent, result, runDir }) {
+  if (!logBytes) {
+    return {
+      status: 'FAIL',
+      reason: 'run abandoned at startup: raw.log is empty, Codex did not run',
+    };
+  }
+  // Ahead of everything else, including LIMIT: a commit under an explicit ban is a broken
+  // contract, not a grade for the work. Whatever else the run produced, the orchestrator has
+  // to learn first that history moved under it.
+  if (agent === 'codex-build') {
+    const committed = commitDuringRun(runDir);
+    if (committed) return { status: 'FAIL', reason: committed };
+    const branched = branchDuringRun(runDir);
+    if (branched) return { status: 'FAIL', reason: branched };
+  }
+  if (!resultOk) {
+    const limit = limitSignal(log);
+    if (limit) return { status: 'LIMIT', reason: limit };
+    return { status: 'FAIL', reason: reasonFrom(log) || `result is empty, exit=${exit}` };
+  }
+  if (exit !== 0) {
+    return { status: 'FAIL', reason: `result exists, but exit=${exit}: ${reasonFrom(log)}` };
+  }
+  // A red verification is a failed job, not an OK with a footnote. The orchestrator
+  // reads the first word; burying "fail" in line three is how a broken build passes.
+  if (agent === 'codex-build' && result?.verify_passed === false) {
+    return {
+      status: 'FAIL',
+      reason: `verification “${line(result.verify_command || 'no command', 60)}” failed; changes remain in the tree`,
+    };
+  }
+  // Answers that never arrived, or arrived as coordinates. Scout-only, and per-question
+  // only when questions.json is absent — see scoutCoverageGap().
+  if (agent === 'codex-scout') {
+    const gap = scoutCoverageGap(runDir, result);
+    if (gap) return { status: 'FAIL', reason: gap };
+  }
+  // Files the task never authorised. Checked before the mismatch below, because a run that
+  // did the job AND edited three unrelated files passes reportVersusWork() — one matching
+  // path is all it needs — and the unrelated files would go unmentioned. No automatic
+  // revert: what to do with the extra edits is the orchestrator's call, not this file's.
+  if (agent === 'codex-build') {
+    const patterns = readText(path.join(runDir, 'scope.txt'))
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+    if (patterns.length) {
+      // Environment writes are subtracted first: attributing them to the run failed an honest
+      // pass for a file it never opened. What was subtracted is reported, not swallowed —
+      // see the "Environment" line in reply.mjs and environment_changes in meta.json.
+      const { work } = splitRunChanges(
+        runDir,
+        changedPaths(
+          readText(path.join(runDir, 'state-before.txt')),
+          readText(path.join(runDir, 'state-after.txt')),
+        ),
+      );
+      const strays = outOfScope(work, patterns);
+      if (strays.length) {
+        return {
+          status: 'FAIL',
+          reason: `out-of-scope changes (${strays.length}): ${strays.slice(0, 3).join(', ')}`,
+        };
+      }
+    }
+  }
+  // Work on the wrong thing is a failed job even when every artifact is well-formed. The
+  // run that forced this check was green on all of them while Codex spent the quota
+  // quarantining someone else's session file.
+  if (agent === 'codex-build') {
+    const verdict = reportVersusWork(runDir, result, chainContextOf(runDir));
+    if (!verdict.ok) {
+      // Hooks on is the known cause of this exact failure, so the reason says so instead
+      // of leaving the operator to rediscover it from the log.
+      const hooks = readJson(path.join(runDir, 'env.json'))?.hooks
+        ? ' (hooks are enabled in run-config.json — a likely cause)'
+        : '';
+      return { status: 'FAIL', reason: `${verdict.reason}${hooks}` };
+    }
+    // Work found in the chain but not in this run's delta is done work, not a lie: the
+    // second pass of a task legitimately has little left to change.
+    if (verdict.carried) return { status: 'OK', reason: null, carried: true };
+  }
+  return { status: 'OK', reason: null };
+}

package/src/rules/codex-bridge.rules

@@ -0,0 +1,173 @@
+# codex-bridge installs this file to constrain delegated Codex runs.
+# It exists because a delegated run must not rewrite the operator's repository history or branches.
+# Check it with: codex execpolicy check --rules src/rules/codex-bridge.rules -- <command> <args>.
+# Codex combines this file with other active rule files, and the strictest matching decision wins.
+# Known limit: prefix rules cannot detect shell redirection into .git/HEAD or equivalent indirect writes.
+
+prefix_rule(
+    pattern = ["git", "reset"],
+    decision = "forbidden",
+    justification = "Leave your work uncommitted in the tree; the index, commits and HEAD belong to the orchestrator.",
+    match = ["git reset --hard HEAD~1", "git reset HEAD -- file.txt"],
+    not_match = ["git status", "git diff --stat"],
+)
+
+prefix_rule(
+    pattern = ["git", "checkout"],
+    decision = "forbidden",
+    justification = "Read another revision with git show <rev>:<path>; branches and revisions are switched by the operator, never by a run.",
+    match = ["git checkout master", "git checkout -- file.txt"],
+    not_match = ["git show HEAD:file.txt", "git restore file.txt"],
+)
+
+prefix_rule(
+    pattern = ["git", "switch"],
+    decision = "forbidden",
+    justification = "Inspect branches with git branch --show-current and leave branch switching or creation to the operator.",
+    match = ["git switch main", "git switch -c feature"],
+    not_match = ["git branch --show-current", "git status"],
+)
+
+prefix_rule(
+    pattern = ["git", "branch", ["-d", "-D", "-m", "-M", "--delete", "--move", "--force"]],
+    decision = "forbidden",
+    justification = "Inspect branches with git branch or git branch --show-current; ask the operator to delete, rename, or force a branch.",
+    match = ["git branch -D feature", "git branch --move old new", "git branch --force feature HEAD"],
+    not_match = ["git branch", "git branch --show-current", "git branch --list"],
+)
+
+prefix_rule(
+    pattern = ["git", ["rebase", "cherry-pick", "revert", "merge"]],
+    decision = "forbidden",
+    justification = "Inspect candidate changes with git show or git diff and leave history integration to the operator.",
+    match = ["git rebase main", "git cherry-pick abc123", "git revert HEAD", "git merge feature"],
+    not_match = ["git show HEAD", "git diff main...feature"],
+)
+
+prefix_rule(
+    pattern = ["git", "stash", ["drop", "clear", "pop"]],
+    decision = "forbidden",
+    justification = "Inspect saved work with git stash list or git stash show and ask the operator before removing or applying it.",
+    match = ["git stash drop", "git stash clear", "git stash pop"],
+    not_match = ["git stash", "git stash list", "git stash show"],
+)
+
+prefix_rule(
+    pattern = ["git", ["update-ref", "symbolic-ref", "worktree", "filter-branch"]],
+    decision = "forbidden",
+    justification = "Inspect references with git show-ref or git branch and ask the operator to mutate refs, worktrees, or repository history.",
+    match = ["git update-ref refs/heads/main HEAD", "git symbolic-ref HEAD refs/heads/main", "git worktree remove ../other", "git filter-branch -- --all"],
+    not_match = ["git show-ref", "git branch --show-current"],
+)
+
+prefix_rule(
+    pattern = ["git", "gc", ["--prune", "--prune=now"]],
+    decision = "forbidden",
+    justification = "Inspect repository size with git count-objects -v and leave object pruning to the operator.",
+    match = ["git gc --prune", "git gc --prune=now"],
+    not_match = ["git gc", "git count-objects -v"],
+)
+
+prefix_rule(
+    pattern = ["git", "reflog", "expire"],
+    decision = "forbidden",
+    justification = "Inspect recovery history with git reflog show and leave reflog expiration to the operator.",
+    match = ["git reflog expire --expire=now --all"],
+    not_match = ["git reflog", "git reflog show"],
+)
+
+prefix_rule(
+    pattern = ["git", "push"],
+    decision = "forbidden",
+    justification = "Prepare local commits and show the operator the verified git push command; only the operator publishes changes.",
+    match = ["git push", "git push origin main", "git push --force"],
+    not_match = ["git status", "git remote -v"],
+)
+
+prefix_rule(
+    pattern = ["git", "remote", ["set-url", "remove", "rm", "set-head"]],
+    decision = "forbidden",
+    justification = "Inspect remotes with git remote -v and ask the operator to change remote configuration.",
+    match = ["git remote set-url origin example.invalid/repo", "git remote remove origin", "git remote rm origin", "git remote set-head origin main"],
+    not_match = ["git remote", "git remote -v", "git remote get-url origin"],
+)
+
+prefix_rule(
+    pattern = ["git", "config", ["--global", "--system"]],
+    decision = "forbidden",
+    justification = "Read configuration with git config --get <key>; ask the operator to change global or system configuration.",
+    match = ["git config --global user.name Agent", "git config --system core.autocrlf false"],
+    not_match = ["git config --get user.name", "git config user.name"],
+)
+
+prefix_rule(
+    pattern = ["git", "commit", "--amend"],
+    decision = "forbidden",
+    justification = "Create a new commit when authorized and leave rewriting the previous commit to the operator.",
+    match = ["git commit --amend", "git commit --amend --no-edit"],
+    not_match = ["git commit -m msg", "git status"],
+)
+
+prefix_rule(
+    pattern = ["git", "clean", ["-f", "-fd", "-df", "-fdx", "-xfd"]],
+    decision = "forbidden",
+    justification = "Preview untracked cleanup with git clean -n and remove only explicitly reviewed paths without forced bulk cleanup.",
+    match = ["git clean -f", "git clean -fd", "git clean -df", "git clean -fdx", "git clean -xfd"],
+    not_match = ["git clean -n", "git status --short"],
+)
+
+prefix_rule(
+    pattern = ["rm", ["-rf", "-fr", "-Rf", "-fR", "-rF", "-Fr", "-RF", "-FR"]],
+    decision = "forbidden",
+    justification = "Remove specific reviewed files without combined recursive-force flags, or ask the operator for bulk deletion.",
+    match = ["rm -rf build", "rm -fr /tmp/example", "rm -RF cache"],
+    not_match = ["rm -f stale.txt", "rm notes.md"],
+)
+
+prefix_rule(
+    pattern = ["rm", ["-r", "-R", "--recursive"], ["-f", "--force"]],
+    decision = "forbidden",
+    justification = "Remove specific reviewed files without recursive forced deletion, or ask the operator for bulk deletion.",
+    match = ["rm -r -f build", "rm --recursive --force cache"],
+    not_match = ["rm -r empty-directory", "rm -f stale.txt"],
+)
+
+prefix_rule(
+    pattern = ["rm", ["-f", "--force"], ["-r", "-R", "--recursive"]],
+    decision = "forbidden",
+    justification = "Remove specific reviewed files without recursive forced deletion, or ask the operator for bulk deletion.",
+    match = ["rm -f -r build", "rm --force --recursive cache"],
+    not_match = ["rm -f stale.txt", "rm -r empty-directory"],
+)
+
+prefix_rule(
+    pattern = ["rm", ".git"],
+    decision = "forbidden",
+    justification = "Inspect repository metadata with git status or git rev-parse and leave removal of the repository database to the operator.",
+    match = ["rm .git"],
+    not_match = ["rm .gitignore", "git status"],
+)
+
+prefix_rule(
+    pattern = ["rm", ["-r", "-R", "--recursive"], ".git"],
+    decision = "forbidden",
+    justification = "Inspect repository metadata with git status or git rev-parse and leave removal of the repository database to the operator.",
+    match = ["rm -r .git", "rm --recursive .git"],
+    not_match = ["rm -r build", "rm .gitignore"],
+)
+
+prefix_rule(
+    pattern = ["mv", ".git"],
+    decision = "forbidden",
+    justification = "Inspect the repository location with git rev-parse --git-dir and ask the operator to move repository metadata.",
+    match = ["mv .git .git-old"],
+    not_match = ["mv notes.txt archive.txt", "git rev-parse --git-dir"],
+)
+
+prefix_rule(
+    pattern = ["git", "restore"],
+    decision = "prompt",
+    justification = "Every form of restore rewinds tracked state: leave the tree as it is and report what you changed instead.",
+    match = ["git restore file.txt", "git restore --worktree file.txt", "git restore --staged file.txt"],
+    not_match = ["git status", "git show HEAD:file.txt"],
+)

package/src/run-codex.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Runs one delegated Codex job end to end:
+ *   node run-codex.mjs --agent <codex-scout|codex-build|codex-review> [options] < task.txt
+ *
+ * Options:
+ *   --agent     codex-scout | codex-build | codex-review   (required)
+ *   --repo      repository path (default: current directory)
+ *   --slug      short run name used in the run folder (default: agent suffix)
+ *   --effort    reasoning effort, passed to Codex as given (default: medium)
+ *   --verify    verification command, codex-build only (e.g. "npm test")
+ *   --scope     comma-separated globs the run may edit, codex-build only (required there)
+ *   --mode      uncommitted | base:<branch> | commit:<sha>, codex-review only
+ *   --continue  acknowledge that this repo+slug already has runs (required if it does)
+ *
+ * The operator's task text arrives on stdin, verbatim.
+ *
+ * Why this is a script and not a list of steps inside an agent prompt: a prompt can be
+ * silently not followed, and twice it wasn't — one dispatcher reviewed the diff itself
+ * after Codex disappointed it, another announced a background run that never existed.
+ * Here the caller still blocks until a verdict exists on disk, the status is computed from
+ * artifacts by write-meta.mjs, and the reply is printed by code. "Started in the
+ * background, will report later" and "I analyzed it myself instead" are unreachable.
+ *
+ * This file is two programs. A plain call is the LAUNCHER: it does every preparation and
+ * every refusal that costs no quota, then spawns the WORKER — this same file called as
+ * `--worker <runDir>`, detached, with no stdio — prints `RUN=<folder>` immediately and waits
+ * for the worker's reply.txt, which it prints verbatim. The worker runs Codex, snapshots the
+ * tree and writes the verdict.
+ *
+ * The split exists because the caller dies long before a 20-25 minute run does. Run
+ * `2026-07-31_114736_*` has no raw.log at all while 11+ files were written into the tree: the
+ * dispatcher's Bash call hit its two-minute timeout, node was killed, spawnSync's buffered
+ * output died with it — and Codex kept going, unwatched and unrecorded. Killing that orphan
+ * is not the fix either: its edits were the work, and later runs finished on top of them. So
+ * the process the caller can kill is now the launcher, and the worker it leaves behind closes
+ * the run with artifacts whether anyone is still listening or not.
+ *
+ * The work itself lives in runner/, one concern per module and the imports pointing one way:
+ * run-context.mjs holds the run in progress and answers for it, run-env.mjs decides what
+ * environment a run gets, args.mjs reads and refuses the command line, schemas.mjs and
+ * prompts.mjs are what each agent is asked for and told, git-state.mjs reads the repository,
+ * codex-cmd.mjs invokes the Codex CLI, and launcher.mjs / worker.mjs are the two halves
+ * above. This file is the command line and the fork between them; importers name it and
+ * nothing below it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFailure } from './write-meta.mjs';
+import { setWorkerDir, getRun, emitReply } from './runner/run-context.mjs';
+import { launcher } from './runner/launcher.mjs';
+import { worker } from './runner/worker.mjs';
+
+export { parseArgs } from './runner/args.mjs';
+export { runsPrefixInside, worktreeSnapshot } from './runner/git-state.mjs';
+
+// `--worker <runDir>` and nothing else: the worker takes its whole order from worker.json in
+// that folder, so a half-parsed command line cannot make the two halves disagree about which
+// run they are working on.
+const WORKER_DIR = process.argv[2] === '--worker' ? process.argv[3] : null;
+
+/**
+ * Only a direct call is a run. Imported — which is how the tests reach parseArgs(),
+ * runsPrefixInside() and worktreeSnapshot() — this file must do nothing at all: no argument
+ * parsing, no stdin, no spawn, not even a global crash handler that would swallow someone
+ * else's exception. Same guard run-config.mjs and write-meta.mjs already use.
+ */
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+setWorkerDir(WORKER_DIR);
+
+// A crash of the runner itself still has to read as a FAIL, and that FAIL still has to
+// be backed by meta.json — otherwise there would be a second path by which a reply
+// exists without an artifact behind it, which is the whole failure mode this design
+// removes. Before the run folder exists there is nowhere to write, so the reply says so.
+//
+// One handler, here, for both halves: it has to catch a crash whichever branch below is
+// running, and a second registration inside launcher.mjs or worker.mjs would be a second
+// answer to the same question.
+if (invokedDirectly) {
+  process.on('uncaughtException', (err) => {
+    const { dir: currentRun, agent: currentAgent } = getRun();
+    if (currentRun) {
+      try {
+        fs.appendFileSync(path.join(currentRun, 'raw.log'), `\nrun-codex crash: ${err.stack}\n`);
+        const { reply } = writeFailure(currentRun, currentAgent, `Codex runner crashed: ${err.message}`, [
+          `Log: ${path.join(currentRun, 'raw.log')}`,
+        ]);
+        emitReply(reply);
+        process.exit(1);
+      } catch {
+        // Falls through to the bare reply below: the disk itself is not cooperating.
+      }
+    }
+    emitReply(
+      [
+        `FAIL — Codex runner crashed before creating the run folder: ${String(err.message).replace(/\s+/g, ' ').slice(0, 150)}`,
+        'No artifacts; nothing to inspect',
+      ].join('\n'),
+    );
+    process.exit(1);
+  });
+}
+
+if (invokedDirectly) {
+  if (WORKER_DIR) {
+    worker(WORKER_DIR);
+  } else {
+    launcher();
+  }
+}

package/src/run-config.json

@@ -0,0 +1,4 @@
+{
+  "hooks": false,
+  "plugins": false
+}