@lyupro/codex-bridge 0.6.9 → 0.6.11

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

@@ -1,140 +1,174 @@
-/**
- * Owns the zero-quota decision about whether a requested continuation was ordered.
- *
- * The 2026-08-05 incident showed why the runner must not infer a second pass from a verdict:
- * only the orchestrator read that verdict and can name the run and reason it is willing to fund.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { CONTINUATION_INPUT, parseContinuationGrant } from '../required-inputs.mjs';
-import { readJson } from '../write-meta.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.
-export const sameRun = (runsRootPath, left, right) => {
-  const a = path.resolve(runsRootPath, left);
-  const b = path.resolve(runsRootPath, right);
-  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
-};
-
-function namedRunDirectory(runsRootPath, run) {
-  if (!run || run === '.' || run === '..' || path.basename(run) !== run) return null;
-  const directory = path.join(runsRootPath, run);
-  try {
-    return fs.statSync(directory).isDirectory() ? directory : null;
-  } catch {
-    return null;
-  }
-}
-
-function normalizeGrant(grant) {
-  if (typeof grant === 'string') return parseContinuationGrant(grant);
-  if (!grant || typeof grant !== 'object') return null;
-  const run = String(grant.run ?? '').trim();
-  const reason = String(grant.reason ?? '').trim();
-  return run && reason ? { run, reason } : null;
-}
-
-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.
- *
- * The limit is counted over the runs carrying THIS order id, not over the whole chain. The chain
- * also ties runs together by slug and by the fingerprint of the task text, which is what catches a
- * repeat that renamed itself — but counting continuations that way makes the escape hatch
- * unreachable: the operator's rule is "more passes than one need a new order id", and a new order
- * id lands in the same chain through the task hash. A task would then be refused with --continue
- * for having spent its continuation and refused without it for already having runs — permanently
- * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
- */
-export function continuationRefusal(runsRootPath, chain, isContinue, orderId, grant) {
-  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. ' +
-      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
-    );
-  }
-
-  const namedDirectory = namedRunDirectory(runsRootPath, continuation.run);
-  if (!namedDirectory) {
-    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}. ` +
-      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
-      `${grantExample} ${grantAction} The submitted grant was not rewritten. ` +
-      'The run folder was not created; quota was not spent.'
-    );
-  }
-
-  const last = chain[chain.length - 1];
-  // Continuing the last run appends a later run, so the old grant stops matching by itself; this
-  // incident needs no counter or new state to make an orchestrator grant single-use.
-  if (!last || !sameRun(runsRootPath, continuation.run, last)) {
-    return (
-      `--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.`
-    );
-  }
-
-  const wanted = String(orderId ?? '').trim();
-  const ofThisOrder = chain.filter(
-    (run) => String(readJson(path.join(runsRootPath, run, 'status.json'))?.order_id ?? '').trim() === wanted,
-  );
-  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}. ` +
-      'A further pass needs a new order id from the orchestrator. The run folder was not ' +
-      'created; quota was not spent.'
-    );
-  }
-  const previous = path.join(runsRootPath, ofThisOrder[0]);
-  const status = readJson(path.join(previous, 'status.json'));
-  const meta = readJson(path.join(previous, 'meta.json'));
-  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 ' +
-      'not created; quota was not spent.'
-    );
-  }
-  return null;
-}
+/**
+ * Owns the zero-quota decision about whether a requested continuation was ordered.
+ *
+ * The 2026-08-05 incident showed why the runner must not infer a second pass from a verdict:
+ * only the orchestrator read that verdict and can name the run and reason it is willing to fund.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONTINUATION_ORDER_INPUT, orderInputName } from '../order-schema.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.
+export const sameRun = (runsRootPath, left, right) => {
+  const a = path.resolve(runsRootPath, left);
+  const b = path.resolve(runsRootPath, right);
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+
+function namedRunDirectory(runsRootPath, run) {
+  if (!run || run === '.' || run === '..' || path.basename(run) !== run) return null;
+  const directory = path.join(runsRootPath, run);
+  try {
+    return fs.statSync(directory).isDirectory() ? directory : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeGrant(grant) {
+  if (!grant || typeof grant !== 'object') return null;
+  const run = String(grant.run ?? '').trim();
+  const reason = String(grant.reason ?? '').trim();
+  return run && reason ? { run, reason } : null;
+}
+
+const grantExample = `Example: \`continue: ${CONTINUATION_ORDER_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, 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) {
+  const last = lastRunOutcome(runsRootPath, chain);
+  if (!last) {
+    return 'Last run: none. Outcome: none. Ready grant line: none (there is no run to continue).';
+  }
+  return `Last run: ${last.run}. Outcome: ${last.status} — ${last.reason}. ` +
+    readyGrantLines(runsRootPath, chain, grantReason);
+}
+
+/**
+ * Applies the one-continuation limit and all continuation safety gates before a folder is created.
+ *
+ * The limit is counted over the runs carrying THIS order id, not over the whole chain. The chain
+ * also ties runs together by slug and by the fingerprint of the task text, which is what catches a
+ * repeat that renamed itself — but counting continuations that way makes the escape hatch
+ * unreachable: the operator's rule is "more passes than one need a new order id", and a new order
+ * id lands in the same chain through the task hash. A task would then be refused with a grant
+ * for having spent its continuation and refused without one for already having runs — permanently
+ * unrunnable, which is a worse failure than the retry storm this limit exists to stop.
+ */
+export function continuationRefusal(runsRootPath, chain, isContinue, orderId, grant) {
+  const continuation = normalizeGrant(grant);
+  // Plan_63 D9: only header grant objects authorize a pass; a string is no grant.
+  if (!isContinue || !continuation) return null;
+
+  const namedDirectory = namedRunDirectory(runsRootPath, continuation.run);
+  if (!namedDirectory) {
+    return (
+      `${orderInputName('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}. ` +
+      `${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${grantExample} ${grantAction} The submitted grant was not rewritten. ` +
+      'The run folder was not created; quota was not spent.'
+    );
+  }
+
+  const last = chain[chain.length - 1];
+  // Continuing the last run appends a later run, so the old grant stops matching by itself; this
+  // incident needs no counter or new state to make an orchestrator grant single-use.
+  if (!last || !sameRun(runsRootPath, continuation.run, last)) {
+    return (
+      `${orderInputName('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. ${lastRunHints(runsRootPath, chain, continuation.reason)} ` +
+      `${grantExample} ${grantAction} The run folder was not created; quota was not spent.`
+    );
+  }
+
+  const wanted = String(orderId ?? '').trim();
+  // 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 (
+      `${orderInputName('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.'
+    );
+  }
+  const previous = path.join(runsRootPath, ofThisOrder[0]);
+  const status = readJson(path.join(previous, 'status.json'));
+  const meta = readJson(path.join(previous, 'meta.json'));
+  if (!meta?.status || status?.state === 'running') {
+    return (
+      `${orderInputName('continue')} is refused: previous run ${previous} has no finished verdict and may still ` +
+      `be editing the worktree. Repeat without ${orderInputName('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.`;
+  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 ${orderInputName('retry')} 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 });
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Judges added lines against start bytes because Plan_60 D3a must not blame earlier dirty work or TODO test data.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readFlagBaseline, removeFlagBaselineCopies, FLAG_BASELINE_DIR } from './flag-baseline.mjs';
+import { runSnapshotChanges } from '../meta/run-snapshots.mjs';
+
+const STUB = /test\.(skip|only)|it\.(skip|only)|describe\.(skip|only)|NotImplemented/;
+const MARKER_PREFIX = /(?:^[ \t]*|\/\/[ \t]*|\/\*+[ \t]*|#[ \t]*|<!--[ \t]*|--[ \t]*|^[ \t]*\*[ \t]*)$/;
+const LIST_PREFIX = /^[ \t]*(?:[-+*]|\d+[.)])[ \t]+(?:\[[ xX]\][ \t]+)?$/;
+
+export function isFlagLine(text) {
+  if (STUB.test(text)) return true;
+  for (const match of text.matchAll(/(?:TODO|FIXME)(?![A-Za-z0-9_])/g)) {
+    const prefix = text.slice(0, match.index);
+    if (MARKER_PREFIX.test(prefix) || LIST_PREFIX.test(prefix)) return true;
+  }
+  return false;
+}
+
+function addedLines(diff) {
+  const added = [];
+  let inside = false;
+  let number = 0;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('diff ')) {
+      inside = false;
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk) {
+      inside = true;
+      number = Number(hunk[1]);
+    } else if (inside && line.startsWith('+')) {
+      added.push({ number, text: line.slice(1) });
+      number += 1;
+    } else if (inside && line.startsWith(' ')) {
+      number += 1;
+    }
+  }
+  return added;
+}
+
+function compareFile(baseFile, currentFile) {
+  const result = spawnSync('git', [
+    '-c', 'core.quotepath=false', 'diff', '--no-index', '--no-color', '--no-ext-diff', '--no-textconv',
+    '--ignore-cr-at-eol', '--diff-algorithm=myers', '-U0', '--', baseFile, currentFile,
+  ], { windowsHide: true, timeout: 30_000, maxBuffer: 8 * 1024 * 1024 });
+  if (result.error || ![0, 1].includes(result.status)) return null;
+  return result.status === 0 ? [] : addedLines(result.stdout.toString('utf8'));
+}
+
+// `git show <head>:<path>` exits non-zero both for a path the start commit lacks (a new file: every line is added)
+// and for a start commit nobody can read; only a readable commit lets the first case accuse anyone.
+function headReadable(repoRoot, head) {
+  const result = spawnSync('git', ['-C', repoRoot, 'cat-file', '-e', `${head}^{commit}`], {
+    windowsHide: true, timeout: 30_000,
+  });
+  return !result.error && result.status === 0;
+}
+
+function scanPath({ name, entry, baseline, headKnown, runDir, repoRoot, gaps }) {
+  const currentFile = path.join(repoRoot, name);
+  let current;
+  try {
+    const stat = fs.lstatSync(currentFile);
+    if (!stat.isFile()) return [];
+    if (stat.size > baseline.limits.perFileBytes) {
+      gaps.push(`${name}: end content over the limit`);
+      return [];
+    }
+    current = fs.readFileSync(currentFile);
+  } catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') gaps.push(`${name}: end content unreadable`);
+    return [];
+  }
+  if (current.length > baseline.limits.perFileBytes) {
+    gaps.push(`${name}: end content over the limit`);
+    return [];
+  }
+  if (current.subarray(0, 8000).includes(0)) return [];
+
+  let base = Buffer.alloc(0);
+  let baseFile;
+  let temporary = false;
+  if (entry) {
+    if (entry.state === 'copied') {
+      baseFile = path.join(runDir, FLAG_BASELINE_DIR, entry.copy);
+      try {
+        base = fs.readFileSync(baseFile);
+      } catch {
+        gaps.push(`${name}: start content unreadable`);
+        return [];
+      }
+    } else if (!['deleted', 'absent'].includes(entry.state)) {
+      gaps.push(`${name}: start content ${entry.state}`);
+      return [];
+    }
+  } else if (!headKnown) {
+    gaps.push(`${name}: start commit unreadable`);
+    return [];
+  } else {
+    const result = spawnSync('git', ['-C', repoRoot, 'show', `${baseline.head}:${name}`], {
+      windowsHide: true, timeout: 30_000, maxBuffer: 8 * 1024 * 1024,
+    });
+    if (result.error || result.status === null) {
+      gaps.push(`${name}: start content unreadable`);
+      return [];
+    }
+    if (result.status === 0) base = result.stdout;
+    if (base.length) {
+      const copyDir = path.join(runDir, FLAG_BASELINE_DIR);
+      fs.mkdirSync(copyDir, { recursive: true });
+      baseFile = path.join(copyDir, `head-${randomUUID()}.bin`);
+      fs.writeFileSync(baseFile, base, { flag: 'wx' });
+      temporary = true;
+    }
+  }
+
+  if (!base.length) {
+    return current.toString('utf8').split('\n').map((text, index) => ({ number: index + 1, text }));
+  }
+  let added;
+  try {
+    added = compareFile(baseFile, currentFile);
+  } finally {
+    if (temporary) fs.unlinkSync(baseFile);
+  }
+  if (added === null) {
+    gaps.push(`${name}: diff failed`);
+    return [];
+  }
+  return added;
+}
+
+export function scanRunFlags({ runDir, repoRoot }) {
+  const gaps = [];
+  const hits = [];
+  try {
+    const baseline = readFlagBaseline(runDir);
+    if (!baseline) {
+      gaps.push('no flag baseline');
+    } else if (!baseline.complete && baseline.files.length === 0) {
+      gaps.push(`flag baseline incomplete: ${baseline.reason}`);
+    } else {
+      const entries = new Map(baseline.files.map((entry) => [entry.path, entry]));
+      const comparison = runSnapshotChanges(runDir);
+      if (!comparison.ok) gaps.push('snapshots not comparable');
+      const names = [...new Set([...entries.keys(), ...(comparison.ok ? comparison.changed : [])])].sort();
+      const headKnown = headReadable(repoRoot, baseline.head);
+      for (const name of names) {
+        const added = scanPath({ name, entry: entries.get(name), baseline, headKnown, runDir, repoRoot, gaps });
+        for (const line of added) {
+          if (hits.length < 20 && isFlagLine(line.text)) hits.push(`${name}:${line.number}: ${line.text.trim()}\n`);
+        }
+      }
+    }
+  } finally {
+    removeFlagBaselineCopies(runDir);
+  }
+  return { text: hits.join(''), coverage: { complete: gaps.length === 0, gaps } };
+}

package/src/home/lib/runner/git-state.mjs

@@ -94,39 +94,6 @@ export const headSha = (repo) => (git(repo, ['rev-parse', 'HEAD']).stdout || '')
 export const branchName = (repo) =>
   (git(repo, ['symbolic-ref', '--short', '-q', 'HEAD']).stdout || '').trim();
 
-const FAKE_DONE_RE =
-  /TODO|FIXME|test\.(skip|only)|it\.(skip|only)|describe\.(skip|only)|NotImplemented/;
-
-/**
- * Traces of fake completion. `git diff` carries nothing for untracked files, so a brand
- * new file full of TODOs would otherwise pass as "Flags: none" — the one case the check
- * exists for.
- */
-export function findFakeDone(repo) {
-  const skip = runsPrefixInside(repo);
-  const hits = (git(repo, ['diff', '-U0']).stdout || '')
-    .split(/\r?\n/)
-    .filter((l) => l.startsWith('+') && FAKE_DONE_RE.test(l));
-  for (const file of (listUntrackedPaths(repo) ?? [])
-    // Same reason as in worktreeSnapshot: inside ~/.claude the run folder is part of the
-    // worktree, and task.md spells out the very words this scans for ("do not leave TODOs,
-    // test.skip"). A run flagged itself for quoting its own instructions.
-    .filter((file) => !(skip && `${file}/`.startsWith(skip)))) {
-    const full = path.join(repo, file);
-    try {
-      if (fs.statSync(full).size > 1024 * 1024) continue;
-      fs.readFileSync(full, 'utf8')
-        .split(/\r?\n/)
-        .forEach((l, i) => {
-          if (FAKE_DONE_RE.test(l)) hits.push(`${file}:${i + 1}: ${l.trim()}`);
-        });
-    } catch {
-      // Binary or unreadable: nothing to flag.
-    }
-  }
-  return hits.length ? `${hits.slice(0, 20).join('\n')}\n` : '';
-}
-
 /** What exactly is under review, resolved from git rather than from wording. */
 export function reviewScope(repo, changeset) {
   if (changeset.startsWith('base:')) {