@lyupro/codex-bridge 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4] - 2026-08-05
+
+### Added
+
+- A continuation has to prove the orchestrator ordered it. `--continue` is refused unless the task text carries a `continue:` grant naming the run being continued and why, and the refusal costs nothing: no run folder is created and Codex is never started. The grant is single-use by construction rather than by a counter — continuing the last run of a chain appends a later one, so the same line stops matching by itself. Until this release a dispatcher could decide on a second pass alone: one did, spent 75 691 tokens of the Codex subscription and created a module the order never asked for.
+- A reply that stays silent about a live `codex-build` run of the same project is blocked. The guard reads the project's runs folder from disk instead of trusting the paths the reply chose to mention, so a second run can no longer be left working in the background while the verdict of the first is handed back. Runs of `codex-scout` and `codex-review` are not counted: they hold a read-only sandbox, and blocking a reply over one would spend the guard's budget on a run that touches nothing.
+- A `PreToolUse` lock refuses file edits inside a repository held by a live `codex-build` run. Knowing that a run is live is not the same as being unable to disturb it — edits made during that window land in the runner's before/after snapshot and fail an honest run for work it never did. An edit made through `Bash` still walks past the lock; parsing a command line is not something a guard can do reliably.
+
+### Fixed
+
+- `doctor` names the file each hook was registered for. With two hooks on one event it matched the installation record by event alone and reported the worktree lock's matcher as pointing at `order-gate.mjs` — the one line where an operator can check what is installed, showing the wrong file.
+- Hook presence is decided by this package's own command rather than by the matcher it currently sits under. The matcher is generated from the list of host tool names and grows whenever a spelling is added, so a host installed under the previous matcher would collect a duplicate hook on update and keep a hook pointing at a deleted file after uninstall.
+
 ## [0.1.3] - 2026-08-05
 
 ### Added

package/cli/doctor.mjs

@@ -73,7 +73,12 @@ async function hookChecks(host, record) {
   return Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
     const key = `hook:${definition.event}`;
     if (!record) return check(key, 'warn', 'cannot check before installation');
-    const recorded = record.hooks.find((hook) => hook.event === definition.event);
+    // The file, not just the event: PreToolUse carries two hooks of this package, and matching
+    // by event alone reported the worktree lock's matcher as pointing at order-gate.mjs. The
+    // hook line is the only place an operator can see WHICH file a matcher was registered for,
+    // so a wrong name here is worse than no line at all.
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
     if (!recorded) {
       return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
     }

package/cli/manifest.mjs

@@ -164,15 +164,17 @@ export function validateInstallRecord(record) {
     if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
       throw new Error('installation record hook must be an object');
     }
-    const definition = HOOK_DEFINITIONS.find((entry) => entry.event === hook.event);
-    if (!definition || typeof hook.path !== 'string' || !hook.path) {
+    const definitions = HOOK_DEFINITIONS.filter((entry) => entry.event === hook.event);
+    if (!definitions.length || typeof hook.path !== 'string' || !hook.path) {
       throw new Error('installation record hook must identify a supported event and its path');
     }
     if (path.isAbsolute(hook.path) || hook.path.split(/[\\/]/).includes('..')) {
       throw new Error('installation record hook path must stay relative to the host root');
     }
-    if (path.basename(hook.path) !== definition.file || !record.files.includes(hook.path)) {
-      throw new Error(`installation record hook path must name the installed ${definition.file}`);
+    const definition = definitions.find((entry) => path.basename(hook.path) === entry.file);
+    if (!definition || !record.files.includes(hook.path)) {
+      const files = definitions.map((entry) => entry.file).join(' or ');
+      throw new Error(`installation record hook path must name the installed ${files}`);
     }
   }
   return record;

package/cli/settings-merge.mjs

@@ -57,13 +57,24 @@ function groupHooks(group) {
   return Array.isArray(group?.hooks) ? group.hooks : [];
 }
 
+const hasOwnCommand = (group, command) =>
+  groupHooks(group).some((hook) => hook?.type === 'command' && hook.command === command);
+
+/**
+ * Presence is decided by the command, not by the matcher it currently sits under.
+ *
+ * The matcher is generated from the tool list in hook-definitions.mjs, so it changes whenever a
+ * host spelling is added — `Agent` became `Agent|Task` in one release, and the write-tool matcher
+ * will grow the same way. A host installed under the old matcher would then be invisible to the
+ * new lookup: update would register a duplicate and uninstall would leave a hook pointing at a
+ * deleted file. The command is this package's own absolute path, so it identifies our entry
+ * wherever the group ended up.
+ */
 export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
   const spec = normalizeSpec(specOrPath);
   const present = groups(state.settings, spec.event)
-    .filter((group) => group?.matcher === spec.matcher)
-    .some((group) => groupHooks(group)
-      .some((hook) => hook?.type === 'command' && hook.command === spec.command));
+    .some((group) => hasOwnCommand(group, spec.command));
   return { ...state, ...spec, present };
 }
 
@@ -110,9 +121,12 @@ export async function removeHook(settingsPath, specOrPath, { createdGroup = fals
   if (!state.present) return { changed: false };
   const settings = structuredClone(state.settings);
   const eventGroups = groups(settings, spec.event);
+  // Removal follows the same rule as the lookup above: our command, whatever matcher it is
+  // filed under. A foreign hook is left alone because its command is not ours, not because it
+  // sits in another group.
   for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
     const group = eventGroups[index];
-    if (group?.matcher !== spec.matcher) continue;
+    if (!hasOwnCommand(group, spec.command)) continue;
     if (!Array.isArray(group?.hooks)) continue;
     group.hooks = group.hooks.filter((hook) =>
       !(hook?.type === 'command' && hook.command === spec.command));

package/package.json

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

@@ -32,12 +32,13 @@ job is to report the run status honestly, including failure.
   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
-  `--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.
+- `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

@@ -31,6 +31,10 @@ opinion, not a verdict.
   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>`.
 
@@ -54,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

@@ -32,11 +32,12 @@ files, do not run grep, do not retell the report, and do not reason about the ta
   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
 
@@ -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/hook-definitions.mjs

@@ -19,7 +19,18 @@ 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/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/required-inputs.mjs

@@ -11,6 +11,15 @@ const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id',
 
 const freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
 
+export const CONTINUATION_INPUT = Object.freeze({
+  label: 'continue',
+  source: 'the orchestrator',
+  explanation:
+    'The run folder this pass is ordered to continue, followed by why the orchestrator is spending another pass. A continuation is assigned by the orchestrator; after a verdict, the dispatcher returns it and stops.',
+  example: '2026-08-05_092913_plan14-build — LIMIT at step 3, tests unwritten',
+  conditional: 'when --continue is passed',
+});
+
 export const REQUIRED_INPUTS = Object.freeze({
   'codex-scout': freezeEntries([
     {
@@ -19,6 +28,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-scout-20260804',
     },
+    CONTINUATION_INPUT,
   ]),
   'codex-build': freezeEntries([
     {
@@ -33,6 +43,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
       example: 'src/runner/**,tests/runner/**',
     },
+    CONTINUATION_INPUT,
   ]),
   'codex-review': freezeEntries([
     {
@@ -41,6 +52,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-review-20260804',
     },
+    CONTINUATION_INPUT,
   ]),
 });
 
@@ -51,14 +63,14 @@ function cleanValue(value) {
   return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
 }
 
-function isPlaceholder(value) {
+export function isPlaceholder(value) {
   const cleaned = cleanValue(value);
   if (!cleaned) return true;
   if (cleaned.startsWith('<') && cleaned.endsWith('>')) return true;
   return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
 }
 
-function extractValue(promptText, label) {
+export function extractValue(promptText, label) {
   const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
   const flag = `--${label.replaceAll(/\s+/g, '-')}`;
   const direct = new RegExp(
@@ -77,6 +89,23 @@ function extractValue(promptText, label) {
   return cleanValue(flagMatch[1] ?? flagMatch[2] ?? flagMatch[3]);
 }
 
+/** Keeps the 2026-08-05 continuation incident's run and reason in the shared input parser. */
+export function parseContinuationGrant(promptText) {
+  const prompt = typeof promptText === 'string' ? promptText : '';
+  const value = extractValue(prompt, CONTINUATION_INPUT.label);
+  if (isPlaceholder(value)) return null;
+
+  for (const separator of [/\s+—\s+/, /\s+-\s+/, /\s*:\s*/]) {
+    const match = value.match(new RegExp(`^(.+?)${separator.source}(.+)$`));
+    if (!match) continue;
+    const run = cleanValue(match[1]);
+    const reason = cleanValue(match[2]);
+    if (isPlaceholder(run) || isPlaceholder(reason)) return null;
+    return { run, reason };
+  }
+  return null;
+}
+
 /** Returns the immutable input entries for one dispatcher type. */
 export function requiredInputsFor(agentType) {
   return REQUIRED_INPUTS[agentType] || [];
@@ -85,20 +114,34 @@ export function requiredInputsFor(agentType) {
 /** Returns required entries whose value is absent or is still an obvious template placeholder. */
 export function missingInputs(agentType, promptText) {
   const prompt = typeof promptText === 'string' ? promptText : '';
-  return requiredInputsFor(agentType).filter((entry) => isPlaceholder(extractValue(prompt, entry.label)));
+  return requiredInputsFor(agentType).filter(
+    (entry) => !entry.conditional && isPlaceholder(extractValue(prompt, entry.label)),
+  );
 }
 
 /** Renders the compact contract the orchestrator sees while choosing a dispatcher. */
 export function renderRequiredInputSummary(agentType) {
   const entries = requiredInputsFor(agentType);
   if (!entries.length) return '';
-  const labels = entries.map((entry) => `\`${entry.label}\``);
-  return `Requires ${entries[0].source}-provided ${labels.join(' and ')}.`;
+  const labels = entries.map((entry) => {
+    const label = `\`${entry.label}\``;
+    return entry.conditional ? `${label} (${entry.conditional})` : label;
+  });
+  // Commas until the last pair: the list grew to three entries when the continuation grant
+  // joined it, and "a and b and c" reads as a stutter in the description the orchestrator
+  // sees while choosing a dispatcher.
+  const rendered = labels.length > 1
+    ? `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]}`
+    : labels[0];
+  return `Requires ${entries[0].source}-provided ${rendered}.`;
 }
 
 /** Renders the same contract for pass 2 agent instructions. */
 export function renderRequiredInputs(agentType) {
   return requiredInputsFor(agentType)
-    .map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`)
+    .map((entry) => {
+      const condition = entry.conditional ? ` Condition: ${entry.conditional}.` : '';
+      return `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.${condition}`;
+    })
     .join('\n');
 }

package/src/runner/continuation.mjs

@@ -0,0 +1,107 @@
+/**
+ * Owns the zero-quota decision about whether a requested continuation was ordered.
+ *
+ * The 2026-08-05 incident showed why the runner must not infer a second pass from a verdict:
+ * only the orchestrator read that verdict and can name the run and reason it is willing to fund.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONTINUATION_INPUT, parseContinuationGrant } from '../required-inputs.mjs';
+import { readJson } from '../write-meta.mjs';
+
+const sameRun = (runsRootPath, left, right) => {
+  const a = path.resolve(runsRootPath, left);
+  const b = path.resolve(runsRootPath, right);
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+
+function namedRunDirectory(runsRootPath, run) {
+  if (!run || run === '.' || run === '..' || path.basename(run) !== run) return null;
+  const directory = path.join(runsRootPath, run);
+  try {
+    return fs.statSync(directory).isDirectory() ? directory : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGrant(grant) {
+  if (typeof grant === 'string') return parseContinuationGrant(grant);
+  if (!grant || typeof grant !== 'object') return null;
+  const run = String(grant.run ?? '').trim();
+  const reason = String(grant.reason ?? '').trim();
+  return run && reason ? { run, reason } : null;
+}
+
+const grantExample = `Example: \`continue: ${CONTINUATION_INPUT.example}\`.`;
+const grantAction =
+  'Action: ask the orchestrator for an explicit grant naming the run and reason; do not invent or reuse a continuation.';
+
+/**
+ * Applies the one-continuation limit and all continuation safety gates before a folder is created.
+ *
+ * The limit is counted over the runs carrying THIS order id, not over the whole chain. The chain
+ * also ties runs together by slug and by the fingerprint of the task text, which is what catches a
+ * repeat that renamed itself — but counting continuations that way makes the escape hatch
+ * unreachable: the operator's rule is "more passes than one need a new order id", and a new order
+ * id lands in the same chain through the task hash. A task would then be refused with --continue
+ * for having spent its continuation and refused without it for already having runs — permanently
+ * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
+ */
+export function continuationRefusal(runsRootPath, chain, isContinue, orderId, grant) {
+  if (!isContinue) return null;
+
+  const continuation = normalizeGrant(grant);
+  if (!continuation) {
+    return (
+      '--continue is refused: the orchestrator did not provide a `continue:` grant in the task text. ' +
+      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+    );
+  }
+
+  const namedDirectory = namedRunDirectory(runsRootPath, continuation.run);
+  if (!namedDirectory) {
+    return (
+      `--continue is refused: the orchestrator named run “${continuation.run}”, but it does not ` +
+      `exist as a run folder in this project's runs directory ${runsRootPath}. ` +
+      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+    );
+  }
+
+  const last = chain[chain.length - 1];
+  // Continuing the last run appends a later run, so the old grant stops matching by itself; this
+  // incident needs no counter or new state to make an orchestrator grant single-use.
+  if (!last || !sameRun(runsRootPath, continuation.run, last)) {
+    return (
+      `--continue is refused: grant ${continuation.run} is not the LAST run of this task's chain; ` +
+      `the current last run is ${last || 'none'}. A continuation is single-use: continuing the ` +
+      'last run appends a later run, so the old grant stops matching by itself — no counter or new ' +
+      `state is used. ${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+    );
+  }
+
+  const wanted = String(orderId ?? '').trim();
+  const ofThisOrder = chain.filter(
+    (run) => String(readJson(path.join(runsRootPath, run, 'status.json'))?.order_id ?? '').trim() === wanted,
+  );
+  if (ofThisOrder.length === 0) return null;
+  if (ofThisOrder.length > 1) {
+    const spent = ofThisOrder.map((run) => path.join(runsRootPath, run)).join(', ');
+    return (
+      `--continue is refused: order “${wanted}” already spent its allowed continuation on ${spent}. ` +
+      'A further pass needs a new order id from the orchestrator. The run folder was not ' +
+      'created; quota was not spent.'
+    );
+  }
+  const previous = path.join(runsRootPath, ofThisOrder[0]);
+  const status = readJson(path.join(previous, 'status.json'));
+  const meta = readJson(path.join(previous, 'meta.json'));
+  if (!meta?.status || status?.state === 'running') {
+    return (
+      `--continue is refused: previous run ${previous} has no finished verdict and may still ` +
+      'be editing the worktree. Repeat without --continue to attach to it. The run folder was ' +
+      'not created; quota was not spent.'
+    );
+  }
+  return null;
+}

package/src/runner/launcher.mjs

@@ -28,6 +28,8 @@ import { attach } from './attach.mjs';
 import { setRun } from './run-context.mjs';
 import { loadRunEnv, RUN_ENV } from './run-env.mjs';
 import { parseArgs, die } from './args.mjs';
+import { parseContinuationGrant } from '../required-inputs.mjs';
+import { continuationRefusal } from './continuation.mjs';
 import { SCHEMAS } from './schemas.mjs';
 import { INSTRUCTIONS } from './prompts.mjs';
 import { git, headSha, branchName, worktreeSnapshot, reviewScope } from './git-state.mjs';
@@ -114,6 +116,7 @@ export async function launcher() {
   // like --scope.
   const taskHash = taskFingerprint(taskText);
   const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
+  const continuationGrant = opts.continue ? parseContinuationGrant(taskText) : null;
 
   // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
   // restart the synchronous launcher. A live same-order run is now the repeat target: attach
@@ -132,7 +135,13 @@ export async function launcher() {
   // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
   // A run without a verdict can therefore only still be in flight; ordinary repeats go through
   // attach(), while --continue must refuse to overlap that live work.
-  const continuationError = continuationRefusal(projectRunsRoot, chain, opts.continue, opts.orderId);
+  const continuationError = continuationRefusal(
+    projectRunsRoot,
+    chain,
+    opts.continue,
+    opts.orderId,
+    continuationGrant,
+  );
   if (continuationError) die(continuationError);
 
   if (chain.length && !opts.continue) {
@@ -183,6 +192,8 @@ export async function launcher() {
     // Which run of this task started the chain — the base every later pass is measured
     // against. Absent means this is the first pass.
     ...(chain.length ? { continues: chain[0] } : {}),
+    // `continued_from` is the exact run the orchestrator named; `continues` above remains the chain base.
+    ...(continuationGrant ? { continued_from: continuationGrant.run } : {}),
   });
 
   // Printed before anything can go wrong: even a dispatcher that dies mid-run leaves the
@@ -333,42 +344,3 @@ export async function launcher() {
   );
   process.exit(0);
 }
-
-/**
- * Applies the one-continuation limit and the in-flight safety gate before a folder is created.
- *
- * The limit is counted over the runs carrying THIS order id, not over the whole chain. The chain
- * also ties runs together by slug and by the fingerprint of the task text, which is what catches a
- * repeat that renamed itself — but counting continuations that way makes the escape hatch
- * unreachable: the operator's rule is "more passes than one need a new order id", and a new order
- * id lands in the same chain through the task hash. A task would then be refused with --continue
- * for having spent its continuation and refused without it for already having runs — permanently
- * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
- */
-export function continuationRefusal(runsRootPath, chain, isContinue, orderId) {
-  if (!isContinue || chain.length === 0) return null;
-  const wanted = String(orderId ?? '').trim();
-  const ofThisOrder = chain.filter(
-    (run) => String(readJson(path.join(runsRootPath, run, 'status.json'))?.order_id ?? '').trim() === wanted,
-  );
-  if (ofThisOrder.length === 0) return null;
-  if (ofThisOrder.length > 1) {
-    const spent = ofThisOrder.map((run) => path.join(runsRootPath, run)).join(', ');
-    return (
-      `--continue is refused: order “${wanted}” already spent its allowed continuation on ${spent}. ` +
-      'A further pass needs a new order id from the orchestrator. The run folder was not ' +
-      'created; quota was not spent.'
-    );
-  }
-  const previous = path.join(runsRootPath, ofThisOrder[0]);
-  const status = readJson(path.join(previous, 'status.json'));
-  const meta = readJson(path.join(previous, 'meta.json'));
-  if (!meta?.status || status?.state === 'running') {
-    return (
-      `--continue is refused: previous run ${previous} has no finished verdict and may still ` +
-      'be editing the worktree. Repeat without --continue to attach to it. The run folder was ' +
-      'not created; quota was not spent.'
-    );
-  }
-  return null;
-}