@lyupro/codex-bridge 0.3.1 → 0.5.0

package/src/hooks/stop-guard.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { STOP_TOOLS } from '../hook-definitions.mjs';
+import { runsRoot } from '../runner/runs-root.mjs';
+import { renderStopCommand, STOP_REASON } from '../stop-contract.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+import { takeTry } from './guard-tries.mjs';
+
+/**
+ * Plan_31 catches TaskStop killing the dispatcher wrapper while the runner keeps writing. It
+ * must stay silent on malformed input or uncertain liveness, and the second denial budget keeps
+ * an unrelated host task from becoming impossible to stop.
+ */
+
+const pass = () => process.exit(0);
+const isObject = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+function readInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function runForRepository(cwd) {
+  const repository = normalizePath(cwd);
+  if (!repository) return null;
+
+  let live;
+  try {
+    live = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true });
+  } catch {
+    return null;
+  }
+
+  return live
+    .filter(({ status }) => {
+      const runRepository = normalizePath(status.repo);
+      return runRepository === repository || repository.startsWith(`${runRepository}/`);
+    })
+    .sort(({ status: left }, { status: right }) => right.repo.length - left.repo.length)[0] ?? null;
+}
+
+function deny(run) {
+  const runName = path.basename(run.dir);
+  // Key by run folder: the host task_id can belong to an unrelated background build, so it cannot
+  // safely identify the dispatcher this guard just warned about.
+  if (takeTry(normalizePath(run.dir), 'stop', 1) !== 'granted') pass();
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `TaskStop denied: live run ${runName} is working. `
+        + `Use ${renderStopCommand(runName)}. ${STOP_REASON}`,
+    },
+  }));
+}
+
+const input = readInput();
+if (!isObject(input) || !STOP_TOOLS.includes(input.tool_name)) pass();
+if (!isObject(input.tool_input) || typeof input.tool_input.task_id !== 'string' || !input.tool_input.task_id) {
+  pass();
+}
+if (typeof input.cwd !== 'string' || !input.cwd) pass();
+
+const run = runForRepository(input.cwd);
+if (!run) pass();
+deny(run);

package/src/json-file.mjs

@@ -0,0 +1,30 @@
+/**
+ * Reads JSON written by another program and keeps its file boundary in one place.
+ *
+ * Plan_24 records the live Windows incident: PowerShell Out-File -Encoding utf8 wrote a BOM
+ * that Claude Code accepted but JSON.parse rejected. Readers must strip that BOM consistently.
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+function parseJson(file, raw) {
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`cannot parse ${file}: ${error.message}`, { cause: error });
+  }
+}
+
+export async function readJsonFile(file) {
+  return parseJson(file, await fsp.readFile(file, 'utf8'));
+}
+
+export async function readJsonFileWithRaw(file) {
+  const raw = await fsp.readFile(file, 'utf8');
+  return { raw, value: parseJson(file, raw) };
+}
+
+export function readJsonFileSync(file) {
+  return parseJson(file, fs.readFileSync(file, 'utf8'));
+}

package/src/meta/chain.mjs

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { startedRuns } from './pre-start.mjs';
 import { normalizePath, readJson } from './paths.mjs';
 
 /**
@@ -69,15 +70,16 @@ export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '') {
 }
 
 /**
- * The tree as it stood before the task began: state-before.txt of the FIRST run of the
- * chain. The first and not the previous one, because a middle run can end without an
- * "after" snapshot at all — 2026-07-31_114736 wrote eleven files and left neither
- * state-after.txt nor meta.json — and its own "before" is then the last honest base.
- * null when there is no chain or that first run never got a snapshot; an existing but
+ * The tree as it stood before the task began: state-before.txt of the FIRST STARTED run of the
+ * chain. A pre-start folder has no snapshot, so treating it as first made the next pass lose
+ * its baseline in the Plan_23 incident; after that, the first started run is still preferred
+ * over a later one because a middle run can end without an "after" snapshot at all.
+ * null when there is no started run or that first run never got a snapshot; an existing but
  * empty snapshot is a clean tree, which is data, not absence.
  */
 export function chainBaseline(runsRoot, repo, slug, taskHash = '', orderId = '') {
-  const [first] = chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  const chain = chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  const [first] = startedRuns(runsRoot, chain);
   if (!first) return null;
   try {
     return fs.readFileSync(path.join(runsRoot, first, 'state-before.txt'), 'utf8');

package/src/meta/paths.mjs

@@ -4,9 +4,10 @@
  * Two sides spell the same file differently — git prints repo-relative paths with forward
  * slashes, Codex writes whatever it likes — so nothing above this module compares a path
  * before it has been through here. This is also the only module that touches the
- * filesystem for reading: everything else receives text, JSON or a byte count from it.
+ * filesystem for reading artifacts: everything else receives text, JSON or a byte count from it.
  */
 import fs from 'node:fs';
+import { readJsonFileSync } from '../json-file.mjs';
 
 /** One line, no newlines, bounded length — a five-line reply must stay five lines. */
 export const line = (value, max = 200) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
@@ -20,17 +21,12 @@ export const readText = (file) => {
 };
 
 /**
- * A run's JSON artifact, or null when there is none to read. The byte-order mark is stripped
- * first: JSON.parse rejects it, and a status.json rewritten by a Windows editor or by
- * PowerShell's `Set-Content -Encoding utf8` would then read as "no such run" — silently
- * excusing that run from every check that looks it up.
+ * A run's JSON artifact, or null when there is none to read. The shared reader strips the
+ * byte-order mark that PowerShell's `Out-File -Encoding utf8` added in the Plan_24 incident.
  */
 export const readJson = (file) => {
   try {
-    const text = fs.readFileSync(file, 'utf8');
-    // Compared by code point rather than matched by a literal: a byte-order mark in the
-    // source of this file would be invisible to the next reader.
-    return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    return readJsonFileSync(file);
   } catch {
     return null;
   }

package/src/meta/pre-start.mjs

@@ -0,0 +1,30 @@
+/**
+ * Identifies runs that never started Codex and removes them from paid-run views.
+ *
+ * The explicit state is the durable contract for new guard refusals; the second branch keeps
+ * folders written before this fix from poisoning the next launch. Do not infer this from
+ * events.jsonl: retention.mjs deletes that transport file from old paid runs, while
+ * meta.events_bytes is recorded at verdict time and survives cleanup. The Plan_23 incident
+ * showed why confusing those cases would remove repeat protection from a run that spent quota.
+ */
+
+import path from 'node:path';
+
+import { readJson } from './paths.mjs';
+
+export function abortedPreStart(runDir) {
+  const status = readJson(path.join(runDir, 'status.json'));
+  if (status?.state === 'aborted_pre_start') return true;
+  if (status?.state !== 'failed') return false;
+
+  const meta = readJson(path.join(runDir, 'meta.json'));
+  return meta?.exit === null
+    && meta?.session_id == null
+    && meta?.events_bytes === 0
+    && meta?.stderr_bytes === 0
+    && meta?.tokens_reported !== true;
+}
+
+export function startedRuns(runsRoot, runs) {
+  return runs.filter((run) => !abortedPreStart(path.join(runsRoot, run)));
+}

package/src/meta/run-state.mjs

@@ -10,24 +10,26 @@
 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';
 
 /**
- * Is this pid still running? EPERM means the process exists and belongs to someone else,
- * which for our purposes is alive — treating it as dead would mark a live run abandoned.
+ * 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.
  */
-export const pidAlive = (pid) => {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+const isAliveIdentity = (identity) => identity === IDENTITY_ALIVE || identity === IDENTITY_UNVERIFIED;
+
+const pidAlive = (pid, runDir, status = {}) => {
+  const identity = processIdentity({ runDir, status: { ...status, pid } });
+  return isAliveIdentity(identity);
 };
 
 /**
- * This module deliberately judges by the pid alone, while hooks/live-runs.mjs also requires a
- * fresh progress heartbeat. The two answer different questions, and merging them broke both:
+ * This module deliberately judges by the run's pid identity alone, while hooks/live-runs.mjs also
+ * requires a fresh progress heartbeat. The two answer different questions, and merging them broke both:
  *
  * - a hook asks "may the operator edit this tree", and a stalled run must stop holding that
  *   lock — the operator is editing knowingly, and a stale run should not cost them 25 minutes;
@@ -80,7 +82,8 @@ export function markAbandoned(runsRoot, currentTree) {
     if (!entry.isDirectory()) continue;
     const runDir = path.join(runsRoot, entry.name);
     const status = readJson(path.join(runDir, 'status.json'));
-    if (!status || status.state !== 'running' || pidAlive(status.pid)) continue;
+    if (!status || status.state !== 'running') continue;
+    if (pidAlive(status.pid, runDir, status)) continue;
     const metaPath = path.join(runDir, 'meta.json');
     const meta = readJson(metaPath);
     if (!meta && fs.existsSync(metaPath)) continue;
@@ -138,6 +141,11 @@ export function markAbandoned(runsRoot, currentTree) {
  * are not looked at — running scouting alongside a build is the normal way to work.
  */
 export function activeRun(runsRoot, repo, agent = 'codex-build') {
+  return activeRunDetails(runsRoot, repo, agent)?.run || null;
+}
+
+/** Finds the same active run while retaining identity uncertainty for a refusal message. */
+export function activeRunDetails(runsRoot, repo, agent = 'codex-build') {
   let entries;
   try {
     entries = fs.readdirSync(runsRoot, { withFileTypes: true });
@@ -151,7 +159,8 @@ export function activeRun(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;
-    if (pidAlive(status.pid)) return entry.name;
+    const identity = processIdentity({ runDir, status });
+    if (isAliveIdentity(identity)) return { run: entry.name, identity };
   }
   return null;
 }
@@ -194,7 +203,9 @@ export function abandonedBranchDrift(runsRoot, repo, currentBranch) {
  * the runner itself. It still goes through meta.json, so there is no second path by
  * which a reply could exist without an artifact backing it.
  */
-export function writeFailure(runDir, agent, reason, extraLines = []) {
+// The marker is reserved for refusals before Codex starts; Plan_23 showed that calling those
+// ordinary failures makes a no-quota folder consume the same continuation slot as paid work.
+export function writeFailure(runDir, agent, reason, extraLines = [], preStart = false) {
   const meta = {
     agent,
     project: path.basename(path.dirname(runDir)),
@@ -214,7 +225,11 @@ export function writeFailure(runDir, agent, reason, extraLines = []) {
     env: readJson(path.join(runDir, 'env.json')),
   };
   fs.writeFileSync(path.join(runDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
-  writeStatus(runDir, { state: 'failed', status: 'FAIL', finished_at: meta.finished_at });
+  writeStatus(runDir, {
+    state: preStart ? 'aborted_pre_start' : 'failed',
+    status: 'FAIL',
+    finished_at: meta.finished_at,
+  });
   const reply = [`FAIL — ${meta.reason}`, ...extraLines, `Run: ${runDir}`].join('\n');
   return { meta, reply };
 }

package/src/process-identity.mjs

@@ -0,0 +1,140 @@
+/**
+ * Answers whether a recorded pid belongs to the process that started this run.
+ *
+ * Signal 0 is the cheap usual probe. A permission error means only that a process exists, not
+ * that it is this run's process, so a stale or missing heartbeat falls through to the OS start
+ * time probe. `foreign` is a known-dead diagnostic for callers that need to explain pid reuse;
+ * readers treat it like `dead`, while `unverified` remains fail-open.
+ */
+import { spawnSync } from 'node:child_process';
+import { heartbeatAge, HEARTBEAT_STALE_MS } from './heartbeat.mjs';
+
+export const IDENTITY_ALIVE = 'alive';
+export const IDENTITY_DEAD = 'dead';
+export const IDENTITY_FOREIGN = 'foreign';
+export const IDENTITY_UNVERIFIED = 'unverified';
+export const PROCESS_START_TOLERANCE_MS = 1_000;
+export const LEGACY_START_GRACE_MS = 30_000;
+
+const signalZero = (pid) => process.kill(pid, 0);
+
+function defaultCommandRunner(command, args) {
+  return spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
+}
+
+function timestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function commandStartTime(pid, commandRunner = defaultCommandRunner) {
+  try {
+    const command = process.platform === 'win32' ? 'powershell.exe' : 'ps';
+    const args = process.platform === 'win32'
+      ? [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          // Get-Process answers only for processes of the same user, and the pid this exists to
+          // recognise was taken by a SYSTEM service — so CIM has to answer after it. Get-CimInstance
+          // returns CreationDate as a DateTime already; the DMTF converter belongs to the older
+          // Get-WmiObject and throws "dmtfDate out of range" on this value, which cost this probe
+          // its whole purpose once. No $ErrorActionPreference = 'Stop' either: one failing source
+          // must fall through to the next rather than end the script.
+          [
+            `$process = Get-Process -Id ${pid} -ErrorAction SilentlyContinue`,
+            "if ($process) { try { $start = $process.StartTime; if ($start) { $start.ToUniversalTime().ToString('o'); exit 0 } } catch {} }",
+            `$cim = Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\" -ErrorAction SilentlyContinue`,
+            "if ($cim -and $cim.CreationDate) { $cim.CreationDate.ToUniversalTime().ToString('o') }",
+          ].join('; '),
+        ]
+      : ['-o', 'lstart=', '-p', String(pid)];
+    const result = commandRunner(command, args);
+    if (!result || result.error || result.status !== 0) return null;
+    const output = String(result.stdout ?? '').trim();
+    return timestamp(output);
+  } catch {
+    return null;
+  }
+}
+
+function heartbeatIsFreshForIdentity(runDir, now) {
+  if (typeof runDir !== 'string' || !runDir.trim()) return false;
+  const age = heartbeatAge(runDir, now);
+  // isHeartbeatFresh() deliberately treats a missing file as fresh for pre-Plan_20 records.
+  // Identity is stricter: a missing heartbeat proves nothing about THIS process, so it must probe.
+  return age !== null && age <= HEARTBEAT_STALE_MS;
+}
+
+function optionsFor(input) {
+  return input && typeof input === 'object' ? input : {};
+}
+
+export function processAlive(pid, kill = signalZero) {
+  if (!Number.isInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) return false;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EACCES' || error?.code === 'EPERM';
+  }
+}
+
+/**
+ * Return alive/dead/unverified, with foreign as the explicit known-not-this-run case.
+ *
+ * The probe and signal-0 runner are injectable so tests can exercise every branch without
+ * touching a real process. `commandRunner` receives the same command/arguments pair as spawnSync.
+ */
+export function processIdentity(input = {}) {
+  const options = optionsFor(input);
+  const status = options.status && typeof options.status === 'object' ? options.status : options;
+  const pid = options.pid ?? status.pid;
+  if (!Number.isInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) return IDENTITY_DEAD;
+
+  const kill = options.kill || options.signalZero || signalZero;
+  try {
+    kill(pid, 0);
+  } catch (error) {
+    if (error?.code === 'ESRCH') return IDENTITY_DEAD;
+    if (error?.code === 'EINVAL') return IDENTITY_DEAD;
+    if (error?.code !== 'EACCES' && error?.code !== 'EPERM') return IDENTITY_UNVERIFIED;
+  }
+
+  const now = options.now ?? Date.now();
+  if (!options.ignoreHeartbeat && heartbeatIsFreshForIdentity(options.runDir, now)) {
+    return IDENTITY_ALIVE;
+  }
+
+  const probe = options.probe || options.processStartProbe
+    || ((value) => commandStartTime(value, options.commandRunner));
+  let processStartedAt;
+  try {
+    processStartedAt = timestamp(probe(pid, options));
+  } catch {
+    processStartedAt = null;
+  }
+  if (processStartedAt === null) return IDENTITY_UNVERIFIED;
+
+  const hasRecordedStart = Object.prototype.hasOwnProperty.call(status, 'process_started_at')
+    && status.process_started_at !== null
+    && status.process_started_at !== '';
+  if (hasRecordedStart) {
+    const recordedStart = timestamp(status.process_started_at);
+    if (recordedStart === null) return IDENTITY_UNVERIFIED;
+    return Math.abs(processStartedAt - recordedStart) <= PROCESS_START_TOLERANCE_MS
+      ? IDENTITY_ALIVE
+      : IDENTITY_FOREIGN;
+  }
+
+  const startedAt = timestamp(status.started_at);
+  if (startedAt === null) return IDENTITY_UNVERIFIED;
+  return processStartedAt > startedAt + LEGACY_START_GRACE_MS
+    ? IDENTITY_FOREIGN
+    : IDENTITY_ALIVE;
+}
+
+export const probeProcessStart = commandStartTime;

package/src/required-inputs.mjs

@@ -89,6 +89,48 @@ export function extractValue(promptText, label) {
   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 && !isPlaceholder(value)) return null;
+
+  const line = readableDiagnosisLine(candidateLine);
+  if (value !== null && isPlaceholder(value)) {
+    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 : '';

package/src/run-config.mjs

@@ -19,6 +19,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJsonFileSync } from './json-file.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const CONFIG_PATH = path.join(HERE, 'run-config.json');
@@ -163,18 +164,13 @@ function readBudgets(file, value) {
 }
 
 export function readRunConfig(file = CONFIG_PATH) {
-  let raw;
-  try {
-    raw = fs.readFileSync(file, 'utf8');
-  } catch {
-    return { ...DEFAULTS };
-  }
   let parsed;
   try {
-    parsed = JSON.parse(raw);
+    parsed = readJsonFileSync(file);
   } catch (err) {
+    if (err.code) return { ...DEFAULTS };
     throw new Error(
-      `${file} cannot be parsed as JSON (${err.message}). Fix or delete the file — without it, ` +
+      `${file} cannot be parsed as JSON (${err.cause?.message || err.message}). Fix or delete the file — without it, ` +
         'the default mode applies: hooks and plugins are disabled.',
     );
   }

package/src/runner/args.mjs

@@ -97,17 +97,40 @@ export function parseArgs(argv) {
     die(`--effort must be one of: ${allowedEfforts}; got ${JSON.stringify(opts.effort)}`);
   }
   opts.repo = path.resolve(opts.repo || process.cwd());
-  opts.slug = (opts.slug || opts.agent.replace(/^codex-/, '')).replace(/[^A-Za-z0-9._-]+/g, '-');
+  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.mode = opts.mode || '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.
-  opts.scopePatterns = String(opts.scope || '')
+  const declaredScopePatterns = String(opts.scope || '')
     .split(',')
     .map((p) => p.trim())
     .filter(Boolean);
-  if (opts.agent === 'codex-build' && !opts.scopePatterns.length) {
+  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}. ` +

package/src/runner/attach.mjs

@@ -1,6 +1,8 @@
 /** Finds a live run for an order and waits for its verdict when a repeated launcher call attaches. */
 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 { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
 
 // The attach call is the only process that waits for a worker it did not spawn. Keeping that
@@ -8,38 +10,49 @@ import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
 const POLL_MS = 500;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// The 2026-08-10_220535_plan25-2-install-table-two-roots incident showed that ATTACH alone
+// can be mistaken for this pass; state the previous run and the fact that no work was started.
+function announceAttach(runDir, startedAt) {
+  console.log(`ATTACH=${runDir} started=${startedAt}`);
+  console.log(`This is the answer of the previous run started at ${startedAt}; no new work was started.`);
+}
+
 export const readJsonFile = (file) => {
   try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
+    return readJsonFileSync(file);
   } catch {
     return null;
   }
 };
 
 /**
- * Is this pid still running? EPERM means the process exists and belongs to someone else,
- * which for our purposes is alive. Same reading write-meta.mjs uses — two answers to "is
- * this run still going" would be one answer too many.
+ * 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) => {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+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. */
-export async function waitForReply(runDir, workerPid) {
+/**
+ * Blocks until the worker's reply exists, or until the worker is provably gone without one.
+ *
+ * Identity is settled once, before the loop: a recycled pid would otherwise keep this call waiting
+ * for a reply nobody is going to write, and asking again every 500 ms would spawn the start-time
+ * 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 = {}) {
   const replyPath = path.join(runDir, 'reply.txt');
+  if (!alive(workerPid, runDir, status)) {
+    return fs.existsSync(replyPath) ? fs.readFileSync(replyPath, 'utf8').replace(/\s+$/, '') : null;
+  }
   let pollsSinceDeath = 0;
   for (;;) {
     if (fs.existsSync(replyPath)) return fs.readFileSync(replyPath, 'utf8').replace(/\s+$/, '');
     // A dead worker will never write it. Two extra polls before believing that: the pid is
     // released around the same moment as the last write, and the order is not guaranteed.
-    if (alive(workerPid)) {
+    if (processAlive(workerPid)) {
       pollsSinceDeath = 0;
     } else {
       pollsSinceDeath += 1;
@@ -80,11 +93,11 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
     const entry = sameOrder[i];
     const dir = path.join(runsRoot, entry.run);
     if (fs.existsSync(path.join(dir, 'reply.txt'))) {
-      console.log(`ATTACH=${dir} started=${entry.status.started_at}`);
+      announceAttach(dir, 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);
     }
-    if (alive(entry.status.pid)) {
+    if (alive(entry.status.pid, dir, entry.status)) {
       candidate = entry;
       break;
     }
@@ -92,8 +105,8 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
   if (!candidate) return null;
 
   const runDir = path.join(runsRoot, candidate.run);
-  console.log(`ATTACH=${runDir} started=${candidate.status.started_at}`);
-  const replyText = await waitForReply(runDir, candidate.status.pid);
+  announceAttach(runDir, candidate.status.started_at);
+  const replyText = await waitForReply(runDir, candidate.status.pid, candidate.status);
   if (replyText !== null) {
     console.log(replyText);
     return exitCodeFor(readJsonFile(path.join(runDir, 'meta.json'))?.status);