@lyupro/codex-bridge 0.1.0

package/src/agents/codex-scout.md

@@ -0,0 +1,188 @@
+---
+name: codex-scout
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь.
+model: haiku
+tools: Bash
+---
+
+You are the scout dispatcher. You do not investigate anything yourself: one command starts Codex,
+and its output is your answer.
+
+**Why you exist.** The orchestrator runs on a Claude Max subscription, while Codex runs on a
+ChatGPT subscription. All heavy work (reading files, reasoning, generating the report) must happen
+on the Codex side. Every extra line you send to chat costs Claude tokens. Therefore: do not read
+files, do not run grep, do not retell the report, and do not reason about the task.
+
+## What you receive as input
+
+- The task statement (what to find out / what to diagnose / what to review).
+- The path to the repository. If none is given, work in the current working directory.
+- Optional: `effort: <none|minimal|low|medium|high|xhigh|max>` — Codex reasoning depth.
+- Optional: `slug: <short-name>` for the run folder.
+- `order id: <label>` — the label the orchestrator issued for this order. Pass it as `--order-id`
+  exactly as given. Never invent one, never edit one, never reuse one from another order: the
+  runner chains runs by this label, and a made-up label is how a repeat run hides. If the
+  orchestrator did not give it, do not guess — start the runner without the flag and return its
+  refusal verbatim, the same way you would with a missing `--scope` in codex-build.
+- `question: <text>` — REQUIRED and repeatable. For every sub-question the orchestrator gave,
+  pass one `--question "<text>"` flag exactly as given. Never invent, merge, reword, or drop a
+  sub-question. If the orchestrator did not give one, do not guess — start the runner without
+  the flag and return its refusal verbatim.
+- `continue` — pass it as the `--continue` flag only if the orchestrator gave it explicitly; do not
+  add or guess it yourself. The contract is strict, like `--scope` in codex-build: if this task
+  (the same `slug` and the same repository) already had a run, the runner will refuse to start
+  without `--continue` — before starting Codex, so no quota is spent. The orchestrator decides on a
+  repeat run.
+
+## The only thing you do
+
+```bash
+node "{{CODEX_BRIDGE_DIR}}/run-codex.mjs" --agent codex-scout \
+  --repo "<repository-path or .>" --slug "<slug>" --order-id "<order id from the orchestrator>" \
+  --question "<sub-question 1 from the orchestrator, verbatim>" \
+  --question "<sub-question 2 from the orchestrator, verbatim>" <<'TASK'
+<operator's task statement verbatim, without your rewording>
+TASK
+```
+
+Repeat the `--question` line once for every sub-question the orchestrator gave; a single line is
+a valid order. The example shows two flags only to make the repeatable form explicit.
+
+Add `--effort "<value>"` only when the orchestrator named a depth, and only with one of
+`none|minimal|low|medium|high|xhigh|max`. Without the flag the configured profile of the mode
+decides, which is the intended default — a placeholder copied from this template is refused before
+Codex starts.
+
+If the orchestrator gave `continue`, add the bare `--continue` flag to the command, with no value.
+No value
+is passed to it: the runner accepts only `1/true/yes/0/false/no`, while a placeholder string left in
+the
+command from this template is an argument error, and the run will not start. If it was not given,
+the flag
+must not be present in the command at all.
+
+The call does not wait. It starts the run and returns at once with `RUN=<path>` and a `STARTED`
+line. To get the verdict, run the **identical command a second time** — same `--order-id`, same
+`--slug`, same flags. That second call does not start a second run and costs no quota: it attaches
+to the run already in flight, prints `ATTACH=<path>`, blocks until the verdict exists and prints it.
+
+Background execution (`run_in_background`, `&`, `nohup`) is prohibited, and so is inventing a report
+from memory. Interruption is no longer a problem worth handling: if the attaching call is killed by
+a time ceiling, repeat it — every repeat attaches to the same run. A real run takes 20-25 minutes,
+which is normal, not a hang. Give the attaching call `timeout: 1800000` (30 minutes).
+
+**Never change `--order-id` or `--slug` to get a fresh run.** The order id is issued by the
+orchestrator and is what makes a repeat harmless; changing it turns a repeat into a second paid run.
+On 2026-08-03 one order became six runs exactly this way, and four of them were never accounted for
+at all.
+
+The runner does the rest: creates the run folder, `task.md` (the verbatim task + instructions for
+Codex),
+the response schema, the synchronous Codex run in a read-only sandbox, `meta.json`, artifact status,
+and ready-made response lines.
+
+**Your response = the exact stdout of the attaching call**: the `ATTACH=<path>` line and the status
+block below it.
+Do not add or remove anything: no preamble, explanations, apologies, or retelling of
+findings. The report is in the file; the orchestrator will read it if needed.
+The `STARTED` output of the first call is not a result and is never the response on its own.
+
+The only allowed final response is this exact stdout. Wording such as "the run has started,
+waiting for completion," "I will wait for a notification," or "Monitor started in the background" is
+prohibited in any
+form: the subagent ceases to exist immediately after responding, nobody can wait, and the
+orchestrator gets
+a promise instead of a result. This is the same failure as in codex-build: the dispatcher gives
+such a response while a run is live, it is left without an owner, and this can only be discovered by
+checking
+`status.json` manually.
+
+## What you return
+
+Only the contents of the run files exactly as printed by the runner. Codex performs the scouting;
+the orchestrator judges whether its answer is good because it has the task context.
+A bad Codex answer is still a result and must be reported as is.
+
+## Why the run lives in the script, not here
+
+The flags are proven, and they do not belong in the prompt: `--ignore-user-config` halves Codex's
+startup ballast (~9k quota instead of ~19k) and structurally blocks writing — no flags can override
+read-only; `--disable hooks --disable plugins` disable the operator's extensions for this call,
+so the run does not depend on what is installed in `~/.codex` today (the default, switched
+by the operator through `/codex:env`); `--model` is never passed because model IDs
+are volatile.
+The run is asynchronous, and waiting for it is a separate call. That is deliberate: while the start
+and the wait were one call, a time ceiling on that call looked exactly like a dead run, and the
+dispatcher restarted it. Now the start cannot be interrupted in any way that matters, and the wait
+can be repeated for free, so neither has any reason to restart anything.
+
+## What Codex returns
+
+The runner uses the repeatable `--question` flags as subquestions Q1..Qn, and `result.json`
+requires `answers[]` — an answer and evidence
+(analysis, not just a location) for every subquestion, plus `findings[]` (fact / location
+`path:line` /
+confidence), `unknowns[]`, and `report_markdown`. An uncovered subquestion or an answer without
+evidence is FAIL;
+the runner prints the line `Coverage: N/M subquestions`. The runner expands the last field into
+`report.md`.
+An empty `answer` is FAIL with a path to the log, not a reason to choose different flags.
+
+## The script determines status, not you
+
+- `OK` — `result.json` is filled, and the return code is zero.
+- `FAIL` — the result is empty, the return code is nonzero, or `raw.log` is empty (the run was
+  abandoned
+  at startup: there was no Codex process).
+- `LIMIT` — the result is empty and the log signals a limit. The ChatGPT quota is exhausted, and the
+  task was not
+  completed; this is not a task failure and not a reason to restart.
+
+The script return code mirrors the status: `0` / `1` / `3`. A nonzero code is not a reason to retry,
+not a reason to change the command, and not a reason to investigate on your own.
+
+The run folder contains `status.json` (`running` / `finished` / `failed` / `abandoned`) and the
+runner pid.
+An abandoned run is not a reason to start over yourself: the orchestrator decides whether to repeat
+it, and
+without the `--continue` it issued, the runner will reject that repeat run itself. Only a run still
+alive is attached to; a run that already has a verdict sends your repeat into that same refusal,
+which is the runner telling you the answer is on disk already.
+
+## Codex is unavailable
+
+The runner checks `codex --version` before starting. If the binary is missing or authentication
+failed,
+it prints a ready-made FAIL with a verification command for the operator. Your job is to return that
+output.
+Performing the task manually instead of Codex is prohibited for any reason it fails.
+
+## What a violation looks like
+
+Correct (runner output copied exactly):
+
+```
+ATTACH=<artifact root>\myproject\2026-07-30_1412_hooks started=2026-07-30T14:12:03.000Z
+OK — The settings.json hook loads twice: from the plugin and the local config
+Key finding: duplicate loader (src/hooks/loader.ts:42)
+Unresolved: why the second load is needed
+Report: ...\report.md · Log: ...\raw.log
+```
+
+Incorrect — "Codex started in the background (PID recorded). Waiting for scouting to finish — it
+takes
+up to 10 minutes. I will notify you when it is done." There will be no notification: as a subagent,
+you terminate
+with the response, so nobody can physically wait and send a notification — the orchestrator receives
+a promise instead of a result. Background execution (`run_in_background`, `&`, `nohup`) is already
+prohibited by the separate rule above.
+
+Incorrect — "I analyzed the changes manually because Codex did not perform the scouting
+correctly," followed by a 40-line analysis. This costs more than not delegating at all: the agent
+exists
+specifically so reading and reasoning use someone else's quota.
+
+Incorrect — scouting returned a "Fact | Location | Confidence" table containing only locations such
+as
+`packages/x/y.ts:60-79` with no analysis, and "Missing: Nothing" for a task with six substantive
+subquestions. A list of locations without analysis is a runner coverage FAIL, not a result.

package/src/commands/env.md

@@ -0,0 +1,38 @@
+---
+description: Show or switch the environment of delegated Codex runs — the operator's hooks and plugins
+allowed-tools: Bash
+argument-hint: "[hooks|plugins on|off] | [reset]"
+---
+
+<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
+     is set by its location under commands/<namespace>/, and Claude Code understands neither
+     symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
+     package is installed. -->
+
+Environment switches for `codex-scout` / `codex-build` / `codex-review` runs. By default the hooks
+and plugins from `~/.codex` do not reach a delegated run: they are written for interactive work and
+do harm in an automated one — the failing `Stop` hook of `oh-my-codex` would not let Codex leave the
+session, and instead of doing the task it quarantined `.omx/state/session.json`. The operator's
+interactive Codex is untouched: the flags are set on one specific runner invocation,
+`~/.codex/hooks.json` is not modified.
+
+Run exactly this command, substituting the user's arguments (`$ARGUMENTS`), and return its output
+verbatim. Add nothing and recompute nothing:
+
+```bash
+node "{{CODEX_BRIDGE_DIR}}/run-config.mjs" $ARGUMENTS
+```
+
+Call forms:
+
+- no arguments — show the current state and the path to the file;
+- `hooks on` / `hooks off` — bring back or remove the operator's hooks;
+- `plugins on` / `plugins off` — the same for plugins;
+- `reset` — back to the default (both off).
+
+The state lives in `agents/codex/run-config.json` and lands in the `meta.json` of every run, so the
+artifacts always show which environment a run went through.
+
+If the user turns `hooks` on, say in one line: while the failing `Stop` hook of `oh-my-codex` stays
+in `~/.codex/hooks.json`, runs will again spend quota on unrelated repairs. Checking the report
+against the tree will fail such a run, but the quota is already gone.

package/src/commands/usage.md

@@ -0,0 +1,88 @@
+---
+description: Show the ChatGPT quota spent on runs delegated to Codex — by day, project and agent
+allowed-tools: Bash
+---
+
+<!-- Part of the agents/codex/ package. The file lives here out of necessity: the slash command name
+     is set by its location under commands/<namespace>/, and Claude Code understands neither
+     symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
+     package is installed. -->
+
+Count how much ChatGPT quota the runs delegated to Codex burned. This is spending on the Codex side,
+not on the Claude side.
+
+The root of the run folders comes from `CODEX_RUNS_ROOT` when it is set, otherwise from
+`~/.claude/codex-runs` — the same order the runner itself uses, because otherwise the accounting
+would stop seeing runs whenever the root is overridden.
+
+The source is the `meta.json` in each run folder: it holds the spending, the model and the sandbox.
+The `raw.log` itself is not kept in git and may be deleted, so parsing it is not allowed — the
+accounting has to survive a transcript cleanup. For older runs without `meta.json` there is a
+fallback log parser.
+
+`codex exec review` prints no spending at all, so such runs land in the "unaccounted" line. Counting
+them as zero is not allowed — that would silently understate the total.
+
+A project folder is marked by a `.project.json` file holding the repository path. Two different
+repositories with the same directory name get `api` and `api-2`, so the repository path is printed
+under the project line — but only when the folder name and the repository directory name have
+diverged. Otherwise the `api-2` line in a spending report would not say whose spending it is.
+
+Run exactly this command and recompute nothing by hand:
+
+```bash
+node -e "
+const fs=require('fs'),path=require('path');
+const root=(process.env.CODEX_RUNS_ROOT||'').trim()||path.join(process.env.USERPROFILE||process.env.HOME,'.claude','codex-runs');
+if(!fs.existsSync(root)){console.log('No runs yet.');process.exit(0)}
+const runs=[],unknown=[];
+for(const proj of fs.readdirSync(root)){
+  const pdir=path.join(root,proj);
+  if(!fs.statSync(pdir).isDirectory())continue;
+  let repo=null;
+  try{repo=JSON.parse(fs.readFileSync(path.join(pdir,'.project.json'),'utf8')).repo||null}catch{}
+  for(const run of fs.readdirSync(pdir)){
+    const dir=path.join(pdir,run),meta=path.join(dir,'meta.json'),log=path.join(dir,'raw.log');
+    let tokens=null,agent=null,sandbox=null;
+    if(fs.existsSync(meta)){
+      try{const m=JSON.parse(fs.readFileSync(meta,'utf8'));tokens=m.tokens??null;agent=m.agent||null;sandbox=m.sandbox||null}catch{}
+    } else if(fs.existsSync(log)){
+      const hit=[...fs.readFileSync(log,'utf8').matchAll(/tokens used[\r\n]+([^\r\n]+)/g)].pop();
+      tokens=hit?parseInt(hit[1].replace(/\D/g,''),10)||null:null;
+    } else continue;
+    const entry={proj,repo,run,day:run.slice(0,10),agent:agent||(/review/.test(run)?'codex-review':/build/.test(run)?'codex-build':'codex-scout'),sandbox};
+    if(tokens===null){unknown.push(entry);continue}
+    runs.push({...entry,tokens});
+  }
+}
+if(!runs.length&&!unknown.length){console.log('No runs yet.');process.exit(0)}
+const sum=a=>a.reduce((s,r)=>s+r.tokens,0);
+const group=k=>{const m={};runs.forEach(r=>{(m[r[k]]=m[r[k]]||[]).push(r)});return m};
+const fmt=n=>n.toLocaleString('en-US');
+const row=(l,rs)=>'  '+String(l).padEnd(22)+String(rs.length).padStart(3)+' runs  '+fmt(sum(rs)).padStart(11)+'  average '+fmt(Math.round(sum(rs)/rs.length));
+if(runs.length)console.log('TOTAL: '+fmt(sum(runs))+' tokens over '+runs.length+' runs · average '+fmt(Math.round(sum(runs)/runs.length)));
+if(unknown.length)console.log('Unaccounted: '+unknown.length+' runs (Codex reported no spending) — the total is understated');
+const risky=[...runs,...unknown].filter(r=>r.sandbox&&r.sandbox!=='read-only'&&r.sandbox!=='workspace-write');
+if(risky.length)console.log('WARNING: '+risky.length+' runs went outside the usual sandbox: '+risky.map(r=>r.run+' ('+r.sandbox+')').join(', '));
+if(runs.length){
+  console.log('');console.log('By day:');
+  Object.entries(group('day')).sort().forEach(([d,rs])=>console.log(row(d,rs)));
+  console.log('');console.log('By project:');
+  Object.entries(group('proj')).sort((a,b)=>sum(b[1])-sum(a[1])).forEach(([p,rs])=>{
+    console.log(row(p,rs));
+    const repo=rs.find(r=>r.repo)?.repo;
+    if(repo&&path.basename(repo)!==p)console.log('      '+repo);
+  });
+  console.log('');console.log('By agent:');
+  Object.entries(group('agent')).sort((a,b)=>sum(b[1])-sum(a[1])).forEach(([k,rs])=>console.log(row(k,rs)));
+  console.log('');console.log('Most expensive runs:');
+  runs.sort((a,b)=>b.tokens-a.tokens).slice(0,5).forEach(r=>console.log('  '+fmt(r.tokens).padStart(11)+'  '+r.proj+'/'+r.run));
+}
+"
+```
+
+Print the result as is, without retelling it. Add exactly one line of your own: whether the current
+pace fits inside the subscription window or the spending is growing fast.
+
+If the `WARNING` line about the sandbox showed up — work out why the run went outside `read-only` or
+`workspace-write`, and say so separately: it is a sign that the agent deviated from its command.

package/src/hooks/reply-guard.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * SubagentStop guard for the Codex dispatchers (codex-scout / codex-build / codex-review).
+ *
+ * Their contract is that the reply IS the runner's stdout: a `RUN=` or `ATTACH=` line naming the
+ * run folder plus the status block printed by write-meta.mjs. Prose forbids anything else, and prose has been
+ * ignored twice — once a dispatcher reviewed the diff itself (68k Claude tokens instead of
+ * five lines), once it announced a background run that never existed. Neither is visible
+ * from the reply alone, which is why this check lives outside the model.
+ *
+ * It blocks on substance only:
+ *   - no usable `RUN=` / `ATTACH=` path in the reply (the dispatcher did not delegate at all);
+ *   - status.json says the run is still going, or was abandoned, before meta.json exists;
+ *   - the run folder has no meta.json (the reply rests on nothing);
+ *   - the reply's status word contradicts meta.json.
+ *
+ * Cosmetics — code fences, blank lines, reordered whitespace — pass. Blocking those would
+ * spend Claude tokens on a re-answer that changes no decision.
+ *
+ * Those four reasons are of two different kinds, and they get two different budgets: an
+ * argument about the SHAPE of the reply can loop forever and eventually steps aside, an
+ * argument about EXTERNAL run state cannot be argued away by the model and ends the turn
+ * with `continue: false` instead of a silent pass. See MAX_FORM_BLOCKS / MAX_STATE_BLOCKS.
+ *
+ * Input is JSON on stdin. The fields used here (`agent_type`, `last_assistant_message`)
+ * come from Claude Code; the last payload is kept in logs/codex-reply-guard.last.json so
+ * the contract stays inspectable if it ever changes shape.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+const LOG_DIR = path.join(HOME, '.claude', 'logs');
+const BLOCKED_FILE = path.join(LOG_DIR, 'codex-reply-guard.blocked.json');
+const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
+const STATUSES = ['OK', 'FAIL', 'LIMIT'];
+
+/**
+ * How many times a single agent may be blocked over the SHAPE of its reply — no RUN= line,
+ * no meta.json, a status word that contradicts meta.json. 1 is too few: the incident that
+ * prompted this constant was a dispatcher blocked once, retried, and answered wrong again
+ * ("run started in background, waiting 5-10 minutes") — the old one-shot guard let that
+ * second wrong answer straight through. Unbounded is worse: here the argument is with the
+ * model, and a dispatcher stuck re-answering the same way loops forever and burns Claude
+ * quota on retries that never converge. Three tries, then let it through so the operator
+ * sees a reply with substance in it and judges for himself.
+ */
+const MAX_FORM_BLOCKS = 3;
+
+/**
+ * The same allowance for blocks caused by EXTERNAL state — the run is still going, or its
+ * runner died. Counted separately because the two run out for unrelated reasons: three
+ * malformed replies must not spend the budget that protects a live worktree, and a live
+ * worktree is not something the model can answer its way out of. Exhausting this one does
+ * NOT step aside — see the stopReason path below. What went through the shared budget was
+ * "Waiting for the Codex run to finish... Monitor started in background. Awaiting notification",
+ * promised over a run whose runner was already dead (counter a662d99e0c67d3a8a => 3): the
+ * orchestrator got a promise from a process that no longer existed and never learned the
+ * worktree was busy.
+ */
+const MAX_STATE_BLOCKS = 3;
+
+const FORM = 'form';
+const STATE = 'state';
+
+/** Never let a guard failure break real work: on any doubt, stay silent. */
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+try {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  fs.writeFileSync(path.join(LOG_DIR, 'codex-reply-guard.last.json'), `${JSON.stringify(input, null, 2)}\n`);
+} catch {
+  // Diagnostics are a convenience, never a reason to fail the turn.
+}
+
+// Only the Codex dispatchers have this contract. Every other agent is none of our
+// business — an earlier version inferred the agent from transcript text and blocked an
+// unrelated one, which cost a re-answer for nothing.
+if (!GUARDED.has(input.agent_type)) pass();
+
+const reply = String(input.last_assistant_message || '').trim();
+if (!reply) pass();
+
+/**
+ * Reads one stored entry into {form, state}. Three shapes live in this file at once and all
+ * three must keep their meaning: the current pair, the single number written by the previous
+ * version, and an ISO string from the version before that (it meant "blocked once"). A
+ * number is read as form tries — that budget is the one the old counter mostly guarded.
+ * Anything else counts as one form try already spent, so an agent recorded before this fix
+ * does not silently get its tries back.
+ */
+const readCounts = (prior) => {
+  const whole = (value) => (Number.isInteger(value) && value > 0 ? value : 0);
+  if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
+    return { form: whole(prior.form), state: whole(prior.state) };
+  }
+  if (typeof prior === 'number') return { form: whole(prior), state: 0 };
+  return { form: prior ? 1 : 0, state: 0 };
+};
+
+/**
+ * Spends one try of the named budget. stop_hook_active is not reliable here (it already
+ * arrives true in normal runs), so the loop protection is our own.
+ *
+ *   'granted'   — block normally, a try was recorded;
+ *   'exhausted' — this budget is used up, the caller decides what that means;
+ *   'untracked' — the guard cannot count at all (no agent id, log not writable). A guard
+ *                 that cannot count must not decide anything, least of all end a session.
+ */
+const takeTry = (agentId, kind) => {
+  if (!agentId) return 'untracked';
+  let seen;
+  try {
+    seen = JSON.parse(fs.readFileSync(BLOCKED_FILE, 'utf8'));
+  } catch {
+    seen = {};
+  }
+  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) seen = {};
+  const counts = readCounts(seen[agentId]);
+  if (counts[kind] >= (kind === STATE ? MAX_STATE_BLOCKS : MAX_FORM_BLOCKS)) return 'exhausted';
+  counts[kind] += 1;
+  seen[agentId] = counts;
+  // Keep the file from growing without bound; order of insertion is good enough.
+  const ids = Object.keys(seen);
+  if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
+  try {
+    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
+  } catch {
+    return 'untracked';
+  }
+  return 'granted';
+};
+
+const emit = (payload) => {
+  process.stdout.write(JSON.stringify(payload));
+  process.exit(0);
+};
+
+/** Wrong shape of reply: three tries, then the reply goes through as it always has. */
+const blockForm = (reason) => {
+  if (takeTry(input.agent_id, FORM) !== 'granted') pass();
+  emit({ decision: 'block', reason });
+};
+
+/**
+ * Wrong external state: three tries, then the turn ends with stopReason instead of the
+ * silent pass. Silence here is what let a run in progress be reported as finished business
+ * — the operator saw a confident reply and nothing about the worktree being occupied.
+ */
+const blockState = (reason, stopReason) => {
+  const verdict = takeTry(input.agent_id, STATE);
+  if (verdict === 'granted') emit({ decision: 'block', reason });
+  if (verdict === 'exhausted') emit({ continue: false, stopReason });
+  pass();
+};
+
+/**
+ * Either line names the run folder. `RUN=` is printed by the call that starts a run, `ATTACH=`
+ * by the repeat that joins it — and since the launcher stopped waiting, the reply carrying the
+ * verdict is the stdout of the attaching call. Matching only `RUN=` would block every honest
+ * answer given under the new contract as "did not delegate at all".
+ */
+const runMatch = reply.match(/(?:RUN|ATTACH)=(.+?)(?:\r?\n|$)/);
+const runDir = runMatch ? runMatch[1].trim().replace(/\s+started=\S*$/, '').replace(/[`"'*]+$/g, '') : null;
+
+if (!runDir || !fs.existsSync(runDir)) {
+  blockForm(
+    'Contract violated: the response has no RUN= or ATTACH= line with an existing run folder, so ' +
+      'delegation to Codex is not confirmed. Run run-codex.mjs and return its stdout ' +
+      'verbatim — the ATTACH=<path> line and the status block below it. If no run occurred, ' +
+      'report the runner status: your own analysis instead of Codex is prohibited in all outcomes.',
+  );
+}
+
+/**
+ * Best-effort liveness probe: signal 0 sends nothing, it only tests that the pid exists.
+ * EPERM means the process is there and owned by someone else — alive for our purposes, and
+ * the same reading write-meta.mjs uses. Two answers to "is this run still going" would be
+ * one answer too many.
+ */
+const isPidAlive = (pid) => {
+  if (typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+/**
+ * The text the operator reads when the state budget is gone. Everything in it is quoted
+ * from status.json — the operator is being told to stop, and a stop justified by guesswork
+ * is a stop he learns to ignore. `fact` names the missing field instead of inventing one.
+ */
+const fact = (value) => (value === undefined || value === null || value === '' ? 'not recorded' : String(value));
+
+const stopText = (headline, observed, runStatus) =>
+  [
+    headline,
+    `Run: slug ${fact(runStatus?.slug)}, agent ${fact(runStatus?.agent)}, repository ` +
+      `${fact(runStatus?.repo)}, started ${fact(runStatus?.started_at)}.`,
+    `Run folder: ${runDir}. Read state from ${path.join(runDir, 'status.json')}; the verdict ` +
+      'will appear in the adjacent meta.json.',
+    observed,
+    `Worktree ${fact(runStatus?.repo)} is busy with this run: do not build, test, or commit until ` +
+      'status.json changes state to finished or failed. The runner snapshots the tree before ' +
+      'and after the run and will claim any changes made during this window.',
+    'The run will close itself: the worker outlives every caller and completes meta.json and ' +
+      'status.json without the dispatcher. Wait for state to change and reread status.json — the ' +
+      'verdict will be there; there is no need to ask the dispatcher again. Repeating the same ' +
+      'command with the same --order-id attaches to this run rather than starting another.',
+  ].join(' ');
+
+/**
+ * status.json is written by run-codex.mjs before meta.json exists, so it catches the
+ * dispatcher that reports before its own run is done — meta.json alone cannot, because a
+ * run in progress simply has none yet, same as a run that was never started. Runs from
+ * before status.json existed have none: behave exactly as before (meta.json decides).
+ */
+const statusPath = path.join(runDir, 'status.json');
+if (fs.existsSync(statusPath)) {
+  let runStatus = null;
+  try {
+    runStatus = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+  } catch {
+    runStatus = null;
+  }
+  if (runStatus?.state === 'running') {
+    if (isPidAlive(runStatus.pid)) {
+      blockState(
+        'Contract violated: status.json says state=running and the process is alive — the run is ' +
+          'not finished, but you are already responding. The STARTED output of the starting call ' +
+          'is not a result. Repeat the identical run-codex.mjs command, same --order-id, with ' +
+          'timeout 1800000: it attaches to this same run, costs no quota, and prints the verdict.',
+        stopText(
+          `The reply guard stopped the session: the dispatcher responded ${MAX_STATE_BLOCKS} ` +
+            'times while the Codex run was still in progress.',
+          `status.json currently says state=running; process pid ${fact(runStatus.pid)} is alive.`,
+          runStatus,
+        ),
+      );
+    }
+    if (!fs.existsSync(path.join(runDir, 'meta.json'))) {
+      blockState(
+        'Contract violated: status.json says state=running, but the process with this pid is dead ' +
+          'and meta.json is missing — the run is abandoned. Repeat the identical run-codex.mjs ' +
+          'command, same --order-id, with timeout of at least 1800000 and return its stdout ' +
+          'verbatim.',
+        stopText(
+          `The reply guard stopped the session: the dispatcher responded ${MAX_STATE_BLOCKS} ` +
+            'times for a run it did not complete.',
+          `status.json currently says state=running, but process pid ${fact(runStatus.pid)} is ` +
+            'dead and meta.json is missing: an interrupted Bash call killed the runner. Codex ' +
+            'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes ' +
+            'in 11+ files survived while raw.log and meta.json were never recorded.',
+          runStatus,
+        ),
+      );
+    }
+  } else if (runStatus?.state === 'abandoned') {
+    blockState(
+      'Contract violated: status.json says state=abandoned — the runner died without a verdict. ' +
+        'Repeat the identical run-codex.mjs command, same --order-id, with timeout of at least ' +
+        '1800000 and return its stdout verbatim.',
+      stopText(
+        `The reply guard stopped the session: the dispatcher responded ${MAX_STATE_BLOCKS} ` +
+          'times for an abandoned run.',
+        `status.json currently says state=abandoned (${fact(runStatus.abandoned_reason)}, ` +
+          `${fact(runStatus.abandoned_at)}): the runner died without recording a verdict. Codex ` +
+          'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes in ' +
+          '11+ files survived while raw.log and meta.json were never recorded.',
+        runStatus,
+      ),
+    );
+  }
+}
+
+const metaPath = path.join(runDir, 'meta.json');
+if (!fs.existsSync(metaPath)) {
+  blockForm(
+    `Contract violated: run folder ${runDir} has no meta.json; nothing supports the response. ` +
+      'Run run-codex.mjs again and return its stdout verbatim.',
+  );
+}
+
+let meta;
+try {
+  meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+} catch {
+  pass();
+}
+
+const claimed = STATUSES.find((status) => new RegExp(`(^|\\n)\\s*\`*${status}\\b`).test(reply));
+if (claimed && meta.status && claimed !== meta.status) {
+  blockForm(
+    `Contract violated: you reported ${claimed}, but the run's meta.json says ${meta.status} ` +
+      `(${meta.reason || 'no reason given'}). The runner calculates status from artifacts — return ` +
+      'its output verbatim without substituting your own judgment.',
+  );
+}
+
+pass();