@lyupro/codex-bridge 0.1.4 → 0.3.0

package/src/heartbeat.mjs

@@ -0,0 +1,80 @@
+/**
+ * The one definition of run progress: a heartbeat file in the run folder, its age, and the
+ * stale threshold. On 2026-08-06 run 2026-08-06_204007_build left a live worker waiting on
+ * Codex's grandchild; a worker timer alone would have kept that dead run looking alive, so
+ * the timer stops at exit.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const HEARTBEAT_FILE = 'heartbeat';
+// Ten seconds bounds metadata writes when a 300KB stream arrives as many chunks; output still
+// proves movement immediately in memory, while the periodic worker stamp keeps silence fresh.
+export const HEARTBEAT_WRITE_INTERVAL_MS = 10_000;
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+// Five minutes leaves a wide margin over the longest model-thinking silence seen in healthy
+// runs. The active-child timer refreshes below it; the margin is safer than unlocking a tree
+// while a working build is silent, which is the failure this heartbeat exists to prevent.
+export const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+
+export function heartbeatPath(runDir) {
+  return path.join(runDir, HEARTBEAT_FILE);
+}
+
+/** A failed stamp is deliberately swallowed: the verdict must not depend on this hint file. */
+export function createHeartbeat(runDir) {
+  let lastStamp = Number.NEGATIVE_INFINITY;
+  return {
+    stamp(now = Date.now()) {
+      if (!Number.isFinite(now)) return;
+      if (now >= lastStamp && now - lastStamp < HEARTBEAT_WRITE_INTERVAL_MS) return;
+      lastStamp = now;
+      try {
+        fs.writeFileSync(heartbeatPath(runDir), `${now}\n`);
+      } catch {
+        // A read-only or full run folder must still produce its normal verdict and artifacts.
+      }
+    },
+  };
+}
+
+/** Missing is an explicit legacy state: old live records keep their lock until their pid dies. */
+export function heartbeatAge(runDir, now = Date.now()) {
+  try {
+    const stat = fs.statSync(heartbeatPath(runDir));
+    if (!stat.isFile() || !Number.isFinite(now)) return Number.POSITIVE_INFINITY;
+    return Math.max(0, now - stat.mtimeMs);
+  } catch (err) {
+    return err.code === 'ENOENT' ? null : Number.POSITIVE_INFINITY;
+  }
+}
+
+/**
+ * How long a run has been silent, in words. It lives beside the age it formats because both the
+ * worktree lock's refusal and `sweep`'s report have to name the same silence to the same operator;
+ * two copies of this drifted apart the moment they were written.
+ */
+export function formatSilence(age) {
+  if (age === null || !Number.isFinite(age)) return 'an unknown duration';
+  const seconds = Math.floor(Math.max(0, age) / 1000);
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? '' : 's'}`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`
+      + (remainingSeconds ? ` ${remainingSeconds} second${remainingSeconds === 1 ? '' : 's'}` : '');
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours} hour${hours === 1 ? '' : 's'}`
+    + (remainingMinutes ? ` ${remainingMinutes} minute${remainingMinutes === 1 ? '' : 's'}` : '');
+}
+
+/**
+ * A running record is live when its heartbeat is fresh. Missing heartbeats remain live only for
+ * pre-Plan_20 records, an explicit fail-closed compatibility choice that preserves their lock.
+ */
+export function isHeartbeatFresh(runDir, now = Date.now()) {
+  const age = heartbeatAge(runDir, now);
+  return age === null || age <= HEARTBEAT_STALE_MS;
+}

package/src/hook-definitions.mjs

@@ -29,8 +29,19 @@ export const WRITE_TOOLS = Object.freeze(['Write', 'Edit', 'MultiEdit', 'Noteboo
 /** A PreToolUse matcher is a regular expression over tool names, so alternation covers all four. */
 export const WRITE_TOOL_MATCHER = WRITE_TOOLS.join('|');
 
+/**
+ * Shell tools, listed here for the same reason as the two lists above: the prune guard must see the
+ * command whichever name a host gives its shell, and a name known only to the hook would leave that
+ * host's agents able to delete run artifacts.
+ */
+export const SHELL_TOOLS = Object.freeze(['Bash', 'PowerShell']);
+
+/** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
+export const SHELL_TOOL_MATCHER = SHELL_TOOLS.join('|');
+
 export const HOOK_DEFINITIONS = Object.freeze([
   Object.freeze({ event: 'SubagentStop', matcher: '*', file: 'reply-guard.mjs' }),
   Object.freeze({ event: 'PreToolUse', matcher: SUBAGENT_TOOL_MATCHER, file: 'order-gate.mjs' }),
   Object.freeze({ event: 'PreToolUse', matcher: WRITE_TOOL_MATCHER, file: 'worktree-lock.mjs' }),
+  Object.freeze({ event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
 ]);

package/src/hooks/live-runs.mjs

@@ -2,12 +2,18 @@
  * Shared, fail-open knowledge of live Codex runs.
  *
  * The reply guard and the worktree lock must answer the same question: a status.json is live
- * only while it says `running` and its runner pid accepts signal 0. Keeping that probe and the
- * directory scan here prevents the two protections from disagreeing about a run, which would
- * recreate the incident where the dispatcher reported while another run still edited the tree.
+ * only while it says `running`, its runner pid accepts signal 0, and its progress heartbeat is
+ * fresh. Keeping those probes and the directory scan here prevents the two protections from
+ * disagreeing about a run, which would recreate the 2026-08-06 incident where a dead Codex
+ * child left its worker and lock looking live through a grandchild-held stdio pipe.
+ *
+ * The heartbeat is required here and deliberately NOT in meta/run-state.mjs: releasing a lock
+ * early costs an operator one knowing edit, while closing a record early makes a second writer
+ * of its meta.json. See the comment above pidAlive() there.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { isHeartbeatFresh } from '../heartbeat.mjs';
 
 /** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
 export const isPidAlive = (pid) => {
@@ -41,7 +47,7 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
 
-function recognizedStatus(status) {
+function recognizedStatus(runDir, status) {
   return Boolean(status)
     && typeof status === 'object'
     && !Array.isArray(status)
@@ -50,7 +56,8 @@ function recognizedStatus(status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isPidAlive(status.pid);
+    && isPidAlive(status.pid)
+    && isHeartbeatFresh(runDir);
 }
 
 function readStatus(runDir) {
@@ -75,7 +82,7 @@ export function liveRuns(runsDir) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(runsDir, entry.name);
     const status = readStatus(dir);
-    if (recognizedStatus(status)) result.push({ dir, status });
+    if (recognizedStatus(dir, status)) result.push({ dir, status });
   }
   return result;
 }

package/src/hooks/prune-guard.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard that keeps `codex-bridge prune` out of agent-issued shell commands.
+ *
+ * Deletion is an operator action. The command already refuses without a terminal, but a guard in
+ * front of it is the second rubezh Plan_17 asks for: the TTY check lives inside the very process an
+ * agent is asking to start, and a package that trusts one check has trusted prose twice before
+ * (Plan_13, Plan_14) and been wrong both times. Denying the call means no deleting process is
+ * created at all.
+ *
+ * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
+ */
+import fs from 'node:fs';
+import { SHELL_TOOLS } from '../hook-definitions.mjs';
+
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+const pass = () => process.exit(0);
+
+// The binary, then the verb, with any path in front of it: an agent reaches the CLI as
+// `codex-bridge`, as `node bin/codex-bridge.mjs`, or through an absolute path, and a guard that
+// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Matching
+// a lone `prune` is not an option either — `git prune` and `npm prune` are not this package's
+// business, and a guard that breaks unrelated work is a guard that gets uninstalled.
+const PRUNE_CALL = /(^|[\s;&|(`])(\S*[\\/])?codex-bridge(\.mjs)?\s+prune(\s|$)/;
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+
+/**
+ * Strips the parts of a command line that are data rather than instructions: heredoc bodies and
+ * quoted strings. Found the moment this guard existed — it denied the commit that introduced it,
+ * because the message text quoted the command name. Nothing was going to be deleted; the words
+ * were cargo. A guard that cannot tell an invocation from a mention refuses honest work, and a
+ * guard that refuses honest work is removed, after which it guards nothing.
+ */
+function withoutQuotedText(command) {
+  return command
+    .replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm, ' ')
+    .replace(/'[^']*'/g, ' ')
+    .replace(/"[^"]*"/g, ' ');
+}
+
+const command = input.tool_input?.command;
+if (typeof command !== 'string' || !command.trim()) pass();
+if (!PRUNE_CALL.test(withoutQuotedText(command))) pass();
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: 'codex-bridge prune deletes run artifacts and is an operator action, '
+      + 'not an agent one. There is deliberately no bypass flag. Ask the operator to run it in '
+      + 'their own terminal; `codex-bridge projects` shows the same store read-only.',
+  },
+}));

package/src/hooks/reply-guard.mjs

@@ -284,7 +284,7 @@ if (fs.existsSync(statusPath)) {
           `status.json currently says state=running, but process pid ${fact(runStatus.pid)} is ` +
             'dead and meta.json is missing: an interrupted Bash call killed the runner. Codex ' +
             'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes ' +
-            'in 11+ files survived while raw.log and meta.json were never recorded.',
+            'in 11+ files survived while no run artifact and no meta.json were ever recorded.',
           runStatus,
         ),
       );
@@ -300,7 +300,7 @@ if (fs.existsSync(statusPath)) {
         `status.json currently says state=abandoned (${fact(runStatus.abandoned_reason)}, ` +
           `${fact(runStatus.abandoned_at)}): the runner died without recording a verdict. Codex ` +
           'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes in ' +
-          '11+ files survived while raw.log and meta.json were never recorded.',
+          '11+ files survived while no run artifact and no meta.json were ever recorded.',
         runStatus,
       ),
     );

package/src/hooks/worktree-lock.mjs

@@ -10,6 +10,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { formatSilence, heartbeatAge } from '../heartbeat.mjs';
 import { WRITE_TOOLS } from '../hook-definitions.mjs';
 import { runsRoot } from '../runner/runs-root.mjs';
 import { allLiveRuns, normalizePath } from './live-runs.mjs';
@@ -65,6 +66,12 @@ process.stdout.write(JSON.stringify({
     permissionDecision: 'deny',
     permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${targetPath} is inside repository `
       + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
-      + 'Wait for status.json to change state before editing this repository.',
+      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
+      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
+      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
+      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
+      // work they meant to keep.
+      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
+      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
   },
 }));

package/src/meta/deadline.mjs

@@ -0,0 +1,19 @@
+/**
+ * Reads the runner-owned deadline fact from status.json.
+ *
+ * stderr.log is diagnostic text and can contain a quoted copy of the runner's own message,
+ * so it cannot prove that the runner actually stopped the process (Plan_15).
+ */
+import path from 'node:path';
+import { readJson } from './paths.mjs';
+
+export function deadlineReason(runDir) {
+  const status = readJson(path.join(runDir, 'status.json'));
+  if (status?.stopped_on_deadline !== true) return null;
+  // How long the run lived, not the budget it was given: a field named for the budget and
+  // holding the elapsed time is read wrong by whoever opens the folder months later.
+  const elapsed = status.elapsed_ms;
+  return Number.isFinite(elapsed)
+    ? `run stopped on its deadline after ${elapsed} ms`
+    : 'run stopped on its deadline';
+}

package/src/meta/events.mjs

@@ -0,0 +1,166 @@
+/**
+ * Reads the runner's structured Codex transport and turns it into facts for metadata and
+ * verdicts. This is the only module that knows the file is JSONL: a model can quote a limit in
+ * its own item text, but only these runner-written error events are allowed to stop a retry.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Quota exhaustion, and nothing else that merely says "limit". A bare `limit` also appears in
+ * "context length limit" — an error about the content of the order, which the orchestrator is
+ * supposed to fix and re-send. Calling that LIMIT would forbid the one retry that would work.
+ */
+const LIMIT_RE = /rate[\s_-]*limit|usage[\s_-]*limit|quota|too many requests|\b429\b/i;
+
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+const compact = (value, max = 300) =>
+  String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+/**
+ * A broken final line is expected when the runner is stopped while Codex is writing.
+ *
+ * Whether the file was there at all is reported separately from what it held: a run killed
+ * before the CLI said one word leaves an empty stream, and telling the operator that such a
+ * run "predates the change" sends them looking for the wrong thing entirely.
+ */
+function readLines(runDir) {
+  if (!runDir) return { exists: false, events: [] };
+  let text;
+  try {
+    text = fs.readFileSync(path.join(runDir, 'events.jsonl'), 'utf8');
+  } catch {
+    return { exists: false, events: [] };
+  }
+  const events = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const source = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    if (!source.trim()) continue;
+    try {
+      const event = JSON.parse(source);
+      if (record(event)) events.push(event);
+    } catch {
+      // A line cut short by MAX_LOG or a killed process is not a transport verdict.
+    }
+  }
+  return { exists: true, events };
+}
+
+function usageOf(events) {
+  const completed = events.filter((event) => event.type === 'turn.completed' && record(event.usage));
+  if (!completed.length) return { tokens: null, usage: null };
+
+  const usage = {};
+  let tokens = 0;
+  for (const event of completed) {
+    for (const [key, value] of Object.entries(event.usage)) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        usage[key] = (usage[key] || 0) + value;
+      } else if (!(key in usage)) {
+        usage[key] = value;
+      }
+    }
+    if (typeof event.usage.input_tokens === 'number' && Number.isFinite(event.usage.input_tokens)) {
+      tokens += event.usage.input_tokens;
+    }
+    if (typeof event.usage.output_tokens === 'number' && Number.isFinite(event.usage.output_tokens)) {
+      tokens += event.usage.output_tokens;
+    }
+  }
+  return { tokens, usage };
+}
+
+/**
+ * Finds the last content error emitted by the model.
+ *
+ * The 2026-08-05 live probe put policy rejections in stderr on a healthy run, so the
+ * model's own complaint must stay separate from that noisy diagnostic stream.
+ *
+ * Only what follows the first `turn.started` is the model's. codex-cli 0.146.0 announces its
+ * own configuration warnings through the same `item.completed` error shape before the turn
+ * begins: on 2026-08-06 every run of this host carried "`[features].codex_hooks` is
+ * deprecated" as its first item, and a failed run would have named that as the reason it
+ * failed. A complaint about the order cannot predate the model's first thought — so a run
+ * that never opened a turn has no content error at all, and falls back to the transport
+ * error or stderr the way it did before this stream existed.
+ */
+export function contentErrorOf(events) {
+  const turn = events.findIndex((event) => event?.type === 'turn.started');
+  if (turn < 0) return null;
+  for (let index = events.length - 1; index > turn; index -= 1) {
+    const event = events[index];
+    if (event?.type !== 'item.completed' || !record(event.item) || event.item.type !== 'error') continue;
+    const value = typeof event.item.message === 'string' ? event.item.message : event.item.text;
+    return typeof value === 'string' ? compact(value) : '';
+  }
+  return null;
+}
+
+function payloadOf(event) {
+  const source =
+    event.type === 'error'
+      ? event.message ?? event.error
+      : event.error?.message ?? event.error ?? event.message;
+  if (typeof source === 'string') {
+    try {
+      const parsed = JSON.parse(source);
+      return record(parsed) ? parsed : { message: source };
+    } catch {
+      return { message: source };
+    }
+  }
+  return record(source) ? source : {};
+}
+
+function transportErrorOf(event) {
+  if (event.type !== 'error' && event.type !== 'turn.failed') return null;
+  const payload = payloadOf(event);
+  const nested = record(payload.error) ? payload.error : {};
+  const errorType =
+    (typeof nested.type === 'string' && nested.type) ||
+    (typeof payload.type === 'string' && payload.type !== 'error' && payload.type) ||
+    null;
+  const message =
+    (typeof nested.message === 'string' && nested.message) ||
+    (typeof payload.message === 'string' && payload.message) ||
+    null;
+  const status = payload.status ?? nested.status ?? null;
+  const marker = [errorType, message].join(' ');
+  const quota = Number(status) === 429 || LIMIT_RE.test(marker);
+  const reason = compact(
+    [errorType, message, status === null || status === undefined ? '' : `status ${status}`]
+      .filter(Boolean)
+      .join(': ') ||
+      (typeof event.message === 'string' ? event.message : '') ||
+      (typeof event.error?.message === 'string' ? event.error.message : '') ||
+      event.type,
+  );
+  return { event, payload, status, error_type: errorType, message, quota, reason };
+}
+
+/**
+ * Reads all usable events and derives accounting without letting unreadable JSONL poison a run.
+ * Numeric usage fields are summed across turns; with one turn this preserves the CLI object
+ * and its fields exactly, while tokens intentionally count input plus output only.
+ */
+export function readEvents(runDir) {
+  const { exists, events } = readLines(runDir);
+  const accounting = usageOf(events);
+  const started = events.find((event) => event.type === 'thread.started' && event.thread_id);
+  const errors = events.map(transportErrorOf).filter(Boolean);
+  const transport_error = errors.find((error) => error.quota) || errors[0] || null;
+  return {
+    events,
+    // The file was written, whatever it holds. Pass 2 judges a run by this: a stream the
+    // runner promised in its own arguments and did not leave behind is damaged evidence,
+    // not an archived run.
+    hasStream: exists,
+    hasEvents: events.length > 0,
+    tokens: accounting.tokens,
+    usage: accounting.usage,
+    session_id: started ? String(started.thread_id) : null,
+    content_error: contentErrorOf(events),
+    transport_error,
+  };
+}

package/src/meta/reason.mjs

@@ -0,0 +1,29 @@
+/**
+ * Resolves the ordered reason for a failed run.
+ *
+ * The 2026-08-05 live probe showed that stderr can contain policy noise during a healthy run,
+ * so diagnostic text is the final fallback rather than the primary verdict evidence.
+ */
+import path from 'node:path';
+import { contentErrorOf } from './events.mjs';
+import { line, readText } from './paths.mjs';
+
+/** Keeps the archived stderr heuristic intact for runs without a useful event message. */
+const stderrReason = (runDir) => {
+  const stderr = readText(path.join(runDir, 'stderr.log'));
+  const messages = [...stderr.matchAll(/"message"\s*:\s*"((?:[^"\\]|\\.)*)"/g)];
+  if (messages.length) return line(messages[messages.length - 1][1].replace(/\\"/g, '"'));
+  const lines = stderr.split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+  const errorLine = [...lines].reverse().find((value) => /error|failed|denied|refused/i.test(value));
+  return line(errorLine || lines[lines.length - 1] || '');
+};
+
+// eventData is required, not defaulted: a caller that forgets it would silently fall back to
+// stderr — the exact behaviour this module was written to replace, and a default would hide it.
+export function reasonFrom(runDir, eventData) {
+  const content = line(eventData.content_error ?? contentErrorOf(eventData.events || []));
+  if (content) return content;
+  const transport = line(eventData.transport_error?.reason || eventData.transport_error?.message);
+  if (transport) return transport;
+  return stderrReason(runDir);
+}

package/src/meta/reply.mjs

@@ -11,7 +11,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { changedPaths, line, readText } from './paths.mjs';
+import { changedPaths, line, readJson, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
 import { scoutCoverage } from './verdict.mjs';
 
@@ -22,6 +22,29 @@ const runChanges = (runDir) =>
     changedPaths(readText(path.join(runDir, 'state-before.txt')), readText(path.join(runDir, 'state-after.txt'))),
   );
 
+const readCommand = (runDir) => `codex-bridge read ${runDir}`;
+
+function formatBytes(bytes) {
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = bytes;
+  let index = 0;
+  while (value >= 1024 && index < units.length - 1) {
+    value /= 1024;
+    index += 1;
+  }
+  return `${value.toFixed(1)} ${units[index]}`;
+}
+
+function retentionReply(runDir) {
+  const retention = readJson(path.join(runDir, 'status.json'))?.retention;
+  const bytes = Number(retention?.bytes_freed);
+  const runs = Number(retention?.runs);
+  const days = Number(retention?.days);
+  if (!Number.isFinite(bytes) || bytes <= 0 || !Number.isFinite(runs) || runs <= 0
+    || !Number.isFinite(days) || days <= 0) return null;
+  return `Retention: freed ${formatBytes(bytes)} from ${runs} runs older than ${days} days`;
+}
+
 export const AGENTS = {
   'codex-scout': {
     result: 'result.json',
@@ -45,13 +68,15 @@ function scoutReply(ctx) {
   const top = (r.findings || [])[0];
   const unknowns = (r.unknowns || []).filter(Boolean);
   const coverage = scoutCoverage(ctx.runDir, r);
+  const retention = retentionReply(ctx.runDir);
   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')}`,
+    ...(retention ? [retention] : []),
+    `Report: ${ctx.file('report.md')} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
 
@@ -81,6 +106,7 @@ function buildReply(ctx) {
   const files = ctx.carried
     ? `${paths ? `${paths} · ` : ''}changes were made by an earlier run of this task`
     : paths || 'worktree untouched';
+  const retention = retentionReply(ctx.runDir);
   return [
     `OK — ${line(r.summary, 160)}`,
     `Files: ${touchedPaths.length} changed · ${files}`,
@@ -91,7 +117,8 @@ function buildReply(ctx) {
       : []),
     `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')}`,
+    ...(retention ? [retention] : []),
+    `Report: ${ctx.file('report.md')} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
 
@@ -102,24 +129,28 @@ function reviewReply(ctx) {
     if (counts[f.severity] !== undefined) counts[f.severity] += 1;
   });
   const top = (r.findings || []).find((f) => f.severity === 'critical' || f.severity === 'high');
+  const retention = retentionReply(ctx.runDir);
   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')}`,
+    ...(retention ? [retention] : []),
+    `Report: ${ctx.file(path.basename(ctx.resultPath))} · Log: ${readCommand(ctx.runDir)}`,
   ];
 }
 
 export function failReply(ctx, meta) {
+  const retention = retentionReply(ctx.runDir);
   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}`,
+    `Artifacts: events.jsonl ${meta.events_bytes} B · stderr.log ${meta.stderr_bytes} B · ${path.basename(ctx.resultPath)} ${meta.result_ok ? 'filled' : 'empty or missing'} · exit=${meta.exit}`,
     // A failed build says what it left behind, exactly as a LIMIT does. "The work was not
     // done" is not "the tree is clean": a run can write half a change and then declare fail,
     // and the orchestrator has to know whether there is something to revert before it decides
     // anything else.
     ...(ctx.agent === 'codex-build' ? [`Worktree: ${worktreeState(ctx.runDir)}`] : []),
-    `Log: ${ctx.file('raw.log')}`,
+    ...(retention ? [retention] : []),
+    `Log: ${readCommand(ctx.runDir)}`,
   ];
 }
 
@@ -141,6 +172,7 @@ function worktreeState(runDir) {
 }
 
 export function limitReply(ctx, meta) {
+  const retention = retentionReply(ctx.runDir);
   const rows = [
     'LIMIT — ChatGPT quota exhausted, work not completed',
     `Signal: ${line(meta.reason, 170)}`,
@@ -151,6 +183,7 @@ export function limitReply(ctx, meta) {
       `Worktree: ${touched.length ? `has unfinished changes (${touched.length}), see git-after.txt` : 'no new changes'}`,
     );
   }
-  rows.push(`Log: ${ctx.file('raw.log')}`);
+  if (retention) rows.push(retention);
+  rows.push(`Log: ${readCommand(ctx.runDir)}`);
   return rows;
 }

package/src/meta/run-state.mjs

@@ -25,10 +25,31 @@ export const pidAlive = (pid) => {
   }
 };
 
+/**
+ * This module deliberately judges by the pid alone, while hooks/live-runs.mjs also requires a
+ * fresh progress heartbeat. The two answer different questions, and merging them broke both:
+ *
+ * - a hook asks "may the operator edit this tree", and a stalled run must stop holding that
+ *   lock — the operator is editing knowingly, and a stale run should not cost them 25 minutes;
+ * - this module asks "may a second paid run write into this tree" and "is this folder finished".
+ *   Closing a run whose pid still lives makes markAbandoned the second writer of its meta.json:
+ *   the live worker reaches collect() afterwards and overwrites the verdict, so the documented
+ *   artifact order stops being a contract. Letting activeRun() past a live pid starts a second
+ *   writing run in one worktree, which is the 2026-08-05 incident this whole lock exists for.
+ *
+ * A stalled-but-live run is closed by `stop`, which kills the process first and only then
+ * records the verdict — one writer, in the right order.
+ */
+
 /**
  * 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.
+ *
+ * It writes status.json and nothing else. Housekeeping facts such as `retention` live here and
+ * are read from here; an earlier attempt also appended them to meta.json, which would have made
+ * two functions write the same artifact and put the documented artifact order (meta.json before
+ * status.json is closed) at the mercy of whoever ran last.
  */
 export function writeStatus(runDir, patch) {
   const current = readJson(path.join(runDir, 'status.json')) || {};
@@ -126,7 +147,8 @@ export function activeRun(runsRoot, repo, agent = 'codex-build') {
   const wanted = normalizePath(repo);
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const status = readJson(path.join(runsRoot, entry.name, 'status.json'));
+    const runDir = path.join(runsRoot, entry.name);
+    const status = readJson(path.join(runDir, 'status.json'));
     if (!status || status.state !== 'running' || status.agent !== agent) continue;
     if (normalizePath(status.repo) !== wanted) continue;
     if (pidAlive(status.pid)) return entry.name;
@@ -182,7 +204,8 @@ export function writeFailure(runDir, agent, reason, extraLines = []) {
     status: 'FAIL',
     reason: line(reason, 300),
     result_ok: false,
-    log_bytes: size(path.join(runDir, 'raw.log')),
+    events_bytes: size(path.join(runDir, 'events.jsonl')),
+    stderr_bytes: size(path.join(runDir, 'stderr.log')),
     tokens: null,
     tokens_reported: false,
     model: null,