@lyupro/codex-bridge 0.6.2 → 0.6.5

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

@@ -2,8 +2,7 @@
  * Renders the reply lines a dispatcher is allowed to return, one format per agent.
  *
  * AGENTS adds reply strategies to the shared agent registry: for each one it describes how
- * to tell the result file is filled in and which of the three reply strategies below
- * renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
+ * to tell the result file is filled in and which reply strategy below renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
  * produced nothing has nothing agent-specific left to say.
  *
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
@@ -12,7 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS as AGENT_DEFINITIONS } from '../agents.mjs';
-import { changedPaths, line, readJson, readText } from './paths.mjs';
+import { changedPaths, line, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
 import { scoutCoverage } from './verdict.mjs';
 
@@ -25,27 +24,6 @@ const runChanges = (runDir) =>
 
 const readCommand = (runDir) => `codex-bridge read ${runDir}`;
 
-function formatBytes(bytes) {
-  const units = ['B', 'KB', 'MB', 'GB'];
-  let value = bytes;
-  let index = 0;
-  while (value >= 1024 && index < units.length - 1) {
-    value /= 1024;
-    index += 1;
-  }
-  return `${value.toFixed(1)} ${units[index]}`;
-}
-
-function retentionReply(runDir) {
-  const retention = readJson(path.join(runDir, 'status.json'))?.retention;
-  const bytes = Number(retention?.bytes_freed);
-  const runs = Number(retention?.runs);
-  const days = Number(retention?.days);
-  if (!Number.isFinite(bytes) || bytes <= 0 || !Number.isFinite(runs) || runs <= 0
-    || !Number.isFinite(days) || days <= 0) return null;
-  return `Retention: freed ${formatBytes(bytes)} from ${runs} runs older than ${days} days`;
-}
-
 export const AGENTS = {
   'codex-scout': {
     ...AGENT_DEFINITIONS['codex-scout'],
@@ -62,6 +40,12 @@ export const AGENTS = {
     filled: (r) => Boolean(String(r?.verdict || '').trim()),
     reply: reviewReply,
   },
+  // Plan_59 D4: one result file, two contracts. Either phase's decisive field proves it is filled.
+  'codex-advisor': {
+    ...AGENT_DEFINITIONS['codex-advisor'],
+    filled: (r) => typeof r?.sufficient === 'boolean' || Boolean(String(r?.recommendation?.option_id || '').trim()),
+    reply: advisorReply,
+  },
 };
 
 function scoutReply(ctx) {
@@ -69,14 +53,12 @@ function scoutReply(ctx) {
   const top = (r.findings || [])[0];
   const unknowns = (r.unknowns || []).filter(Boolean);
   const coverage = scoutCoverage(ctx.runDir, r);
-  const retention = retentionReply(ctx.runDir);
   return [
     `OK — ${line(r.answer, 160)}`,
     // Any explicit question gets a coverage line, including a valid one-question order.
     ...(coverage ? [`Coverage: ${coverage}`] : []),
     `Key finding: ${top ? `${line(top.fact, 130)} (${line(top.where, 60)})` : 'no findings listed'}`,
     `Unresolved: ${unknowns.length ? line(unknowns.join('; '), 160) : 'none'}`,
-    ...(retention ? [retention] : []),
     `Report: ${ctx.file('report.md')} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
@@ -107,7 +89,6 @@ function buildReply(ctx) {
   const files = ctx.carried
     ? `${paths ? `${paths} · ` : ''}changes were made by an earlier run of this task`
     : paths || 'worktree untouched';
-  const retention = retentionReply(ctx.runDir);
   return [
     `OK — ${line(r.summary, 300)}`,
     `Files: ${touchedPaths.length} changed · ${files}`,
@@ -118,7 +99,6 @@ function buildReply(ctx) {
       : []),
     `Verification: ${verify} — ${verdict}`,
     `Flags: ${flags.length ? `${flags.length} TODO/skip — ${line(flags.slice(0, 3).join(' | '), 140)}` : 'none'}`,
-    ...(retention ? [retention] : []),
     `Report: ${ctx.file('report.md')} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
@@ -130,16 +110,48 @@ function reviewReply(ctx) {
     if (counts[f.severity] !== undefined) counts[f.severity] += 1;
   });
   const top = (r.findings || []).find((f) => f.severity === 'critical' || f.severity === 'high');
-  const retention = retentionReply(ctx.runDir);
   return [
     `OK — verdict ${line(r.verdict, 40)}`,
     `Findings: critical ${counts.critical} · high ${counts.high} · medium ${counts.medium} · low ${counts.low}`,
     `Top: ${top ? `${top.severity} ${line(top.file, 80)}:${top.line_start} — ${line(top.title, 90)}` : 'no critical or high findings'}`,
-    ...(retention ? [retention] : []),
     `Report: ${ctx.file(path.basename(ctx.resultPath))} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
 
+/**
+ * Plan_59 D4: an insufficient scope is an OK run with a named outcome, not a LIMIT — the first
+ * word stays the status, and the outcome that decides the orchestrator's next step is the first
+ * thing after it, derived from the same fields meta.json records.
+ */
+function advisorReply(ctx) {
+  const r = ctx.result;
+  const log = `Report: ${ctx.file(path.basename(ctx.resultPath))} · Log: ${readCommand(ctx.runDir)}`;
+  // The result's own shape picks the lines, as it does in `filled`: a run folder missing its phase
+  // record must not send a scope answer into the advise branch and crash the verdict.
+  if (typeof r.sufficient === 'boolean') {
+    const missing = r.missing_paths || [];
+    const risks = r.predicted_risks || [];
+    return [
+      r.sufficient
+        ? 'OK — scope: sufficient; continue this run with --phase advise'
+        : `OK — scope: insufficient; ${missing.length} paths named`,
+      ...(missing.length ? [`Missing: ${line(missing.join(', '), 160)}`] : []),
+      `Predicted risks: ${risks.length}${risks[0] ? ` — ${risks[0].id} ${line(risks[0].risk, 120)}` : ''}`,
+      log,
+    ];
+  }
+  const outcomes = r.risk_outcomes || [];
+  const confirmed = outcomes.filter((o) => o.outcome === 'confirmed').length;
+  const rejected = (r.rejected || []).map((o) => `${o.option_id} (${line(o.cost, 60)})`);
+  return [
+    `OK — recommend ${r.recommendation.option_id}: ${line(r.recommendation.text, 200)}`,
+    `Rejected: ${rejected.length ? line(rejected.join('; '), 180) : 'none'}`,
+    `Counter: ${line(r.strongest_counterargument, 180)}`,
+    `Risks: ${confirmed} confirmed · ${outcomes.length - confirmed} refuted · open questions ${(r.open_questions || []).length} · confidence ${r.confidence}`,
+    log,
+  ];
+}
+
 /**
  * Which worker actually ran, printed next to the log link.
  *
@@ -168,7 +180,6 @@ export function withProfileRow(rows, meta) {
 }
 
 export function failReply(ctx, meta) {
-  const retention = retentionReply(ctx.runDir);
   return [
     `FAIL — ${line(meta.reason, 170)}`,
     `Artifacts: events.jsonl ${meta.events_bytes} B · stderr.log ${meta.stderr_bytes} B · ${path.basename(ctx.resultPath)} ${meta.result_ok ? 'filled' : 'empty or missing'} · exit=${meta.exit}`,
@@ -177,7 +188,6 @@ export function failReply(ctx, meta) {
     // and the orchestrator has to know whether there is something to revert before it decides
     // anything else.
     ...(ctx.agent === 'codex-build' ? [`Worktree: ${worktreeState(ctx.runDir)}`] : []),
-    ...(retention ? [retention] : []),
     `Log: ${readCommand(ctx.runDir)}`,
   ];
 }
@@ -200,7 +210,6 @@ function worktreeState(runDir) {
 }
 
 export function limitReply(ctx, meta) {
-  const retention = retentionReply(ctx.runDir);
   const rows = [
     'LIMIT — ChatGPT quota exhausted, work not completed',
     `Signal: ${line(meta.reason, 170)}`,
@@ -211,7 +220,6 @@ export function limitReply(ctx, meta) {
       `Worktree: ${touched.length ? `has unfinished changes (${touched.length}), see git-after.txt` : 'no new changes'}`,
     );
   }
-  if (retention) rows.push(retention);
   rows.push(`Log: ${readCommand(ctx.runDir)}`);
   return rows;
 }

package/src/home/lib/meta/run-liveness.mjs

@@ -0,0 +1,64 @@
+/**
+ * Judges whether a recorded run is still live and what state its artifacts support.
+ *
+ * Plan_57 D27 centralizes this rule after reply-guard's bare-pid check mistook a reused
+ * Windows pid for a live run, while the project list printed `running` for a dead run.
+ * Requiring the run folder keeps identity and artifact evidence in every judgment.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { heartbeatAge } from '../heartbeat.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_DEAD,
+  IDENTITY_FOREIGN,
+  IDENTITY_UNVERIFIED,
+  processIdentity,
+} from '../process-identity.mjs';
+import { readJson } from './paths.mjs';
+
+// Fail open: treating an unverified process as dead could close a live run and make
+// markAbandoned a second writer of its meta.json, or let another paid run write into
+// the same tree (the 2026-08-05 incident). Only a known-dead writer permits either.
+function identityMayBeAlive(identity) {
+  return identity === IDENTITY_ALIVE || identity === IDENTITY_UNVERIFIED;
+}
+
+export function runLiveness({ runDir, status, ...identityOptions }) {
+  if (typeof runDir !== 'string' || !runDir.trim()) {
+    throw new TypeError('runLiveness requires a non-empty runDir string');
+  }
+  if (status === undefined) status = readJson(path.join(runDir, 'status.json'));
+  const recordedState = status && typeof status === 'object' && typeof status.state === 'string'
+    ? status.state
+    : null;
+  const heartbeatAgeMs = heartbeatAge(runDir, identityOptions.now);
+  if (recordedState !== 'running') {
+    return { recordedState, identity: null, processMayBeAlive: null, heartbeatAgeMs, state: recordedState };
+  }
+
+  const identity = processIdentity({ runDir, status, ...identityOptions });
+  const processMayBeAlive = identityMayBeAlive(identity);
+  let state = identity === IDENTITY_ALIVE ? 'running' : 'unverified';
+  if (identity === IDENTITY_DEAD || identity === IDENTITY_FOREIGN) {
+    const metaPath = path.join(runDir, 'meta.json');
+    const meta = readJson(metaPath);
+    state = meta ? 'finished' : fs.existsSync(metaPath) ? 'unverified' : 'abandoned';
+  }
+  return { recordedState, identity, processMayBeAlive, heartbeatAgeMs, state };
+}
+
+/**
+ * D28: a worker can still be writing reply.txt after status.json records finished.
+ * This is for waiting on that worker during the closing window, not deciding the
+ * record's state; runLiveness preserves already-closed records without probing.
+ * @returns {boolean} Whether the recorded worker may still be alive, regardless of status.state.
+ */
+export function workerMayBeAlive({ runDir, status, ...identityOptions }) {
+  if (typeof runDir !== 'string' || !runDir.trim()) {
+    throw new TypeError('workerMayBeAlive requires a non-empty runDir string');
+  }
+  if (status === undefined) status = readJson(path.join(runDir, 'status.json'));
+  if (!status || typeof status !== 'object') return false;
+  return identityMayBeAlive(processIdentity({ runDir, status, ...identityOptions }));
+}

package/src/home/lib/meta/run-state.mjs

@@ -10,22 +10,25 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { changedPaths, line, normalizePath, readJson, readText, size } from './paths.mjs';
-import {
-  IDENTITY_ALIVE,
-  IDENTITY_UNVERIFIED,
-  processIdentity,
-} from '../process-identity.mjs';
+import { withLaunchRows } from './launch-rows.mjs';
+import { runLiveness } from './run-liveness.mjs';
 
 /**
- * Is this pid still running for this run? Unknown identity remains live here: treating an
- * unverified process as dead would mark a live run abandoned, and readers must fail open.
+ * Run state on disk, merged over whatever is already there. A killed runner leaves no
+ * report and no meta.json, and four abandoned folders from one order were indistinguishable
+ * from four runs still working — status.json is what makes that difference visible.
+ *
+ * It writes status.json and nothing else. Housekeeping facts such as `retention` live here and
+ * are read from here; an earlier attempt also appended them to meta.json, which would have made
+ * two functions write the same artifact and put the documented artifact order (meta.json before
+ * status.json is closed) at the mercy of whoever ran last.
  */
-const isAliveIdentity = (identity) => identity === IDENTITY_ALIVE || identity === IDENTITY_UNVERIFIED;
-
-const pidAlive = (pid, runDir, status = {}) => {
-  const identity = processIdentity({ runDir, status: { ...status, pid } });
-  return isAliveIdentity(identity);
-};
+export function writeStatus(runDir, patch) {
+  const current = readJson(path.join(runDir, 'status.json')) || {};
+  const next = { ...current, ...patch };
+  fs.writeFileSync(path.join(runDir, 'status.json'), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
 
 /**
  * This module deliberately judges by the run's pid identity alone, while hooks/live-runs.mjs also
@@ -43,23 +46,6 @@ const pidAlive = (pid, runDir, status = {}) => {
  * records the verdict — one writer, in the right order.
  */
 
-/**
- * Run state on disk, merged over whatever is already there. A killed runner leaves no
- * report and no meta.json, and four abandoned folders from one order were indistinguishable
- * from four runs still working — status.json is what makes that difference visible.
- *
- * It writes status.json and nothing else. Housekeeping facts such as `retention` live here and
- * are read from here; an earlier attempt also appended them to meta.json, which would have made
- * two functions write the same artifact and put the documented artifact order (meta.json before
- * status.json is closed) at the mercy of whoever ran last.
- */
-export function writeStatus(runDir, patch) {
-  const current = readJson(path.join(runDir, 'status.json')) || {};
-  const next = { ...current, ...patch };
-  fs.writeFileSync(path.join(runDir, 'status.json'), `${JSON.stringify(next, null, 2)}\n`);
-  return next;
-}
-
 /**
  * Closes out runs whose runner died without writing a verdict. Called at the start of every
  * run, so a folder left by a killed dispatcher gets an explicit state instead of reading as
@@ -83,9 +69,12 @@ export function markAbandoned(runsRoot, currentTree) {
     const runDir = path.join(runsRoot, entry.name);
     const status = readJson(path.join(runDir, 'status.json'));
     if (!status || status.state !== 'running') continue;
-    if (pidAlive(status.pid, runDir, status)) continue;
+    const liveness = runLiveness({ runDir, status });
+    if (liveness.state !== 'abandoned' && liveness.state !== 'finished') continue;
     const metaPath = path.join(runDir, 'meta.json');
     const meta = readJson(metaPath);
+    // The judge read meta.json already; this is a second read, and a failure here must still never
+    // turn an existing verdict into an abandoned FAIL (review 2026-09-17, Plan_57 D28).
     if (!meta && fs.existsSync(metaPath)) continue;
     let patch = meta
       ? { state: 'finished', status: meta.status, finished_at: meta.finished_at }
@@ -159,8 +148,8 @@ export function activeRunDetails(runsRoot, repo, agent = 'codex-build') {
     const status = readJson(path.join(runDir, 'status.json'));
     if (!status || status.state !== 'running' || status.agent !== agent) continue;
     if (normalizePath(status.repo) !== wanted) continue;
-    const identity = processIdentity({ runDir, status });
-    if (isAliveIdentity(identity)) return { run: entry.name, identity };
+    const { identity, processMayBeAlive } = runLiveness({ runDir, status });
+    if (processMayBeAlive) return { run: entry.name, identity };
   }
   return null;
 }
@@ -208,6 +197,8 @@ export function abandonedBranchDrift(runsRoot, repo, currentBranch) {
 export function writeFailure(runDir, agent, reason, extraLines = [], preStart = false) {
   const meta = {
     agent,
+    phase: readJson(path.join(runDir, 'worker.json'))?.phase
+      ?? readJson(path.join(runDir, 'status.json'))?.phase ?? null,
     project: path.basename(path.dirname(runDir)),
     run: path.basename(runDir),
     finished_at: new Date().toISOString(),
@@ -230,6 +221,9 @@ export function writeFailure(runDir, agent, reason, extraLines = [], preStart =
     status: 'FAIL',
     finished_at: meta.finished_at,
   });
-  const reply = [`FAIL — ${meta.reason}`, ...extraLines, `Run: ${runDir}`].join('\n');
+  const reply = withLaunchRows(
+    [`FAIL — ${meta.reason}`, ...extraLines, `Run: ${runDir}`],
+    runDir,
+  ).join('\n');
   return { meta, reply };
 }

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

@@ -28,6 +28,7 @@ import { deadlineReason } from './deadline.mjs';
 import { startupGap } from './startup.mjs';
 import { transportGap } from './transport.mjs';
 import { reasonFrom } from './reason.mjs';
+import { adviceGap } from './advice-status.mjs';
 
 // How much prose an answer must carry once coordinates and paths are subtracted. Measured
 // on the scout run of 2026-07-30 that replied with a table of `file.ts:60-79` rows: every
@@ -315,9 +316,26 @@ 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') {
+    // 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) {
+      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);
     if (gap) return { status: 'FAIL', reason: gap };
   }
+  // 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.
+  if (agent === 'codex-advisor') {
+    const gap = adviceGap(runDir, result, eventData);
+    if (gap) return { status: 'FAIL', reason: gap };
+  }
   // Files the task never authorised. Checked before the mismatch below, because a run that
   // did the job AND edited three unrelated files passes reportVersusWork() — one matching
   // path is all it needs — and the unrelated files would go unmentioned. No automatic

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

@@ -80,6 +80,23 @@ export const REQUIRED_INPUTS = Object.freeze({
     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, '\\$&');
@@ -101,6 +118,10 @@ export function isPlaceholder(value) {
   return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
 }
 
+// Plan_59: scope is a real phase value, while it remains a placeholder for existing inputs.
+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, '-')}`;
@@ -141,7 +162,7 @@ export function diagnoseInput(promptText, label) {
   if (candidateLine === undefined) return null;
 
   const value = extractValue(candidateLine, label);
-  if (value !== null && !isPlaceholder(value)) {
+  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` };
     }
@@ -149,7 +170,7 @@ export function diagnoseInput(promptText, label) {
   }
 
   const line = readableDiagnosisLine(candidateLine);
-  if (value !== null && isPlaceholder(value)) {
+  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 {
@@ -195,7 +216,7 @@ export function missingInputs(agentType, promptText) {
   return requiredInputsFor(agentType).filter((entry) => {
     if (entry.conditional) return false;
     const value = extractValue(prompt, entry.label);
-    if (isPlaceholder(value)) return true;
+    if (isInputPlaceholder(value, entry.label)) return true;
     return entry === TASK_FILE_INPUT && !isAbsoluteTaskFilePath(value);
   });
 }
@@ -206,7 +227,7 @@ export function shellUnsafeInputs(agentType, promptText) {
   return requiredInputsFor(agentType).flatMap((entry) => {
     if (entry.conditional) return [];
     const value = extractValue(prompt, entry.label);
-    if (value === null || isPlaceholder(value)) return [];
+    if (value === null || isInputPlaceholder(value, entry.label)) return [];
     const sequence = firstShellUnsafeSequence(value);
     return sequence === null ? [] : [{ entry, sequence }];
   });

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

@@ -6,6 +6,7 @@
  *
  * Options:
  *   --agent     codex-scout | codex-build | codex-review   (required)
+ *   --phase     declared phase name (optional only for a role with just the default phase)
  *   --repo      repository path (default: current directory)
  *   --slug      short run name used in the run folder (default: agent suffix)
  *   --effort    reasoning effort, passed to Codex as given (default: medium)

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

@@ -79,7 +79,11 @@ const state = (config) => [
     return `${key}: ${model}${profile.effort ? ` at ${profile.effort} effort` : ''}`
       + (profile.speed ? ` on ${profile.speed} tier` : '');
   }).join('; ')}`,
-  `budgets: ${ROLES.map((role) => `${role}: ${config.budgets?.[role] ?? DEFAULTS.budgets[role]} minutes`).join('; ')}`,
+  `budgets: ${ROLES.map((role) => {
+    const phases = Object.entries(config.budgets?.[role] ?? DEFAULTS.budgets[role]);
+    return `${role}: ` + (phases.length === 1 ? `${phases[0][1]} minutes`
+      : phases.map(([phase, minutes]) => `${phase}: ${minutes} minutes`).join(', '));
+  }).join('; ')}`,
   `retention: ${config.retention?.enabled ? `on — transport older than ${config.retention.days} days` : 'off — automatic cleanup disabled'}`,
 ];
 

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

@@ -13,15 +13,18 @@ import { firstShellUnsafeSequence } from '../shell-unsafe.mjs';
 import { parseTaskDocument } from './task-file.mjs';
 
 export class RunnerUsageError extends Error {
-  constructor(message) {
+  // 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 = 2;
+    this.exitCode = exitCode;
   }
 }
 
-export function die(message) {
+export function die(message, exitCode = 2) {
   console.error(`run-codex: ${message}`);
-  throw new RunnerUsageError(message);
+  throw new RunnerUsageError(message, exitCode);
 }
 
 export function readTaskDocument(opts) {
@@ -86,6 +89,7 @@ const SHELL_CHECKED_FLAGS = Object.freeze([
   'scope-new',
   'repo',
   'agent',
+  'phase',
   'effort',
   'changeset',
   'task-file',

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

@@ -2,7 +2,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
-import { IDENTITY_DEAD, IDENTITY_FOREIGN, processAlive, processIdentity } from '../process-identity.mjs';
+import { workerMayBeAlive } from '../meta/run-liveness.mjs';
+import { processAlive } from '../process-identity.mjs';
 import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
 import { conflictingOrderOwner, runsForOrder } from './order-owner.mjs';
 
@@ -52,15 +53,6 @@ export const readJsonFile = (file) => {
   }
 };
 
-/**
- * Is this pid still running for this run? Unknown identity remains live so an attach does not
- * declare a worker dead merely because the identity probe was unavailable.
- */
-export const alive = (pid, runDir, status = {}) => {
-  const identity = processIdentity({ runDir, status: { ...status, pid } });
-  return identity !== IDENTITY_DEAD && identity !== IDENTITY_FOREIGN;
-};
-
 /**
  * Blocks until the worker's reply exists, or until the worker is provably gone without one.
  *
@@ -69,9 +61,9 @@ export const alive = (pid, runDir, status = {}) => {
  * probe for the whole length of a 20-minute run. Inside the loop the question is only whether the
  * number is still busy, which signal 0 answers for free.
  */
-export async function waitForReply(runDir, workerPid, status = {}) {
+export async function waitForReply(runDir, workerPid, status) {
   const replyPath = path.join(runDir, 'reply.txt');
-  if (!alive(workerPid, runDir, status)) {
+  if (!workerMayBeAlive({ runDir, status })) {
     return fs.existsSync(replyPath) ? fs.readFileSync(replyPath, 'utf8').replace(/\s+$/, '') : null;
   }
   let pollsSinceDeath = 0;
@@ -136,7 +128,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
       console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
       return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
     }
-    if (alive(entry.status.pid, dir, entry.status)) {
+    if (workerMayBeAlive({ runDir: dir, status: entry.status })) {
       candidate = entry;
       break;
     }

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

@@ -60,14 +60,23 @@ export function runProfile(opts) {
   };
 }
 
+// Plan_57: the preflight must probe the same permissions that the role will request.
+export function sandboxModeFor(agent) {
+  if (agent === 'codex-build') return 'workspace-write';
+  if (agent === 'codex-scout' || agent === 'codex-review' || agent === 'codex-advisor') return 'read-only';
+  throw new Error(`unknown agent for sandbox mode: ${agent}`);
+}
+
 export function codexArgs(opts, runDir, isGitRepo) {
+  const sandboxMode = sandboxModeFor(opts.agent);
   const schema = path.join(runDir, 'schema.json');
   const profile = runProfile(opts);
   const effort = `model_reasoning_effort=${profile.effort}`;
   const modelArgs = profile.model ? ['-m', profile.model] : [];
   // Plan_56 D35: there is no identifier for ordinary speed; an unpinned tier adds no override.
   const speedArgs = profile.speed ? ['-c', `service_tier=${profile.speed}`] : [];
-  if (opts.agent === 'codex-scout') {
+  // Plan_59: advisor uses schema-backed plain exec with the same read-only isolation as scout.
+  if (opts.agent === 'codex-scout' || opts.agent === 'codex-advisor') {
     return [
       'exec',
       '--json',
@@ -80,8 +89,8 @@ export function codexArgs(opts, runDir, isGitRepo) {
       ...platformSandboxArgs(),
       ...modelArgs,
       '--sandbox',
-      'read-only',
-      '--skip-git-repo-check',
+      sandboxMode,
+      ...(opts.agent === 'codex-scout' || !isGitRepo ? ['--skip-git-repo-check'] : []),
       '-C',
       opts.repo,
       '--output-schema',
@@ -105,7 +114,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
       ...platformSandboxArgs(),
       ...modelArgs,
       '--sandbox',
-      'workspace-write',
+      sandboxMode,
       '-C',
       opts.repo,
       ...(isGitRepo ? [] : ['--skip-git-repo-check']),
@@ -139,7 +148,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
     ...platformSandboxArgs(),
     ...modelArgs,
     '--sandbox',
-    'read-only',
+    sandboxMode,
     '-C',
     opts.repo,
     '--output-schema',