@lyupro/codex-bridge 0.6.8 → 0.6.10

package/src/home/lib/runner/advise-carry.mjs

@@ -1,4 +1,5 @@
 /** Owns the scope snapshot shared by advise readers because run 2026-09-23_141341_plan59-a1-stdin-hang left them with different inputs. */
+import { EXIT } from './exit-codes.mjs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { parseAdvisorTask } from '../meta/advisor-task.mjs';
@@ -32,7 +33,7 @@ export function advisorTaskOrRefuse(input) {
   try {
     return advisorTaskArtifact(input);
   } catch (error) {
-    return die(`${error.message} The run folder was not created; quota was not spent.`, 1);
+    return die(`${error.message} The run folder was not created; quota was not spent.`, EXIT.FAIL);
   }
 }
 

package/src/home/lib/runner/args.mjs

@@ -5,24 +5,26 @@
  * else's quota is touched, and every refusal is an exit code rather than a message: a
  * dispatcher branches on it.
  */
+import { EXIT } from './exit-codes.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { isAbsoluteTaskFilePath, requiredInputsFor } from '../required-inputs.mjs';
 import { firstShellUnsafeSequence } from '../shell-unsafe.mjs';
 import { parseTaskDocument } from './task-file.mjs';
+import { parseTaskHeader, taskHeaderRefusal } from '../task-header.mjs';
 
 export class RunnerUsageError extends Error {
   // 2 says the order itself is wrong and has to be rewritten. A refusal about the state of the
   // host or the worktree passes 1: the order was fine, nothing about it needs changing, and
   // Plan_58 moved two such refusals here from a code path that already answered 1.
-  constructor(message, exitCode = 2) {
+  constructor(message, exitCode = EXIT.USAGE) {
     super(message);
     this.exitCode = exitCode;
   }
 }
 
-export function die(message, exitCode = 2) {
+export function die(message, exitCode = EXIT.USAGE) {
   console.error(`run-codex: ${message}`);
   throw new RunnerUsageError(message, exitCode);
 }
@@ -46,9 +48,14 @@ export function readTaskDocument(opts) {
       die(`task file from --task-file could not be read: ${err.message}`);
     }
     if (!fileText.trim()) die(`task file from --task-file is empty: ${taskFile}`);
+    // Plan_75 D5, 2026-10-03 20:42: validate raw metadata before sections can hide a grant.
+    const parsed = parseTaskHeader(fileText);
+    const refusal = taskHeaderRefusal(parsed);
+    if (refusal) die(`${taskFile}: ${refusal}`);
+    if (!parsed.body.trim()) die(`task file from --task-file is empty: ${taskFile}`);
     let document;
     try {
-      document = parseTaskDocument(fileText);
+      document = parseTaskDocument(parsed.body);
     } catch (err) {
       die(`${taskFile}: ${err.message}`);
     }
@@ -58,11 +65,15 @@ export function readTaskDocument(opts) {
     if (document.verify !== undefined && opts.verify !== undefined) {
       die('verification command was supplied through both --verify and the task file; choose exactly one channel');
     }
-    return document;
+    return { ...document, header: parsed };
   }
   if (!stdinText.trim()) die('task text on stdin is empty');
+  const parsed = parseTaskHeader(stdinText);
+  const refusal = taskHeaderRefusal(parsed);
+  if (refusal) die(refusal);
+  if (!parsed.body.trim()) die('task text on stdin is empty');
   try {
-    return parseTaskDocument(stdinText);
+    return { ...parseTaskDocument(parsed.body), header: parsed };
   } catch (err) {
     die(err.message);
   }

package/src/home/lib/runner/attach.mjs

@@ -1,12 +1,13 @@
 /** Finds a live run for an order and waits for its verdict when a repeated launcher call attaches. */
+import { EXIT } from './exit-codes.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { workerMayBeAlive } from '../meta/run-liveness.mjs';
 import { processAlive } from '../process-identity.mjs';
 import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
-import { sameRun } from './continuation.mjs';
-import { conflictingOrderOwner, runsForOrder } from './order-owner.mjs';
+import { readyGrantLines, sameRun } from './continuation.mjs';
+import { conflictingOrderOwner, orderOwnerConflictText, runsForOrder } from './order-owner.mjs';
 
 // The attach call is the only process that waits for a worker it did not spawn. Keeping that
 // wait here leaves the launcher free to return before a caller's time ceiling kills it.
@@ -97,26 +98,26 @@ export async function waitForReply(runDir, workerPid, status) {
  * reason. `--continue` may attach to a run created from its grant: the 2026-09-23 dispatcher
  * incident showed that repeating the identical continuation command must return to that run.
  */
-export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, grantRun, isContinue, noWait } = {}) {
+export async function attach({
+  runsRoot, repo, slug, taskHash, orderId, chain, grantRun, retryRun, isContinue, noWait, beforeWait,
+} = {}) {
   const runs = chain || chainRuns(runsRoot, repo, slug, taskHash, orderId);
   const runRecords = runs
     .map((run) => ({ run, status: readJsonFile(path.join(runsRoot, run, 'status.json')) }))
     .filter(({ status }) => status);
   const sameOrder = runsForOrder(runRecords, orderId);
   const attachRuns = isContinue
-    ? sameOrder.filter(({ status }) => grantRun && status.continued_from && sameRun(runsRoot, status.continued_from, grantRun))
+    ? sameOrder.filter(({ status }) => retryRun
+      ? status.retry_of && sameRun(runsRoot, status.retry_of, retryRun)
+      : grantRun && status.continued_from && sameRun(runsRoot, status.continued_from, grantRun))
     : sameOrder;
   if (isContinue && !attachRuns.length) return null;
 
   const owner = isContinue ? null : conflictingOrderOwner(runRecords, orderId, taskHash);
   if (owner) {
     const ownerDir = path.join(runsRoot, owner.run);
-    console.log(
-      `Order id collision: ${JSON.stringify(String(orderId ?? ''))} already belongs to run folder ${ownerDir} ` +
-        `(slug ${owner.status.slug}, started_at ${owner.status.started_at}) with a different task. ` +
-        'Pass a new --order-id, or pass --continue if this really is another pass of the same order.',
-    );
-    return 2;
+    console.log(orderOwnerConflictText(owner, ownerDir, orderId));
+    return EXIT.USAGE;
   }
 
   // The run an order is currently about is its newest one, and the chain arrives oldest first.
@@ -130,7 +131,12 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
     if (fs.existsSync(path.join(dir, 'reply.txt'))) {
       announceSavedReply(dir, orderId, entry.status.started_at);
       console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
-      return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
+      const meta = readJsonFile(path.join(dir, 'meta.json'));
+      // Plan_75 D1, 2026-10-03 TradeForge: a cached failure must name its current repair.
+      if (meta?.status !== 'OK' && entry.run === runs.at(-1)) {
+        console.log(readyGrantLines(runsRoot, runs));
+      }
+      return exitCodeFor(meta?.status);
     }
     if (workerMayBeAlive({ runDir: dir, status: entry.status })) {
       candidate = entry;
@@ -140,7 +146,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
   if (!candidate) {
     if (!noWait) return null;
     console.log(`No run exists for order id ${JSON.stringify(String(orderId ?? ''))}; --no-wait never starts a new run.`);
-    return 4;
+    return EXIT.PENDING;
   }
 
   const runDir = path.join(runsRoot, candidate.run);
@@ -148,8 +154,9 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
   // A distinct call outcome lets the dispatcher inspect disk without mistaking pending for failure.
   if (noWait) {
     announcePending(runDir, orderId, candidate.status.started_at);
-    return 4;
+    return EXIT.PENDING;
   }
+  await beforeWait?.();
   announceLiveAttach(runDir, orderId, candidate.status.started_at);
   const replyText = await waitForReply(runDir, candidate.status.pid, candidate.status);
   if (replyText !== null) {
@@ -174,5 +181,5 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, g
     'Any Codex changes remain in the tree — check them with git status',
   ]);
   console.log(reply);
-  return 1;
+  return EXIT.FAIL;
 }

package/src/home/lib/runner/build-evidence.mjs

@@ -0,0 +1,29 @@
+/**
+ * Writes the evidence a build run leaves of the tree before and after it.
+ * The before half was written by the launcher and the after half by the worker, so one artifact pair was
+ * named in two files; Plan_60 D3a adds a content baseline and its comparison to both halves.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, headSha, branchName, worktreeSnapshot } from './git-state.mjs';
+import { captureFlagBaseline } from './flag-baseline.mjs';
+import { scanRunFlags } from './flag-scan.mjs';
+
+export function writeBuildBefore({ runDir, repoRoot, isGitRepo }) {
+  fs.writeFileSync(path.join(runDir, 'head-before.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'branch-before.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'git-before.txt'), git(repoRoot, ['-c', 'core.quotepath=false', 'status', '--porcelain']).stdout || '');
+  fs.writeFileSync(path.join(runDir, 'state-before.txt'), worktreeSnapshot(repoRoot));
+  captureFlagBaseline({ runDir, repoRoot, isGitRepo });
+}
+
+export function writeBuildAfter({ runDir, repoRoot, isGitRepo }) {
+  fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'branch-after.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
+  fs.writeFileSync(path.join(runDir, 'git-after.txt'), git(repoRoot, ['-c', 'core.quotepath=false', 'status', '--porcelain']).stdout || '');
+  fs.writeFileSync(path.join(runDir, 'state-after.txt'), worktreeSnapshot(repoRoot));
+  fs.writeFileSync(path.join(runDir, 'diff.stat'), git(repoRoot, ['-c', 'core.quotepath=false', 'diff', '--stat']).stdout || '');
+  const scan = scanRunFlags({ runDir, repoRoot });
+  fs.writeFileSync(path.join(runDir, 'flags.txt'), scan.text);
+  fs.writeFileSync(path.join(runDir, 'flags-coverage.txt'), scan.coverage.gaps.map((gap) => `${gap}\n`).join(''));
+}

package/src/home/lib/runner/codex-availability.mjs

@@ -0,0 +1,50 @@
+/**
+ * Decides from conclusive evidence only whether Codex is missing, signed out, available, or cannot be judged.
+ * Plan_60 D2: an inconclusive probe must never become "do not retry".
+ */
+import { resolveCommandOnPath } from '../command-path.mjs';
+import { codexSpawnSpec, spawnCaptured } from './codex-cmd.mjs';
+
+// A signed-in answer takes ~200 ms; ten seconds bounds a hung CLI without delaying a healthy start.
+export const PROBE_TIMEOUT_MS = 10_000;
+
+function lines(text) {
+  return String(text ?? '').split(/[\r\n]+/).map((line) => line.trim()).filter(Boolean);
+}
+
+function failureDetail(result, command) {
+  return lines(result.stderr).at(-1)
+    || lines(result.error?.message).at(-1)
+    || `${command} exited ${result.status}`;
+}
+
+export async function probeCodexAvailability({
+  env = process.env, platform = process.platform,
+  run = spawnCaptured, resolve = resolveCommandOnPath, timeoutMs = PROBE_TIMEOUT_MS,
+} = {}) {
+  try {
+    if (resolve('codex', env) === null) {
+      return { state: 'missing', detail: 'codex is not on PATH' };
+    }
+    const capture = (args) => {
+      const spec = codexSpawnSpec(args, platform);
+      return run(spec.command, spec.args, { ...spec.options, env, timeout: timeoutMs, encoding: 'utf8' });
+    };
+    const version = await capture(['--version']);
+    if (version.error || version.status !== 0) {
+      return { state: 'inconclusive', detail: failureDetail(version, 'codex --version') };
+    }
+    const login = await capture(['login', 'status']);
+    // Plan_60 D2: capture errors invalidate even a familiar line; only a completed probe proves sign-out.
+    if (login.error) {
+      return { state: 'inconclusive', detail: failureDetail(login, 'codex login status') };
+    }
+    if (login.status === 0) return { state: 'available' };
+    if (login.status === 1 && [...lines(login.stderr), ...lines(login.stdout)].includes('Not logged in')) {
+      return { state: 'logged-out', detail: 'codex login status: Not logged in' };
+    }
+    return { state: 'inconclusive', detail: failureDetail(login, 'codex login status') };
+  } catch (error) {
+    return { state: 'inconclusive', detail: lines(error?.message).at(-1) || 'codex availability probe failed' };
+  }
+}

package/src/home/lib/runner/codex-cmd.mjs

@@ -1,6 +1,6 @@
 /**
- * Invoking the `codex` CLI: starting it, stopping its whole tree, telling whether it is there at
- * all, and keeping its JSONL stdout in events.jsonl while stderr stays separate.
+ * Invoking the `codex` CLI: starting it, stopping its whole tree, and keeping its JSONL stdout
+ * in events.jsonl while stderr stays separate. Availability belongs to codex-availability.mjs.
  *
  * Which flags a run gets is the neighbouring codex-args.mjs: this file starts the process and
  * stops it, and knows nothing about what the arguments mean. The two were one module until it
@@ -336,20 +336,3 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes, graceMs = ST
     child.on('close', (code) => finish(code, true));
   });
 }
-
-/**
- * Codex missing or not authorised is a deterministic FAIL, never a reason to improvise.
- * Plan_58, 2026-09-19: return a reason for refusal before registration, like the dead-sandbox
- * probe. One no-quota question must not have two answers about whether it leaves a folder.
- */
-export function codexUnavailableReason() {
-  const probe = spawnSync(
-    process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex',
-    process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'],
-    { encoding: 'utf8', windowsHide: true },
-  );
-  if (probe.error || probe.status !== 0) {
-    return (probe.stderr || probe.error?.message || 'codex --version is not responding').trim();
-  }
-  return null;
-}

package/src/home/lib/runner/continuation.mjs

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CONTINUATION_INPUT, parseContinuationGrant } from '../required-inputs.mjs';
 import { readJson } from '../write-meta.mjs';
+import { workerMayBeAlive } from '../meta/run-liveness.mjs';
 
 // One comparison of run names for the grant gate and for attach, so a repeat and a grant can never
 // disagree about whether two spellings name the same folder.
@@ -48,7 +49,20 @@ function lastRunOutcome(runsRootPath, chain) {
   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 };
+  return { run, status: outcomeStatus, reason: outcomeReason, verdict: meta.status, orderId: status.order_id };
+}
+
+export function readyGrantLines(runsRootPath, chain, grantReason) {
+  const last = lastRunOutcome(runsRootPath, chain);
+  if (!last) return 'Ready grant line: none (there is no run to continue).';
+  const reason = String(grantReason ?? last.reason).trim() || last.reason;
+  const continuation = `Ready grant line: continue: ${last.run} — ${reason}.`;
+  // Plan_75 D1: the TradeForge failed advise spent its continuation, so show the same-pass repair.
+  // A run without order_id cannot be retried (retryRefusal step d), so it gets no retry line.
+  const orderId = String(last.orderId ?? '').trim();
+  if (!last.verdict || last.verdict === 'OK' || !orderId) return continuation;
+  return continuation +
+    ` Ready retry line: retry: ${last.run} — ${last.reason} (repeats that pass under order ${orderId}).`;
 }
 
 function lastRunHints(runsRootPath, chain, grantReason) {
@@ -56,9 +70,8 @@ function lastRunHints(runsRootPath, chain, grantReason) {
   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}.`;
+    readyGrantLines(runsRootPath, chain, grantReason);
 }
 
 /**
@@ -86,6 +99,7 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
   if (!continuation) {
     return (
       '--continue is refused: the orchestrator did not provide a `continue:` grant in the task text. ' +
+      `${lastRunHints(runsRootPath, chain)} ` +
       `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
     );
   }
@@ -109,19 +123,23 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
       `--continue is refused: grant ${continuation.run} is not the LAST run of this task's chain; ` +
       `the current last run is ${last || 'none'}. A continuation is single-use: continuing the ` +
       'last run appends a later run, so the old grant stops matching by itself — no counter or new ' +
-      `state is used. ${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+      `state is used. ${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
     );
   }
 
   const wanted = String(orderId ?? '').trim();
-  const ofThisOrder = chain.filter(
-    (run) => String(readJson(path.join(runsRootPath, run, 'status.json'))?.order_id ?? '').trim() === wanted,
-  );
+  // Plan_75 D1, TradeForge capacity incident: a retry spends no new pass, even after an OK verdict.
+  const ofThisOrder = chain.filter((run) => {
+    const status = readJson(path.join(runsRootPath, run, 'status.json'));
+    return String(status?.order_id ?? '').trim() === wanted && !String(status?.retry_of ?? '').trim();
+  });
   if (ofThisOrder.length === 0) return null;
   if (ofThisOrder.length > 1) {
     const spent = ofThisOrder.map((run) => path.join(runsRootPath, run)).join(', ');
     return (
       `--continue is refused: order “${wanted}” already spent its allowed continuation on ${spent}. ` +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
       'A further pass needs a new order id from the orchestrator. The run folder was not ' +
       'created; quota was not spent.'
     );
@@ -132,9 +150,43 @@ export function continuationRefusal(runsRootPath, chain, isContinue, orderId, gr
   if (!meta?.status || status?.state === 'running') {
     return (
       `--continue is refused: previous run ${previous} has no finished verdict and may still ` +
-      'be editing the worktree. Repeat without --continue to attach to it. The run folder was ' +
+      'be editing the worktree. Repeat without --continue to attach to it. ' +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} The run folder was ` +
       'not created; quota was not spent.'
     );
   }
   return null;
 }
+
+export function retryRefusal(runsRootPath, chain, isContinue, orderId, grant, liveness = workerMayBeAlive) {
+  const refuse = (message) => `${message} The run folder was not created; quota was not spent.`;
+  if (!isContinue) {
+    return refuse('--continue is required for a `retry:` grant: the orchestrator deliberately repeats the same pass.');
+  }
+  const runDir = namedRunDirectory(runsRootPath, grant?.run);
+  if (!runDir) {
+    return refuse(`Retry is refused: ${grant?.run || 'none'} is not a bare existing run folder in ${runsRootPath}.`);
+  }
+  const last = chain[chain.length - 1];
+  // Plan_75 D1: appending the TradeForge retry makes this grant single-use without a new counter.
+  if (!last || !sameRun(runsRootPath, grant.run, last)) {
+    return refuse(`Retry is refused: grant ${grant.run} is not the LAST run of this task's chain; a retry is single-use.`);
+  }
+  const status = readJson(path.join(runDir, 'status.json'));
+  const wanted = String(orderId ?? '').trim();
+  const previousOrder = String(status?.order_id ?? '').trim();
+  if (!previousOrder || previousOrder !== wanted) {
+    return refuse(`Retry is refused: run ${grant.run} order_id ${previousOrder || '(missing)'} differs from order ${wanted}. ` +
+      'A retry repeats its own order; a run without order_id predates orders — start a new order.');
+  }
+  const meta = readJson(path.join(runDir, 'meta.json'));
+  // Plan_75 D1: a verdict alone must not let a retry overlap the failed advise's live writer.
+  if (!meta?.status || liveness({ runDir, status })) {
+    return refuse(`Retry is refused: run ${grant.run} has no finished verdict or its worker may still be alive and writing. ` +
+      'Repeat without --continue to attach to it.');
+  }
+  if (meta.status === 'OK') {
+    return refuse(`Retry is refused: run ${grant.run} ended OK. A retry repeats a failed pass; use continue: for the next pass.`);
+  }
+  return null;
+}

package/src/home/lib/runner/exit-codes.mjs

@@ -0,0 +1,13 @@
+/**
+ * Owns every exit code the runner returns.
+ * Plan_60 D2a: a new status took code 4, already the released --no-wait outcome, because the codes
+ * were literals scattered over six modules.
+ */
+export const EXIT = Object.freeze({
+  OK: 0,          // the run's artifacts confirm the contract
+  FAIL: 1,        // the run failed, or a pre-flight refusal: the order was right, the host or tree was not
+  USAGE: 2,       // argument error: the order itself must be rewritten
+  LIMIT: 3,       // ChatGPT quota exhausted; not a task failure
+  PENDING: 4,     // --no-wait only: the run is still in progress, or no run exists (a call outcome, not a status)
+  UNAVAILABLE: 5, // Codex missing or signed out; hand the task to the next executor
+});

package/src/home/lib/runner/flag-baseline.mjs

@@ -0,0 +1,105 @@
+/**
+ * Records dirty files' start bytes so Plan_60 D3a can distinguish this run's flags from earlier uncommitted work.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { headSha, runsPrefixInside } from './git-state.mjs';
+import { diffNames, listUntrackedPaths } from './git-paths.mjs';
+import { readJsonFileSync } from '../json-file.mjs';
+
+export const FLAG_BASELINE_VERSION = 1;
+export const FLAG_BASELINE_MANIFEST = 'flags-baseline.json';
+export const FLAG_BASELINE_DIR = 'flags-baseline';
+export const FLAG_BASELINE_LIMITS = Object.freeze({
+  perFileBytes: 1024 * 1024,
+  perRunBytes: 32 * 1024 * 1024,
+});
+
+export function captureFlagBaseline({ runDir, repoRoot, isGitRepo, limits = FLAG_BASELINE_LIMITS }) {
+  const manifest = {
+    version: FLAG_BASELINE_VERSION,
+    head: '',
+    complete: false,
+    reason: '',
+    limits: { ...limits },
+    files: [],
+  };
+  if (!isGitRepo) {
+    manifest.reason = 'not a git repository';
+  } else {
+    const head = headSha(repoRoot);
+    // rev-parse prints the literal HEAD on an unborn branch; it is not a start commit.
+    manifest.head = head === 'HEAD' ? '' : head;
+    if (!manifest.head) {
+      manifest.reason = 'no start commit';
+    } else {
+      const dirty = diffNames(repoRoot, 'HEAD');
+      const untracked = listUntrackedPaths(repoRoot);
+      if (dirty === null || untracked === null) {
+        manifest.reason = 'git listing failed';
+      } else {
+        const tracked = new Set(dirty);
+        const skip = runsPrefixInside(repoRoot);
+        const names = [...new Set([...dirty, ...untracked])]
+          .filter((name) => !(skip && `${name}/`.startsWith(skip)))
+          .sort();
+        let total = 0;
+        for (const [index, name] of names.entries()) {
+          const entry = { path: name, tracked: tracked.has(name), state: 'unreadable' };
+          manifest.files.push(entry);
+          const full = path.join(repoRoot, name);
+          let content;
+          try {
+            const stat = fs.lstatSync(full);
+            if (!stat.isFile()) continue;
+            if (stat.size > limits.perFileBytes) {
+              entry.state = 'truncated';
+              continue;
+            }
+            if (total + stat.size > limits.perRunBytes) {
+              entry.state = 'over-run-cap';
+              continue;
+            }
+            content = fs.readFileSync(full);
+          } catch (error) {
+            if (error.code === 'ENOENT') entry.state = entry.tracked ? 'deleted' : 'absent';
+            continue;
+          }
+          // Recheck actual bytes: the file may have grown since its metadata was read.
+          if (content.length > limits.perFileBytes) {
+            entry.state = 'truncated';
+          } else if (total + content.length > limits.perRunBytes) {
+            entry.state = 'over-run-cap';
+          } else if (content.subarray(0, 8000).includes(0)) {
+            entry.state = 'binary';
+          } else {
+            const copyDir = path.join(runDir, FLAG_BASELINE_DIR);
+            fs.mkdirSync(copyDir, { recursive: true });
+            const copy = `${index}.bin`;
+            fs.writeFileSync(path.join(copyDir, copy), content);
+            Object.assign(entry, { state: 'copied', copy, bytes: content.length });
+            total += content.length;
+          }
+        }
+        manifest.complete = manifest.files.every((entry) =>
+          ['copied', 'deleted', 'absent'].includes(entry.state));
+        if (!manifest.complete) manifest.reason = 'some start contents are unknown';
+      }
+    }
+  }
+  fs.writeFileSync(path.join(runDir, FLAG_BASELINE_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export function readFlagBaseline(runDir) {
+  try {
+    const manifest = readJsonFileSync(path.join(runDir, FLAG_BASELINE_MANIFEST));
+    return manifest?.version === FLAG_BASELINE_VERSION ? manifest : null;
+  } catch {
+    return null;
+  }
+}
+
+export function removeFlagBaselineCopies(runDir) {
+  fs.rmSync(path.join(runDir, FLAG_BASELINE_DIR), { recursive: true, force: true });
+}