@lyupro/codex-bridge 0.1.2 → 0.1.4

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') {

package/src/required-inputs.mjs

@@ -0,0 +1,147 @@
+/**
+ * Defines the inputs the orchestrator must give each Codex dispatcher.
+ *
+ * This contract belongs beside the gate because the dispatcher prompt was the only place that
+ * named order id and scope, so the caller launched codex-build without either value and the
+ * runner refused the call before Codex could do any work. Pass 2 can render the same entries
+ * into agent instructions without creating a second list that can drift.
+ */
+
+const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id', 'scope', 'xxx']);
+
+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([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      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([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      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-build-20260804',
+    },
+    {
+      label: 'scope',
+      source: 'the orchestrator',
+      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([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      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,
+  ]),
+});
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function cleanValue(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
+}
+
+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());
+}
+
+export function extractValue(promptText, label) {
+  const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
+  const flag = `--${label.replaceAll(/\s+/g, '-')}`;
+  const direct = new RegExp(
+    `(?:^|\\r?\\n)\\s*(?:[-*]\\s*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)\\s*(?::|=|—|-)\\s*([^\\r\\n]*)`,
+    'im',
+  );
+  const directMatch = promptText.match(direct);
+  if (directMatch) return cleanValue(directMatch[1]);
+
+  const flagPattern = new RegExp(
+    `${escapeRegExp(flag)}(?:=|\\s+)(?:"([^"]*)"|'([^']*)'|([^\\s\\r\\n]+))`,
+    'i',
+  );
+  const flagMatch = promptText.match(flagPattern);
+  if (!flagMatch) return null;
+  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] || [];
+}
+
+/** 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) => !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) => {
+    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) => {
+      const condition = entry.conditional ? ` Condition: ${entry.conditional}.` : '';
+      return `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.${condition}`;
+    })
+    .join('\n');
+}

package/src/runner/args.mjs

@@ -8,12 +8,17 @@
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { ALLOWED_EFFORTS } from '../run-config.mjs';
+import { requiredInputsFor } from '../required-inputs.mjs';
 
 export function die(message) {
   console.error(`run-codex: ${message}`);
   process.exit(2);
 }
 
+function requiredInput(agentType, label) {
+  return requiredInputsFor(agentType).find((entry) => entry.label === label);
+}
+
 // Flags that carry no value. A value is accepted only in its explicit yes/no spellings;
 // anything else stops the run. The permissive reading this replaces — "not 0/false/no means
 // yes" — turned the prompt's own placeholder text (`--continue "<only if the orchestrator provided
@@ -63,10 +68,12 @@ export function parseArgs(argv) {
   if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
   opts.orderId = String(opts['order-id'] ?? '').trim();
   if (!opts.orderId) {
+    const orderInput = requiredInput(opts.agent, 'order id');
     die(
-      '--order-id is required: the orchestrator issues the order label and the runner will not invent one. ' +
+      `--order-id is required: ${orderInput.source} supplies the ${orderInput.label}; the runner will not invent one. ` +
         'A repeat of the same order should come back with --continue. If this appeared right after a package update, ' +
-        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update.',
+        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update. ' +
+        `Example: --order-id "${orderInput.example}". Action: get the value from ${orderInput.source}, pass it as --order-id, and retry.`,
     );
   }
   if (opts.agent === 'codex-scout') {
@@ -101,10 +108,11 @@ export function parseArgs(argv) {
     .map((p) => p.trim())
     .filter(Boolean);
   if (opts.agent === 'codex-build' && !opts.scopePatterns.length) {
+    const scopeInput = requiredInput(opts.agent, 'scope');
     die(
-      '--scope is required for codex-build: comma-separated globs relative to the repo root, ' +
-        'e.g. --scope "packages/event-calendar/**,apps/orchestrator/src/maestro/calendar-refresh.ts". ' +
-        'Anything outside the list is off limits and fails the run.',
+      `--scope is required for codex-build: ${scopeInput.source} supplies the ${scopeInput.label}. ` +
+        `${scopeInput.explanation} Example: --scope "${scopeInput.example}". ` +
+        `Action: get the value from ${scopeInput.source}, pass it as --scope, and retry.`,
     );
   }
   return opts;

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;
-}

package/src/runner/prompts.mjs

@@ -52,6 +52,15 @@ Working rules:
   cannot be done, do not pretend it is done; list it in leftovers.
 - After making changes, run verification: ${opts.verify || 'determine the command from the project'}.
   Put the command actually run in verify_command and whether it passed in verify_passed.
+- Declare the outcome in outcome: "done" if the work the task asked for was carried out,
+  "fail" if it was not — for any reason at all, including an impossible order, a file that
+  does not exist, a scope that forbids the only fix, or running out of time. "done" with an
+  empty changes[] is correct only when the task asked you to check something and nothing
+  needed changing; if you could not do what was asked, "fail" is the answer even when the
+  worktree is clean and verification is green. This is not a self-grade: work that was done
+  and merely leaves follow-ups is "done" with the follow-ups in leftovers, and partial work
+  that satisfies the definition of done is "done" too. On "fail" the first sentence of summary
+  states the reason — it is what the orchestrator is shown.
 - summary and changes describe only changes in this repository for this task. Do not include
   anything unrelated in them.
 - Each change is a separate changes[] entry, exactly one file per entry. The file field contains

package/src/runner/schemas.mjs

@@ -51,8 +51,30 @@ const BUILD_SCHEMA = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   type: 'object',
   additionalProperties: false,
-  required: ['summary', 'changes', 'verify_command', 'verify_passed', 'leftovers', 'report_markdown'],
+  required: [
+    'outcome',
+    'summary',
+    'changes',
+    'verify_command',
+    'verify_passed',
+    'leftovers',
+    'report_markdown',
+  ],
   properties: {
+    // The outcome is declared, never inferred. On 2026-08-04 a build asked to fix a function
+    // in a module that does not exist answered `OK — no code change was made`: every artifact
+    // was well-formed, the tree was legitimately clean, and the runner has no way to know
+    // whether the order required an edit. A string rather than a boolean because the set of
+    // outcomes will grow (`blocked` is a candidate) and an enum extends without breaking the
+    // contract. Presence of this field in the run's own schema.json is also the marker that
+    // says the run was contracted to declare an outcome — see meta/outcome.mjs.
+    outcome: {
+      type: 'string',
+      enum: ['done', 'fail'],
+      description:
+        'done — the work the task asked for was carried out. fail — it was not, for any ' +
+        'reason at all (impossible order, missing file, blocked by scope, out of time).',
+    },
     summary: { type: 'string', minLength: 1 },
     changes: {
       type: 'array',