@lyupro/codex-bridge 0.3.0 → 0.4.0

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}. ` +

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
@@ -10,36 +12,40 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 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;
@@ -84,7 +90,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)) {
+    if (alive(entry.status.pid, dir, entry.status)) {
       candidate = entry;
       break;
     }
@@ -93,7 +99,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
 
   const runDir = path.join(runsRoot, candidate.run);
   console.log(`ATTACH=${runDir} started=${candidate.status.started_at}`);
-  const replyText = await waitForReply(runDir, candidate.status.pid);
+  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);

package/src/runner/codex-cmd.mjs

@@ -263,7 +263,7 @@ export function requireCodex(runDir, agent) {
     const why = (probe.stderr || probe.error?.message || 'codex --version is not responding').trim();
     const { reply } = writeFailure(runDir, agent, `Codex CLI unavailable: ${why}`, [
       'Operator check: codex --version (and codex login if authorization is rejected)',
-    ]);
+    ], true);
     console.log(reply);
     process.exit(1);
   }

package/src/runner/conventions.mjs

@@ -0,0 +1,39 @@
+/** Renders the host and repository conventions that a run must carry in its task artifact. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH } from '../run-config.mjs';
+
+const HOST_FILE = path.join(path.dirname(CONFIG_PATH), 'conventions.md');
+const REPOSITORY_FILE = '.codex-conventions.md';
+
+function readOptional(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Reads both convention layers at the point of use. Plan_13 showed that a reference to a required
+ * file is not enforcement: the task must contain the bytes the run was given.
+ *
+ * A layer that is present but blank is dropped rather than rendered as an empty heading, for the
+ * same reason doctor warns about it — an empty rules file looks like a working mechanism and is
+ * not one, and in the artifact it would look like rules that were given and ignored.
+ *
+ * Duplication is impossible by construction and deliberately not guarded against: `sections`
+ * starts empty on every launch and task.md is written into a folder that is never reused, so
+ * there is nothing to append to. A guard reading the operator's task text for this heading would
+ * only find the word in a task that talks ABOUT conventions, and silently drop the section from
+ * the one run that most obviously needed it.
+ */
+export function renderConventions(repoRoot, hostFile = HOST_FILE) {
+  const layers = [];
+  const host = readOptional(hostFile);
+  if (host?.trim()) layers.push(`### Host conventions\n\n${host}`);
+  const repository = readOptional(path.join(repoRoot, REPOSITORY_FILE));
+  if (repository?.trim()) layers.push(`### Repository conventions\n\n${repository}`);
+  return layers.length ? `## Conventions\n\n${layers.join('\n\n')}` : '';
+}

package/src/runner/launcher.mjs

@@ -4,11 +4,13 @@
  *
  * The order it leaves for the worker is worker.json in the run folder — after the split
  * that file is the only connection between the two halves. It is written here with
- * `agent`, `slug`, `order_id`, `repo`, `is_git_repo`, `launcher_pid`, `budget_minutes` and `args`;
- * worker.mjs reads `repo`, `agent`, `args`, `is_git_repo` and `budget_minutes`. The three extra fields are deliberate: `slug`,
- * `order_id` and `launcher_pid` are what a run folder read back months later needs in order to
- * explain itself — which order it belonged to included. Nothing may be dropped from this shape
- * without changing worker.mjs and saying so out loud.
+ * `agent`, `slug`, `order_id`, `repo`, `is_git_repo`, `launcher_pid`, `budget_minutes`, `scope_new`
+ * and `args`;
+ * worker.mjs reads `repo`, `agent`, `args`, `is_git_repo` and `budget_minutes`. The extra fields
+ * are deliberate: `slug`, `order_id`, `launcher_pid` and `scope_new` are what a run folder read
+ * back months later needs in order to explain itself — which order it belonged to and which new
+ * paths it declared included. Nothing may be dropped from this shape without changing worker.mjs
+ * and saying so out loud.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,8 +21,9 @@ import {
   writeStatus,
   markAbandoned,
   abandonedBranchDrift,
-  activeRun,
+  activeRunDetails,
   chainRuns,
+  startedRuns,
   taskFingerprint,
   readJson,
 } from '../write-meta.mjs';
@@ -37,6 +40,8 @@ import { codexArgs, requireCodex, runMode, unsafeForCmd } from './codex-cmd.mjs'
 import { runsRoot } from './runs-root.mjs';
 import { resolveProjectRunsDir } from './project-dir.mjs';
 import { cleanupRetention } from '../retention.mjs';
+import { renderConventions } from './conventions.mjs';
+import { validateScope } from './scope-check.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
@@ -87,6 +92,18 @@ export async function launcher() {
   const topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
   const isGitRepo = topLevel.status === 0;
   const repoRoot = isGitRepo ? topLevel.stdout.trim() : opts.repo;
+  // Plan_27 moved impossible scope failures ahead of the run directory: an absolute pattern had
+  // already cost 18 minutes before the verdict could prove it matched nothing.
+  // Every agent, not only the writing one: a pattern that cannot match gives a scout empty coverage
+  // instead of an answer. Only codex-build may declare a not-yet-existing path, so only its scope
+  // carries --scope-new; for the other two the list is empty and every pattern must match.
+  const scopeRefusal = validateScope(repoRoot, opts.scopePatterns, opts.scopeNewPatterns);
+  if (scopeRefusal) {
+    die(
+      `--scope pattern ${JSON.stringify(scopeRefusal.pattern)} refused: ${scopeRefusal.reason}. ` +
+        `Action: ${scopeRefusal.action}. The run folder was not created; quota was not spent.`,
+    );
+  }
   const projectRunsRoot = resolveProjectRunsDir(runsRoot(), repoRoot).dir;
 
   // Folders left behind by a runner that was killed mid-run get an explicit state before
@@ -117,6 +134,7 @@ export async function launcher() {
   // like --scope.
   const taskHash = taskFingerprint(taskText);
   const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
+  const startedChain = startedRuns(projectRunsRoot, chain);
   const continuationGrant = opts.continue ? parseContinuationGrant(taskText) : null;
 
   // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
@@ -138,15 +156,15 @@ export async function launcher() {
   // attach(), while --continue must refuse to overlap that live work.
   const continuationError = continuationRefusal(
     projectRunsRoot,
-    chain,
+    startedChain,
     opts.continue,
     opts.orderId,
     continuationGrant,
   );
   if (continuationError) die(continuationError);
 
-  if (chain.length && !opts.continue) {
-    const last = chain[chain.length - 1];
+  if (startedChain.length && !opts.continue) {
+    const last = startedChain[startedChain.length - 1];
     const lastSlug = String(readJson(path.join(projectRunsRoot, last, 'status.json'))?.slug || '');
     const renamed = lastSlug && lastSlug.toLowerCase() !== String(opts.slug).toLowerCase();
     die(
@@ -154,7 +172,7 @@ export async function launcher() {
         renamed
           ? `this task already ran in this repository under the name “${lastSlug}”`
           : `runs for task “${opts.slug}” already exist in this repository`
-      } (${chain.length}), latest: ${path.join(projectRunsRoot, last)}. ` +
+      } (${startedChain.length}), latest: ${path.join(projectRunsRoot, last)}. ` +
         'A repeat run is allowed, but the orchestrator decides, not the runner: it read the ' +
         'previous response and knows whether work remains. Add --continue if you are finishing ' +
         'the same task; changing --slug with the same task text does not stop it being a repeat. ' +
@@ -165,7 +183,7 @@ export async function launcher() {
   // Asked before this run registers itself, so it cannot find itself. Two writing runs share
   // one worktree with no isolation: the second one's before/after snapshot picks up the
   // first one's edits, and an honest run gets failed for work it never did.
-  const busy = opts.agent === 'codex-build' ? activeRun(projectRunsRoot, repoRoot) : null;
+  const busy = opts.agent === 'codex-build' ? activeRunDetails(projectRunsRoot, repoRoot) : null;
 
   let retention = null;
   try {
@@ -191,6 +209,7 @@ export async function launcher() {
     state: 'running',
     pid: process.pid,
     launcher_pid: process.pid,
+    process_started_at: performance.timeOrigin,
     agent: opts.agent,
     slug: opts.slug,
     order_id: opts.orderId,
@@ -201,7 +220,7 @@ export async function launcher() {
     started_at: new Date().toISOString(),
     // Which run of this task started the chain — the base every later pass is measured
     // against. Absent means this is the first pass.
-    ...(chain.length ? { continues: chain[0] } : {}),
+    ...(startedChain.length ? { continues: startedChain[0] } : {}),
     // `continued_from` is the exact run the orchestrator named; `continues` above remains the chain base.
     ...(continuationGrant ? { continued_from: continuationGrant.run } : {}),
     ...(retention ? { retention } : {}),
@@ -213,11 +232,15 @@ export async function launcher() {
 
   // Before requireCodex, so a blocked run costs nothing at all.
   if (busy) {
+    const identityNote = busy.identity === 'unverified'
+      ? '; process identity could not be confirmed'
+      : '';
     const { reply } = writeFailure(
       runDir,
       opts.agent,
-      `run ${busy} is already active for this repository; two writing runs in one tree are prohibited`,
-      [`Active run: ${path.join(projectRunsRoot, busy)}`, 'Codex was not started; quota was not spent'],
+      `run ${busy.run} is already active for this repository; two writing runs in one tree are prohibited${identityNote}`,
+      [`Active run: ${path.join(projectRunsRoot, busy.run)}`, 'Codex was not started; quota was not spent'],
+      true,
     );
     console.log(reply);
     process.exit(1);
@@ -279,6 +302,8 @@ export async function launcher() {
       ].join('\n'),
     );
   }
+  const conventions = renderConventions(repoRoot);
+  if (conventions) sections.push(conventions);
   sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
   fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
   fs.writeFileSync(
@@ -304,6 +329,7 @@ export async function launcher() {
       opts.agent,
       `argument cannot be passed through cmd.exe (contains % or "): ${unsafe}`,
       ['Codex was not started; quota was not spent'],
+      true,
     );
     console.log(reply);
     process.exit(1);
@@ -321,6 +347,7 @@ export async function launcher() {
         // The mode's wall-clock budget, resolved here and never re-read by the worker: a run
         // that consulted run-config.json twice could end up honouring two different limits.
         budget_minutes: RUN_ENV?.budgets?.[runMode(opts.agent)],
+        scope_new: opts.scopeNewPatterns,
         args: codexArgv,
       },
       null,
@@ -340,12 +367,12 @@ export async function launcher() {
   worker.on('error', (err) => {
     const { reply } = writeFailure(runDir, opts.agent, `run worker process failed to start: ${err.message}`, [
       'Codex was not started; quota was not spent',
-    ]);
+    ], true);
     console.log(reply);
     process.exit(1);
   });
   worker.unref();
-  writeStatus(runDir, { pid: worker.pid, runner_pid: worker.pid });
+  writeStatus(runDir, { pid: worker.pid, runner_pid: worker.pid, process_started_at: null });
 
   console.log(
     `STARTED agent=${opts.agent} slug=${opts.slug} order-id=${opts.orderId} worker-pid=${worker.pid}`,

package/src/runner/project-dir.mjs

@@ -1,6 +1,7 @@
 /** Assigns a stable runs directory to one repository. */
 import fs from 'node:fs';
 import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
 import { projectFolder } from '../write-meta.mjs';
 
 export const PROJECT_MARKER = '.project.json';
@@ -18,9 +19,9 @@ function readMarker(dir) {
   if (!fs.existsSync(markerPath)) return null;
   let marker;
   try {
-    marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    marker = readJsonFileSync(markerPath);
   } catch (err) {
-    throw new Error(`Cannot read project marker ${markerPath}: ${err.message}`);
+    throw new Error(`Cannot read project marker ${markerPath}: ${err.cause?.message || err.message}`);
   }
   if (!marker || typeof marker.repo !== 'string' || !marker.repo) {
     throw new Error(`Project marker ${markerPath} must contain a non-empty repo path`);
@@ -65,7 +66,7 @@ function legacyOwner(dir) {
     .sort((a, b) => a.name.localeCompare(b.name));
   const statuses = entries.map((entry) => {
     try {
-      return JSON.parse(fs.readFileSync(path.join(dir, entry.name, 'status.json'), 'utf8'));
+      return readJsonFileSync(path.join(dir, entry.name, 'status.json'));
     } catch {
       return null;
     }

package/src/runner/scope-check.mjs

@@ -0,0 +1,159 @@
+/**
+ * Answers whether each scope pattern can match an existing repository file.
+ *
+ * Plan_27 moved impossible scope failures before the run folder: an absolute pattern had already
+ * spent 18 minutes before the verdict proved that it matched nothing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { globToRegExp, normalizePath } from '../meta/paths.mjs';
+
+// Directories a self-walk must never descend into. Only reached when the repository has no git:
+// with git present the file list comes from the repository itself, which already knows what is
+// ignored. The first Plan_27 pass walked everything, `.git` and `node_modules` included — invisible
+// here, where the package has no dependencies, and tens of thousands of files in a working monorepo.
+const SKIP_DIRECTORIES = new Set(['.git', 'node_modules']);
+
+function absolutePattern(pattern) {
+  return (
+    /^[A-Za-z]:/.test(pattern) ||
+    pattern.startsWith('/') ||
+    pattern.startsWith('\\\\?\\') ||
+    pattern.startsWith('\\\\')
+  );
+}
+
+function structuralRefusal(pattern) {
+  if (absolutePattern(pattern)) {
+    return {
+      reason: 'is an absolute or drive-qualified path',
+      action: 'use a path relative to the repository root with forward slashes',
+    };
+  }
+  if (pattern.includes('\\')) {
+    return {
+      reason: 'uses backslash separators',
+      action: 'replace backslashes with forward slashes',
+    };
+  }
+  if (pattern.split('/').some((segment) => segment === '..')) {
+    return {
+      reason: 'contains a parent-directory (..) segment',
+      action: 'remove the .. segment and keep the path relative to the repository root',
+    };
+  }
+  return null;
+}
+
+function noMatchRefusal(pattern) {
+  return {
+    pattern,
+    reason: 'does not match any existing path in the repository',
+    action: 'correct the pattern or declare an intentionally new path with --scope-new',
+  };
+}
+
+function repositoryPath(repoRoot, absolutePath) {
+  const relative = path.relative(repoRoot, absolutePath).split(path.sep).join('/');
+  return normalizePath(relative);
+}
+
+/**
+ * The repository's own answer to "which files are there": tracked plus new-but-uncommitted, minus
+ * everything ignored. It is the same boundary the run is judged by afterwards, it costs one process
+ * instead of a full walk, and it cannot wander into `.git` or a dependency tree.
+ */
+function gitPaths(repoRoot) {
+  const result = spawnSync(
+    'git',
+    ['-C', repoRoot, 'ls-files', '--cached', '--others', '--exclude-standard'],
+    { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/** Walks a directory that has no git, skipping dependency trees and anything unreadable. */
+function walkPaths(repoRoot) {
+  const pending = [repoRoot];
+  const found = [];
+  while (pending.length) {
+    const current = pending.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      // An unreadable subdirectory is not a reason to refuse a run: the pattern may well match
+      // somewhere else, and a permission error here would fail work that has nothing to do with it.
+      continue;
+    }
+    for (const entry of entries) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        if (!SKIP_DIRECTORIES.has(entry.name)) pending.push(absolute);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+      found.push(repositoryPath(repoRoot, absolute));
+    }
+  }
+  return found;
+}
+
+function matchingPaths(repoRoot, matchers) {
+  const candidates = gitPaths(repoRoot)?.map((relative) => normalizePath(relative))
+    ?? walkPaths(repoRoot);
+  const matched = new Set();
+  for (const candidate of candidates) {
+    for (const matcher of matchers) {
+      if (!matched.has(matcher.pattern) && matcher.regexp.test(candidate)) {
+        matched.add(matcher.pattern);
+      }
+    }
+    if (matched.size === matchers.length) break;
+  }
+  return matched;
+}
+
+function patternList(value, label) {
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be an array`);
+  return value.map((pattern) => String(pattern ?? '').trim());
+}
+
+/**
+ * Returns the first scope refusal, or null when every ordinary pattern can match a repository
+ * path. New-file declarations are still structurally checked; only their existence check is
+ * exempted.
+ */
+export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
+  if (typeof repoRoot !== 'string' || !repoRoot) throw new TypeError('repoRoot must be a non-empty string');
+  const declared = patternList(patterns, 'patterns');
+  const newPaths = patternList(scopeNewPatterns, 'scopeNewPatterns');
+  const allPatterns = [...declared, ...newPaths];
+
+  for (const pattern of allPatterns) {
+    const refusal = structuralRefusal(pattern);
+    if (refusal) return { pattern, ...refusal };
+    if (!pattern) return noMatchRefusal(pattern);
+  }
+
+  const newPathKeys = new Set(newPaths.map((pattern) => normalizePath(pattern)));
+  const required = allPatterns.filter((pattern) => !newPathKeys.has(normalizePath(pattern)));
+  if (!required.length) return null;
+
+  let matchers;
+  try {
+    matchers = required.map((pattern) => ({ pattern, regexp: globToRegExp(pattern) }));
+  } catch (error) {
+    return {
+      pattern: required[0].pattern,
+      reason: `could not parse the pattern: ${error.message}`,
+      action: 'correct the pattern and retry',
+    };
+  }
+
+  const matched = matchingPaths(repoRoot, matchers);
+  const missing = matchers.find((matcher) => !matched.has(matcher.pattern));
+  return missing ? noMatchRefusal(missing.pattern) : null;
+}

package/src/runner/worker.mjs

@@ -4,14 +4,15 @@
  * It takes its whole order from worker.json, written by launcher.mjs into the run folder —
  * after the split that file is the only connection between the two halves. Read here:
  * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`. Written there: those five plus
- * `slug` and `launcher_pid`, which nothing here needs but a run folder read back months later
- * does. The launcher must write the selected mode's budget into worker.json before spawning
- * this half, so the worker never re-reads run-config.json and one run cannot acquire two
+ * `slug`, `launcher_pid` and `scope_new`, which nothing here needs but a run folder read back
+ * months later does. The launcher must write the selected mode's budget into worker.json before
+ * spawning this half, so the worker never re-reads run-config.json and one run cannot acquire two
  * configurations.
  * Neither side may change the shape alone.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { readJsonFileSync } from '../json-file.mjs';
 import { collect, exitCodeFor, AGENTS } from '../write-meta.mjs';
 import { writeStatus } from '../meta/run-state.mjs';
 import { setRun, emitReply } from './run-context.mjs';
@@ -23,9 +24,16 @@ import { runCodex } from './codex-cmd.mjs';
  * may depend on anyone still being on the other end of a pipe.
  */
 export async function worker(runDir) {
-  const cfg = JSON.parse(fs.readFileSync(path.join(runDir, 'worker.json'), 'utf8'));
+  const cfg = readJsonFileSync(path.join(runDir, 'worker.json'));
   const repoRoot = cfg.repo;
   setRun(runDir, cfg.agent);
+  // The launcher cannot know this detached process's clock origin; takeover must record the
+  // worker's own identity before it starts producing the run's artifacts.
+  writeStatus(runDir, {
+    pid: process.pid,
+    runner_pid: process.pid,
+    process_started_at: performance.timeOrigin,
+  });
 
   const run = await runCodex(
     cfg.args,
@@ -58,7 +66,7 @@ export async function worker(runDir) {
   const resultPath = path.join(runDir, AGENTS[cfg.agent].result);
   if (cfg.agent !== 'codex-review') {
     try {
-      const result = JSON.parse(fs.readFileSync(resultPath, 'utf8'));
+      const result = readJsonFileSync(resultPath);
       if (result.report_markdown) fs.writeFileSync(path.join(runDir, 'report.md'), `${result.report_markdown}\n`);
     } catch {
       // No parseable result — write-meta.mjs turns that into FAIL with the log reason.

package/src/write-meta.mjs

@@ -31,7 +31,14 @@ import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
 
 export { expandDeclared, globToRegExp, readJson } from './meta/paths.mjs';
 export { chainBaseline, chainRuns, taskFingerprint } from './meta/chain.mjs';
-export { abandonedBranchDrift, activeRun, markAbandoned, writeFailure } from './meta/run-state.mjs';
+export { abortedPreStart, startedRuns } from './meta/pre-start.mjs';
+export {
+  abandonedBranchDrift,
+  activeRun,
+  activeRunDetails,
+  markAbandoned,
+  writeFailure,
+} from './meta/run-state.mjs';
 export { outOfScope, reportVersusWork } from './meta/verdict.mjs';
 export { AGENTS, writeStatus };