@lyupro/codex-bridge 0.3.1 → 0.5.0

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/continuation.mjs

@@ -37,6 +37,28 @@ const grantExample = `Example: \`continue: ${CONTINUATION_INPUT.example}\`.`;
 const grantAction =
   'Action: ask the orchestrator for an explicit grant naming the run and reason; do not invent or reuse a continuation.';
 
+// The 2026-08-10_220535_plan25-2-install-table-two-roots incident showed that a refusal must
+// carry the repair line; otherwise a typo forces an unnecessary directory listing and retry.
+function lastRunOutcome(runsRootPath, chain) {
+  const run = chain[chain.length - 1];
+  if (!run) return null;
+  const status = readJson(path.join(runsRootPath, run, 'status.json')) || {};
+  const meta = readJson(path.join(runsRootPath, run, 'meta.json')) || {};
+  const outcomeStatus = String(meta.status ?? status.status ?? status.state ?? 'unknown').trim() || 'unknown';
+  const outcomeReason = String(meta.reason ?? status.reason ?? 'reason not recorded').trim() || 'reason not recorded';
+  return { run, status: outcomeStatus, reason: outcomeReason };
+}
+
+function lastRunHints(runsRootPath, chain, grantReason) {
+  const last = lastRunOutcome(runsRootPath, chain);
+  if (!last) {
+    return 'Last run: none. Outcome: none. Ready grant line: none (there is no run to continue).';
+  }
+  const reason = String(grantReason ?? last.reason).trim() || last.reason;
+  return `Last run: ${last.run}. Outcome: ${last.status} — ${last.reason}. ` +
+    `Ready grant line: continue: ${last.run} — ${reason}.`;
+}
+
 /**
  * Applies the one-continuation limit and all continuation safety gates before a folder is created.
  *
@@ -49,9 +71,16 @@ const grantAction =
  * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
  */
 export function continuationRefusal(runsRootPath, chain, isContinue, orderId, grant) {
-  if (!isContinue) return null;
-
   const continuation = normalizeGrant(grant);
+  if (!isContinue) {
+    if (!continuation) return null;
+    return (
+      '--continue is required when the task text contains a `continue:` grant. ' +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      'The submitted grant was not rewritten. The run folder was not created; quota was not spent.'
+    );
+  }
+
   if (!continuation) {
     return (
       '--continue is refused: the orchestrator did not provide a `continue:` grant in the task text. ' +
@@ -64,7 +93,9 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
     return (
       `--continue is refused: the orchestrator named run “${continuation.run}”, but it does not ` +
       `exist as a run folder in this project's runs directory ${runsRootPath}. ` +
-      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${grantExample} ${grantAction} The submitted grant was not rewritten. ` +
+      'The run folder was not created; quota was not spent.'
     );
   }
 

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,7 +134,22 @@ export async function launcher() {
   // like --scope.
   const taskHash = taskFingerprint(taskText);
   const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
-  const continuationGrant = opts.continue ? parseContinuationGrant(taskText) : null;
+  const startedChain = startedRuns(projectRunsRoot, chain);
+  const continuationGrant = parseContinuationGrant(taskText);
+
+  // The 2026-08-10_220535_plan25-2-install-table-two-roots incident exposed this ordering:
+  // a grant without its flag must refuse before attach can print an older run's verdict.
+  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
+  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
+  // attach(), while --continue must refuse to overlap that live work.
+  const continuationError = continuationRefusal(
+    projectRunsRoot,
+    startedChain,
+    opts.continue,
+    opts.orderId,
+    continuationGrant,
+  );
+  if (continuationError) die(continuationError);
 
   // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
   // restart the synchronous launcher. A live same-order run is now the repeat target: attach
@@ -134,20 +165,8 @@ export async function launcher() {
   });
   if (attachedExitCode !== null) process.exit(attachedExitCode);
 
-  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
-  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
-  // attach(), while --continue must refuse to overlap that live work.
-  const continuationError = continuationRefusal(
-    projectRunsRoot,
-    chain,
-    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 +174,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 +185,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 +211,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 +222,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 +234,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 +331,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 +349,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 +369,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/stop-contract.mjs

@@ -0,0 +1,15 @@
+export const STOP_COMMAND = 'codex-bridge stop';
+export const STOP_COMMAND_TEMPLATE = `${STOP_COMMAND} <run>`;
+export const STOP_REASON =
+  'TaskStop removes the wrapper while the run keeps writing to the worktree.';
+
+export function renderStopCommand(run) {
+  if (typeof run !== 'string' || !run.trim()) {
+    throw new TypeError('A run folder name is required to render the stop command.');
+  }
+  return `${STOP_COMMAND} ${run.trim()}`;
+}
+
+export function renderStopSummary() {
+  return `Stop live runs with \`${STOP_COMMAND_TEMPLATE}\` before \`TaskStop\`: ${STOP_REASON}`;
+}

package/src/write-meta.mjs

@@ -22,6 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJsonFileSync } from './json-file.mjs';
 import { changedPaths, readJson, readText, size } from './meta/paths.mjs';
 import { splitRunChanges } from './meta/environment.mjs';
 import { readEvents } from './meta/events.mjs';
@@ -29,9 +30,18 @@ import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
 import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
 
+const RUNNER_VERSION = readJsonFileSync(new URL('../package.json', import.meta.url)).version;
+
 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 };
 
@@ -77,6 +87,7 @@ export function collect(runDir, agent, exitCode) {
 
   const meta = {
     agent,
+    runner_version: RUNNER_VERSION,
     project: path.basename(path.dirname(runDir)),
     run: path.basename(runDir),
     finished_at: new Date().toISOString(),