@lyupro/codex-bridge 0.6.9 → 0.6.11

package/src/home/lib/runner/worker-admission.mjs

@@ -0,0 +1,43 @@
+/**
+ * Admits a worker and records its identity under its order claim before any paid work starts.
+ * Plan_60 D4/D4c, A4 r4: a launcher killed after spawn frees the claim before recording the
+ * detached worker, so a second launcher could abandon its run and start another paid run.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
+import { writeStatus } from '../meta/run-state.mjs';
+import { acquireOrderClaim } from './order-claim.mjs';
+
+export async function admitWorker({ runDir, orderId, timing, platform, createServer }) {
+  const claim = await acquireOrderClaim({
+    projectRunsRoot: path.dirname(runDir),
+    orderId,
+    role: 'worker',
+    ...(timing !== undefined ? { timing } : {}),
+    ...(platform !== undefined ? { platform } : {}),
+    ...(createServer !== undefined ? { createServer } : {}),
+  });
+  try {
+    if (claim.busy) return { admitted: false, reason: 'claim-timeout', holder: claim.holder };
+    let status = null;
+    try {
+      status = readJsonFileSync(path.join(runDir, 'status.json'));
+    } catch {
+      // Plan_60 A4 r4: an unreadable run cannot authorize paid work after a launcher dies.
+    }
+    if (status?.state !== 'running' || fs.existsSync(path.join(runDir, 'meta.json'))) {
+      return { admitted: false, reason: 'closed', state: status?.state ?? null };
+    }
+    // The launcher cannot know this detached process's clock origin; takeover must record the
+    // worker's own identity before it starts producing the run's artifacts.
+    writeStatus(runDir, {
+      pid: process.pid,
+      runner_pid: process.pid,
+      process_started_at: performance.timeOrigin,
+    });
+    return { admitted: true };
+  } finally {
+    await claim.release?.();
+  }
+}

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

@@ -3,7 +3,7 @@
  *
  * It takes its whole order from worker.json, written by launcher.mjs into the run folder —
  * after the split that file is the only connection between the two halves. Read here:
- * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`. Written there: those five plus
+ * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`, `order_id`. Written there: those six plus
  * `phase`, `slug`, `launcher_pid` and `scope_new`, which nothing here needs but a run folder read back
  * months later does. The launcher must write the selected phase's budget into worker.json before
  * spawning this half, so the worker never re-reads config.json and one run cannot acquire two
@@ -13,11 +13,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
-import { collect, exitCodeFor, AGENTS } from '../write-meta.mjs';
+import { collect, exitCodeFor, AGENTS, writeFailure } from '../write-meta.mjs';
 import { writeStatus } from '../meta/run-state.mjs';
 import { setRun, emitReply } from './run-context.mjs';
-import { git, headSha, branchName, worktreeSnapshot, findFakeDone } from './git-state.mjs';
+import { writeBuildAfter } from './build-evidence.mjs';
 import { runCodex } from './codex-cmd.mjs';
+import { admitWorker } from './worker-admission.mjs';
+import { orderClaimHolderText } from './order-claim.mjs';
+import { EXIT } from './exit-codes.mjs';
 
 /**
  * Runs the order in runDir and answers into reply.txt, never to a console — nothing here
@@ -27,13 +30,18 @@ export async function worker(runDir) {
   const cfg = readJsonFileSync(path.join(runDir, 'worker.json'));
   const repoRoot = cfg.repo;
   setRun(runDir, cfg.agent);
-  // The launcher cannot know this detached process's clock origin; takeover must record the
-  // worker's own identity before it starts producing the run's artifacts.
-  writeStatus(runDir, {
-    pid: process.pid,
-    runner_pid: process.pid,
-    process_started_at: performance.timeOrigin,
-  });
+  const admission = await admitWorker({ runDir, orderId: cfg.order_id });
+  if (!admission.admitted) {
+    // Plan_60 A4 r4: a replacement launcher may have closed this run while the worker was starting.
+    if (admission.reason === 'claim-timeout') {
+      const { reply } = writeFailure(
+        runDir, cfg.agent, 'run worker was not admitted: the order claim stayed busy',
+        [`Claim held by ${orderClaimHolderText(admission.holder)}`, 'Codex was not started; quota was not spent'],
+      );
+      emitReply(reply);
+    }
+    process.exit(EXIT.FAIL);
+  }
 
   const run = await runCodex(
     cfg.args,
@@ -52,14 +60,7 @@ export async function worker(runDir) {
     stdio_drained: run.stdioDrained,
   });
 
-  if (cfg.agent === 'codex-build') {
-    fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${cfg.is_git_repo ? headSha(repoRoot) : ''}\n`);
-    fs.writeFileSync(path.join(runDir, 'branch-after.txt'), `${cfg.is_git_repo ? 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 || '');
-    fs.writeFileSync(path.join(runDir, 'flags.txt'), findFakeDone(repoRoot));
-  }
+  if (cfg.agent === 'codex-build') writeBuildAfter({ runDir, repoRoot, isGitRepo: cfg.is_git_repo });
 
   // Human-readable report is carried inside the schema: a read-only scout cannot write
   // files itself, so the runner unpacks it.

package/src/home/lib/subagent-model-env.mjs

@@ -0,0 +1,44 @@
+/** decides whether the host's subagent-model environment overrides a dispatcher's frontmatter pin
+ * Plan_67 D6 (b) and the host documentation facts recorded in its Council (2026-09-25):
+ * env moved below frontmatter in 2.1.251; FORCE=1 overrides it starting with 2.1.257.
+ * Unknown host versions are not evidence for a pre-start refusal.
+ */
+import { modelFamily } from './model-family.mjs';
+
+// Host contract facts, not package versions or volatile model identifiers (Plan_67 D6 (b)).
+export const FRONTMATTER_PRECEDENCE_VERSION = '2.1.251';
+export const SUBAGENT_MODEL_FORCE_VERSION = '2.1.257';
+
+function versionParts(value) {
+  if (typeof value !== 'string' || !/^\d+\.\d+\.\d+(?:\.\d+)*$/.test(value)) return null;
+  return value.split('.').map(BigInt);
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0n) - (right[index] ?? 0n);
+    if (difference !== 0n) return difference < 0n ? -1 : 1;
+  }
+  return 0;
+}
+
+export function envOverridesPin({ env, hostVersion }) {
+  const model = env.CLAUDE_CODE_SUBAGENT_MODEL;
+  if (typeof model !== 'string' || model.length === 0) return false;
+  const version = versionParts(hostVersion);
+  if (version === null) return false;
+  return compareVersions(version, versionParts(FRONTMATTER_PRECEDENCE_VERSION)) < 0
+    || (env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE === '1'
+      && compareVersions(version, versionParts(SUBAGENT_MODEL_FORCE_VERSION)) >= 0);
+}
+
+export function envModelProblem({ env, hostVersion, pinFamily }) {
+  if (!envOverridesPin({ env, hostVersion })) return null;
+  const model = env.CLAUDE_CODE_SUBAGENT_MODEL;
+  const family = modelFamily(model);
+  if (family === null || pinFamily === null || family === pinFamily) return null;
+  return `Order gate denied the Agent call because CLAUDE_CODE_SUBAGENT_MODEL=${JSON.stringify(model)} `
+    + `overrides the installed dispatcher pin ${pinFamily} on host ${hostVersion}. `
+    + `Unset CLAUDE_CODE_SUBAGENT_MODEL or set it to the pinned family ${pinFamily}. `
+    + 'The run folder was not created; quota was not spent.';
+}

package/src/home/lib/task-header.mjs

@@ -0,0 +1,158 @@
+/**
+ * Reads the orchestrator's metadata header at the top of a task file — the one place a grant or an
+ * advice line may stand.
+ *
+ * Plan_75 D5: on 2026-10-03 20:42 wrapped prose in a task file began a line with `continue:`, and
+ * the runner, which looked for grants on any line, refused the order over its own prose. Grants and
+ * advice had two parsers and the task hash a third rule; this module is the single reader, and a
+ * line below the header that still looks like real metadata is refused rather than silently obeyed
+ * or silently ignored.
+ */
+import path from 'node:path';
+import { splitGrantValue } from './order-values.mjs';
+import { ALL_ORDER_LABELS } from './order-schema.mjs';
+
+const BARE_RUN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
+const MISPLACED_GRANT = /^[A-Za-z0-9._-]+(?:$| — | - |:)/;
+
+function validateGrant(value) {
+  const grant = splitGrantValue(value);
+  return grant && BARE_RUN.test(grant.run)
+    ? null
+    : 'grant must name a bare run folder (not . or ..) and a non-placeholder reason';
+}
+
+function descriptor(label, validate, misplaced) {
+  const spellings = [`${label}[ \\t]*[:=]`];
+  for (const wrapper of ['\\*', '_', '`', '\\*\\*', '__']) {
+    spellings.push(`${wrapper}${label}${wrapper}[ \\t]*[:=]`);
+    spellings.push(`${wrapper}${label}[ \\t]*[:=]${wrapper}`);
+  }
+  return Object.freeze({
+    label,
+    validate,
+    misplaced,
+    shape: new RegExp(
+      // Plan_75 D5: try a wrapper before treating its first star as a list marker.
+      `^[ \\t]*(?:[-*][ \\t]*)??(?:${spellings.join('|')})[ \\t]*(.*?)[ \\t]*$`,
+      'i',
+    ),
+    repairHint: `move it into the header at the top of the file, spelled ${label}: <value>; `
+      + 'if it is an example, quote it with > or reword it inside a sentence',
+  });
+}
+
+// Plan_75 D5, 2026-10-03 20:42: one registry prevents wrapped task prose becoming a grant.
+const LABELS = Object.freeze([
+  // Plan_75 D5: empty advice closes the strict header but must still explain the missing value.
+  descriptor('advice', (value) => value.trim() && !/[\r\n]/.test(value)
+    ? null : 'advice value must be non-empty and single line',
+  (value) => !value || /^\S+$/.test(value)
+    || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)),
+  descriptor('continue', validateGrant, (value) => MISPLACED_GRANT.test(value)),
+  descriptor('retry', validateGrant, (value) => MISPLACED_GRANT.test(value)),
+]);
+
+const HEADER_LABELS = Object.freeze([...ALL_ORDER_LABELS, 'advice']);
+const GUARDED_LABELS = Object.freeze(LABELS.map(({ label }) => label));
+const ORDER_ONLY_LABELS = Object.freeze(HEADER_LABELS.filter((label) => !GUARDED_LABELS.includes(label)));
+const HEADER_LINE = new RegExp(`^(${HEADER_LABELS.join('|')}):[ \\t]*(\\S.*?)[ \\t]*$`);
+
+function normalizedHeaderLabel(line) {
+  const colon = line.indexOf(':');
+  if (colon === -1) return null;
+  return line.slice(0, colon).trim().toLowerCase()
+    .replace(/^[-*][ \t]+/, '')
+    .replace(/^[*`_]+|[*`_]+$/g, '')
+    .replace(/[-_]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+export function parseTaskHeader(text) {
+  const lines = text.replace(/^\uFEFF/, '').split(/\r\n|\n|\r/);
+  const fields = {};
+  const entries = [];
+  const problems = [];
+  let headerEnd = 0;
+
+  for (const line of lines) {
+    const match = line.match(HEADER_LINE);
+    if (!match) {
+      // Plan_63 D1/D3: a misspelled or unknown order line must not silently turn into task prose. The
+      // header still closes here (Plan_75 D5), and grant/advice spellings stay with the misplaced guard.
+      const label = normalizedHeaderLabel(line);
+      const rawLabel = line.slice(0, line.indexOf(':')).trim();
+      let reason = null;
+      if (ORDER_ONLY_LABELS.includes(label)) {
+        reason = line.trimEnd() === `${label}:` ? `header label "${label}" has an empty value`
+          : `write the header label exactly as "${label}:"`;
+      } else if (!GUARDED_LABELS.includes(label) && entries.length && /^[a-z][a-z _-]*:[ \t]*\S/.test(line)) {
+        reason = `unknown header label "${rawLabel}"; known labels: ${HEADER_LABELS.join(', ')}`;
+      }
+      if (reason) problems.push({ lineNo: headerEnd + 1, line, reason });
+      break;
+    }
+    const [, label, value] = match;
+    const entry = { label, value, lineNo: headerEnd + 1, line };
+    if (Object.hasOwn(fields, label)) {
+      problems.push({ lineNo: entry.lineNo, line, reason: `duplicate ${label} label` });
+    } else {
+      fields[label] = value;
+    }
+    entries.push(entry);
+    headerEnd++;
+  }
+
+  // Plan_75 D5: conflicting authorization is a label-presence error even if a value is invalid.
+  if (Object.hasOwn(fields, 'continue') && Object.hasOwn(fields, 'retry')) {
+    const conflict = entries.find(({ label }) => label === 'retry');
+    problems.push({
+      lineNo: conflict.lineNo,
+      line: conflict.line,
+      reason: 'continue and retry cannot both be present; keep exactly one grant label',
+    });
+  }
+
+  let grant = null;
+  let advice = null;
+  for (const entry of entries) {
+    const definition = LABELS.find(({ label }) => label === entry.label);
+    if (!definition) continue;
+    const reason = definition.validate(entry.value);
+    if (reason) {
+      problems.push({ lineNo: entry.lineNo, line: entry.line, reason: `${entry.label}: ${reason}` });
+    } else if (entry.value !== fields[entry.label]) {
+      continue;
+    } else if (entry.label === 'advice') {
+      advice ??= entry.value;
+    } else {
+      grant ??= { kind: entry.label, ...splitGrantValue(entry.value) };
+    }
+  }
+
+  // Plan_75 D5, 2026-10-03 20:42: fences are examples, not an escape from the misplaced guard.
+  for (let index = headerEnd; index < lines.length; index++) {
+    for (const definition of LABELS) {
+      const match = lines[index].match(definition.shape);
+      if (!match || !definition.misplaced(match[1])) continue;
+      const reason = match[1] ? `misplaced ${definition.label} metadata`
+        : `${definition.label} value must be non-empty and single line`;
+      problems.push({
+        lineNo: index + 1,
+        line: lines[index],
+        reason: `${reason}; ${definition.repairHint}`,
+      });
+    }
+  }
+
+  problems.sort((a, b) => a.lineNo - b.lineNo);
+  const parsed = { fields, grant, advice, body: lines.slice(headerEnd).join('\n'), problems };
+  // Plan_63 C1: retain source locations for schema diagnostics without changing serialized results.
+  Object.defineProperty(parsed, 'entries', { value: entries });
+  return parsed;
+}
+
+export function taskHeaderRefusal(parsed) {
+  if (!parsed.problems.length) return null;
+  return parsed.problems.map(({ lineNo, line, reason }) => `line ${lineNo}: ${reason}: ${line}`)
+    .concat('The run folder was not created; quota was not spent.').join('\n');
+}

package/src/home/lib/untyped-stop.mjs

@@ -0,0 +1,30 @@
+/** decides whether a subagent stop without agent_type was a Codex dispatcher, from evidence bound to that stop
+ * Plan_67 D9: all 13 missing-type alarms across nine host versions were noise; require evidence
+ * for this stop instead of assuming every untyped subagent is a dispatcher.
+ */
+import { CLI_NAMES } from './cli-names.mjs';
+import { ORDER_AGENTS } from './order-schema.mjs';
+
+export function untypedStopEvidence({ state, toolUses }) {
+  if (state && typeof state === 'object' && !Array.isArray(state) && !state.corrupt
+    && typeof state.agentType === 'string' && ORDER_AGENTS.includes(state.agentType)
+    && Array.isArray(state.seenToolUseIds) && state.seenToolUseIds.length > 0) {
+    return { dispatcher: true, via: 'gate-state', agentType: state.agentType };
+  }
+
+  if (toolUses !== null) {
+    for (const toolUse of toolUses) {
+      if (toolUse?.name !== 'Bash' || typeof toolUse.command !== 'string'
+        || /[;&|`$<>\r\n]/.test(toolUse.command)) continue;
+      const tokens = toolUse.command.trim().split(/\s+/);
+      if (!CLI_NAMES.includes(tokens[0]) || tokens[1] !== 'run') continue;
+      for (let index = 2; index < tokens.length - 1; index += 1) {
+        if (tokens[index] === '--agent' && ORDER_AGENTS.includes(tokens[index + 1])) {
+          return { dispatcher: true, via: 'run-command', runAgent: tokens[index + 1] };
+        }
+      }
+    }
+  }
+
+  return { dispatcher: false, reason: toolUses === null ? 'transcript-unreadable' : 'no-evidence' };
+}

package/src/home/lib/write-meta.mjs

@@ -19,6 +19,7 @@
  * run-state.mjs keeps status.json honest, verdict.mjs decides OK/FAIL/LIMIT, reply.mjs
  * renders the lines. Importers name this file and nothing below it.
  */
+import { EXIT } from './runner/exit-codes.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -28,7 +29,7 @@ import { splitRunChanges } from './meta/environment.mjs';
 import { readEvents } from './meta/events.mjs';
 import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
-import { AGENTS, failReply, limitReply, withProfileRow } from './meta/reply.mjs';
+import { AGENTS, failReply, limitReply, unavailableReply, withProfileRow } from './meta/reply.mjs';
 import { withLaunchRows } from './meta/launch-rows.mjs';
 
 function readRunnerVersion() {
@@ -164,7 +165,13 @@ export function collect(runDir, agent, exitCode) {
   const reply =
     withProfileRow(
       withLaunchRows(
-        status === 'OK' ? cfg.reply(ctx) : status === 'LIMIT' ? limitReply(ctx, meta) : failReply(ctx, meta),
+        status === 'OK'
+          ? cfg.reply(ctx)
+          : status === 'LIMIT'
+            ? limitReply(ctx, meta)
+            : status === 'UNAVAILABLE'
+              ? unavailableReply(ctx, meta)
+              : failReply(ctx, meta),
         runDir,
       ),
       meta,
@@ -173,8 +180,13 @@ export function collect(runDir, agent, exitCode) {
   return { meta, reply: reply.join('\n') };
 }
 
-/** Exit code mirrors the status so an orchestrator can branch without parsing text. */
-export const exitCodeFor = (status) => (status === 'OK' ? 0 : status === 'LIMIT' ? 3 : 1);
+/**
+ * Exit code numbers live in runner/exit-codes.mjs.
+ * USAGE is the launcher's argument error and never comes from here.
+ */
+export const exitCodeFor = (status) =>
+  (status === 'OK' ? EXIT.OK : status === 'LIMIT' ? EXIT.LIMIT :
+    status === 'UNAVAILABLE' ? EXIT.UNAVAILABLE : EXIT.FAIL);
 
 const invokedDirectly =
   process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
@@ -183,7 +195,7 @@ if (invokedDirectly) {
   const [runDir, agent, exitCode] = process.argv.slice(2);
   if (!runDir || !agent) {
     console.error('usage: node write-meta.mjs <runDir> <agent> <exitCode>');
-    process.exit(1);
+    process.exit(EXIT.FAIL);
   }
   const { meta, reply } = collect(runDir, agent, exitCode);
   console.log(reply);

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

@@ -1,261 +0,0 @@
-import path from 'node:path';
-import { firstShellUnsafeSequence } from './shell-unsafe.mjs';
-
-/**
- * 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',
-});
-
-/**
- * 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
- * quoted argument the shell mangles. The orchestrator writes that file with its own file tool,
- * which never crosses the shell at all.
- *
- * It is listed as a required input, not merely explained in the prompt body, because the rendered
- * summary is the ONLY part of this contract the orchestrator ever reads. Left out of the list, a
- * dispatcher that was given no path filled the gap itself: on 2026-08-15 codex-build wrote the file
- * with `cat > … << 'EOF'` and earned exactly the permission window the file was introduced to end.
- * The 2026-08-15 relative-path incident also made the repository cwd silently choose a different
- * task.md, so both the producer gate and runner use this cross-platform absolute-path contract.
- */
-export const TASK_FILE_INPUT = Object.freeze({
-  label: 'task file',
-  source: 'the orchestrator',
-  explanation: 'Absolute path to a file holding the task statement verbatim, written by the orchestrator with its file tool. The dispatcher passes it as --task-file and never creates, reads or rewrites it: writing it from the shell reintroduces the permission prompt this flag exists to remove. Given no path, start the runner without the flag and return its refusal.',
-  example: 'C:/Users/me/AppData/Local/Temp/claude/<session>/scratchpad/task-plan-13.md',
-});
-
-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',
-    },
-    TASK_FILE_INPUT,
-    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/home/lib/runner/**,tests/runner/**',
-    },
-    TASK_FILE_INPUT,
-    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',
-    },
-    TASK_FILE_INPUT,
-    CONTINUATION_INPUT,
-  ]),
-  // Plan_59 D7: the caller must name the phase and authorize the continued decision pass.
-  'codex-advisor': freezeEntries([
-    {
-      label: 'order id',
-      source: 'the orchestrator',
-      explanation: 'The label this design order is known by. Keep the same order id for scope and advise so phase 2 can settle the risks predicted in phase 1.',
-      example: 'plan-59-advisor-20260922',
-    },
-    TASK_FILE_INPUT,
-    CONTINUATION_INPUT,
-    {
-      label: 'phase',
-      source: 'the orchestrator',
-      explanation: 'Pass scope first to predict risks and check the reading boundary, then advise with --continue and a continuation grant naming the scope run of the same order.',
-      example: 'scope',
-    },
-  ]),
-});
-
-const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-function cleanValue(value) {
-  if (typeof value !== 'string') return '';
-  return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
-}
-
-export function isAbsoluteTaskFilePath(value) {
-  const cleaned = cleanValue(value);
-  return path.posix.isAbsolute(cleaned) || path.win32.isAbsolute(cleaned);
-}
-
-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());
-}
-
-// Plan_59: scope is a real phase value, while it remains a placeholder for existing inputs.
-export const isInputPlaceholder = (value, label) =>
-  !(label === 'phase' && cleanValue(value) === 'scope') && isPlaceholder(value);
-
-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]);
-}
-
-const MAX_DIAGNOSIS_LINE_LENGTH = 160;
-
-function readableDiagnosisLine(line) {
-  const trimmed = line.trim();
-  if (trimmed.length <= MAX_DIAGNOSIS_LINE_LENGTH) return trimmed;
-  return `${trimmed.slice(0, MAX_DIAGNOSIS_LINE_LENGTH - 1)}…`;
-}
-
-/** Explains the Plan_28 incident without widening the strict input parser's accepted spellings. */
-export function diagnoseInput(promptText, label) {
-  if (typeof label !== 'string' || !label.trim()) return null;
-  const prompt = typeof promptText === 'string' ? promptText : '';
-  const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
-  const candidatePattern = new RegExp(
-    `^[ \\t]*(?:[-*][ \\t]*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)(?=$|[^A-Za-z0-9_])[^\\r\\n]*`,
-    'i',
-  );
-  const candidateLine = prompt.split(/\r?\n/).find((line) => candidatePattern.test(line));
-  if (candidateLine === undefined) return null;
-
-  const value = extractValue(candidateLine, label);
-  if (value !== null && !isInputPlaceholder(value, label)) {
-    if (label === TASK_FILE_INPUT.label && !isAbsoluteTaskFilePath(value)) {
-      return { line: readableDiagnosisLine(candidateLine), reason: `value \`${value}\` is not an absolute path` };
-    }
-    return null;
-  }
-
-  const line = readableDiagnosisLine(candidateLine);
-  if (value !== null && isInputPlaceholder(value, label)) {
-    const displayedValue = value.trim();
-    if (!displayedValue) return { line, reason: 'value is empty; replace it with a concrete value' };
-    return {
-      line,
-      reason: `value \`${displayedValue}\` is a placeholder; replace it with a concrete value`,
-    };
-  }
-
-  const labelTail = candidateLine.match(
-    new RegExp(`^[ \\t]*(?:[-*][ \\t]*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)([^\\r\\n]*)$`, 'i'),
-  )?.[1] ?? '';
-  if (labelTail.includes(':')) {
-    return { line, reason: `expected \`${label}:\` with nothing between the label and the colon` };
-  }
-  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) {
-  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) => {
-    if (entry.conditional) return false;
-    const value = extractValue(prompt, entry.label);
-    if (isInputPlaceholder(value, entry.label)) return true;
-    return entry === TASK_FILE_INPUT && !isAbsoluteTaskFilePath(value);
-  });
-}
-
-/** Finds labelled command-line values that would disable the host's standing permission. */
-export function shellUnsafeInputs(agentType, promptText) {
-  const prompt = typeof promptText === 'string' ? promptText : '';
-  return requiredInputsFor(agentType).flatMap((entry) => {
-    if (entry.conditional) return [];
-    const value = extractValue(prompt, entry.label);
-    if (value === null || isInputPlaceholder(value, entry.label)) return [];
-    const sequence = firstShellUnsafeSequence(value);
-    return sequence === null ? [] : [{ entry, sequence }];
-  });
-}
-
-/** 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');
-}