@lyupro/codex-bridge 0.6.1 → 0.6.4

package/src/home/hooks/worktree-witness.mjs

@@ -7,13 +7,17 @@
  * split-guard run and made an honest build appear out of scope. This hook compares the live
  * run's recorded git state with the repository after every shell tool and directs the
  * orchestrator to undo any change outside the run's declared scope.
+ * The 2026-09-19 run accused itself of editing its own artifacts: the witness must use
+ * the verdict's snapshot and environment split, not a second definition of changed work.
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { SHELL_TOOLS } from '../lib/hook-definitions.mjs';
 import { parseJsonText } from '../lib/json-file.mjs';
-import { globToRegExp } from '../lib/meta/paths.mjs';
+import { splitRunChanges } from '../lib/meta/environment.mjs';
+import { changedPaths } from '../lib/meta/paths.mjs';
+import { outOfScope } from '../lib/meta/verdict.mjs';
+import { git, worktreeSnapshot } from '../lib/runner/git-state.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
 import { allLiveRuns, normalizePath } from './live-runs.mjs';
 
@@ -28,19 +32,6 @@ function readRequired(file) {
   }
 }
 
-function statusMap(text) {
-  if (typeof text !== 'string') return null;
-  const result = new Map();
-  for (const line of text.split(/\r?\n/).filter(Boolean)) {
-    if (!/^.. /.test(line)) return null;
-    const rawPath = line.slice(3);
-    const file = rawPath.includes(' -> ') ? rawPath.slice(rawPath.lastIndexOf(' -> ') + 4) : rawPath;
-    if (!file.trim()) return null;
-    result.set(file, line.slice(0, 2));
-  }
-  return result;
-}
-
 let input;
 try {
   input = parseJsonText('stdin', fs.readFileSync(0, 'utf8'));
@@ -67,37 +58,26 @@ const owner = liveRuns.find(({ status }) => {
 if (!owner) pass();
 
 const { dir, status } = owner;
-const beforeText = readRequired(path.join(dir, 'git-before.txt'));
+const beforeText = readRequired(path.join(dir, 'state-before.txt'));
 const scopeText = readRequired(path.join(dir, 'scope.txt'));
 if (beforeText === null || scopeText === null) pass();
 
-const before = statusMap(beforeText);
-let allowed;
+let outside;
 try {
+  // changedPaths tolerates malformed rows; a hook must instead fail open on a damaged baseline.
+  if (beforeText.split(/\r?\n/).filter(Boolean).some((row) =>
+    !/^(?:\d+\t\d+|-\t-|U\t\d+)\t\S.*$/.test(row))) pass();
   const patterns = scopeText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   if (!patterns.length) pass();
-  allowed = patterns.map(globToRegExp);
+  // The shared snapshot returns empty output on git errors; do not call that a restored tree.
+  const repository = git(status.repo, ['rev-parse', '--is-inside-work-tree']);
+  if (repository.error || repository.status !== 0 || repository.stdout?.trim() !== 'true') pass();
+  const current = worktreeSnapshot(status.repo);
+  const { work } = splitRunChanges(dir, changedPaths(beforeText, current));
+  outside = outOfScope(work, patterns);
 } catch {
   pass();
 }
-if (!before) pass();
-
-let currentResult;
-try {
-  currentResult = spawnSync('git', ['-C', status.repo, 'status', '--porcelain'], {
-    encoding: 'utf8',
-  });
-} catch {
-  pass();
-}
-if (currentResult.error || currentResult.status !== 0 || typeof currentResult.stdout !== 'string') pass();
-const current = statusMap(currentResult.stdout);
-if (!current) pass();
-
-const changed = [];
-for (const [file, state] of current) if (before.get(file) !== state) changed.push(file);
-for (const file of before.keys()) if (!current.has(file)) changed.push(file);
-const outside = [...new Set(changed)].filter((file) => !allowed.some((pattern) => pattern.test(file)));
 if (!outside.length) pass();
 
 const folder = path.basename(dir);
@@ -105,9 +85,10 @@ const paths = outside.join(', ');
 process.stdout.write(JSON.stringify({
   hookSpecificOutput: {
     hookEventName: 'PostToolUse',
-    additionalContext: `WORKTREE WITNESS — act now: the shell changed paths outside the scope of `
-      + `live run folder ${dir} (agent ${status.agent}, slug ${status.slug}): ${paths}. `
-      + `Revert those paths now, or run codex-bridge stop ${folder} to take the repository back `
+    additionalContext: `WORKTREE WITNESS — the run's own folder, environment paths and gitignored `
+      + `files are already excluded. These are the orchestrator's own edits inside the repository `
+      + `of live run folder ${dir} (agent ${status.agent}, slug ${status.slug}), outside its scope: ${paths}. `
+      + `Act now: revert those paths, or run codex-bridge stop ${folder} to take the repository back `
       + `before making further changes.`,
   },
 }));

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

@@ -157,6 +157,10 @@ export function readEvents(runDir) {
     // not an archived run.
     hasStream: exists,
     hasEvents: events.length > 0,
+    // The 2026-09-16 dead sandbox rejected every command; refused calls never enter the
+    // stream. Only completed items prove execution, including commands with nonzero exits.
+    commands_executed: events.filter((event) =>
+      event.type === 'item.completed' && event.item?.type === 'command_execution').length,
     tokens: accounting.tokens,
     usage: accounting.usage,
     session_id: started ? String(started.thread_id) : null,

package/src/home/lib/meta/launch-rows.mjs

@@ -0,0 +1,45 @@
+/** Reply rows about facts the launcher recorded in status.json before the run began. */
+import path from 'node:path';
+import { line, readJson } from './paths.mjs';
+
+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`;
+}
+
+// Five copies of Retention missed writeFailure(), so both reply assemblers share this point.
+// The 2026-09-16 dead Codex sandbox incident is why the launcher probes the sandbox at all.
+export function launchRows(runDir) {
+  const retention = retentionReply(runDir);
+  const rows = retention ? [retention] : [];
+  const probe = readJson(path.join(runDir, 'status.json'))?.sandbox_probe;
+  if (probe?.outcome === 'inconclusive') {
+    const reason = line(probe.reason, 160) || 'no reason recorded';
+    rows.push(`Sandbox probe: inconclusive — ${reason} The run started without a sandbox check.`);
+  }
+  return rows;
+}
+
+export function withLaunchRows(rows, runDir) {
+  const launch = launchRows(runDir);
+  if (!launch.length) return rows;
+  let at = rows.findIndex((row) => row.includes('Log: '));
+  if (at === -1) at = rows.findIndex((row) => row.startsWith('Run: '));
+  return at === -1 ? [...rows, ...launch] : [...rows.slice(0, at), ...launch, ...rows.slice(at)];
+}

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

@@ -12,7 +12,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 +25,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'],
@@ -69,14 +48,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 +84,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 +94,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,12 +105,10 @@ 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)}`,
   ];
 }
@@ -168,7 +141,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 +149,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 +171,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 +181,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;
 }
@@ -230,6 +219,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

@@ -315,6 +315,17 @@ 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 };
   }

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

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,7 +60,15 @@ 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') 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}`;
@@ -80,7 +88,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
       ...platformSandboxArgs(),
       ...modelArgs,
       '--sandbox',
-      'read-only',
+      sandboxMode,
       '--skip-git-repo-check',
       '-C',
       opts.repo,
@@ -105,7 +113,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
       ...platformSandboxArgs(),
       ...modelArgs,
       '--sandbox',
-      'workspace-write',
+      sandboxMode,
       '-C',
       opts.repo,
       ...(isGitRepo ? [] : ['--skip-git-repo-check']),
@@ -139,7 +147,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
     ...platformSandboxArgs(),
     ...modelArgs,
     '--sandbox',
-    'read-only',
+    sandboxMode,
     '-C',
     opts.repo,
     '--output-schema',