@lyupro/codex-bridge 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
   "keywords": [
     "claude-code",

package/src/agents/codex-build.md

@@ -1,6 +1,6 @@
 ---
 name: codex-build
-description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот.
+description: Имплементация ВНЕ подписки Claude — правки кода, новые модули, рефакторинг по образцу, починка тестов. Работу выполняет Codex CLI (подписка ChatGPT) с правом записи в репозиторий строго в пределах обязательного `scope`, Claude платит только за постановку задачи и ≤5 строк выжимки. Отчёт и полный лог кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. Ревью и приёмку делает отдельный агент Claude, не этот. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -19,25 +19,26 @@ diff, and do not reason about the task.
 Your
 job is to report the run status honestly, including failure.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## What you receive as input
 
 - The task statement: what to change and the completion criteria.
 - The path to the repository. If none is given, use the current working directory.
-- `scope: "<glob,glob>"` — REQUIRED. The list of paths Codex may touch, relative to the
-  repository root; the runner will not start without it. If the orchestrator did not give it, do not
-  guess:
-  start the runner without `--scope` and return its refusal exactly.
-- `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. Absent means
-  the same as an absent `--scope`: 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 the same kind as `--scope`: 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; your job is to
-  pass the flag if given and return the runner's refusal exactly if it is absent.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`, `scope` as `--scope`. Never invent a value, never edit one, never
+  reuse an order id from another order — the runner chains runs by that label, and a made-up label
+  is how a repeat run hides. If the orchestrator did not give a required input, do not guess: start
+  the runner without its flag and return the runner's refusal exactly.
+- `continue` — pass the `--continue` flag only when the orchestrator gave the matching `continue:`
+  grant explicitly; do not add or guess it yourself. A continuation is assigned by the
+  orchestrator, never chosen by you. After the verdict, return the exact attaching output and stop;
+  do not issue or invent another continuation. The contract is the same kind as `--scope`: 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. If the orchestrator did not
+  grant a repeat, return the runner's refusal exactly.
 - Optional: `effort: <none|minimal|low|medium|high|xhigh|max>`, `slug:`, `verify: <verification
   command>` (for example `npm test`, `tsc --noEmit`).
 
@@ -57,7 +58,8 @@ Add `--effort "<value>"` only when the orchestrator named a depth, and only with
 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.
+If the orchestrator gave the matching `continue:` grant, 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

package/src/agents/codex-review.md

@@ -1,6 +1,6 @@
 ---
 name: codex-review
-description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности.
+description: Независимое второе мнение по коду от другой модели — ревью незакоммиченных правок, ветки или коммита силами Codex CLI (подписка ChatGPT). Не заменяет приёмку на стороне Claude, а дополняет её взглядом со стороны. Выдаёт строгий JSON с severity и confidence по каждой находке, в чат — ≤5 строк со счётчиком по важности. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -15,6 +15,10 @@ against the Claude Max quota. Claude still performs acceptance in a separate pas
 second
 opinion, not a verdict.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## What you receive as input
 
 - What to review. One of these modes:
@@ -22,10 +26,15 @@ opinion, not a verdict.
   - branch against base — `--mode base:<branch>`;
   - specific commit — `--mode commit:<sha>`.
 - The path to the repository. If none is given, use the current working directory.
-- `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 it was not
-  given, start the runner without the flag and return its refusal verbatim.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
+  another order — the runner chains runs by that label, and a made-up label is how a repeat run
+  hides. If the orchestrator did not give a required input, do not guess — start the runner without
+  its flag and return the runner's refusal verbatim.
+- `continue` is conditional — pass the `--continue` flag only when the orchestrator gave the
+  matching `continue:` grant explicitly; do not add or guess it yourself. A continuation is
+  assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
+  output and stop; do not issue or invent another continuation.
 - Optional: review focus as text ("look for races and error handling"), `slug:`, `effort:
   <none|minimal|low|medium|high|xhigh|max>`.
 
@@ -49,6 +58,9 @@ line. To get the verdict, run the **identical command a second time** — 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.
 
+If the orchestrator gave the matching `continue:` grant, add the bare `--continue` flag to the
+command, with no value. If it was not given, the flag must not be present in the command at all.
+
 Background execution (`run_in_background`, `&`, `nohup`) is prohibited. 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

package/src/agents/codex-scout.md

@@ -1,6 +1,6 @@
 ---
 name: codex-scout
-description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь.
+description: Разведка и диагностика ВНЕ подписки Claude — исследование кодовой базы, поиск причины бага, ревью, сбор фактов. Работу выполняет Codex CLI (подписка ChatGPT), Claude платит только за постановку задачи и ≤5 строк выжимки. Строго read-only: писать в репозиторий физически не может. Подробный отчёт кладёт в ~/.claude/codex-runs/, в чат — короткая выжимка + путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}}
 model: haiku
 tools: Bash
 ---
@@ -13,26 +13,31 @@ ChatGPT subscription. All heavy work (reading files, reasoning, generating the r
 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.
 
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
 ## 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.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`. Never invent a value, never edit one, never reuse an order id from
+  another order — the runner chains runs by that label, and a made-up label is how a repeat run
+  hides. If the orchestrator did not give a required input, do not guess — start the runner without
+  its flag and return the runner's refusal verbatim.
 - `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.
+- `continue` — pass the `--continue` flag only when the orchestrator gave the matching `continue:`
+  grant explicitly; do not add or guess it yourself. A continuation is assigned by the
+  orchestrator, never chosen by you. After the verdict, return the exact attaching output and stop;
+  do not issue or invent another continuation. 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 only thing you do
 
@@ -53,7 +58,8 @@ Add `--effort "<value>"` only when the orchestrator named a depth, and only with
 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.
+If the orchestrator gave the matching `continue:` grant, 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

package/src/hook-definitions.mjs

@@ -0,0 +1,36 @@
+/**
+ * Names the hooks this package registers in a host, and the tools they listen to.
+ *
+ * The gate and the installer would otherwise each carry their own idea of which tool starts a
+ * subagent, and the first host that renames it would leave a registered hook listening for a
+ * tool that never fires — silence indistinguishable from approval, which is the exact failure
+ * the gate exists to end. `cli/manifest.mjs` builds the settings matcher from SUBAGENT_TOOLS
+ * and `src/hooks/order-gate.mjs` recognises the same names, so a matcher can never drift away
+ * from what the hook actually checks.
+ */
+
+/**
+ * Every name a Claude Code host has used for the tool that launches a subagent. Both are live:
+ * this package is installed into hosts of different ages, `Task` is the long-standing name and
+ * `Agent` the current one. A hook registered for only one of them is dead weight on the other.
+ */
+export const SUBAGENT_TOOLS = Object.freeze(['Agent', 'Task']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
+export const SUBAGENT_TOOL_MATCHER = SUBAGENT_TOOLS.join('|');
+
+/**
+ * File-writing tools differ across Claude Code hosts just like subagent tools do. Register every
+ * host spelling here so the worktree lock receives the edit before it can enter a live runner's
+ * before/after snapshot; a list kept only in the hook would leave one host silently unlocked.
+ */
+export const WRITE_TOOLS = Object.freeze(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so alternation covers all four. */
+export const WRITE_TOOL_MATCHER = WRITE_TOOLS.join('|');
+
+export const HOOK_DEFINITIONS = Object.freeze([
+  Object.freeze({ event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
+  Object.freeze({ event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
+  Object.freeze({ event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
+]);

package/src/hooks/live-runs.mjs

@@ -0,0 +1,98 @@
+/**
+ * Shared, fail-open knowledge of live Codex runs.
+ *
+ * The reply guard and the worktree lock must answer the same question: a status.json is live
+ * only while it says `running` and its runner pid accepts signal 0. Keeping that probe and the
+ * directory scan here prevents the two protections from disagreeing about a run, which would
+ * recreate the incident where the dispatcher reported while another run still edited the tree.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
+export const isPidAlive = (pid) => {
+  if (typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+/**
+ * Match the package's repository comparison without resolving symlinks: Windows realpath adds
+ * `\\?\\` and UNC spellings, turning equal paths into unequal ones. A null result is uncertainty,
+ * and callers must pass rather than deny on it.
+ */
+export function normalizePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    let normalized = path.resolve(value).replaceAll('\\', '/').replace(/\/+$/, '');
+    if (!normalized) normalized = '/';
+    if (process.platform === 'win32') normalized = normalized.toLowerCase();
+    return normalized;
+  } catch {
+    return null;
+  }
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && Boolean(value.trim());
+}
+
+function recognizedStatus(status) {
+  return Boolean(status)
+    && typeof status === 'object'
+    && !Array.isArray(status)
+    && status.state === 'running'
+    && typeof status.pid === 'number'
+    && isNonEmptyString(status.agent)
+    && isNonEmptyString(status.slug)
+    && isNonEmptyString(status.repo)
+    && isPidAlive(status.pid);
+}
+
+function readStatus(runDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(runDir, 'status.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Scan one project's direct run folders; unreadable or unfamiliar entries are ignored. */
+export function liveRuns(runsDir) {
+  if (typeof runsDir !== 'string' || !runsDir.trim()) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(runsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(runsDir, entry.name);
+    const status = readStatus(dir);
+    if (recognizedStatus(status)) result.push({ dir, status });
+  }
+  return result;
+}
+
+/** Scan every project under the configured runs root for worktree ownership. */
+export function allLiveRuns(runsRoot) {
+  if (typeof runsRoot !== 'string' || !runsRoot.trim()) return [];
+  let projects;
+  try {
+    projects = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result = [];
+  for (const project of projects) {
+    if (!project.isDirectory()) continue;
+    result.push(...liveRuns(path.join(runsRoot, project.name)));
+  }
+  return result;
+}

package/src/hooks/order-gate.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse gate for the Codex dispatchers (codex-scout / codex-build / codex-review).
+ *
+ * The runner rejects a dispatcher immediately when order id (and scope for codex-build) is
+ * absent, but the old requirement lived only in the prompt read by the dispatcher. The caller
+ * therefore had no enforced place to provide it and codex-build died before doing work. This
+ * gate checks the producer's task text while it can still be corrected.
+ *
+ * Input is Claude Code's hook JSON on stdin. The last payload is retained for diagnostics so a
+ * future host schema change can be inspected instead of guessed at. Any uncertain shape passes
+ * silently because a diagnostic guard must never break an unrelated tool call.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { missingInputs } from '../required-inputs.mjs';
+import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
+
+const HOME = os.homedir();
+const LOG_DIR = path.join(HOME, '.claude', 'logs');
+const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
+/**
+ * Both spellings of the subagent-launching tool, from the same list the installer builds its
+ * matcher from. Recognising only the name this host happens to use would make the gate silent
+ * on every other host, and a gate that is silent for an unknown reason is worse than none.
+ */
+const SUBAGENT_TOOL_NAMES = new Set(SUBAGENT_TOOLS);
+
+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-order-gate.last.json'), `${JSON.stringify(input, null, 2)}\n`);
+} catch {
+  // Diagnostics are a convenience, never a reason to fail the turn.
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SUBAGENT_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+if (!GUARDED.has(toolInput.subagent_type) || typeof toolInput.prompt !== 'string') pass();
+
+const missing = missingInputs(toolInput.subagent_type, toolInput.prompt);
+if (!missing.length) pass();
+
+const reason = [
+  'Order gate denied the Agent call because required dispatcher input(s) are missing or still placeholders.',
+  'Write each value in tool_input.prompt using `label: value` before launching the dispatcher:',
+  ...missing.map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`),
+].join('\n');
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: reason,
+  },
+}));

package/src/hooks/reply-guard.mjs

@@ -29,6 +29,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
 
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
@@ -168,8 +169,9 @@ const blockState = (reason, stopReason) => {
  * 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;
+const cleanRunDir = (value) => value.trim().replace(/\s+started=\S*$/, '').replace(/[`"'*]+$/g, '');
+const runDirs = [...reply.matchAll(/(?:RUN|ATTACH)=(.+?)(?:\r?\n|$)/g)].map((match) => cleanRunDir(match[1]));
+const runDir = runDirs[0] || null;
 
 if (!runDir || !fs.existsSync(runDir)) {
   blockForm(
@@ -180,22 +182,6 @@ if (!runDir || !fs.existsSync(runDir)) {
   );
 }
 
-/**
- * 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
@@ -203,12 +189,12 @@ const isPidAlive = (pid) => {
  */
 const fact = (value) => (value === undefined || value === null || value === '' ? 'not recorded' : String(value));
 
-const stopText = (headline, observed, runStatus) =>
+const stopText = (headline, observed, runStatus, folder = runDir) =>
   [
     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 ` +
+    `Run folder: ${folder}. Read state from ${path.join(folder, '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 ` +
@@ -220,6 +206,43 @@ const stopText = (headline, observed, runStatus) =>
       'command with the same --order-id attaches to this run rather than starting another.',
   ].join(' ');
 
+/**
+ * The dispatcher must name every WRITING run the project has live, not just the one it chose to
+ * quote. The sibling scan is disk-only, so silence cannot hide a second runner; a scan failure
+ * remains fail-open because an uncertain diagnostic must never deny unrelated work.
+ *
+ * Only codex-build counts. Scout and review run in a read-only sandbox and leave the worktree
+ * alone, and launching them alongside other work is deliberate practice here — blocking a reply
+ * over a live reader would spend the state budget, and possibly the session, on a run that
+ * threatens nothing. What the 2026-08-05 incident cost was a hidden WRITER: the orchestrator
+ * edited files that landed in its before/after snapshot.
+ */
+const namedRunDirs = new Set(runDirs.map((dir) => normalizePath(dir)).filter(Boolean));
+let silentLiveSibling = null;
+try {
+  silentLiveSibling = liveRuns(path.dirname(runDir)).find((run) => {
+    if (run.status.agent !== 'codex-build') return false;
+    const normalized = normalizePath(run.dir);
+    return normalized && !namedRunDirs.has(normalized);
+  });
+} catch {
+  silentLiveSibling = null;
+}
+if (silentLiveSibling) {
+  const { dir, status } = silentLiveSibling;
+  blockState(
+    `Contract violated: the response names ${runDir} but omits live run folder ${dir}; report every `
+      + `live run with its agent ${status.agent}, slug ${status.slug}, and repository ${status.repo}.`,
+    stopText(
+      `The reply guard stopped the session: the dispatcher responded ${MAX_STATE_BLOCKS} times `
+        + 'while a live sibling Codex run was omitted from its reply.',
+      `status.json in ${dir} says state=running; process pid ${fact(status.pid)} is alive.`,
+      status,
+      dir,
+    ),
+  );
+}
+
 /**
  * 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

package/src/hooks/worktree-lock.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse lock for file-writing tools in the Claude Code host.
+ *
+ * A live codex-build runner snapshots its repository before and after editing. Letting the
+ * orchestrator write during that window folds unrelated work into the runner's result, exactly
+ * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
+ * build run's repository; every malformed or unreadable input passes so diagnostics never break
+ * unrelated host work.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { WRITE_TOOLS } from '../hook-definitions.mjs';
+import { runsRoot } from '../runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!WRITE_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+const rawPath = toolInput[pathField];
+if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
+
+let targetPath;
+try {
+  if (path.isAbsolute(rawPath)) targetPath = rawPath;
+  else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
+  else pass();
+} catch {
+  pass();
+}
+
+const target = normalizePath(targetPath);
+if (!target) pass();
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+const owner = liveRuns.find(({ status }) => {
+  if (status.agent !== 'codex-build') return false;
+  const repository = normalizePath(status.repo);
+  return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
+});
+if (!owner) pass();
+
+const { status, dir } = owner;
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${targetPath} is inside repository `
+      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
+      + 'Wait for status.json to change state before editing this repository.',
+  },
+}));

package/src/meta/outcome.mjs

@@ -0,0 +1,65 @@
+/**
+ * The outcome a build run declared about itself, and whether it was contracted to declare one.
+ *
+ * The runner cannot infer this. On 2026-08-04 (`2026-08-04_202959_build`) a build was asked to
+ * fix a function in a module absent from the checkout and answered `OK — No code change was
+ * made because the requested target file is absent`: every artifact was well-formed and a clean
+ * tree is a legitimate outcome for "check and fix if broken", so nothing in the verdict could
+ * object. Plan_12 moved the outcome from inference to declaration — the executor states it, the
+ * runner reads it.
+ *
+ * The contract marker is the run's own schema.json, not a version number written beside it. The
+ * schema IS the contract Codex was handed, so "was this run required to declare an outcome" and
+ * "what was it required to answer" cannot drift apart: they are the same file. A run from before
+ * this version, or a replay of an archived folder, has no `outcome` in its schema and keeps the
+ * verdict it always had.
+ */
+import path from 'node:path';
+import { line, readJson } from './paths.mjs';
+
+const FIELD = 'outcome';
+
+/** The values schemas.mjs allows; anything else in a result.json is a broken answer. */
+const DONE = 'done';
+const FAIL = 'fail';
+
+/**
+ * Was this run handed a schema that demands an outcome? Read off the run's own schema.json,
+ * which the launcher writes before Codex is invoked, so the answer describes the contract this
+ * run actually ran under rather than the one the current source happens to define.
+ */
+export function requiresOutcome(runDir) {
+  const schema = readJson(path.join(runDir, 'schema.json'));
+  return Array.isArray(schema?.required) && schema.required.includes(FIELD);
+}
+
+/**
+ * Why the declared outcome fails the run, or null when it does not. Three ways to fail: the
+ * executor said the work was not done; the field is missing although the schema required it
+ * (Codex enforces the schema, so this is a hand-edited or truncated result rather than a normal
+ * answer); the field holds a value the enum does not define.
+ *
+ * A declared `done` is not proof of anything — it only stops here. The tree, the scope and the
+ * report are checked after this, exactly as before: the field adds a reason to go red, it
+ * removes none.
+ */
+export function outcomeGap(runDir, result) {
+  if (!requiresOutcome(runDir)) return null;
+  // Compared exactly, never normalised. Trimming and lower-casing would let `"DONE"` or
+  // `" done "` — values the enum forbids and Codex would have rejected — buy their way past
+  // this check, and a malformed success is exactly the shape this file exists to stop. A
+  // malformed failure loses nothing by the same rule: it still goes red, only by the
+  // unknown-value branch.
+  const declared = result?.[FIELD];
+  if (declared === DONE) return null;
+  if (declared === FAIL) {
+    // The reason comes from summary rather than a field of its own: summary is already
+    // mandatory and already describes what happened, and two fields about one thing drift.
+    const stated = line(result?.summary || '', 240);
+    return `the task was not done: ${stated || 'build declared fail and gave no summary'}`;
+  }
+  if (declared === undefined || declared === null || declared === '') {
+    return 'result is not filled in: the response contract requires outcome "done" or "fail"';
+  }
+  return `result declares an unknown outcome “${line(String(declared), 40)}”, expected "done" or "fail"`;
+}