@lyupro/codex-bridge 0.1.1 → 0.1.3

package/cli/uninstall.mjs

@@ -1,8 +1,13 @@
 /** Uninstalls only recorded codex-bridge files while preserving host data and foreign files. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileFingerprint, installRecordPath, readInstallRecord } from './manifest.mjs';
-import { removeHook } from './settings-merge.mjs';
+import {
+  fileFingerprint,
+  HOOK_DEFINITIONS,
+  installRecordPath,
+  readInstallRecord,
+} from './manifest.mjs';
+import { commandFor, removeHook } from './settings-merge.mjs';
 import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
 
 async function removeEmpty(directory) {
@@ -25,7 +30,19 @@ function remainingOwnersText(count) {
   return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
 }
 
+function hookDefinition(event) {
+  return HOOK_DEFINITIONS.find((definition) => definition.event === event);
+}
+
 export async function uninstall({ host, dryRun = false } = {}) {
+  // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
+  let registry = null;
+  let registryError = null;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    registryError = err;
+  }
   const record = await readInstallRecord(host);
   const preservation = `Run artifacts in ${path.join(host.root, 'codex-runs')} and the run `
     + `configuration in ${path.join(host.agentsDir, 'run-config.json')} are preserved.`;
@@ -34,38 +51,68 @@ export async function uninstall({ host, dryRun = false } = {}) {
   if (dryRun) {
     const lines = record.files.map((file) => `Would remove ${file}`);
     if (record.rules) {
-      const registry = await readRulesRegistry(host);
-      const remainingOwners = remainingRulesOwners(registry, host);
-      const currentFingerprint = await fileFingerprint(record.rules.path);
-      if (remainingOwners?.length) {
-        lines.push(`Would leave ${record.rules.path} because ${remainingOwnersText(remainingOwners.length)}.`);
-      } else if (currentFingerprint === record.rules.fingerprint) {
-        lines.push(`Would remove ${record.rules.path}; no other owners remain and its fingerprint is unchanged.`);
-      } else if (currentFingerprint !== null) {
-        lines.push(`Would leave ${record.rules.path} because its contents changed after installation.`);
+      if (registryError) {
+        lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
       } else {
-        lines.push(`Would leave ${record.rules.path} because it is already absent.`);
+        const remainingOwners = remainingRulesOwners(registry, host);
+        const currentFingerprint = await fileFingerprint(record.rules.path);
+        if (remainingOwners?.length) {
+          lines.push(`Would leave ${record.rules.path} because ${remainingOwnersText(remainingOwners.length)}.`);
+        } else if (currentFingerprint === record.rules.fingerprint) {
+          lines.push(`Would remove ${record.rules.path}; no other owners remain and its fingerprint is unchanged.`);
+        } else if (currentFingerprint !== null) {
+          lines.push(`Would leave ${record.rules.path} because its contents changed after installation.`);
+        } else {
+          lines.push(`Would leave ${record.rules.path} because it is already absent.`);
+        }
+        if (!registry) {
+          lines.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
+        }
       }
     }
-    lines.push('Would remove the SubagentStop hook and installation record.');
+    for (const hook of record.hooks) {
+      const definition = hookDefinition(hook.event);
+      lines.push(`Would remove the ${hook.event} hook for matcher ${definition.matcher}.`);
+    }
+    lines.push('Would remove the installation record.');
     lines.push(preservation);
     return { exitCode: 0, output: lines.join('\n') };
   }
 
-  await removeHook(host.settingsPath, path.join(host.root, record.hook.path), {
-    createdGroup: record.hook.createdGroup === true,
-  });
-  const ownership = await removeRulesOwner(host);
-  let rulesOutput;
+  for (const hook of record.hooks) {
+    const definition = hookDefinition(hook.event);
+    const target = path.join(host.root, hook.path);
+    await removeHook(host.settingsPath, {
+      event: hook.event,
+      matcher: definition.matcher,
+      command: commandFor(target),
+    }, { createdGroup: hook.createdGroup === true });
+  }
+  let ownership = null;
+  if (!registryError) {
+    try {
+      ownership = await removeRulesOwner(host);
+    } catch (err) {
+      registryError = err;
+    }
+  }
+  const rulesOutput = [];
   if (record.rules) {
-    if (ownership?.owners.length) {
-      rulesOutput = `Left ${record.rules.path} because ${remainingOwnersText(ownership.owners.length)}.`;
+    if (registryError) {
+      rulesOutput.push(`Left ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
     } else {
-      const currentFingerprint = await fileFingerprint(record.rules.path);
-      if (currentFingerprint === record.rules.fingerprint) {
-        await fs.rm(record.rules.path, { force: true });
-      } else if (currentFingerprint !== null) {
-        rulesOutput = `Left ${record.rules.path} because its contents changed after installation.`;
+      if (ownership?.owners.length) {
+        rulesOutput.push(`Left ${record.rules.path} because ${remainingOwnersText(ownership.owners.length)}.`);
+      } else {
+        const currentFingerprint = await fileFingerprint(record.rules.path);
+        if (currentFingerprint === record.rules.fingerprint) {
+          await fs.rm(record.rules.path, { force: true });
+        } else if (currentFingerprint !== null) {
+          rulesOutput.push(`Left ${record.rules.path} because its contents changed after installation.`);
+        }
+      }
+      if (!registry) {
+        rulesOutput.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
       }
     }
   }
@@ -80,6 +127,6 @@ export async function uninstall({ host, dryRun = false } = {}) {
   await removeEmpty(host.agentsDir);
   return {
     exitCode: 0,
-    output: [`Uninstalled codex-bridge.`, rulesOutput, preservation].filter(Boolean).join('\n'),
+    output: [`Uninstalled codex-bridge.`, ...rulesOutput, preservation].join('\n'),
   };
 }

package/cli/update.mjs

@@ -5,14 +5,16 @@ import { install } from './install.mjs';
 import {
   buildInstallPlan,
   fileFingerprint,
+  HOOK_DEFINITIONS,
+  installedHookPath,
   packageInfo,
   readInstallRecord,
   recordMatchesPackage,
   rulesPlan,
 } from './manifest.mjs';
 import { targetMatches } from './copy.mjs';
-import { inspectHook } from './settings-merge.mjs';
-import { addRulesOwner } from './rules-owners.mjs';
+import { commandFor, inspectHook } from './settings-merge.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function exists(target) {
   try {
@@ -37,6 +39,23 @@ function classifyOrphan(state, record) {
   return 'modified';
 }
 
+function hookTargets(host) {
+  return HOOK_DEFINITIONS.map((definition) => {
+    const target = installedHookPath(host, definition);
+    return {
+      definition,
+      relative: path.relative(host.root, target).split(path.sep).join('/'),
+      spec: { event: definition.event, matcher: definition.matcher, command: commandFor(target) },
+    };
+  });
+}
+
+function recordHasHooks(record, targets) {
+  return Boolean(record)
+    && targets.every(({ definition, relative }) => record.hooks?.some((hook) =>
+      hook.event === definition.event && hook.path === relative));
+}
+
 /**
  * What the run actually did, counted by outcome. `Updated codex-bridge.` alone told the operator
  * nothing about the files that were rewritten or removed on their behalf.
@@ -62,7 +81,7 @@ function conflictOutput(conflicts, legacy, dryRun) {
   return [heading, ...lines].join('\n');
 }
 
-function dryRunOutput(states, hookPresent, legacy) {
+function dryRunOutput(states, hookStates, legacy) {
   const lines = [];
   for (const state of states) {
     if (state.status === 'outdated') lines.push(`Would update ${state.relative}.`);
@@ -72,7 +91,10 @@ function dryRunOutput(states, hookPresent, legacy) {
     if (state.status === 'orphaned' && state.exists) lines.push(`Would remove ${state.relative}.`);
     if (state.status === 'modified' && !state.item) lines.push(`Would preserve modified orphan ${state.relative}.`);
   }
-  if (!hookPresent) lines.push('Would register SubagentStop hook.');
+  hookStates.forEach(({ state, target }) => {
+    const { definition } = target;
+    if (!state.present) lines.push(`Would register ${definition.event} hook for matcher ${definition.matcher}.`);
+  });
   lines.push('Would write installation record with new fingerprints.');
   if (legacy && states.some((state) => state.status === 'modified')) {
     lines.push('Installation record has no fingerprints; differing files are treated as modified.');
@@ -81,6 +103,7 @@ function dryRunOutput(states, hookPresent, legacy) {
 }
 
 export async function update({ host, dryRun = false, force = false, packageRoot } = {}) {
+  await readRulesRegistry(host);
   const record = await readInstallRecord(host);
   if (!record) {
     return { exitCode: 1, output: 'codex-bridge is not installed. Run codex-bridge install first.' };
@@ -134,19 +157,23 @@ export async function update({ host, dryRun = false, force = false, packageRoot
     return { exitCode: 1, output: conflictOutput(conflicts, legacy, dryRun) };
   }
 
-  const guardPath = path.join(host.agentsDir, 'hooks', 'reply-guard.mjs');
-  const inspectedHook = await inspectHook(host.settingsPath, guardPath);
+  const targets = hookTargets(host);
+  const inspectedHooks = await Promise.all(targets.map(async (target) => ({
+    target,
+    state: await inspectHook(host.settingsPath, target.spec),
+  })));
   const currentPackage = await packageInfo(packageRoot);
   const recordCurrent = recordMatchesPackage(record, plan, currentPackage,
     new Map(plannedStates.map((state) => [state.relative, state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
   const changed = states.some((state) => state.status !== 'up-to-date');
-  if (!changed && inspectedHook.present && recordCurrent) {
+  if (!changed && inspectedHooks.every(({ state }) => state.present)
+    && recordHasHooks(record, targets) && recordCurrent) {
     if (!dryRun) await addRulesOwner(host);
     return { exitCode: 0, output: 'codex-bridge is up to date' };
   }
   if (dryRun) {
-    return { exitCode: 0, output: dryRunOutput(states, inspectedHook.present, legacy) };
+    return { exitCode: 0, output: dryRunOutput(states, inspectedHooks, legacy) };
   }
 
   for (const state of orphanStates) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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,19 +19,19 @@ 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.
+- 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 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

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,11 @@ 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.
 - Optional: review focus as text ("look for races and error handling"), `slug:`, `effort:
   <none|minimal|low|medium|high|xhigh|max>`.
 

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,17 +13,21 @@ 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

package/src/hook-definitions.mjs

@@ -0,0 +1,25 @@
+/**
+ * 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('|');
+
+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' }),
+]);

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/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"`;
+}

package/src/meta/reply.mjs

@@ -9,6 +9,7 @@
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
  * composing prose, which is what keeps a delegated run at five lines.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { changedPaths, line, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
@@ -113,10 +114,32 @@ export function failReply(ctx, meta) {
   return [
     `FAIL — ${line(meta.reason, 170)}`,
     `Artifacts: raw.log ${meta.log_bytes} B · ${path.basename(ctx.resultPath)} ${meta.result_ok ? 'filled' : 'empty or missing'} · exit=${meta.exit}`,
+    // A failed build says what it left behind, exactly as a LIMIT does. "The work was not
+    // done" is not "the tree is clean": a run can write half a change and then declare fail,
+    // and the orchestrator has to know whether there is something to revert before it decides
+    // anything else.
+    ...(ctx.agent === 'codex-build' ? [`Worktree: ${worktreeState(ctx.runDir)}`] : []),
     `Log: ${ctx.file('raw.log')}`,
   ];
 }
 
+/**
+ * What the run left in the tree, or an admission that nobody knows. Both snapshots are
+ * required: a run killed before it wrote state-after.txt has no delta to compute, and
+ * printing "no new changes" there would be a claim made out of missing data — the same
+ * mistake status.json's `tree_after: false` exists to prevent.
+ */
+function worktreeState(runDir) {
+  const hasSnapshots = ['state-before.txt', 'state-after.txt'].every((f) =>
+    fs.existsSync(path.join(runDir, f)),
+  );
+  if (!hasSnapshots) return 'unknown — the run left no worktree snapshot, check git status';
+  const { work } = runChanges(runDir);
+  return work.length
+    ? `has unfinished changes (${work.length}): ${line(work.slice(0, 3).join(', '), 120)}`
+    : 'no new changes';
+}
+
 export function limitReply(ctx, meta) {
   const rows = [
     'LIMIT — ChatGPT quota exhausted, work not completed',

package/src/meta/verdict.mjs

@@ -22,6 +22,7 @@ import {
 } from './paths.mjs';
 import { chainBaseline } from './chain.mjs';
 import { splitRunChanges } from './environment.mjs';
+import { outcomeGap } from './outcome.mjs';
 
 /**
  * Quota exhaustion is a transport error, not a word. Both markers must sit on the same
@@ -306,6 +307,13 @@ export function resolveStatus({ log, logBytes, resultOk, exit, agent, result, ru
       reason: `verification “${line(result.verify_command || 'no command', 60)}” failed; changes remain in the tree`,
     };
   }
+  // What the executor says about its own work, after verification and ahead of scope: work
+  // that was never done matters more than where it was not done. Only runs whose schema.json
+  // demanded the field are judged by it — see outcome.mjs.
+  if (agent === 'codex-build') {
+    const declared = outcomeGap(runDir, result);
+    if (declared) return { status: 'FAIL', reason: declared };
+  }
   // 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') {