@lyupro/codex-bridge 0.5.0 → 0.5.2

package/src/home/hooks/order-gate.mjs

@@ -0,0 +1,135 @@
+#!/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 { readJsonFileSync } from '../lib/json-file.mjs';
+import {
+  diagnoseInput,
+  extractValue,
+  missingInputs,
+  parseContinuationGrant,
+  shellUnsafeInputs,
+} from '../lib/required-inputs.mjs';
+import { SUBAGENT_TOOLS } from '../lib/hook-definitions.mjs';
+import { taskFingerprint } from '../lib/meta/chain.mjs';
+import { conflictingOrderOwner } from '../lib/runner/order-owner.mjs';
+import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { parseTaskDocument } from '../lib/runner/task-file.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);
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }));
+  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);
+const unsafe = shellUnsafeInputs(toolInput.subagent_type, toolInput.prompt);
+if (missing.length || unsafe.length) {
+  const reason = missing.length
+    ? [
+        '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.flatMap((entry) => {
+          const lines = [`- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`];
+          const diagnosis = diagnoseInput(toolInput.prompt, entry.label);
+          if (diagnosis) lines.push(`  found \`${diagnosis.line}\`, ${diagnosis.reason}`);
+          return lines;
+        }),
+      ].join('\n')
+    : [
+        'Order gate denied the Agent call because labelled dispatcher input(s) contain forbidden shell sequences.',
+        'Correct each field before launching the dispatcher:',
+        ...unsafe.map(({ entry, sequence }) =>
+          `- ${entry.label}: found ${JSON.stringify(sequence)}; put free text in the task file and pass only a short command-line value.`),
+      ].join('\n');
+  deny(reason);
+}
+
+const readStatus = (file) => {
+  try {
+    return readJsonFileSync(file);
+  } catch {
+    return null;
+  }
+};
+
+const orderId = extractValue(toolInput.prompt, 'order id');
+const taskFile = extractValue(toolInput.prompt, 'task file');
+if (!orderId || !taskFile || parseContinuationGrant(toolInput.prompt)) pass();
+
+try {
+  const taskDocument = parseTaskDocument(fs.readFileSync(taskFile, 'utf8'));
+  const taskHash = taskFingerprint(taskDocument.task);
+  const projectRunsDir = resolveProjectRunsDir(runsRoot(), input.cwd, { create: false }).dir;
+  // Per folder, not per directory: a run folder created a moment before its status.json, or any
+  // leftover beside the runs, would otherwise throw out of the whole check and silently disarm the
+  // gate for every other order. A guard that one stray folder switches off is not a guard.
+  const runs = fs.readdirSync(projectRunsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({ run: entry.name, status: readStatus(path.join(projectRunsDir, entry.name, 'status.json')) }))
+    .filter(({ status }) => status);
+  const owner = conflictingOrderOwner(runs, orderId, taskHash);
+  if (owner) {
+    const ownerDir = path.join(projectRunsDir, owner.run);
+    deny(
+      `Order gate denied the Agent call because order id ${JSON.stringify(orderId)} already belongs ` +
+        `to run folder ${ownerDir} (slug ${owner.status.slug}, started_at ${owner.status.started_at}) ` +
+        'with a different task. Use a new order id, or provide an explicit continuation grant if ' +
+        'this is another pass of that order.',
+    );
+  }
+} catch {
+  // The 2026-08-15 collision guard is diagnostic: uncertain disk state must not block real work.
+}
+
+pass();

package/src/{hooks → home/hooks}/prune-guard.mjs

@@ -11,8 +11,8 @@
  * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
  */
 import fs from 'node:fs';
-import { CLI_NAMES } from '../cli-names.mjs';
-import { SHELL_TOOLS } from '../hook-definitions.mjs';
+import { CLI_NAMES } from '../lib/cli-names.mjs';
+import { SHELL_TOOLS } from '../lib/hook-definitions.mjs';
 
 const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
 const pass = () => process.exit(0);

package/src/{hooks → home/hooks}/reply-guard.mjs

@@ -29,14 +29,43 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { readJsonFileSync } from '../json-file.mjs';
-import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
+import { runOrderMismatch, transcriptOrderId } from '../lib/dispatcher-order.mjs';
+import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
+import { readJsonFileSync } from '../lib/json-file.mjs';
+import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { isPidAlive, liveRuns, normalizePath, recentRuns } from './live-runs.mjs';
 import { FORM, MAX_STATE_BLOCKS, STATE, takeTry } from './guard-tries.mjs';
+import { parseReply } from './reply-parser.mjs';
+import {
+  abandonedRunReason,
+  abandonedRunStop,
+  deadRunReason,
+  deadRunStop,
+  liveRunReason,
+  liveRunStop,
+  missingDiscoveredMetaStop,
+  missingHostOrderIdReason,
+  missingMetaReason,
+  missingRunReason,
+  noRecentRunReason,
+  noRecentRunStop,
+  nonexistentRunReason,
+  omittedDiscoveredRunReason,
+  omittedDiscoveredRunStop,
+  omittedSiblingReason,
+  omittedSiblingStop,
+  orderMismatchStop,
+  statusMismatchReason,
+  statusMismatchStop,
+} from './reply-verdicts.mjs';
 
+// Plan_46's first invariant recognizes only direct expressions such as
+// blockForm('Contract violated: run codex-bridge run and return its stdout verbatim.');
+// The broader hook-directory scan protects the extracted verdict text from the same incident.
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
 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,
@@ -83,18 +112,23 @@ if (!GUARDED.has(input.agent_type)) pass();
 
 const reply = String(input.last_assistant_message || '').trim();
 if (!reply) pass();
-
 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 });
 };
 
+// The 2026-08-16 probe spent all state tries on an honest refusal; decide it before RUN/disk checks.
+const hostRefusal = recognizeHostRefusal(reply);
+if (hostRefusal.recognized) pass();
+if (hostRefusal.declaresFailure && hostRefusal.namesInstallRemedy && !hostRefusal.namesOrderId) {
+  blockForm(missingHostOrderIdReason);
+}
+
 /**
  * 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
@@ -107,48 +141,45 @@ const blockState = (reason, 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 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;
+const { runDirs, claimed } = parseReply(reply);
+let runDir = runDirs[0] || null;
+let discoveredRun = false;
+let discoveredStatus = null;
+let searchedRunsDir = 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.',
-  );
+if (runDir && !fs.existsSync(runDir)) {
+  blockForm(nonexistentRunReason);
 }
 
-/**
- * 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 orderedOrderId = transcriptOrderId(input.agent_transcript_path);
+
+if (!runDir && !claimed) {
+  // A reply that pronounces nothing cannot contradict the disk. It stays on the old, softer path:
+  // three tries about the SHAPE of the answer and then through, which is what a quoted refusal
+  // needs. Only a reply that hands down a verdict earns the disk search below.
+  blockForm(missingRunReason);
+}
+
+if (!runDir) {
+  let candidates;
+  try {
+    searchedRunsDir = resolveProjectRunsDir(runsRoot(), input.cwd, { create: false }).dir;
+    candidates = recentRuns(searchedRunsDir, { agent: input.agent_type });
+  } catch {
+    pass();
+  }
+  if (candidates === null) pass();
 
-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: ${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 ` +
-      '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(' ');
+  if (!candidates.length) {
+    blockState(
+      noRecentRunReason,
+      noRecentRunStop(MAX_STATE_BLOCKS, input.agent_type, searchedRunsDir),
+    );
+  }
+
+  ({ dir: runDir, status: discoveredStatus } = candidates[0]);
+  discoveredRun = true;
+}
 
 /**
  * The dispatcher must name every WRITING run the project has live, not just the one it chose to
@@ -175,15 +206,8 @@ try {
 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,
-    ),
+    omittedSiblingReason(runDir, dir, status),
+    omittedSiblingStop(MAX_STATE_BLOCKS, dir, status),
   );
 }
 
@@ -194,69 +218,54 @@ if (silentLiveSibling) {
  * before status.json existed have none: behave exactly as before (meta.json decides).
  */
 const statusPath = path.join(runDir, 'status.json');
+let runStatus = null;
 if (fs.existsSync(statusPath)) {
-  let runStatus = null;
   try {
     runStatus = readJsonFileSync(statusPath);
   } catch {
     runStatus = null;
   }
+  const mismatch = runOrderMismatch(orderedOrderId, runStatus, runDir);
+
+  if (mismatch) {
+    blockState(mismatch.reason, orderMismatchStop(MAX_STATE_BLOCKS, mismatch, runStatus, runDir));
+  }
+
   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,
-        ),
+        liveRunReason,
+        liveRunStop(MAX_STATE_BLOCKS, runStatus, runDir),
       );
     }
+
     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 no run artifact and no meta.json were ever recorded.',
-          runStatus,
-        ),
+        deadRunReason,
+        deadRunStop(MAX_STATE_BLOCKS, runStatus, runDir),
       );
     }
   } 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 no run artifact and no meta.json were ever recorded.',
-        runStatus,
-      ),
+      abandonedRunReason,
+      abandonedRunStop(MAX_STATE_BLOCKS, runStatus, runDir),
     );
   }
 }
 
 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.',
-  );
+  const reason = missingMetaReason(runDir);
+
+  if (discoveredRun) {
+    blockState(
+      reason,
+      missingDiscoveredMetaStop(MAX_STATE_BLOCKS, discoveredStatus, runDir),
+    );
+  }
+
+  blockForm(reason);
 }
 
 let meta;
@@ -266,12 +275,23 @@ try {
   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.',
+  const reason = statusMismatchReason(claimed, meta, discoveredStatus, runDir);
+
+  if (discoveredRun) {
+    blockState(
+      reason,
+      statusMismatchStop(MAX_STATE_BLOCKS, claimed, meta, discoveredStatus, runDir),
+    );
+  }
+
+  blockForm(reason);
+}
+
+if (discoveredRun) {
+  blockState(
+    omittedDiscoveredRunReason(meta, discoveredStatus, runDir),
+    omittedDiscoveredRunStop(MAX_STATE_BLOCKS, meta, discoveredStatus, runDir),
   );
 }
 

package/src/home/hooks/reply-parser.mjs

@@ -0,0 +1,27 @@
+/** Parses dispatcher replies into guard facts. */
+const STATUSES = ['OK', 'FAIL', 'LIMIT'];
+
+/**
+ * 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".
+ */
+export const cleanRunDir = (value) => value.trim().replace(/\s+(?:order-id|started)=.*$/, '').replace(/[`"'*]+$/g, '');
+
+export function parseReply(reply) {
+  const runDirs = [...reply.matchAll(/(?:RUN|ATTACH)=(.+?)(?:\r?\n|$)/g)].map((match) => cleanRunDir(match[1]));
+
+  /**
+   * Does this reply pronounce a verdict at all? Computed here rather than after meta.json is read,
+   * because it decides whether an unnamed folder is worth searching the disk for.
+   *
+   * Not every honest reply carries one. The runner refuses before creating a folder — a repeat
+   * without `--continue`, an impossible `--scope`, a missing `--question` — and its refusal is the
+   * whole truthful answer, with no run to name. Escalating those would punish the dispatcher for
+   * quoting the runner correctly, and on 2026-08-14 two such refusals arrived in a row.
+   */
+  const claimed = STATUSES.find((status) => new RegExp(`(^|\\n)\\s*\`*${status}\\b`).test(reply));
+
+  return { runDirs, claimed };
+}

package/src/home/hooks/reply-verdicts.mjs

@@ -0,0 +1,174 @@
+/** Provides the reply guard's operator-facing verdict text. */
+import path from 'node:path';
+
+export const fact = (value) => (value === undefined || value === null || value === '' ? 'not recorded' : String(value));
+
+/**
+ * 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.
+ */
+export const stopText = (headline, observed, runStatus, folder) => {
+  if (!runStatus) {
+    return [headline, observed, `Project runs directory checked: ${folder || 'not recorded'}.`].join(' ');
+  }
+
+  if (runStatus.state === 'finished' || runStatus.state === 'failed') {
+    return [
+      headline,
+      `Run: slug ${fact(runStatus.slug)}, agent ${fact(runStatus.agent)}, repository ` +
+        `${fact(runStatus.repo)}, started ${fact(runStatus.started_at)}.`,
+      `Run folder: ${folder}. Read state from ${path.join(folder, 'status.json')} and verdict ` +
+        `from ${path.join(folder, 'meta.json')}.`,
+      observed,
+      'The recorded run is complete; return the runner artifacts verbatim instead of replacing ' +
+        'their verdict or omitting their folder.',
+    ].join(' ');
+  }
+
+  return [
+    headline,
+    `Run: slug ${fact(runStatus?.slug)}, agent ${fact(runStatus?.agent)}, repository ` +
+      `${fact(runStatus?.repo)}, started ${fact(runStatus?.started_at)}.`,
+    `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 ` +
+      '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(' ');
+};
+
+export const missingHostOrderIdReason =
+  'Contract violated: the host-refusal reply is missing the order id the orchestrator issued.';
+
+export const nonexistentRunReason =
+  'Contract violated: the response has no RUN= or ATTACH= line with an existing run folder, so ' +
+  'delegation to Codex is not confirmed. Run codex-bridge run 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.';
+
+export const missingRunReason =
+  'Contract violated: the response has no RUN= or ATTACH= line, so delegation to Codex is not ' +
+  'confirmed. Run codex-bridge run and return its stdout verbatim. If the runner refused before ' +
+  'creating a folder, return that refusal exactly as printed.';
+
+export const noRecentRunReason =
+  'Contract violated: the response has no RUN= or ATTACH= line, and no recent run for this ' +
+  'dispatcher was found on disk. Run codex-bridge run and return its stdout verbatim; your own ' +
+  'analysis instead of Codex is prohibited in all outcomes.';
+
+export const noRecentRunStop = (maxBlocks, agentType, runsDir) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} times ` +
+    'without naming a run and no recent matching run was found on disk.',
+  `No run for agent ${agentType} was found in the last 24 hours.`,
+  null,
+  runsDir,
+);
+
+export const omittedSiblingReason = (runDir, dir, status) =>
+  `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}.`;
+
+export const omittedSiblingStop = (maxBlocks, dir, status) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} 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,
+);
+
+export const orderMismatchStop = (maxBlocks, mismatch, runStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher returned another order's run ${maxBlocks} times.`,
+  mismatch.observed,
+  runStatus,
+  runDir,
+);
+
+export const liveRunReason =
+  '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 codex-bridge run command, same --order-id, with ' +
+  'timeout 1800000: it attaches to this same run, costs no quota, and prints the verdict.';
+
+export const liveRunStop = (maxBlocks, runStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} ` +
+    'times while the Codex run was still in progress.',
+  `status.json currently says state=running; process pid ${fact(runStatus.pid)} is alive.`,
+  runStatus,
+  runDir,
+);
+
+export const deadRunReason =
+  '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 codex-bridge run ' +
+  'command, same --order-id, with timeout of at least 1800000 and return its stdout verbatim.';
+
+export const deadRunStop = (maxBlocks, runStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} 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 no run artifact and no meta.json were ever recorded.',
+  runStatus,
+  runDir,
+);
+
+export const abandonedRunReason =
+  'Contract violated: status.json says state=abandoned — the runner died without a verdict. ' +
+  'Repeat the identical codex-bridge run command, same --order-id, with timeout of at least ' +
+  '1800000 and return its stdout verbatim.';
+
+export const abandonedRunStop = (maxBlocks, runStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} 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 no run artifact and no meta.json were ever recorded.',
+  runStatus,
+  runDir,
+);
+
+export const missingMetaReason = (runDir) =>
+  `Contract violated: run folder ${runDir} has no meta.json; nothing supports the ` +
+  'response. Run codex-bridge run again and return its stdout verbatim.';
+
+export const missingDiscoveredMetaStop = (maxBlocks, discoveredStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher responded ${maxBlocks} times ` +
+    'without naming the recent run found on disk.',
+  `status.json says state=${fact(discoveredStatus?.state)}, status=${fact(discoveredStatus?.status)}, ` +
+    'but the adjacent meta.json is missing.',
+  discoveredStatus,
+  runDir,
+);
+
+export const statusMismatchReason = (claimed, meta, discoveredStatus, runDir) =>
+  `Contract violated: you reported ${claimed}, but run folder ${runDir} has ` +
+  `state=${fact(discoveredStatus?.state)} in status.json and status=${meta.status} in meta.json ` +
+  `(${meta.reason || 'no reason given'}). The runner calculates status from artifacts — return ` +
+  'its output verbatim without substituting your own judgment.';
+
+export const statusMismatchStop = (maxBlocks, claimed, meta, discoveredStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher contradicted the recent run on disk ${maxBlocks} times.`,
+  `status.json says state=${fact(discoveredStatus.state)}, status=${fact(discoveredStatus.status)}; ` +
+    `meta.json says status=${meta.status}, but the reply says ${claimed}.`,
+  discoveredStatus,
+  runDir,
+);
+
+export const omittedDiscoveredRunReason = (meta, discoveredStatus, runDir) =>
+  `Contract violated: the response omitted RUN=${runDir}; status.json says ` +
+  `state=${fact(discoveredStatus.state)}, status=${fact(discoveredStatus.status)}, and meta.json ` +
+  `says status=${fact(meta.status)}. Return the runner stdout verbatim.`;
+
+export const omittedDiscoveredRunStop = (maxBlocks, meta, discoveredStatus, runDir) => stopText(
+  `The reply guard stopped the session: the dispatcher omitted the recent run found on disk ${maxBlocks} times.`,
+  `status.json says state=${fact(discoveredStatus.state)}, status=${fact(discoveredStatus.status)}; ` +
+    `meta.json says status=${fact(meta.status)}.`,
+  discoveredStatus,
+  runDir,
+);

package/src/{hooks → home/hooks}/stop-guard.mjs

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { STOP_TOOLS } from '../hook-definitions.mjs';
-import { runsRoot } from '../runner/runs-root.mjs';
-import { renderStopCommand, STOP_REASON } from '../stop-contract.mjs';
+import { STOP_TOOLS } from '../lib/hook-definitions.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { renderStopCommand, STOP_REASON } from '../lib/stop-contract.mjs';
 import { allLiveRuns, normalizePath } from './live-runs.mjs';
 import { takeTry } from './guard-tries.mjs';