@lyupro/codex-bridge 0.1.0

package/src/meta/chain.mjs

@@ -0,0 +1,87 @@
+/**
+ * Finds the earlier passes of the task a run belongs to.
+ *
+ * Runs are tied together by slug or by the task text itself, against the repository — all
+ * read from the status.json each run writes before Codex is even probed. Nothing here judges
+ * a run; it only says which other runs were the same task, so a verdict can be graded against
+ * the whole of it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { normalizePath, readJson } from './paths.mjs';
+
+/**
+ * What makes two runs the same task when their names disagree.
+ *
+ * The slug alone cannot answer it: the slug is chosen by whoever repeats the run. On
+ * 2026-08-02 a dispatcher lost its launcher to a kill, decided the run had died, and started
+ * the identical task again as `<slug>-v2` — 46k of quota on a repeat the --continue gate was
+ * built to refuse. Whitespace and case are normalized away because the same order re-sent
+ * through a shell is rewrapped, not rewritten; anything more forgiving would tie together
+ * tasks that merely look alike.
+ */
+export const taskFingerprint = (taskText) => {
+  const normalized = String(taskText ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+  return normalized ? createHash('sha256').update(normalized).digest('hex').slice(0, 16) : '';
+};
+
+/**
+ * Every run of one task, oldest first — same slug against the same repository. A task is
+ * not a run: after a kill or a LIMIT the work is finished by a second pass, and grading
+ * that pass against its own delta alone is what produced the false verdict of
+ * 2026-07-31_121703, where Codex found its earlier edits already in place, listed them
+ * honestly, changed nothing and was told it had done no work. Folder names rather than
+ * full paths; the current run joins the list as soon as its status.json exists.
+ */
+export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '') {
+  const wantedRepo = normalizePath(repo);
+  const wantedSlug = String(slug ?? '').trim().toLowerCase();
+  const wantedHash = String(taskHash ?? '').trim().toLowerCase();
+  const wantedOrderId = String(orderId ?? '').trim();
+  // No handle on the task, or no repo, means nothing to chain — an empty context must find
+  // nothing rather than fall back to "every run in this folder".
+  if (!wantedRepo || (!wantedSlug && !wantedHash && !wantedOrderId)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const runs = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const status = readJson(path.join(runsRoot, entry.name, 'status.json'));
+    if (!status) continue;
+    // Either handle identifies the task. The hash catches a repeat that renamed itself; the
+    // slug still catches the follow-up whose wording the orchestrator edited on purpose.
+    const sameSlug = Boolean(wantedSlug) && String(status.slug ?? '').trim().toLowerCase() === wantedSlug;
+    const sameTask = Boolean(wantedHash) && String(status.task_hash ?? '').trim().toLowerCase() === wantedHash;
+    const sameOrder = Boolean(wantedOrderId) && String(status.order_id ?? '').trim() === wantedOrderId;
+    if (!sameSlug && !sameTask && !sameOrder) continue;
+    if (normalizePath(status.repo) !== wantedRepo) continue;
+    runs.push({ name: entry.name, at: String(status.started_at || '') });
+  }
+  // started_at decides, folder name breaks ties: folders are stamped `<date>_<time>_<slug>`,
+  // so they sort the same way for runs written before the field existed.
+  runs.sort((a, b) => (a.at === b.at ? (a.name < b.name ? -1 : 1) : a.at < b.at ? -1 : 1));
+  return runs.map((r) => r.name);
+}
+
+/**
+ * The tree as it stood before the task began: state-before.txt of the FIRST run of the
+ * chain. The first and not the previous one, because a middle run can end without an
+ * "after" snapshot at all — 2026-07-31_114736 wrote eleven files and left neither
+ * state-after.txt nor meta.json — and its own "before" is then the last honest base.
+ * null when there is no chain or that first run never got a snapshot; an existing but
+ * empty snapshot is a clean tree, which is data, not absence.
+ */
+export function chainBaseline(runsRoot, repo, slug, taskHash = '', orderId = '') {
+  const [first] = chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  if (!first) return null;
+  try {
+    return fs.readFileSync(path.join(runsRoot, first, 'state-before.txt'), 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/meta/environment.mjs

@@ -0,0 +1,36 @@
+/**
+ * Tells apart what a run changed from what the tooling around it changed.
+ *
+ * Every verdict about a build run rests on the worktree either side of it, and that
+ * comparison assumes the run is the only writer. In a repository under OMC and Claude Code it
+ * never is: on 2026-08-02 a run that touched exactly its three scoped files was failed for
+ * “out-of-scope changes: .omc/project-memory.json”, written by the orchestrator's own tooling
+ * while Codex worked.
+ *
+ * The patterns are read from the run's own env.json, not from the config, so recomputing an
+ * old run's verdict gives the answer it gave then — the config may have changed since.
+ */
+import path from 'node:path';
+import { displayPath, globToRegExp, normalizePath, readJson } from './paths.mjs';
+
+/** Empty for runs made before the list existed: absence means "the run was the only writer". */
+export function environmentPatterns(runDir) {
+  const configured = readJson(path.join(runDir, 'env.json'))?.environmentPaths;
+  return Array.isArray(configured) ? configured.map((row) => String(row).trim()).filter(Boolean) : [];
+}
+
+/** Touched paths, normalized and sorted into the run's own work and the environment's. */
+export function splitEnvironment(paths, patterns) {
+  const matchers = (patterns || []).filter(Boolean).map(globToRegExp);
+  const work = [];
+  const environment = [];
+  for (const raw of paths || []) {
+    const file = displayPath(raw);
+    if (!normalizePath(file)) continue;
+    (matchers.some((re) => re.test(file)) ? environment : work).push(file);
+  }
+  return { work, environment };
+}
+
+/** The same split for a run on disk, using the patterns that were in force when it started. */
+export const splitRunChanges = (runDir, paths) => splitEnvironment(paths, environmentPatterns(runDir));

package/src/meta/paths.mjs

@@ -0,0 +1,193 @@
+/**
+ * Turns a run's artifacts on disk into values the rest of the verdict can compare.
+ *
+ * Two sides spell the same file differently — git prints repo-relative paths with forward
+ * slashes, Codex writes whatever it likes — so nothing above this module compares a path
+ * before it has been through here. This is also the only module that touches the
+ * filesystem for reading: everything else receives text, JSON or a byte count from it.
+ */
+import fs from 'node:fs';
+
+/** One line, no newlines, bounded length — a five-line reply must stay five lines. */
+export const line = (value, max = 200) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+export const readText = (file) => {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * A run's JSON artifact, or null when there is none to read. The byte-order mark is stripped
+ * first: JSON.parse rejects it, and a status.json rewritten by a Windows editor or by
+ * PowerShell's `Set-Content -Encoding utf8` would then read as "no such run" — silently
+ * excusing that run from every check that looks it up.
+ */
+export const readJson = (file) => {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    // Compared by code point rather than matched by a literal: a byte-order mark in the
+    // source of this file would be invisible to the next reader.
+    return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+  } catch {
+    return null;
+  }
+};
+
+export const size = (file) => {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return 0;
+  }
+};
+
+/**
+ * Snapshot lines are `<added>\t<deleted>\t<path>` for tracked files and `U\t<bytes>\t<path>`
+ * for untracked ones — see worktreeSnapshot() in runner/git-state.mjs. Path last, state first.
+ */
+export const snapshotMap = (text) => {
+  const map = new Map();
+  for (const row of text.split(/\r?\n/).filter(Boolean)) {
+    const parts = row.split('\t');
+    if (parts.length < 3) continue;
+    map.set(parts.slice(2).join('\t').trim(), `${parts[0]}\t${parts[1]}`);
+  }
+  return map;
+};
+
+/**
+ * Paths Codex actually touched, by content rather than by porcelain letter: a file that
+ * was already ` M` stays ` M` after further edits, so status codes would report zero
+ * work. Line counts (or size, for untracked files) do change.
+ */
+export const changedPaths = (before, after) => {
+  const was = snapshotMap(before);
+  const now = snapshotMap(after);
+  const paths = [];
+  for (const [file, state] of now) if (was.get(file) !== state) paths.push(file);
+  // A path that dropped out was touched too: Codex restored it to its committed state.
+  for (const file of was.keys()) if (!now.has(file)) paths.push(file);
+  return paths;
+};
+
+/** Directories a delegated build has no business editing, whatever the task says. */
+export const SERVICE_RE = /^(\.omx|\.omc|\.claude|\.codex|\.git|node_modules)\//;
+
+/**
+ * Paths arrive from two sides that spell them differently: git prints repo-relative with
+ * forward slashes, while Codex writes whatever it likes — backslashes, `./` prefixes,
+ * absolute paths, the occasional backtick left over from markdown.
+ */
+export const displayPath = (value) =>
+  String(value ?? '')
+    .trim()
+    .replace(/^[`'"]+|[`'"]+$/g, '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+
+/** Comparison spelling: displayPath's canonical separators plus Windows-style case folding. */
+export const normalizePath = (value) => displayPath(value).toLowerCase();
+
+/** Suffix match, so an absolute path from Codex still meets a relative one from git. */
+export const samePath = (declared, touched) => {
+  const left = normalizePath(declared);
+  const right = normalizePath(touched);
+  return left === right || right.endsWith(`/${left}`) || left.endsWith(`/${right}`);
+};
+
+/**
+ * One --scope pattern as a regular expression. Deliberately a small glob dialect and not a
+ * dependency: `**` crosses directory boundaries, `*` and `?` stop at `/`, matching is
+ * case-insensitive because Windows paths arrive in whatever case Codex felt like using.
+ * A slash right after `**` is optional, so `src/**` covers `src/a.ts` too — otherwise the
+ * most natural way to write a scope would silently match nothing.
+ */
+export function globToRegExp(pattern) {
+  const glob = String(pattern ?? '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+  let out = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        i += 1;
+        if (glob[i + 1] === '/') {
+          i += 1;
+          out += '(?:.*/)?';
+        } else {
+          out += '.*';
+        }
+      } else {
+        out += '[^/]*';
+      }
+      continue;
+    }
+    if (ch === '?') {
+      out += '[^/]';
+      continue;
+    }
+    out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`, 'i');
+}
+
+/**
+ * The paths one changes[].file entry actually names. BUILD_SCHEMA asks only for a non-empty
+ * string, so Codex folds several files into one: 2026-07-31_120340 edited three real files
+ * and called them `.../cost/{types,phase-cost-recorder,tier1-capture}.ts`, a string no git
+ * path can ever equal. Enumerations split on `;` and `,` outside braces, braces expand one
+ * level, and globs come back as patterns — `src/*.test.ts` is a claim about a set of files,
+ * not a file. Nested braces are deliberately unsupported: Codex has never written one.
+ */
+export function expandDeclared(file) {
+  const raw = String(file ?? '');
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of raw) {
+    if (ch === '{') depth += 1;
+    else if (ch === '}') depth = Math.max(0, depth - 1);
+    if ((ch === ';' || ch === ',') && depth === 0) {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+
+  const expand = (value) => {
+    const brace = /\{([^{}]*)\}/.exec(value);
+    if (!brace) return [value];
+    const head = value.slice(0, brace.index);
+    const tail = value.slice(brace.index + brace[0].length);
+    return brace[1].split(',').flatMap((option) => expand(`${head}${option.trim()}${tail}`));
+  };
+
+  // Deduplication compares exact spellings, not suffixes: `a/x.mjs` and `b/a/x.mjs` declared in
+  // one entry are two files, and samePath would fold the pair into one.
+  const out = [];
+  const seen = new Set();
+  for (const part of parts) {
+    for (const candidate of expand(part)) {
+      const displayed = displayPath(candidate);
+      const key = normalizePath(displayed);
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      out.push(displayed);
+    }
+  }
+  return out;
+}
+
+/** A declared entry against real paths: a glob matches as a pattern, a path by suffix. */
+export const declaredHits = (declared, paths) => {
+  if (!/[*?]/.test(declared)) return paths.some((p) => samePath(declared, p));
+  const re = globToRegExp(declared);
+  return paths.some((p) => re.test(p));
+};

package/src/meta/reply.mjs

@@ -0,0 +1,133 @@
+/**
+ * Renders the reply lines a dispatcher is allowed to return, one format per agent.
+ *
+ * AGENTS is the registry of the three dispatchers: for each one it names the result file
+ * that run writes, how to tell that file is filled in, and which of the three reply
+ * strategies below renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
+ * produced nothing has nothing agent-specific left to say.
+ *
+ * The lines built here ARE the reply. Agents forward this text verbatim instead of
+ * composing prose, which is what keeps a delegated run at five lines.
+ */
+import path from 'node:path';
+import { changedPaths, line, readText } from './paths.mjs';
+import { splitRunChanges } from './environment.mjs';
+import { scoutCoverage } from './verdict.mjs';
+
+/** What the run itself changed, and what the tooling around it changed while it worked. */
+const runChanges = (runDir) =>
+  splitRunChanges(
+    runDir,
+    changedPaths(readText(path.join(runDir, 'state-before.txt')), readText(path.join(runDir, 'state-after.txt'))),
+  );
+
+export const AGENTS = {
+  'codex-scout': {
+    result: 'result.json',
+    filled: (r) => Boolean(String(r?.answer || '').trim()),
+    reply: scoutReply,
+  },
+  'codex-build': {
+    result: 'result.json',
+    filled: (r) => Boolean(String(r?.summary || '').trim()),
+    reply: buildReply,
+  },
+  'codex-review': {
+    result: 'review.json',
+    filled: (r) => Boolean(String(r?.verdict || '').trim()),
+    reply: reviewReply,
+  },
+};
+
+function scoutReply(ctx) {
+  const r = ctx.result;
+  const top = (r.findings || [])[0];
+  const unknowns = (r.unknowns || []).filter(Boolean);
+  const coverage = scoutCoverage(ctx.runDir, r);
+  return [
+    `OK — ${line(r.answer, 160)}`,
+    // Any explicit question gets a coverage line, including a valid one-question order.
+    ...(coverage ? [`Coverage: ${coverage}`] : []),
+    `Key finding: ${top ? `${line(top.fact, 130)} (${line(top.where, 60)})` : 'no findings listed'}`,
+    `Unresolved: ${unknowns.length ? line(unknowns.join('; '), 160) : 'none'}`,
+    `Report: ${ctx.file('report.md')} · Log: ${ctx.file('raw.log')}`,
+  ];
+}
+
+function buildReply(ctx) {
+  const r = ctx.result;
+  const { work: touchedPaths, environment } = runChanges(ctx.runDir);
+  const paths = touchedPaths.slice(0, 3).join(', ');
+  const flags = readText(path.join(ctx.runDir, 'flags.txt')).split(/\r?\n/).filter(Boolean);
+  // A multi-line verification is several commands, and collapsing them into one 60-character
+  // line cut the last one mid-word: the reply named a command nobody could run.
+  const commands = String(r.verify_command ?? '')
+    .split(/\r?\n/)
+    .map((command) => command.trim())
+    .filter(Boolean);
+  const verify = commands.length
+    ? `${line(commands[0], 60)}${commands.length > 1 ? ` (+${commands.length - 1} more)` : ''}`
+    : 'not run';
+  const verdict = r.verify_command
+    ? r.verify_passed === true
+      ? 'pass'
+      : r.verify_passed === false
+        ? 'fail'
+        : 'result not reported'
+    : 'n/a';
+  // A pass that changed nothing because the previous pass of the same task already did the
+  // work says so on the files line: "0 changed" alone reads as a run that achieved nothing.
+  const files = ctx.carried
+    ? `${paths ? `${paths} · ` : ''}changes were made by an earlier run of this task`
+    : paths || 'worktree untouched';
+  return [
+    `OK — ${line(r.summary, 160)}`,
+    `Files: ${touchedPaths.length} changed · ${files}`,
+    // Only when something outside the run wrote to the tree. Subtracting those paths from the
+    // verdict without naming them would hide a real edit behind a pattern.
+    ...(environment.length
+      ? [`Environment: ${environment.length} changed outside the run — ${line(environment.slice(0, 3).join(', '), 120)}`]
+      : []),
+    `Verification: ${verify} — ${verdict}`,
+    `Flags: ${flags.length ? `${flags.length} TODO/skip — ${line(flags.slice(0, 3).join(' | '), 140)}` : 'none'}`,
+    `Report: ${ctx.file('report.md')} · Log: ${ctx.file('raw.log')}`,
+  ];
+}
+
+function reviewReply(ctx) {
+  const r = ctx.result;
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  (r.findings || []).forEach((f) => {
+    if (counts[f.severity] !== undefined) counts[f.severity] += 1;
+  });
+  const top = (r.findings || []).find((f) => f.severity === 'critical' || f.severity === 'high');
+  return [
+    `OK — verdict ${line(r.verdict, 40)}`,
+    `Findings: critical ${counts.critical} · high ${counts.high} · medium ${counts.medium} · low ${counts.low}`,
+    `Top: ${top ? `${top.severity} ${line(top.file, 80)}:${top.line_start} — ${line(top.title, 90)}` : 'no critical or high findings'}`,
+    `Report: ${ctx.file(path.basename(ctx.resultPath))} · Log: ${ctx.file('raw.log')}`,
+  ];
+}
+
+export function failReply(ctx, meta) {
+  return [
+    `FAIL — ${line(meta.reason, 170)}`,
+    `Artifacts: raw.log ${meta.log_bytes} B · ${path.basename(ctx.resultPath)} ${meta.result_ok ? 'filled' : 'empty or missing'} · exit=${meta.exit}`,
+    `Log: ${ctx.file('raw.log')}`,
+  ];
+}
+
+export function limitReply(ctx, meta) {
+  const rows = [
+    'LIMIT — ChatGPT quota exhausted, work not completed',
+    `Signal: ${line(meta.reason, 170)}`,
+  ];
+  if (ctx.agent === 'codex-build') {
+    const { work: touched } = runChanges(ctx.runDir);
+    rows.push(
+      `Worktree: ${touched.length ? `has unfinished changes (${touched.length}), see git-after.txt` : 'no new changes'}`,
+    );
+  }
+  rows.push(`Log: ${ctx.file('raw.log')}`);
+  return rows;
+}

package/src/meta/run-state.mjs

@@ -0,0 +1,197 @@
+/**
+ * Records what state a run is in, on disk, where the next run can see it.
+ *
+ * A killed runner leaves no report and no meta.json, and four abandoned folders from one
+ * order were indistinguishable from four runs still working — status.json is what makes
+ * that difference visible. writeFailure() lives here for the same reason: a failure that
+ * happens before Codex could produce anything still has to leave both files behind, so
+ * there is no second path by which a reply could exist without an artifact backing it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { changedPaths, line, normalizePath, readJson, readText, size } from './paths.mjs';
+
+/**
+ * Is this pid still running? EPERM means the process exists and belongs to someone else,
+ * which for our purposes is alive — treating it as dead would mark a live run abandoned.
+ */
+export const pidAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+/**
+ * Run state on disk, merged over whatever is already there. A killed runner leaves no
+ * report and no meta.json, and four abandoned folders from one order were indistinguishable
+ * from four runs still working — status.json is what makes that difference visible.
+ */
+export function writeStatus(runDir, patch) {
+  const current = readJson(path.join(runDir, 'status.json')) || {};
+  const next = { ...current, ...patch };
+  fs.writeFileSync(path.join(runDir, 'status.json'), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * Closes out runs whose runner died without writing a verdict. Called at the start of every
+ * run, so a folder left by a killed dispatcher gets an explicit state instead of reading as
+ * "something is missing here". A dead pid with meta.json present is not abandoned — the
+ * verdict exists, only the final status write was lost, so the state is repaired to
+ * finished. The caller supplies the current worktree snapshot because this module deliberately
+ * has no git calls; that snapshot is compared with the run's own state-before.txt and described
+ * as a later-run file list rather than exact authorship by the abandoned run. Returns what
+ * changed, for callers that want to report it.
+ */
+export function markAbandoned(runsRoot, currentTree) {
+  let entries;
+  try {
+    entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const changed = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(runsRoot, entry.name);
+    const status = readJson(path.join(runDir, 'status.json'));
+    if (!status || status.state !== 'running' || pidAlive(status.pid)) continue;
+    const metaPath = path.join(runDir, 'meta.json');
+    const meta = readJson(metaPath);
+    if (!meta && fs.existsSync(metaPath)) continue;
+    let patch = meta
+      ? { state: 'finished', status: meta.status, finished_at: meta.finished_at }
+      : {
+          state: 'abandoned',
+          // The verdict is not the only thing missing. 2026-07-31_114736 wrote eleven files
+          // and never snapshotted the tree afterwards, so the next pass of that task started
+          // from a base that already contained them and every later count lied in silence.
+          // The flag exists so that base is read as unknown rather than as clean.
+          tree_after: false,
+          abandoned_reason:
+            'runner process is dead, meta.json was not recorded; post-run worktree state was not ' +
+              'captured — its changes will enter the baseline of the next run',
+          abandoned_at: new Date().toISOString(),
+    };
+    if (!meta) {
+      const hasCurrentTree = typeof currentTree === 'string';
+      const beforePath = path.join(runDir, 'state-before.txt');
+      const hasBeforeSnapshot = fs.existsSync(beforePath);
+      const files = hasCurrentTree && hasBeforeSnapshot
+        ? changedPaths(readText(beforePath), currentTree)
+        : [];
+      const treeReason = hasCurrentTree && hasBeforeSnapshot
+        ? files.length
+          ? `the current worktree differs from state-before.txt in: ${files.join(', ')}`
+          : 'the current worktree has no files differing from state-before.txt'
+        : hasCurrentTree
+          ? 'the run has no state-before.txt, so no file list is available'
+          : 'no current worktree snapshot was supplied, so no file list is available';
+      const reason =
+        'runner process is dead, meta.json was not recorded; ' +
+        `${treeReason}. This comparison runs at the start of a later run, so its file list may ` +
+        'include work made after the abandoned run and is not a definitive list of that run\'s work; ' +
+        'post-run worktree state was not captured — its changes will enter the baseline of the next run';
+      const { meta: failure } = writeFailure(runDir, status.agent, reason);
+      fs.writeFileSync(metaPath, `${JSON.stringify({ ...failure, reason }, null, 2)}\n`);
+      patch = { ...patch, abandoned_reason: reason, abandoned_at: failure.finished_at };
+    }
+    try {
+      writeStatus(runDir, patch);
+      changed.push({ run: entry.name, state: patch.state });
+    } catch {
+      // A folder that cannot be written to is not worth failing a fresh run over.
+    }
+  }
+  return changed;
+}
+
+/**
+ * A live run of the same agent against the same repository, or null. Two writing runs share
+ * one worktree with no isolation: the second one's before/after snapshot picks up the
+ * first one's edits, so an honest run gets failed for work it never did. Read-only agents
+ * are not looked at — running scouting alongside a build is the normal way to work.
+ */
+export function activeRun(runsRoot, repo, agent = 'codex-build') {
+  let entries;
+  try {
+    entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const wanted = normalizePath(repo);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const status = readJson(path.join(runsRoot, entry.name, 'status.json'));
+    if (!status || status.state !== 'running' || status.agent !== agent) continue;
+    if (normalizePath(status.repo) !== wanted) continue;
+    if (pidAlive(status.pid)) return entry.name;
+  }
+  return null;
+}
+
+/**
+ * Finds the newest abandoned run that recorded a branch while the repository is detached.
+ * The caller supplies the current branch because this module deliberately has no git calls.
+ */
+export function abandonedBranchDrift(runsRoot, repo, currentBranch) {
+  if (String(currentBranch ?? '').trim()) return null;
+  const wanted = normalizePath(repo);
+  if (!wanted) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const runDir = path.join(runsRoot, entry.name);
+    const status = readJson(path.join(runDir, 'status.json'));
+    if (!status || status.state !== 'abandoned' || normalizePath(status.repo) !== wanted) continue;
+    let branch;
+    try {
+      branch = fs.readFileSync(path.join(runDir, 'branch-before.txt'), 'utf8').trim();
+    } catch {
+      continue;
+    }
+    if (branch) matches.push({ name: entry.name, at: String(status.started_at || ''), branch });
+  }
+  matches.sort((a, b) => (a.at === b.at ? (a.name < b.name ? -1 : 1) : a.at < b.at ? -1 : 1));
+  const newest = matches.at(-1);
+  return newest ? { run: newest.name, branch: newest.branch } : null;
+}
+
+/**
+ * A failure that happens before Codex could produce anything — missing CLI, a crash of
+ * the runner itself. It still goes through meta.json, so there is no second path by
+ * which a reply could exist without an artifact backing it.
+ */
+export function writeFailure(runDir, agent, reason, extraLines = []) {
+  const meta = {
+    agent,
+    project: path.basename(path.dirname(runDir)),
+    run: path.basename(runDir),
+    finished_at: new Date().toISOString(),
+    exit: null,
+    status: 'FAIL',
+    reason: line(reason, 300),
+    result_ok: false,
+    log_bytes: size(path.join(runDir, 'raw.log')),
+    tokens: null,
+    tokens_reported: false,
+    model: null,
+    sandbox: null,
+    session_id: null,
+    env: readJson(path.join(runDir, 'env.json')),
+  };
+  fs.writeFileSync(path.join(runDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+  writeStatus(runDir, { state: 'failed', status: 'FAIL', finished_at: meta.finished_at });
+  const reply = [`FAIL — ${meta.reason}`, ...extraLines, `Run: ${runDir}`].join('\n');
+  return { meta, reply };
+}