@lyupro/codex-bridge 0.1.3 → 0.2.0

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/required-inputs.mjs

@@ -11,6 +11,15 @@ const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id',
 
 const freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
 
+export const CONTINUATION_INPUT = Object.freeze({
+  label: 'continue',
+  source: 'the orchestrator',
+  explanation:
+    'The run folder this pass is ordered to continue, followed by why the orchestrator is spending another pass. A continuation is assigned by the orchestrator; after a verdict, the dispatcher returns it and stops.',
+  example: '2026-08-05_092913_plan14-build — LIMIT at step 3, tests unwritten',
+  conditional: 'when --continue is passed',
+});
+
 export const REQUIRED_INPUTS = Object.freeze({
   'codex-scout': freezeEntries([
     {
@@ -19,6 +28,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-scout-20260804',
     },
+    CONTINUATION_INPUT,
   ]),
   'codex-build': freezeEntries([
     {
@@ -33,6 +43,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
       example: 'src/runner/**,tests/runner/**',
     },
+    CONTINUATION_INPUT,
   ]),
   'codex-review': freezeEntries([
     {
@@ -41,6 +52,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-review-20260804',
     },
+    CONTINUATION_INPUT,
   ]),
 });
 
@@ -51,14 +63,14 @@ function cleanValue(value) {
   return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
 }
 
-function isPlaceholder(value) {
+export function isPlaceholder(value) {
   const cleaned = cleanValue(value);
   if (!cleaned) return true;
   if (cleaned.startsWith('<') && cleaned.endsWith('>')) return true;
   return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
 }
 
-function extractValue(promptText, label) {
+export function extractValue(promptText, label) {
   const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
   const flag = `--${label.replaceAll(/\s+/g, '-')}`;
   const direct = new RegExp(
@@ -77,6 +89,23 @@ function extractValue(promptText, label) {
   return cleanValue(flagMatch[1] ?? flagMatch[2] ?? flagMatch[3]);
 }
 
+/** Keeps the 2026-08-05 continuation incident's run and reason in the shared input parser. */
+export function parseContinuationGrant(promptText) {
+  const prompt = typeof promptText === 'string' ? promptText : '';
+  const value = extractValue(prompt, CONTINUATION_INPUT.label);
+  if (isPlaceholder(value)) return null;
+
+  for (const separator of [/\s+—\s+/, /\s+-\s+/, /\s*:\s*/]) {
+    const match = value.match(new RegExp(`^(.+?)${separator.source}(.+)$`));
+    if (!match) continue;
+    const run = cleanValue(match[1]);
+    const reason = cleanValue(match[2]);
+    if (isPlaceholder(run) || isPlaceholder(reason)) return null;
+    return { run, reason };
+  }
+  return null;
+}
+
 /** Returns the immutable input entries for one dispatcher type. */
 export function requiredInputsFor(agentType) {
   return REQUIRED_INPUTS[agentType] || [];
@@ -85,20 +114,34 @@ export function requiredInputsFor(agentType) {
 /** Returns required entries whose value is absent or is still an obvious template placeholder. */
 export function missingInputs(agentType, promptText) {
   const prompt = typeof promptText === 'string' ? promptText : '';
-  return requiredInputsFor(agentType).filter((entry) => isPlaceholder(extractValue(prompt, entry.label)));
+  return requiredInputsFor(agentType).filter(
+    (entry) => !entry.conditional && isPlaceholder(extractValue(prompt, entry.label)),
+  );
 }
 
 /** Renders the compact contract the orchestrator sees while choosing a dispatcher. */
 export function renderRequiredInputSummary(agentType) {
   const entries = requiredInputsFor(agentType);
   if (!entries.length) return '';
-  const labels = entries.map((entry) => `\`${entry.label}\``);
-  return `Requires ${entries[0].source}-provided ${labels.join(' and ')}.`;
+  const labels = entries.map((entry) => {
+    const label = `\`${entry.label}\``;
+    return entry.conditional ? `${label} (${entry.conditional})` : label;
+  });
+  // Commas until the last pair: the list grew to three entries when the continuation grant
+  // joined it, and "a and b and c" reads as a stutter in the description the orchestrator
+  // sees while choosing a dispatcher.
+  const rendered = labels.length > 1
+    ? `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]}`
+    : labels[0];
+  return `Requires ${entries[0].source}-provided ${rendered}.`;
 }
 
 /** Renders the same contract for pass 2 agent instructions. */
 export function renderRequiredInputs(agentType) {
   return requiredInputsFor(agentType)
-    .map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`)
+    .map((entry) => {
+      const condition = entry.conditional ? ` Condition: ${entry.conditional}.` : '';
+      return `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.${condition}`;
+    })
     .join('\n');
 }

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
+  }
 }