@lyupro/codex-bridge 0.6.9 → 0.6.11

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

@@ -1,220 +1,140 @@
-/**
- * Reads the command line of a run and refuses it before anything is spent.
- *
- * Every check here happens before the run folder exists and before a single token of someone
- * else's quota is touched, and every refusal is an exit code rather than a message: a
- * dispatcher branches on it.
- */
-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';
-
-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) {
-    super(message);
-    this.exitCode = exitCode;
-  }
-}
-
-export function die(message, exitCode = 2) {
-  console.error(`run-codex: ${message}`);
-  throw new RunnerUsageError(message, exitCode);
-}
-
-export function readTaskDocument(opts) {
-  const stdinText = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8');
-  if (opts['task-file'] !== undefined) {
-    if (stdinText.trim()) {
-      die('task text was supplied through both stdin and --task-file; choose exactly one channel');
-    }
-    const taskFile = opts['task-file'];
-    // The 2026-08-15 incident resolved a relative order against the repository cwd and ran an
-    // unrelated task.md. Refuse the supplied value instead of silently selecting another file.
-    if (!isAbsoluteTaskFilePath(taskFile)) {
-      die(`--task-file must be an absolute path; got ${JSON.stringify(taskFile)}`);
-    }
-    let fileText;
-    try {
-      fileText = fs.readFileSync(taskFile, 'utf8');
-    } catch (err) {
-      die(`task file from --task-file could not be read: ${err.message}`);
-    }
-    if (!fileText.trim()) die(`task file from --task-file is empty: ${taskFile}`);
-    let document;
-    try {
-      document = parseTaskDocument(fileText);
-    } catch (err) {
-      die(`${taskFile}: ${err.message}`);
-    }
-    if (document.questions.length && opts.questions?.length) {
-      die('questions were supplied through both --question and the task file; choose exactly one channel');
-    }
-    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;
-  }
-  if (!stdinText.trim()) die('task text on stdin is empty');
-  try {
-    return parseTaskDocument(stdinText);
-  } catch (err) {
-    die(err.message);
-  }
-}
-
-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
-// continue>"`) into a silent opt-in, and a real run started on someone else's quota. A flag
-// whose whole point is that a human decided it must never be switched on by a leftover
-// template.
-const BOOLEAN_FLAGS = new Set(['continue', 'no-wait']);
-const REPEATABLE_FLAGS = new Set(['question']);
-// Plan_42 keeps free text in the task file because these command-line values otherwise disable
-// the host's standing permission before the runner can spend quota.
-const SHELL_CHECKED_FLAGS = Object.freeze([
-  'order-id',
-  'slug',
-  'scope',
-  'scope-new',
-  'repo',
-  'agent',
-  'phase',
-  'effort',
-  'changeset',
-  'task-file',
-]);
-const BOOLEAN_YES = /^(1|true|yes)$/i;
-const BOOLEAN_NO = /^(0|false|no)$/i;
-
-export function parseArgs(argv) {
-  const opts = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const key = argv[i];
-    if (!key.startsWith('--')) die(`unexpected argument: ${key}`);
-    const name = key.slice(2);
-    // Plan_56 D10 requires --changeset: a stale reviewer flag must not silently select uncommitted work.
-    if (name === 'mode') die('unknown flag: --mode; use --changeset instead');
-    const value = argv[i + 1];
-    if (BOOLEAN_FLAGS.has(name)) {
-      if (value !== undefined && !value.startsWith('--')) {
-        if (!BOOLEAN_YES.test(value) && !BOOLEAN_NO.test(value)) {
-          die(
-            `--${name} takes no value, or one of 1/true/yes/0/false/no; got ${JSON.stringify(value)}. ` +
-              'A placeholder left in from the prompt template is not consent.',
-          );
-        }
-        opts[name] = BOOLEAN_YES.test(value);
-        i += 1;
-      } else {
-        opts[name] = true;
-      }
-      continue;
-    }
-    // A flag name where a value belongs means the value was left out: `--question --continue`
-    // otherwise records `--continue` as the question and passes every later check.
-    if (value === undefined || value.startsWith('--')) die(`missing value for ${key}`);
-    if (REPEATABLE_FLAGS.has(name)) {
-      if (!opts.questions) opts.questions = [];
-      opts.questions.push(value);
-      i += 1;
-      continue;
-    }
-    opts[name] = value;
-    i += 1;
-  }
-  for (const name of SHELL_CHECKED_FLAGS) {
-    if (opts[name] === undefined) continue;
-    const sequence = firstShellUnsafeSequence(opts[name]);
-    if (sequence !== null) {
-      die(
-        `--${name} contains forbidden shell sequence ${JSON.stringify(sequence)}; ` +
-          'put free text in the task file and pass only a short command-line value.',
-      );
-    }
-  }
-  if (!opts.agent) die('--agent is required');
-  if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
-  opts.orderId = String(opts['order-id'] ?? '').trim();
-  opts.noWait = Boolean(opts['no-wait']);
-  if (opts.noWait && opts.continue) {
-    die('--no-wait cannot be combined with --continue: checking an existing run must never authorize a new one.');
-  }
-  if (!opts.orderId) {
-    const orderInput = requiredInput(opts.agent, 'order id');
-    die(
-      `--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. ' +
-        `Example: --order-id "${orderInput.example}". Action: get the value from ${orderInput.source}, pass it as --order-id, and retry.`,
-    );
-  }
-  if (opts.agent === 'codex-scout') {
-    // The requirement itself moved to the launcher, which is the first point that has seen both
-    // sources: questions now arrive either as flags or as a section of the task file, and this
-    // check runs before either file or stdin has been read. Only the shape of a supplied flag is
-    // still judged here.
-    if (opts.questions?.some((question) => !String(question).trim())) {
-      die('--question must not be empty for codex-scout; no quota was spent');
-    }
-  }
-  // Left unset when not given, rather than defaulted here: the role's configured profile is
-  // what fills the gap, and a default applied this early would always win over it.
-  // Plan_56 step 3: support belongs to the live catalogue on write and Codex at run start.
-  if (opts.effort !== undefined && (!opts.effort || /\s/.test(opts.effort))) {
-    die(`--effort must be a non-empty single word with no whitespace; got ${JSON.stringify(opts.effort)}`);
-  }
-  opts.repo = path.resolve(opts.repo || process.cwd());
-  const slugSource = opts.slug ? '--slug' : '--order-id';
-  opts.slug = (opts.slug || opts.orderId).replace(/[^A-Za-z0-9._-]+/g, '-');
-  // Plan_29 incident: the generic `build` slug made an honest order inherit a days-old chain;
-  // reject a value with no alphanumeric anchor instead of creating an empty or dot-only folder.
-  if (!/[A-Za-z0-9]/.test(opts.slug)) {
-    die(
-      `${slugSource} produces an unusable run folder name after sanitization: ` +
-        `${JSON.stringify(opts.slug)} must contain a letter or digit.`,
-    );
-  }
-  opts.changeset = opts.changeset || 'uncommitted';
-  // A writing run without a declared scope is how `!Plans/*.md` got edited by a run that was
-  // told in prose not to touch them: prose does not bind, a file list does. Required rather
-  // than defaulted to "everything", and checked here — before the folder exists and before a
-  // single token of someone else's quota is spent.
-  const declaredScopePatterns = String(opts.scope || '')
-    .split(',')
-    .map((p) => p.trim())
-    .filter(Boolean);
-  opts.scopeNewPatterns = String(opts['scope-new'] || '')
-    .split(',')
-    .map((p) => p.trim())
-    .filter(Boolean);
-  // Plan_27 keeps ordinary patterns strict: only paths named explicitly as new may be absent.
-  opts.scopePatterns = [...declaredScopePatterns, ...opts.scopeNewPatterns];
-  // Only the writing agent creates files, so only its scope may name one that does not exist yet.
-  // Accepting the flag elsewhere would hand scout and review a way to waive the check for nothing.
-  if (opts.agent !== 'codex-build' && opts.scopeNewPatterns.length) {
-    die(
-      `--scope-new is only for codex-build: ${opts.agent} does not create files. ` +
-        'Action: drop --scope-new and pass every path through --scope.',
-    );
-  }
-  if (opts.agent === 'codex-build' && !declaredScopePatterns.length) {
-    const scopeInput = requiredInput(opts.agent, 'scope');
-    die(
-      `--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;
-}
+/**
+ * Reads the command line of a run and refuses it before anything is spent.
+ *
+ * Every check here happens before the run folder exists and before a single token of someone
+ * 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 { AGENTS } from '../write-meta.mjs';
+import { isAbsoluteTaskFilePath } from '../order-values.mjs';
+import { firstShellUnsafeSequence } from '../shell-unsafe.mjs';
+import { parseTaskDocument } from './task-file.mjs';
+import { parseTaskHeader, taskHeaderRefusal } from '../task-header.mjs';
+import { renderOrderHeaderHelp } from '../order-schema.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 = EXIT.USAGE) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+export function die(message, exitCode = EXIT.USAGE) {
+  console.error(`run-codex: ${message}`);
+  throw new RunnerUsageError(message, exitCode);
+}
+
+export function readTaskDocument(opts) {
+  const refuse = (message) => die([message, renderOrderHeaderHelp(opts.agent)].filter(Boolean).join('\n'));
+  const stdinText = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8');
+  if (opts['task-file'] !== undefined) {
+    if (stdinText.trim()) {
+      refuse('task text was supplied through both stdin and --task-file; choose exactly one channel');
+    }
+    const taskFile = opts['task-file'];
+    // The 2026-08-15 incident resolved a relative order against the repository cwd and ran an
+    // unrelated task.md. Refuse the supplied value instead of silently selecting another file.
+    if (!isAbsoluteTaskFilePath(taskFile)) {
+      refuse(`--task-file must be an absolute path; got ${JSON.stringify(taskFile)}`);
+    }
+    let fileText;
+    try {
+      fileText = fs.readFileSync(taskFile, 'utf8');
+    } catch (err) {
+      refuse(`task file from --task-file could not be read: ${err.message}`);
+    }
+    if (!fileText.trim()) refuse(`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) refuse(`${taskFile}: ${refusal}`);
+    if (!parsed.body.trim()) refuse(`task file from --task-file is empty: ${taskFile}`);
+    let document;
+    try {
+      document = parseTaskDocument(parsed.body);
+    } catch (err) {
+      refuse(`${taskFile}: ${err.message}`);
+    }
+    return { ...document, header: parsed };
+  }
+  if (!stdinText.trim()) refuse('task text on stdin is empty');
+  const parsed = parseTaskHeader(stdinText);
+  const refusal = taskHeaderRefusal(parsed);
+  if (refusal) refuse(refusal);
+  if (!parsed.body.trim()) refuse('task text on stdin is empty');
+  try {
+    return { ...parseTaskDocument(parsed.body), header: parsed };
+  } catch (err) {
+    refuse(err.message);
+  }
+}
+
+// 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
+// continue>"`) into a silent opt-in, and a real run started on someone else's quota. A flag
+// whose whole point is that a human decided it must never be switched on by a leftover
+// template.
+const BOOLEAN_FLAGS = new Set(['no-wait']);
+// Plan_42 keeps free text in the task file because these command-line values otherwise disable
+// the host's standing permission before the runner can spend quota.
+const SHELL_CHECKED_FLAGS = Object.freeze([
+  'agent',
+  'task-file',
+]);
+const BOOLEAN_YES = /^(1|true|yes)$/i;
+const BOOLEAN_NO = /^(0|false|no)$/i;
+
+export function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    if (!key.startsWith('--')) die(`unexpected argument: ${key}`);
+    const name = key.slice(2);
+    if (!['agent', 'task-file', 'no-wait'].includes(name)) {
+      const agent = opts.agent ?? argv[argv.indexOf('--agent') + 1];
+      const help = Object.hasOwn(AGENTS, agent) ? renderOrderHeaderHelp(agent) : '';
+      die(`unknown flag --${name}: codex-bridge run takes only --agent, --task-file and --no-wait; ` +
+        'the order belongs in the task-file header' + (help ? `\n${help}` : ''));
+    }
+    const value = argv[i + 1];
+    if (BOOLEAN_FLAGS.has(name)) {
+      if (value !== undefined && !value.startsWith('--')) {
+        if (!BOOLEAN_YES.test(value) && !BOOLEAN_NO.test(value)) {
+          die(
+            `--${name} takes no value, or one of 1/true/yes/0/false/no; got ${JSON.stringify(value)}. ` +
+              'A placeholder left in from the prompt template is not consent.',
+          );
+        }
+        opts[name] = BOOLEAN_YES.test(value);
+        i += 1;
+      } else {
+        opts[name] = true;
+      }
+      continue;
+    }
+    // A flag name where a value belongs means the value was left out.
+    if (value === undefined || value.startsWith('--')) die(`missing value for ${key}`);
+    opts[name] = value;
+    i += 1;
+  }
+  for (const name of SHELL_CHECKED_FLAGS) {
+    if (opts[name] === undefined) continue;
+    const sequence = firstShellUnsafeSequence(opts[name]);
+    if (sequence !== null) {
+      die(
+        `--${name} contains forbidden shell sequence ${JSON.stringify(sequence)}; ` +
+          'put free text in the task file and pass only a short command-line value.',
+      );
+    }
+  }
+  if (!opts.agent) die('--agent is required');
+  if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
+  opts.noWait = Boolean(opts['no-wait']);
+  return opts;
+}

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.
@@ -88,39 +89,39 @@ export async function waitForReply(runDir, workerPid, status) {
  * What counts as "not finished yet" is the absence of reply.txt, not the absence of meta.json.
  * The artifact order is meta.json first, reply.txt last, so between the two there is a moment
  * where the verdict exists and the run is not closed — judged by meta.json, a repeat arriving in
- * that window would be refused and sent to the --continue gate instead of being answered. The
+ * that window would be refused and sent to the continuation gate instead of being answered. The
  * promise being kept here is that repeating the command is always safe, and a promise with a
  * window in it is not one. markAbandoned() closes dead runs with FAIL before the gate, so this
  * path only covers a live run that has not recorded a verdict yet.
  *
  * A repeat that arrives after the verdict is answered from disk rather than refused, for the same
- * reason. `--continue` may attach to a run created from its grant: the 2026-09-23 dispatcher
+ * reason. A `continue:` grant may attach to a run created from it: 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.
-  // Reading it from the end is the whole point: `--continue` adds a second run under the same
+  // Reading it from the end is the whole point: a continuation adds a second run under the same
   // order, and while it was in flight a repeat used to be answered by the first run's reply.txt —
   // a stale verdict presented as this pass's answer. Found by the Plan_11-2 checklist, 2026-08-04.
   let candidate = null;
@@ -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;
-}