@lyupro/codex-bridge 0.6.9 → 0.6.10

package/src/home/lib/meta/verdict.mjs

@@ -28,6 +28,7 @@ import { startupGap } from './startup.mjs';
 import { transportGap } from './transport.mjs';
 import { reasonFrom } from './reason.mjs';
 import { adviceGap } from './advice-status.mjs';
+import { allStartupContext, contextOnlyGap } from './context-only.mjs';
 import { compareSnapshots } from './snapshot-format.mjs';
 import { readSnapshot, runSnapshotChanges, snapshotRefusal } from './run-snapshots.mjs';
 
@@ -156,7 +157,7 @@ function substanceLength(text) {
 
 const questionsOf = (runDir) => {
   const parsed = readJson(path.join(runDir, 'questions.json'));
-  return Array.isArray(parsed) ? parsed.filter((q) => q && q.id) : [];
+  return Array.isArray(parsed) ? parsed : [];
 };
 
 /** Answers indexed by question id, first one wins; ids come back in whatever case Codex used. */
@@ -175,8 +176,8 @@ const answersById = (result) => {
  * single-answer check. Every branch here exists because a schema alone accepted the run that
  * answered in coordinates.
  */
-function scoutCoverageGap(runDir, result) {
-  const questions = questionsOf(runDir);
+function scoutCoverageGap(orderedQuestions, result) {
+  const questions = orderedQuestions.filter((q) => q && q.id);
   const show = (list) => list.slice(0, 8).join(', ');
 
   if (!questions.length) {
@@ -211,7 +212,7 @@ function scoutCoverageGap(runDir, result) {
 
 /** `1/1 sub-questions`, or null for legacy runs with no questions.json artifact. */
 export function scoutCoverage(runDir, result) {
-  const questions = questionsOf(runDir);
+  const questions = questionsOf(runDir).filter((q) => q && q.id);
   if (!questions.length) return null;
   const byId = answersById(result);
   const answered = questions.filter((q) => String(byId.get(q.id)?.answer || '').trim()).length;
@@ -288,9 +289,10 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
     // This branch already knows why the run died: the CLI said so itself, with a status. Letting
     // the ordered reason speak here would answer a transport question with the model's older
     // complaint about the task — a LIMIT that never mentions quota is the same "verdict says the
-    // wrong thing" defect this module exists to remove.
+    // wrong thing" defect this module exists to remove. Plan_60 D2: UNAVAILABLE only on a measured
+    // signed-out sample (events.mjs); an unfamiliar failure stays FAIL with its raw CLI text.
     return {
-      status: transportError.quota ? 'LIMIT' : 'FAIL',
+      status: transportError.quota ? 'LIMIT' : transportError.unavailable ? 'UNAVAILABLE' : 'FAIL',
       reason: transportError.reason,
     };
   }
@@ -318,19 +320,25 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
   // 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') {
+    const questions = questionsOf(runDir);
     // The 2026-09-16 dead sandbox produced nonempty evidence without reading code. Require an
     // execution fact first: checking whether evidence paths existed falsely rejected 64/151 runs.
     // Only a run that left a stream can prove it: an archived run from before `--json` has none and
     // is judged by the contract of its day; a `--json` run missing its stream already failed above.
-    if (eventData.hasStream && eventData.commands_executed === 0) {
+    // Plan_60 D1 exempts only orders whose every question asks about handed startup context.
+    if (eventData.hasStream && eventData.commands_executed === 0 && !allStartupContext(questions)) {
       return {
         status: 'FAIL',
         reason: 'scout executed no command, so no answer rests on reading the code; '
           + 'check stderr.log for sandbox refusals before changing the order',
       };
     }
-    const gap = scoutCoverageGap(runDir, result);
+    const gap = scoutCoverageGap(questions, result);
     if (gap) return { status: 'FAIL', reason: gap };
+    const contextGap = contextOnlyGap({
+      questions, result, commandsExecuted: eventData.hasStream ? eventData.commands_executed : null,
+    });
+    if (contextGap) return { status: 'FAIL', reason: contextGap };
   }
   // Plan_59 D3/D4/D5/D10: a schema-valid agreement still needs evidence and decision checks.
   // Place the advisor judge before the build-only scope check, alongside the other agent contracts.

package/src/home/lib/required-inputs.mjs

@@ -23,6 +23,15 @@ export const CONTINUATION_INPUT = Object.freeze({
   conditional: 'when --continue is passed',
 });
 
+export const RETRY_INPUT = Object.freeze({
+  label: 'retry',
+  source: 'the orchestrator',
+  explanation:
+    'The failed run this pass repeats, followed by why the orchestrator pays for the same pass again. A retry repeats that failed pass under its own order; it does not authorize the next pass.',
+  example: '2026-10-03_172017_cc-d66-advisor — model at capacity, same pass again',
+  conditional: 'when --continue is passed',
+});
+
 /**
  * The task statement reaches the runner as a file because every other channel puts the invocation
  * back into the multi-line form that no permission rule can cover — a heredoc on stdin, or a
@@ -53,6 +62,7 @@ export const REQUIRED_INPUTS = Object.freeze({
     },
     TASK_FILE_INPUT,
     CONTINUATION_INPUT,
+    RETRY_INPUT,
   ]),
   'codex-build': freezeEntries([
     {
@@ -69,6 +79,7 @@ export const REQUIRED_INPUTS = Object.freeze({
     },
     TASK_FILE_INPUT,
     CONTINUATION_INPUT,
+    RETRY_INPUT,
   ]),
   'codex-review': freezeEntries([
     {
@@ -79,6 +90,7 @@ export const REQUIRED_INPUTS = Object.freeze({
     },
     TASK_FILE_INPUT,
     CONTINUATION_INPUT,
+    RETRY_INPUT,
   ]),
   // Plan_59 D7: the caller must name the phase and authorize the continued decision pass.
   'codex-advisor': freezeEntries([
@@ -90,6 +102,7 @@ export const REQUIRED_INPUTS = Object.freeze({
     },
     TASK_FILE_INPUT,
     CONTINUATION_INPUT,
+    RETRY_INPUT,
     {
       label: 'phase',
       source: 'the orchestrator',
@@ -122,13 +135,15 @@ export function isPlaceholder(value) {
 export const isInputPlaceholder = (value, label) =>
   !(label === 'phase' && cleanValue(value) === 'scope') && isPlaceholder(value);
 
-export function extractValue(promptText, label) {
+// Plan_75 D5: dispatcher prompts still need one spelling of a labelled line for reading values.
+const labelledLine = (label) => {
   const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
+  return `(?:[-*]\\s*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)\\s*(?::|=|—|-)`;
+};
+
+export function extractValue(promptText, label) {
   const flag = `--${label.replaceAll(/\s+/g, '-')}`;
-  const direct = new RegExp(
-    `(?:^|\\r?\\n)\\s*(?:[-*]\\s*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)\\s*(?::|=|—|-)\\s*([^\\r\\n]*)`,
-    'im',
-  );
+  const direct = new RegExp(`(?:^|\\r?\\n)\\s*${labelledLine(label)}\\s*([^\\r\\n]*)`, 'im');
   const directMatch = promptText.match(direct);
   if (directMatch) return cleanValue(directMatch[1]);
 
@@ -188,10 +203,15 @@ export function diagnoseInput(promptText, label) {
   return { line, reason: `expected \`${label}: value\` with a separator immediately after the label` };
 }
 
-/** Keeps the 2026-08-05 continuation incident's run and reason in the shared input parser. */
-export function parseContinuationGrant(promptText) {
+// Plan_75 D1, TradeForge capacity incident (2026-10-03): both grants need the same run/reason grammar.
+function parseLabelledGrant(promptText, label) {
   const prompt = typeof promptText === 'string' ? promptText : '';
-  const value = extractValue(prompt, CONTINUATION_INPUT.label);
+  const value = extractValue(prompt, label);
+  return splitGrantValue(value);
+}
+
+// Plan_75 D5, 2026-10-03 20:42: header parsing must reuse the existing grant value grammar.
+export function splitGrantValue(value) {
   if (isPlaceholder(value)) return null;
 
   for (const separator of [/\s+—\s+/, /\s+-\s+/, /\s*:\s*/]) {
@@ -205,6 +225,26 @@ export function parseContinuationGrant(promptText) {
   return null;
 }
 
+/** Keeps the 2026-08-05 continuation incident's run and reason in the shared input parser. */
+export function parseContinuationGrant(promptText) {
+  return parseLabelledGrant(promptText, CONTINUATION_INPUT.label);
+}
+
+export function parseRetryGrant(promptText) {
+  return parseLabelledGrant(promptText, RETRY_INPUT.label);
+}
+
+export function parseGrant(promptText) {
+  const continuation = parseContinuationGrant(promptText);
+  const retry = parseRetryGrant(promptText);
+  if (continuation && retry) {
+    return { error: 'exactly one grant per task: remove either the continue: or the retry: line' };
+  }
+  if (continuation) return { kind: 'continue', ...continuation };
+  if (retry) return { kind: 'retry', ...retry };
+  return null;
+}
+
 /** Returns the immutable input entries for one dispatcher type. */
 export function requiredInputsFor(agentType) {
   return REQUIRED_INPUTS[agentType] || [];

package/src/home/lib/run-codex.mjs

@@ -54,6 +54,7 @@ import { setWorkerDir, getRun, emitReply } from './runner/run-context.mjs';
 import { launcher } from './runner/launcher.mjs';
 import { worker } from './runner/worker.mjs';
 import { RunnerUsageError } from './runner/args.mjs';
+import { EXIT } from './runner/exit-codes.mjs';
 
 export { parseArgs } from './runner/args.mjs';
 export { runsPrefixInside, worktreeSnapshot } from './runner/git-state.mjs';
@@ -88,18 +89,20 @@ export function installRunnerCrashBoundary() {
           `Log: codex-bridge read ${currentRun}`,
         ]);
         emitReply(reply);
-        process.exit(1);
+        process.exit(EXIT.FAIL);
       } catch {
         // Falls through to the bare reply below: the disk itself is not cooperating.
       }
     }
     emitReply(
       [
-        `FAIL — Codex runner crashed before creating the run folder: ${String(err.message).replace(/\s+/g, ' ').slice(0, 150)}`,
+        `FAIL — Codex runner crashed before creating the run folder: ${
+          String(err.message).replace(/\s+/g, ' ').slice(0, 150)
+        }`,
         'No artifacts; nothing to inspect',
       ].join('\n'),
     );
-    process.exit(1);
+    process.exit(EXIT.FAIL);
   });
 }
 

package/src/home/lib/runner/advise-carry.mjs

@@ -1,4 +1,5 @@
 /** Owns the scope snapshot shared by advise readers because run 2026-09-23_141341_plan59-a1-stdin-hang left them with different inputs. */
+import { EXIT } from './exit-codes.mjs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { parseAdvisorTask } from '../meta/advisor-task.mjs';
@@ -32,7 +33,7 @@ export function advisorTaskOrRefuse(input) {
   try {
     return advisorTaskArtifact(input);
   } catch (error) {
-    return die(`${error.message} The run folder was not created; quota was not spent.`, 1);
+    return die(`${error.message} The run folder was not created; quota was not spent.`, EXIT.FAIL);
   }
 }
 

package/src/home/lib/runner/args.mjs

@@ -5,24 +5,26 @@
  * else's quota is touched, and every refusal is an exit code rather than a message: a
  * dispatcher branches on it.
  */
+import { EXIT } from './exit-codes.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { isAbsoluteTaskFilePath, requiredInputsFor } from '../required-inputs.mjs';
 import { firstShellUnsafeSequence } from '../shell-unsafe.mjs';
 import { parseTaskDocument } from './task-file.mjs';
+import { parseTaskHeader, taskHeaderRefusal } from '../task-header.mjs';
 
 export class RunnerUsageError extends Error {
   // 2 says the order itself is wrong and has to be rewritten. A refusal about the state of the
   // host or the worktree passes 1: the order was fine, nothing about it needs changing, and
   // Plan_58 moved two such refusals here from a code path that already answered 1.
-  constructor(message, exitCode = 2) {
+  constructor(message, exitCode = EXIT.USAGE) {
     super(message);
     this.exitCode = exitCode;
   }
 }
 
-export function die(message, exitCode = 2) {
+export function die(message, exitCode = EXIT.USAGE) {
   console.error(`run-codex: ${message}`);
   throw new RunnerUsageError(message, exitCode);
 }
@@ -46,9 +48,14 @@ export function readTaskDocument(opts) {
       die(`task file from --task-file could not be read: ${err.message}`);
     }
     if (!fileText.trim()) die(`task file from --task-file is empty: ${taskFile}`);
+    // Plan_75 D5, 2026-10-03 20:42: validate raw metadata before sections can hide a grant.
+    const parsed = parseTaskHeader(fileText);
+    const refusal = taskHeaderRefusal(parsed);
+    if (refusal) die(`${taskFile}: ${refusal}`);
+    if (!parsed.body.trim()) die(`task file from --task-file is empty: ${taskFile}`);
     let document;
     try {
-      document = parseTaskDocument(fileText);
+      document = parseTaskDocument(parsed.body);
     } catch (err) {
       die(`${taskFile}: ${err.message}`);
     }
@@ -58,11 +65,15 @@ export function readTaskDocument(opts) {
     if (document.verify !== undefined && opts.verify !== undefined) {
       die('verification command was supplied through both --verify and the task file; choose exactly one channel');
     }
-    return document;
+    return { ...document, header: parsed };
   }
   if (!stdinText.trim()) die('task text on stdin is empty');
+  const parsed = parseTaskHeader(stdinText);
+  const refusal = taskHeaderRefusal(parsed);
+  if (refusal) die(refusal);
+  if (!parsed.body.trim()) die('task text on stdin is empty');
   try {
-    return parseTaskDocument(stdinText);
+    return { ...parseTaskDocument(parsed.body), header: parsed };
   } catch (err) {
     die(err.message);
   }

package/src/home/lib/runner/attach.mjs

@@ -1,12 +1,13 @@
 /** Finds a live run for an order and waits for its verdict when a repeated launcher call attaches. */
+import { EXIT } from './exit-codes.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { workerMayBeAlive } from '../meta/run-liveness.mjs';
 import { processAlive } from '../process-identity.mjs';
 import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
-import { sameRun } from './continuation.mjs';
-import { conflictingOrderOwner, runsForOrder } from './order-owner.mjs';
+import { readyGrantLines, sameRun } from './continuation.mjs';
+import { conflictingOrderOwner, orderOwnerConflictText, runsForOrder } from './order-owner.mjs';
 
 // The attach call is the only process that waits for a worker it did not spawn. Keeping that
 // wait here leaves the launcher free to return before a caller's time ceiling kills it.
@@ -97,26 +98,26 @@ export async function waitForReply(runDir, workerPid, status) {
  * reason. `--continue` may attach to a run created from its grant: the 2026-09-23 dispatcher
  * incident showed that repeating the identical continuation command must return to that run.
  */
-export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, grantRun, isContinue, noWait } = {}) {
+export async function attach({
+  runsRoot, repo, slug, taskHash, orderId, chain, grantRun, retryRun, isContinue, noWait, beforeWait,
+} = {}) {
   const runs = chain || chainRuns(runsRoot, repo, slug, taskHash, orderId);
   const runRecords = runs
     .map((run) => ({ run, status: readJsonFile(path.join(runsRoot, run, 'status.json')) }))
     .filter(({ status }) => status);
   const sameOrder = runsForOrder(runRecords, orderId);
   const attachRuns = isContinue
-    ? sameOrder.filter(({ status }) => grantRun && status.continued_from && sameRun(runsRoot, status.continued_from, grantRun))
+    ? sameOrder.filter(({ status }) => retryRun
+      ? status.retry_of && sameRun(runsRoot, status.retry_of, retryRun)
+      : grantRun && status.continued_from && sameRun(runsRoot, status.continued_from, grantRun))
     : sameOrder;
   if (isContinue && !attachRuns.length) return null;
 
   const owner = isContinue ? null : conflictingOrderOwner(runRecords, orderId, taskHash);
   if (owner) {
     const ownerDir = path.join(runsRoot, owner.run);
-    console.log(
-      `Order id collision: ${JSON.stringify(String(orderId ?? ''))} already belongs to run folder ${ownerDir} ` +
-        `(slug ${owner.status.slug}, started_at ${owner.status.started_at}) with a different task. ` +
-        'Pass a new --order-id, or pass --continue if this really is another pass of the same order.',
-    );
-    return 2;
+    console.log(orderOwnerConflictText(owner, ownerDir, orderId));
+    return EXIT.USAGE;
   }
 
   // The run an order is currently about is its newest one, and the chain arrives oldest first.
@@ -130,7 +131,12 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
     if (fs.existsSync(path.join(dir, 'reply.txt'))) {
       announceSavedReply(dir, orderId, entry.status.started_at);
       console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
-      return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
+      const meta = readJsonFile(path.join(dir, 'meta.json'));
+      // Plan_75 D1, 2026-10-03 TradeForge: a cached failure must name its current repair.
+      if (meta?.status !== 'OK' && entry.run === runs.at(-1)) {
+        console.log(readyGrantLines(runsRoot, runs));
+      }
+      return exitCodeFor(meta?.status);
     }
     if (workerMayBeAlive({ runDir: dir, status: entry.status })) {
       candidate = entry;
@@ -140,7 +146,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
   if (!candidate) {
     if (!noWait) return null;
     console.log(`No run exists for order id ${JSON.stringify(String(orderId ?? ''))}; --no-wait never starts a new run.`);
-    return 4;
+    return EXIT.PENDING;
   }
 
   const runDir = path.join(runsRoot, candidate.run);
@@ -148,8 +154,9 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
   // A distinct call outcome lets the dispatcher inspect disk without mistaking pending for failure.
   if (noWait) {
     announcePending(runDir, orderId, candidate.status.started_at);
-    return 4;
+    return EXIT.PENDING;
   }
+  await beforeWait?.();
   announceLiveAttach(runDir, orderId, candidate.status.started_at);
   const replyText = await waitForReply(runDir, candidate.status.pid, candidate.status);
   if (replyText !== null) {
@@ -174,5 +181,5 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
     'Any Codex changes remain in the tree — check them with git status',
   ]);
   console.log(reply);
-  return 1;
+  return EXIT.FAIL;
 }

package/src/home/lib/runner/build-evidence.mjs

@@ -0,0 +1,29 @@
+/**
+ * Writes the evidence a build run leaves of the tree before and after it.
+ * The before half was written by the launcher and the after half by the worker, so one artifact pair was
+ * named in two files; Plan_60 D3a adds a content baseline and its comparison to both halves.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, headSha, branchName, worktreeSnapshot } from './git-state.mjs';
+import { captureFlagBaseline } from './flag-baseline.mjs';
+import { scanRunFlags } from './flag-scan.mjs';
+
+export function writeBuildBefore({ runDir, repoRoot, isGitRepo }) {
+  fs.writeFileSync(path.join(runDir, 'head-before.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'branch-before.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'git-before.txt'), git(repoRoot, ['-c', 'core.quotepath=false', 'status', '--porcelain']).stdout || '');
+  fs.writeFileSync(path.join(runDir, 'state-before.txt'), worktreeSnapshot(repoRoot));
+  captureFlagBaseline({ runDir, repoRoot, isGitRepo });
+}
+
+export function writeBuildAfter({ runDir, repoRoot, isGitRepo }) {
+  fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'branch-after.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'git-after.txt'), git(repoRoot, ['-c', 'core.quotepath=false', 'status', '--porcelain']).stdout || '');
+  fs.writeFileSync(path.join(runDir, 'state-after.txt'), worktreeSnapshot(repoRoot));
+  fs.writeFileSync(path.join(runDir, 'diff.stat'), git(repoRoot, ['-c', 'core.quotepath=false', 'diff', '--stat']).stdout || '');
+  const scan = scanRunFlags({ runDir, repoRoot });
+  fs.writeFileSync(path.join(runDir, 'flags.txt'), scan.text);
+  fs.writeFileSync(path.join(runDir, 'flags-coverage.txt'), scan.coverage.gaps.map((gap) => `${gap}\n`).join(''));
+}

package/src/home/lib/runner/codex-availability.mjs

@@ -0,0 +1,50 @@
+/**
+ * Decides from conclusive evidence only whether Codex is missing, signed out, available, or cannot be judged.
+ * Plan_60 D2: an inconclusive probe must never become "do not retry".
+ */
+import { resolveCommandOnPath } from '../command-path.mjs';
+import { codexSpawnSpec, spawnCaptured } from './codex-cmd.mjs';
+
+// A signed-in answer takes ~200 ms; ten seconds bounds a hung CLI without delaying a healthy start.
+export const PROBE_TIMEOUT_MS = 10_000;
+
+function lines(text) {
+  return String(text ?? '').split(/[\r\n]+/).map((line) => line.trim()).filter(Boolean);
+}
+
+function failureDetail(result, command) {
+  return lines(result.stderr).at(-1)
+    || lines(result.error?.message).at(-1)
+    || `${command} exited ${result.status}`;
+}
+
+export async function probeCodexAvailability({
+  env = process.env, platform = process.platform,
+  run = spawnCaptured, resolve = resolveCommandOnPath, timeoutMs = PROBE_TIMEOUT_MS,
+} = {}) {
+  try {
+    if (resolve('codex', env) === null) {
+      return { state: 'missing', detail: 'codex is not on PATH' };
+    }
+    const capture = (args) => {
+      const spec = codexSpawnSpec(args, platform);
+      return run(spec.command, spec.args, { ...spec.options, env, timeout: timeoutMs, encoding: 'utf8' });
+    };
+    const version = await capture(['--version']);
+    if (version.error || version.status !== 0) {
+      return { state: 'inconclusive', detail: failureDetail(version, 'codex --version') };
+    }
+    const login = await capture(['login', 'status']);
+    // Plan_60 D2: capture errors invalidate even a familiar line; only a completed probe proves sign-out.
+    if (login.error) {
+      return { state: 'inconclusive', detail: failureDetail(login, 'codex login status') };
+    }
+    if (login.status === 0) return { state: 'available' };
+    if (login.status === 1 && [...lines(login.stderr), ...lines(login.stdout)].includes('Not logged in')) {
+      return { state: 'logged-out', detail: 'codex login status: Not logged in' };
+    }
+    return { state: 'inconclusive', detail: failureDetail(login, 'codex login status') };
+  } catch (error) {
+    return { state: 'inconclusive', detail: lines(error?.message).at(-1) || 'codex availability probe failed' };
+  }
+}

package/src/home/lib/runner/codex-cmd.mjs

@@ -1,6 +1,6 @@
 /**
- * Invoking the `codex` CLI: starting it, stopping its whole tree, telling whether it is there at
- * all, and keeping its JSONL stdout in events.jsonl while stderr stays separate.
+ * Invoking the `codex` CLI: starting it, stopping its whole tree, and keeping its JSONL stdout
+ * in events.jsonl while stderr stays separate. Availability belongs to codex-availability.mjs.
  *
  * Which flags a run gets is the neighbouring codex-args.mjs: this file starts the process and
  * stops it, and knows nothing about what the arguments mean. The two were one module until it
@@ -336,20 +336,3 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes, graceMs = ST
     child.on('close', (code) => finish(code, true));
   });
 }
-
-/**
- * Codex missing or not authorised is a deterministic FAIL, never a reason to improvise.
- * Plan_58, 2026-09-19: return a reason for refusal before registration, like the dead-sandbox
- * probe. One no-quota question must not have two answers about whether it leaves a folder.
- */
-export function codexUnavailableReason() {
-  const probe = spawnSync(
-    process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex',
-    process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'],
-    { encoding: 'utf8', windowsHide: true },
-  );
-  if (probe.error || probe.status !== 0) {
-    return (probe.stderr || probe.error?.message || 'codex --version is not responding').trim();
-  }
-  return null;
-}

package/src/home/lib/runner/continuation.mjs

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CONTINUATION_INPUT, parseContinuationGrant } from '../required-inputs.mjs';
 import { readJson } from '../write-meta.mjs';
+import { workerMayBeAlive } from '../meta/run-liveness.mjs';
 
 // One comparison of run names for the grant gate and for attach, so a repeat and a grant can never
 // disagree about whether two spellings name the same folder.
@@ -48,7 +49,20 @@ function lastRunOutcome(runsRootPath, chain) {
   const meta = readJson(path.join(runsRootPath, run, 'meta.json')) || {};
   const outcomeStatus = String(meta.status ?? status.status ?? status.state ?? 'unknown').trim() || 'unknown';
   const outcomeReason = String(meta.reason ?? status.reason ?? 'reason not recorded').trim() || 'reason not recorded';
-  return { run, status: outcomeStatus, reason: outcomeReason };
+  return { run, status: outcomeStatus, reason: outcomeReason, verdict: meta.status, orderId: status.order_id };
+}
+
+export function readyGrantLines(runsRootPath, chain, grantReason) {
+  const last = lastRunOutcome(runsRootPath, chain);
+  if (!last) return 'Ready grant line: none (there is no run to continue).';
+  const reason = String(grantReason ?? last.reason).trim() || last.reason;
+  const continuation = `Ready grant line: continue: ${last.run} — ${reason}.`;
+  // Plan_75 D1: the TradeForge failed advise spent its continuation, so show the same-pass repair.
+  // A run without order_id cannot be retried (retryRefusal step d), so it gets no retry line.
+  const orderId = String(last.orderId ?? '').trim();
+  if (!last.verdict || last.verdict === 'OK' || !orderId) return continuation;
+  return continuation +
+    ` Ready retry line: retry: ${last.run} — ${last.reason} (repeats that pass under order ${orderId}).`;
 }
 
 function lastRunHints(runsRootPath, chain, grantReason) {
@@ -56,9 +70,8 @@ function lastRunHints(runsRootPath, chain, grantReason) {
   if (!last) {
     return 'Last run: none. Outcome: none. Ready grant line: none (there is no run to continue).';
   }
-  const reason = String(grantReason ?? last.reason).trim() || last.reason;
   return `Last run: ${last.run}. Outcome: ${last.status} — ${last.reason}. ` +
-    `Ready grant line: continue: ${last.run} — ${reason}.`;
+    readyGrantLines(runsRootPath, chain, grantReason);
 }
 
 /**
@@ -86,6 +99,7 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
   if (!continuation) {
     return (
       '--continue is refused: the orchestrator did not provide a `continue:` grant in the task text. ' +
+      `${lastRunHints(runsRootPath, chain)} ` +
       `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
     );
   }
@@ -109,19 +123,23 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
       `--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.`
+      `state is used. ${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${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,
-  );
+  // Plan_75 D1, TradeForge capacity incident: a retry spends no new pass, even after an OK verdict.
+  const ofThisOrder = chain.filter((run) => {
+    const status = readJson(path.join(runsRootPath, run, 'status.json'));
+    return String(status?.order_id ?? '').trim() === wanted && !String(status?.retry_of ?? '').trim();
+  });
   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}. ` +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
       'A further pass needs a new order id from the orchestrator. The run folder was not ' +
       'created; quota was not spent.'
     );
@@ -132,9 +150,43 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
   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 ' +
+      'be editing the worktree. Repeat without --continue to attach to it. ' +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} The run folder was ` +
       'not created; quota was not spent.'
     );
   }
   return null;
 }
+
+export function retryRefusal(runsRootPath, chain, isContinue, orderId, grant, liveness = workerMayBeAlive) {
+  const refuse = (message) => `${message} The run folder was not created; quota was not spent.`;
+  if (!isContinue) {
+    return refuse('--continue is required for a `retry:` grant: the orchestrator deliberately repeats the same pass.');
+  }
+  const runDir = namedRunDirectory(runsRootPath, grant?.run);
+  if (!runDir) {
+    return refuse(`Retry is refused: ${grant?.run || 'none'} is not a bare existing run folder in ${runsRootPath}.`);
+  }
+  const last = chain[chain.length - 1];
+  // Plan_75 D1: appending the TradeForge retry makes this grant single-use without a new counter.
+  if (!last || !sameRun(runsRootPath, grant.run, last)) {
+    return refuse(`Retry is refused: grant ${grant.run} is not the LAST run of this task's chain; a retry is single-use.`);
+  }
+  const status = readJson(path.join(runDir, 'status.json'));
+  const wanted = String(orderId ?? '').trim();
+  const previousOrder = String(status?.order_id ?? '').trim();
+  if (!previousOrder || previousOrder !== wanted) {
+    return refuse(`Retry is refused: run ${grant.run} order_id ${previousOrder || '(missing)'} differs from order ${wanted}. ` +
+      'A retry repeats its own order; a run without order_id predates orders — start a new order.');
+  }
+  const meta = readJson(path.join(runDir, 'meta.json'));
+  // Plan_75 D1: a verdict alone must not let a retry overlap the failed advise's live writer.
+  if (!meta?.status || liveness({ runDir, status })) {
+    return refuse(`Retry is refused: run ${grant.run} has no finished verdict or its worker may still be alive and writing. ` +
+      'Repeat without --continue to attach to it.');
+  }
+  if (meta.status === 'OK') {
+    return refuse(`Retry is refused: run ${grant.run} ended OK. A retry repeats a failed pass; use continue: for the next pass.`);
+  }
+  return null;
+}

package/src/home/lib/runner/exit-codes.mjs

@@ -0,0 +1,13 @@
+/**
+ * Owns every exit code the runner returns.
+ * Plan_60 D2a: a new status took code 4, already the released --no-wait outcome, because the codes
+ * were literals scattered over six modules.
+ */
+export const EXIT = Object.freeze({
+  OK: 0,          // the run's artifacts confirm the contract
+  FAIL: 1,        // the run failed, or a pre-flight refusal: the order was right, the host or tree was not
+  USAGE: 2,       // argument error: the order itself must be rewritten
+  LIMIT: 3,       // ChatGPT quota exhausted; not a task failure
+  PENDING: 4,     // --no-wait only: the run is still in progress, or no run exists (a call outcome, not a status)
+  UNAVAILABLE: 5, // Codex missing or signed out; hand the task to the next executor
+});