@lyupro/codex-bridge 0.3.1 → 0.4.0

package/src/heartbeat.mjs

@@ -51,7 +51,7 @@ export function heartbeatAge(runDir, now = Date.now()) {
 
 /**
  * How long a run has been silent, in words. It lives beside the age it formats because both the
- * worktree lock's refusal and `sweep`'s report have to name the same silence to the same operator;
+ * worktree lock's refusal and `unlock`'s report have to name the same silence to the same operator;
  * two copies of this drifted apart the moment they were written.
  */
 export function formatSilence(age) {

package/src/hooks/live-runs.mjs

@@ -2,8 +2,8 @@
  * Shared, fail-open knowledge of live Codex runs.
  *
  * The reply guard and the worktree lock must answer the same question: a status.json is live
- * only while it says `running`, its runner pid accepts signal 0, and its progress heartbeat is
- * fresh. Keeping those probes and the directory scan here prevents the two protections from
+ * only while it says `running`, its runner pid is judged alive for this run, and its progress
+ * heartbeat is fresh. Keeping those probes and the directory scan here prevents the two protections from
  * disagreeing about a run, which would recreate the 2026-08-06 incident where a dead Codex
  * child left its worker and lock looking live through a grandchild-held stdio pipe.
  *
@@ -14,16 +14,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isHeartbeatFresh } from '../heartbeat.mjs';
+import { readJsonFileSync } from '../json-file.mjs';
+import { IDENTITY_DEAD, IDENTITY_FOREIGN, processIdentity } from '../process-identity.mjs';
 
-/** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
-export const isPidAlive = (pid) => {
-  if (typeof pid !== 'number') return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
+/**
+ * The hook requires pid judgment plus a fresh heartbeat. Identity uncertainty stays live here
+ * (fail-open), while the identity module deliberately treats a missing heartbeat as unverified;
+ * isHeartbeatFresh() keeps its pre-Plan_20 missing-file compatibility for this separate question.
+ */
+export const isPidAlive = (pid, runDir, status = {}) => {
+  const identity = processIdentity({ runDir, status: { ...status, pid } });
+  return identity !== IDENTITY_DEAD && identity !== IDENTITY_FOREIGN;
 };
 
 /**
@@ -56,13 +57,13 @@ function recognizedStatus(runDir, status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isPidAlive(status.pid)
-    && isHeartbeatFresh(runDir);
+    && isHeartbeatFresh(runDir)
+    && isPidAlive(status.pid, runDir, status);
 }
 
 function readStatus(runDir) {
   try {
-    return JSON.parse(fs.readFileSync(path.join(runDir, 'status.json'), 'utf8'));
+    return readJsonFileSync(path.join(runDir, 'status.json'));
   } catch {
     return null;
   }

package/src/hooks/order-gate.mjs

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { missingInputs } from '../required-inputs.mjs';
+import { diagnoseInput, missingInputs } from '../required-inputs.mjs';
 import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
 
 const HOME = os.homedir();
@@ -56,7 +56,12 @@ if (!missing.length) pass();
 const reason = [
   'Order gate denied the Agent call because required dispatcher input(s) are missing or still placeholders.',
   'Write each value in tool_input.prompt using `label: value` before launching the dispatcher:',
-  ...missing.map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`),
+  ...missing.flatMap((entry) => {
+    const lines = [`- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`];
+    const diagnosis = diagnoseInput(toolInput.prompt, entry.label);
+    if (diagnosis) lines.push(`  found \`${diagnosis.line}\`, ${diagnosis.reason}`);
+    return lines;
+  }),
 ].join('\n');
 
 process.stdout.write(JSON.stringify({

package/src/hooks/reply-guard.mjs

@@ -29,6 +29,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
 import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
 
 const HOME = os.homedir();
@@ -120,7 +121,7 @@ const takeTry = (agentId, kind) => {
   if (!agentId) return 'untracked';
   let seen;
   try {
-    seen = JSON.parse(fs.readFileSync(BLOCKED_FILE, 'utf8'));
+    seen = readJsonFileSync(BLOCKED_FILE);
   } catch {
     seen = {};
   }
@@ -253,7 +254,7 @@ const statusPath = path.join(runDir, 'status.json');
 if (fs.existsSync(statusPath)) {
   let runStatus = null;
   try {
-    runStatus = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    runStatus = readJsonFileSync(statusPath);
   } catch {
     runStatus = null;
   }
@@ -317,7 +318,7 @@ if (!fs.existsSync(metaPath)) {
 
 let meta;
 try {
-  meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  meta = readJsonFileSync(metaPath);
 } catch {
   pass();
 }

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

@@ -103,11 +103,25 @@ export function parseArgs(argv) {
   // 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}. ` +