@lyupro/codex-bridge 0.1.4 → 0.2.0

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

@@ -29,6 +29,11 @@ export const pidAlive = (pid) => {
  * 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')) || {};
@@ -182,7 +187,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,

package/src/meta/startup.mjs

@@ -0,0 +1,21 @@
+/**
+ * Explains a current run that never reached either of its two output streams.
+ *
+ * The existing events file is enough to distinguish this shape: an archived folder has no
+ * events stream at all, while a folder with an empty stream and silent stderr proves the CLI
+ * never started.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readText } from './paths.mjs';
+
+export function startupGap(runDir, events) {
+  if (!events?.hasStream || events.hasEvents) return null;
+  // Existence before emptiness: a stderr.log that is not there is a missing witness, not a
+  // silent one, and the two mean opposite things. Reading an absent file as "" would let a run
+  // whose evidence was deleted after the fact pass for a run that never started — the damaged
+  // -artifacts check below this one exists precisely to name that case instead.
+  const stderr = path.join(runDir, 'stderr.log');
+  if (!fs.existsSync(stderr) || readText(stderr)) return null;
+  return 'run abandoned at startup: events.jsonl has no events and stderr.log is empty, Codex did not run';
+}

package/src/meta/transport.mjs

@@ -0,0 +1,35 @@
+/**
+ * Where a run's transport errors live, and whether that evidence can be trusted.
+ *
+ * Quota exhaustion is the one signal that tells the orchestrator not to retry, so it is read
+ * only from structured events the CLI itself writes. Text outside that protocol is diagnostic
+ * evidence, not a verdict.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from './paths.mjs';
+import { readEvents } from './events.mjs';
+
+const stderrPath = (runDir) => path.join(runDir, 'stderr.log');
+const hasJsonContract = (runDir) => {
+  const args = readJson(path.join(runDir, 'worker.json'))?.args;
+  return Array.isArray(args) && args.includes('--json');
+};
+
+/**
+ * Artifacts that contradict each other about which contract the run was written under.
+ *
+ * A current run whose worker reached the end of runCodex() has an events.jsonl file. One whose
+ * own args promise `--json` but lacks that file lost evidence after the fact; calling it an
+ * archived run would make a quota refusal indistinguishable from a quoted one. The deadline
+ * marker remains a second consistency check because the same worker also creates stderr.log.
+ */
+export function transportGap(runDir, events = readEvents(runDir)) {
+  if (hasJsonContract(runDir) && !events.hasStream) {
+    return 'artifacts disagree: worker.json requests --json, but events.jsonl is missing; the evidence was damaged, so a quota refusal cannot be told apart from a quoted one';
+  }
+  const status = readJson(path.join(runDir, 'status.json'));
+  if (!status || !('stopped_on_deadline' in status)) return null;
+  if (fs.existsSync(stderrPath(runDir))) return null;
+  return 'artifacts disagree: this run recorded a deadline watch but has no stderr.log, so a quota signal cannot be told apart from a quoted one';
+}

package/src/meta/verdict.mjs

@@ -22,17 +22,12 @@ import {
 } from './paths.mjs';
 import { chainBaseline } from './chain.mjs';
 import { splitRunChanges } from './environment.mjs';
+import { readEvents } from './events.mjs';
 import { outcomeGap } from './outcome.mjs';
-
-/**
- * Quota exhaustion is a transport error, not a word. Both markers must sit on the same
- * line: a run whose review text merely discusses "quota exhaustion" is not a run that
- * hit the quota, and reporting LIMIT there tells the orchestrator not to retry when it
- * should. "try again later" is deliberately absent — it is a transient-failure phrase,
- * not a quota one.
- */
-const LIMIT_RE = /rate.?limit|usage limit|usage_limit|quota exceeded|quota exhausted|too many requests|\b429\b/i;
-const ERROR_RE = /\bERROR\b|error[:=]|stream error|"status"\s*:\s*429|rejected|refused|failed/i;
+import { deadlineReason } from './deadline.mjs';
+import { startupGap } from './startup.mjs';
+import { transportGap } from './transport.mjs';
+import { reasonFrom } from './reason.mjs';
 
 // How much prose an answer must carry once coordinates and paths are subtracted. Measured
 // on the scout run of 2026-07-30 that replied with a table of `file.ts:60-79` rows: every
@@ -42,24 +37,6 @@ const ERROR_RE = /\bERROR\b|error[:=]|stream error|"status"\s*:\s*429|rejected|r
 const MIN_SUBSTANCE_CHARS = 80;
 const MIN_SINGLE_SUBSTANCE_CHARS = 200;
 
-/**
- * The honest reason for a failure. Codex prints API errors as pretty-printed JSON, so
- * the literally-last line is often just `}` — useless in a one-line reply. Prefer the
- * error message field, then any error line, then the last line that carries text.
- */
-const reasonFrom = (log) => {
-  const messages = [...log.matchAll(/"message"\s*:\s*"((?:[^"\\]|\\.)*)"/g)];
-  if (messages.length) return line(messages[messages.length - 1][1].replace(/\\"/g, '"'));
-  const lines = log.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  const errorLine = [...lines].reverse().find((l) => /error|failed|denied|refused/i.test(l));
-  return line(errorLine || lines[lines.length - 1] || '');
-};
-
-const limitSignal = (log) => {
-  const hit = log.split(/\r?\n/).find((l) => LIMIT_RE.test(l) && ERROR_RE.test(l));
-  return hit ? line(hit) : null;
-};
-
 /**
  * Which touched paths the task never authorised. The scope exists because prose does not
  * bind: one build run was told in words to keep away from `!Plans/*.md` and edited them
@@ -271,17 +248,18 @@ function branchDuringRun(runDir) {
 }
 
 /**
- * Status comes from artifacts, never from intent. An abandoned run leaves raw.log at
- * zero bytes, and that is a FAIL with its own reason — not a retry hint. An empty
- * result with a quota signal in the log is LIMIT; without one it is FAIL.
+ * Status comes from artifacts, never from intent. A current run with an events stream but no
+ * events and silent stderr is abandoned at startup; an empty result with no structured
+ * transport error is FAIL, because diagnostic text cannot turn a quoted limit into LIMIT.
  */
-export function resolveStatus({ log, logBytes, resultOk, exit, agent, result, runDir }) {
-  if (!logBytes) {
-    return {
-      status: 'FAIL',
-      reason: 'run abandoned at startup: raw.log is empty, Codex did not run',
-    };
-  }
+export function resolveStatus({ resultOk, exit, agent, result, runDir, events }) {
+  const eventData = events ?? readEvents(runDir);
+  // First, as the empty raw.log check was before it: a run that never started cannot be graded
+  // for what happened in its window. Below this line sit accusations about the run's conduct —
+  // a commit, a moved branch — and HEAD moving while Codex was absent is somebody else's doing.
+  // Blaming a run that did not exist is the same class of lie every other check here prevents.
+  const startup = startupGap(runDir, eventData);
+  if (startup) return { status: 'FAIL', reason: startup };
   // Ahead of everything else, including LIMIT: a commit under an explicit ban is a broken
   // contract, not a grade for the work. Whatever else the run produced, the orchestrator has
   // to learn first that history moved under it.
@@ -291,13 +269,33 @@ export function resolveStatus({ log, logBytes, resultOk, exit, agent, result, ru
     const branched = branchDuringRun(runDir);
     if (branched) return { status: 'FAIL', reason: branched };
   }
+  const deadline = deadlineReason(runDir);
+  if (deadline) return { status: 'FAIL', reason: deadline };
+  // Damaged transport evidence is not archived transport evidence. Checked before LIMIT, since
+  // the fallback it guards is what LIMIT would otherwise use.
+  const transport = transportGap(runDir, eventData);
+  if (transport) return { status: 'FAIL', reason: transport };
+  // Only a run with nothing to show is judged by its transport errors. The CLI prints an error
+  // event for a dropped stream and then retries it, so a run that recovered, filled its result
+  // and exited zero did the job — turning that survived error into a verdict would fail honest
+  // work, the mirror image of the false LIMIT this whole module exists to remove.
+  const transportError =
+    eventData.hasEvents && (!resultOk || exit !== 0) ? eventData.transport_error : null;
+  if (transportError) {
+    // This branch already knows why the run died: the CLI said so itself, with a status. Letting
+    // the ordered reason speak here would answer a transport question with the model's older
+    // complaint about the task — a LIMIT that never mentions quota is the same "verdict says the
+    // wrong thing" defect this module exists to remove.
+    return {
+      status: transportError.quota ? 'LIMIT' : 'FAIL',
+      reason: transportError.reason,
+    };
+  }
   if (!resultOk) {
-    const limit = limitSignal(log);
-    if (limit) return { status: 'LIMIT', reason: limit };
-    return { status: 'FAIL', reason: reasonFrom(log) || `result is empty, exit=${exit}` };
+    return { status: 'FAIL', reason: reasonFrom(runDir, eventData) || `result is empty, exit=${exit}` };
   }
   if (exit !== 0) {
-    return { status: 'FAIL', reason: `result exists, but exit=${exit}: ${reasonFrom(log)}` };
+    return { status: 'FAIL', reason: `result exists, but exit=${exit}: ${reasonFrom(runDir, eventData)}` };
   }
   // A red verification is a failed job, not an OK with a footnote. The orchestrator
   // reads the first word; burying "fail" in line three is how a broken build passes.

package/src/retention.mjs

@@ -0,0 +1,120 @@
+/** Owns the transport list and age decision shared by automatic and manual cleanup. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { liveRuns, normalizePath } from './hooks/live-runs.mjs';
+
+// Plan_17 step 3 found one order's copied list and age default diverging on the same day. Keeping
+// the transport boundary here prevents automatic cleanup from eating accounting files.
+export const TRANSPORT_FILES = Object.freeze(['events.jsonl', 'stderr.log', 'raw.log']);
+
+function ageDate(name) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})_(\d{2})(\d{2})(\d{2})(?:_|$)/.exec(name);
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second] = match;
+  const timestamp = Date.UTC(
+    Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second),
+  );
+  const date = new Date(timestamp);
+  if (date.getUTCFullYear() !== Number(year)
+    || date.getUTCMonth() !== Number(month) - 1
+    || date.getUTCDate() !== Number(day)
+    || date.getUTCHours() !== Number(hour)
+    || date.getUTCMinutes() !== Number(minute)
+    || date.getUTCSeconds() !== Number(second)) return null;
+  return timestamp;
+}
+
+function nowTimestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  const parsed = Date.parse(value ?? '');
+  return Number.isNaN(parsed) ? Date.now() : parsed;
+}
+
+function ageCutoff(olderThan, now) {
+  if (!olderThan) return null;
+  if (olderThan.kind === 'duration') {
+    const unit = olderThan.unit === 'h' ? 60 * 60 * 1000 : 24 * 60 * 60 * 1000;
+    return now - olderThan.amount * unit;
+  }
+  return Date.parse(`${olderThan.date}T00:00:00.000Z`);
+}
+
+/** Returns whether a run is older than a parsed threshold, using only its folder name. */
+export function runIsOlderThan(runName, olderThan, now = Date.now()) {
+  const timestamp = ageDate(runName);
+  if (timestamp === null || !olderThan) return false;
+  return timestamp < ageCutoff(olderThan, nowTimestamp(now));
+}
+
+/**
+ * Removes only regular transport files from old, non-live runs.
+ *
+ * Plan_17 step 4 makes cleanup deliberately best effort: a full disk must not stop a new run, and
+ * deleting one named file cannot justify recursive removal of a run folder or accounting artifacts.
+ */
+export function cleanupRetention(runsDir, config, options = {}) {
+  // Do not inspect days when disabled. A stale or malformed day value must not re-enable cleanup.
+  if (!config?.enabled) return null;
+  const days = config.days;
+  if (typeof days !== 'number' || !Number.isFinite(days) || days <= 0) return null;
+
+  const filesystem = options.fs || fs;
+  const now = options.now ?? Date.now();
+  let entries;
+  try {
+    entries = filesystem.readdirSync(runsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  let live = new Set();
+  try {
+    // Normalized like every other path comparison in the package: a case difference between the
+    // scan and the probe would make a live run look like a stale one, and this deletes files.
+    live = new Set(liveRuns(runsDir).map(({ dir }) => normalizePath(dir)));
+  } catch {
+    // The launcher wraps the whole pass too; when the shared probe cannot answer, retain every
+    // run rather than repeating the abandoned-run incident with a live folder as a target.
+    return null;
+  }
+
+  const removedRuns = new Set();
+  let bytesFreed = 0;
+  for (const entry of entries) {
+    let isDirectory;
+    try {
+      isDirectory = entry.isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDirectory) continue;
+
+    const runDir = path.join(runsDir, entry.name);
+    if (live.has(normalizePath(runDir)) || !runIsOlderThan(entry.name, {
+      kind: 'duration',
+      amount: days,
+      unit: 'd',
+    }, now)) continue;
+
+    for (const filename of TRANSPORT_FILES) {
+      const target = path.join(runDir, filename);
+      let stat;
+      try {
+        stat = filesystem.lstatSync(target);
+      } catch {
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      try {
+        filesystem.unlinkSync(target);
+      } catch {
+        continue;
+      }
+      removedRuns.add(entry.name);
+      if (Number.isFinite(stat.size) && stat.size > 0) bytesFreed += stat.size;
+    }
+  }
+
+  return removedRuns.size ? { bytes_freed: bytesFreed, runs: removedRuns.size, days } : null;
+}

package/src/run-codex.mjs

@@ -29,7 +29,7 @@
  * tree and writes the verdict.
  *
  * The split exists because the caller dies long before a 20-25 minute run does. Run
- * `2026-07-31_114736_*` has no raw.log at all while 11+ files were written into the tree: the
+ * `2026-07-31_114736_*` has no events.jsonl at all while 11+ files were written into the tree: the
  * dispatcher's Bash call hit its two-minute timeout, node was killed, spawnSync's buffered
  * output died with it — and Codex kept going, unwatched and unrecorded. Killing that orphan
  * is not the fix either: its edits were the work, and later runs finished on top of them. So
@@ -84,9 +84,9 @@ if (invokedDirectly) {
     const { dir: currentRun, agent: currentAgent } = getRun();
     if (currentRun) {
       try {
-        fs.appendFileSync(path.join(currentRun, 'raw.log'), `\nrun-codex crash: ${err.stack}\n`);
+        fs.appendFileSync(path.join(currentRun, 'stderr.log'), `\nrun-codex crash: ${err.stack}\n`);
         const { reply } = writeFailure(currentRun, currentAgent, `Codex runner crashed: ${err.message}`, [
-          `Log: ${path.join(currentRun, 'raw.log')}`,
+          `Log: codex-bridge read ${currentRun}`,
         ]);
         emitReply(reply);
         process.exit(1);

package/src/run-config.json

@@ -1,4 +1,8 @@
 {
   "hooks": false,
-  "plugins": false
+  "plugins": false,
+  "retention": {
+    "enabled": true,
+    "days": 30
+  }
 }