@lyupro/codex-bridge 0.1.4 → 0.3.0

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/no-self-execution.mjs

@@ -0,0 +1,18 @@
+/**
+ * Keeps the dispatcher's first rule identical across all three prompts.
+ * On 2026-08-06 codex-build wrote 19 files using the Claude quota, which is why a failed
+ * delegation must end in an explicit failure instead of inviting the dispatcher to continue.
+ */
+const NO_SELF_EXECUTION = `## No self-execution
+
+Your only job is to start a run through \`run-codex.mjs\` and report its result; you are not the one who performs the task.
+
+- If \`run-codex.mjs\` is missing, does not start, exits without \`RUN=\`/\`ATTACH=\`, or the run fails to begin for any reason, immediately return \`FAIL — could not start the Codex run: <reason>\` and stop.
+- Performing the task yourself when the run could not be started is prohibited: do not read code, write files, or fix tests. Doing it yourself spends the Claude Max quota on exactly what the delegation existed to avoid, and does so silently.
+- Claiming "files were created" without a run that actually happened is prohibited under all circumstances. No run, no result.
+
+On 2026-08-06, codex-build wrote 19 files using the Claude quota; no quota was saved and no Codex verification happened.`;
+
+export function renderNoSelfExecution() {
+  return NO_SELF_EXECUTION;
+}

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

package/src/run-config.mjs

@@ -26,6 +26,9 @@ export const CONFIG_PATH = path.join(HERE, 'run-config.json');
 const BUDGET_KEY = 'budgets';
 const BUDGET_MODES = ['scout', 'build', 'review'];
 const DEFAULT_BUDGETS = { scout: 15, build: 25, review: 20 };
+const RETENTION_KEY = 'retention';
+const RETENTION_FIELDS = ['enabled', 'days'];
+const DEFAULT_RETENTION = { enabled: true, days: 30 };
 
 /**
  * Files the surrounding tooling writes on its own, in any repository a run touches.
@@ -52,6 +55,7 @@ export const DEFAULTS = {
   plugins: false,
   models: {},
   budgets: DEFAULT_BUDGETS,
+  retention: DEFAULT_RETENTION,
   environmentPaths: DEFAULT_ENVIRONMENT_PATHS,
   answerLanguage: 'English',
 };
@@ -75,7 +79,51 @@ export const ALLOWED_EFFORTS = Object.freeze(['none', 'minimal', 'low', 'medium'
  * two languages. English is the default because the package is read by strangers.
  */
 const STRING_KEYS = ['answerLanguage'];
-const KEYS = [...SWITCH_KEYS, ...LIST_KEYS, ...OBJECT_KEYS, ...STRING_KEYS, BUDGET_KEY];
+const KEYS = [...SWITCH_KEYS, ...LIST_KEYS, ...OBJECT_KEYS, ...STRING_KEYS, BUDGET_KEY, RETENTION_KEY];
+
+function readRetention(file, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}” must be an object with enabled and days, not ${JSON.stringify(value)}`,
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (!RETENTION_FIELDS.includes(key)) {
+      throw new Error(
+        `${file}: key “${RETENTION_KEY}” has unknown field “${key}”. ` +
+          `Only ${RETENTION_FIELDS.join(', ')} are allowed`,
+      );
+    }
+  }
+  if (typeof value.enabled !== 'boolean') {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}.enabled” must be true or false, not ${JSON.stringify(value.enabled)}`,
+    );
+  }
+  // Plan_17 step 4 does not read days when disabled, so stale values cannot revive deletion after
+  // the step 3 incident where a copied default silently turned cleanup back on.
+  if (!value.enabled) return { enabled: false };
+  if (typeof value.days !== 'number' || !Number.isFinite(value.days) || value.days <= 0) {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}.days” must be a positive number of days, not ${JSON.stringify(value.days)}`,
+    );
+  }
+  return { enabled: true, days: value.days };
+}
+
+export function retentionNotice(config) {
+  if (config?.retention?.enabled) {
+    const days = config.retention.days;
+    return {
+      enabled: true,
+      text: `Automatic cleanup is ON — run transport older than ${days} days is removed to reclaim disk space. Accounting and reports are never touched. Change or disable: retention in run-config.json.`,
+    };
+  }
+  return {
+    enabled: false,
+    text: 'Automatic cleanup is OFF — run transport is retained until manually pruned.',
+  };
+}
 
 /**
  * A run gets a hard wall-clock budget, because the caller's timeout is not a run contract:
@@ -152,6 +200,10 @@ export function readRunConfig(file = CONFIG_PATH) {
       config[key] = readBudgets(file, value);
       continue;
     }
+    if (key === RETENTION_KEY) {
+      config[key] = readRetention(file, value);
+      continue;
+    }
     if (LIST_KEYS.includes(key)) {
       if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
         throw new Error(
@@ -252,6 +304,7 @@ const state = (config) => [
     return `${key}: ${model}${profile.effort ? ` at ${profile.effort} effort` : ''}`;
   }).join('; ')}`,
   `budgets: ${BUDGET_MODES.map((mode) => `${mode}: ${config.budgets?.[mode] ?? DEFAULT_BUDGETS[mode]} minutes`).join('; ')}`,
+  `retention: ${config.retention?.enabled ? `on — transport older than ${config.retention.days} days` : 'off — automatic cleanup disabled'}`,
 ];
 
 function main(argv) {

package/src/runner/attach.mjs

@@ -112,7 +112,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
     return exitCodeFor(meta.status);
   }
   const { reply } = writeFailure(runDir, candidate.status.agent, 'run worker process died without recording a verdict', [
-    `Log: ${path.join(runDir, 'raw.log')}`,
+    `Log: codex-bridge read ${runDir}`,
     'Any Codex changes remain in the tree — check them with git status',
   ]);
   console.log(reply);