@lyupro/codex-bridge 0.3.1 → 0.4.0

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/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';
@@ -38,6 +41,7 @@ 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
@@ -88,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
@@ -118,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
@@ -139,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(
@@ -155,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. ' +
@@ -166,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 {
@@ -192,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,
@@ -202,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 } : {}),
@@ -214,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);
@@ -307,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);
@@ -324,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,
@@ -343,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 };
 

package/cli/sweep.mjs

@@ -1,144 +0,0 @@
-#!/usr/bin/env node
-/** Closes dead-pid running records without deleting any run artifacts. */
-import fs from 'node:fs';
-import path from 'node:path';
-import { formatSilence, heartbeatAge, isHeartbeatFresh } from '../src/heartbeat.mjs';
-import { markAbandoned, pidAlive } from '../src/meta/run-state.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
-import { readJson } from '../src/write-meta.mjs';
-import { renderTable } from './table.mjs';
-
-const CLOSED_COLUMNS = [
-  { key: 'project', label: 'project' },
-  { key: 'run', label: 'run' },
-  { key: 'state', label: 'state' },
-];
-const STALE_COLUMNS = [
-  { key: 'project', label: 'project' },
-  { key: 'run', label: 'run' },
-  { key: 'silence', label: 'silent for' },
-];
-
-function result(exitCode, output) {
-  return { exitCode, output };
-}
-
-function parseArgs(argv) {
-  const positional = [];
-  for (const arg of argv) {
-    if (typeof arg !== 'string' || arg.startsWith('-')) {
-      return { error: `codex-bridge sweep: unknown option "${arg}".` };
-    }
-    positional.push(arg);
-  }
-  if (positional.length > 1) {
-    return { error: 'codex-bridge sweep accepts at most one project name.' };
-  }
-  const project = positional[0] || null;
-  if (project && (path.isAbsolute(project) || path.dirname(project) !== '.')) {
-    return { error: 'codex-bridge sweep requires a bare project name.' };
-  }
-  return { project };
-}
-
-function directories(root) {
-  try {
-    return fs.readdirSync(root, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .sort((left, right) => left.name.localeCompare(right.name));
-  } catch {
-    return [];
-  }
-}
-
-function selectedProjects(root, projectName) {
-  const entries = directories(root);
-  if (!projectName) {
-    return entries.map((entry) => ({ name: entry.name, dir: path.join(root, entry.name) }));
-  }
-  const entry = entries.find((candidate) => candidate.name === projectName);
-  if (!entry) return { error: `codex-bridge sweep: unknown project "${projectName}".` };
-  return [{ name: entry.name, dir: path.join(root, entry.name) }];
-}
-
-function staleLiveRuns(project) {
-  // The 2026-08-06 incident showed why stale heartbeat is report-only: a live worker remains
-  // the sole writer until stop kills it and records the outcome.
-  const stale = [];
-  for (const entry of directories(project.dir)) {
-    const dir = path.join(project.dir, entry.name);
-    const status = readJson(path.join(dir, 'status.json'));
-    if (!status || status.state !== 'running' || !pidAlive(status.pid) || isHeartbeatFresh(dir)) continue;
-    stale.push({
-      project: project.name,
-      run: entry.name,
-      silence: formatSilence(heartbeatAge(dir)),
-    });
-  }
-  return stale;
-}
-
-export function sweepPlan(argv = [], options = {}) {
-  const parsed = parseArgs(argv);
-  if (parsed.error) return parsed;
-  const root = path.resolve(options.runsRootPath || runsRoot());
-  const projects = selectedProjects(root, parsed.project);
-  if (projects.error) return projects;
-  return { root, project: parsed.project, projects };
-}
-
-function closeDeadRuns(plan) {
-  const closed = [];
-  const failures = [];
-  for (const project of plan.projects) {
-    try {
-      // No worktree snapshot is passed, and that is the choice rather than an omission: `stop`
-      // closes one named run and knows which repository to look at, while a sweep of the whole
-      // store would have to run git in every repository every project ever pointed at. The runs
-      // it closes died long ago, so that list would describe today's tree, not their work — the
-      // reason text already says a file list is unavailable, which is the honest answer here.
-      for (const change of markAbandoned(project.dir)) {
-        closed.push({ project: project.name, run: change.run, state: change.state });
-      }
-    } catch (error) {
-      failures.push({ project: project.name, message: error.message });
-    }
-  }
-  return { closed, failures };
-}
-
-function renderReport(plan, closed, stale, failures, options) {
-  const scope = plan.project ? `project "${plan.project}"` : 'all projects';
-  const lines = [`Sweep of ${scope} completed.`];
-  if (closed.length) {
-    lines.push(`Closed ${closed.length} running record${closed.length === 1 ? '' : 's'}:`);
-    lines.push(renderTable(CLOSED_COLUMNS, closed, options));
-  } else {
-    lines.push('Nothing to close; the store is unchanged.');
-  }
-  if (stale.length) {
-    lines.push(`Left ${stale.length} live-pid run${stale.length === 1 ? '' : 's'} with stale heartbeats untouched:`);
-    lines.push(renderTable(STALE_COLUMNS, stale, options));
-    lines.push('End each one explicitly:');
-    for (const run of stale) lines.push(`  codex-bridge stop ${run.run}`);
-  } else {
-    lines.push('Live-pid runs with stale heartbeats left untouched: none.');
-  }
-  if (failures.length) {
-    lines.push('Some project records could not be swept:');
-    for (const failure of failures) lines.push(`  ${failure.project}: ${failure.message}`);
-  }
-  return lines.join('\n');
-}
-
-export function sweep(argv = [], options = {}) {
-  const plan = sweepPlan(argv, options);
-  if (plan.error) return result(2, plan.error);
-  const { closed, failures } = closeDeadRuns(plan);
-  // This is a report-only probe. markAbandoned owns the closure decision and is the only writer.
-  const stale = plan.projects.flatMap((project) => staleLiveRuns(project));
-  return result(
-    failures.length ? 1 : 0,
-    renderReport(plan, closed, stale, failures, options),
-  );
-}