@lyupro/codex-bridge 0.1.4 → 0.2.0

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);

package/src/runner/codex-cmd.mjs

@@ -1,6 +1,6 @@
 /**
  * Everything about invoking the `codex` CLI: which flags a run gets, whether the CLI is
- * there at all, and how its output reaches raw.log.
+ * there at all, and how its JSONL stdout reaches events.jsonl while stderr stays separate.
  *
  * The flag sets below are the ones the three agent files carried before, verbatim.
  * Sandboxes especially must not drift: codex-scout is read-only through
@@ -47,36 +47,74 @@ export function stopCodex(child, onWindows = process.platform === 'win32') {
  * shell. One command line through cmd.exe keeps a single code path; every argument is
  * quoted here, and unsafeForCmd() has already refused the ones that cannot be.
  *
- * The log is streamed, not collected: spawnSync kept every byte in memory and wrote the file
- * only on return, so a worker killed at minute twelve left raw.log missing entirely and the
- * run became unexplainable (2026-07-31, run 114736). Now whatever Codex has already said is
- * on disk, and the task text is pushed into stdin by hand since there is no `input` option
- * outside spawnSync. MAX_LOG stays the ceiling; past it the log is cut with a note rather
- * than the run being killed — a huge log is a diagnosis, not a reason to lose the work.
+ * Stdout is streamed, not collected: spawnSync kept every byte in memory and wrote the file
+ * only on return, so a worker killed at minute twelve left events.jsonl missing entirely and
+ * the run became unexplainable (2026-07-31, run 114736). Now whatever Codex has already said
+ * is on disk, and the task text is pushed into stdin by hand since there is no `input` option
+ * outside spawnSync. MAX_LOG stays the ceiling; past it the stream is cut rather than the run
+ * being killed — a huge stream is a diagnosis, not a reason to lose the work. stderr has its
+ * own bounded file because text outside the JSONL protocol must remain distinguishable from
+ * protocol events, and a line cut in half cannot be parsed back safely.
  */
-export function runCodex(args, taskText, logPath, budgetMinutes) {
+export function runCodex(args, taskText, eventsPath, budgetMinutes) {
   const onWindows = process.platform === 'win32';
   const deadlineMs =
     typeof budgetMinutes === 'number' && Number.isFinite(budgetMinutes) && budgetMinutes > 0
       ? budgetMinutes * 60 * 1000
       : null;
-  const log = fs.createWriteStream(logPath, { flags: 'a' });
-  let written = 0;
-  let cut = false;
-  const append = (chunk) => {
-    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
-    if (written >= MAX_LOG) {
-      if (!cut) {
-        cut = true;
-        log.write(`\nrun-codex: log truncated at ${MAX_LOG} bytes; further output is not saved\n`);
+  const stderrLog = fs.createWriteStream(path.join(path.dirname(eventsPath), 'stderr.log'), { flags: 'a' });
+  const eventsLog = fs.createWriteStream(eventsPath, { flags: 'a' });
+  const appendTo = (stream, label) => {
+    let written = 0;
+    let cut = false;
+    return (chunk) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
+      if (written >= MAX_LOG) {
+        if (!cut) {
+          cut = true;
+          stream.write(`\nrun-codex: ${label} truncated at ${MAX_LOG} bytes; further output is not saved\n`);
+        }
+        return;
       }
-      return;
-    }
-    const room = MAX_LOG - written;
-    const slice = buf.length > room ? buf.subarray(0, room) : buf;
-    written += slice.length;
-    log.write(slice);
+      const room = MAX_LOG - written;
+      const slice = buf.length > room ? buf.subarray(0, room) : buf;
+      written += slice.length;
+      stream.write(slice);
+    };
   };
+  const appendStderr = appendTo(stderrLog, 'stderr log');
+  const appendEvents = (() => {
+    let pending = Buffer.alloc(0);
+    let written = 0;
+    let cut = false;
+    const append = (chunk) => {
+      if (cut) return;
+      const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
+      pending = pending.length ? Buffer.concat([pending, incoming]) : incoming;
+      let newline = pending.indexOf(0x0a);
+      while (newline !== -1) {
+        const line = pending.subarray(0, newline + 1);
+        pending = pending.subarray(newline + 1);
+        if (written + line.length > MAX_LOG) {
+          cut = true;
+          pending = Buffer.alloc(0);
+          return;
+        }
+        written += line.length;
+        eventsLog.write(line);
+        newline = pending.indexOf(0x0a);
+      }
+      if (pending.length > MAX_LOG - written) {
+        cut = true;
+        pending = Buffer.alloc(0);
+      }
+    };
+    const finish = () => {
+      if (!cut && pending.length && written + pending.length <= MAX_LOG) eventsLog.write(pending);
+      pending = Buffer.alloc(0);
+    };
+    return { append, finish };
+  })();
 
   let child;
   if (onWindows) {
@@ -97,12 +135,36 @@ export function runCodex(args, taskText, logPath, budgetMinutes) {
   return new Promise((resolve) => {
     let failed = false;
     let deadlineTimer;
+    let stoppedOnDeadline = false;
+    let exited = false;
+    let elapsedMs = 0;
     const startedAt = Date.now();
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
+    child.stdout.on('data', appendEvents.append);
+    child.stdout.on('end', appendEvents.finish);
+    child.stderr.on('data', (chunk) => {
+      appendStderr(chunk);
+    });
+    // A log file that cannot be opened must not leave Codex spending quota unattended. Without
+    // a listener the stream's 'error' event throws inside the worker, and the crash handler
+    // closes the run folder while the CLI keeps running — the orphan of 2026-07-31 with an
+    // extra step. The run dies, but it dies with its child: killing first, recording second.
+    const onStreamError = (which) => (err) => {
+      failed = true;
+      const note = `\nrun-codex: cannot write ${which}: ${err.message}\n`;
+      if (which !== 'stderr.log' && stderrLog.writable) stderrLog.write(note);
+      stopCodex(child, onWindows);
+    };
+    stderrLog.on('error', onStreamError('stderr.log'));
+    eventsLog.on('error', onStreamError('events.jsonl'));
     child.on('error', (err) => {
       failed = true;
-      append(`\nrun-codex: ${err.message}\n`);
+      appendStderr(`\nrun-codex: ${err.message}\n`);
+    });
+    // 'exit' fires when the process is gone; 'close' waits for stdio, which a grandchild can
+    // hold open past the deadline. Judging by 'close' would let the timer brand a run that
+    // finished honestly at minute 24 as one the runner killed.
+    child.on('exit', () => {
+      exited = true;
     });
     // Codex that dies before reading the order leaves an EPIPE here; the exit code and the
     // log already say what happened, and an unhandled stream error would replace that with
@@ -112,15 +174,38 @@ export function runCodex(args, taskText, logPath, budgetMinutes) {
     if (deadlineMs !== null) {
       deadlineTimer = setTimeout(() => {
         const elapsed = Date.now() - startedAt;
-        log.write(
-          `\nrun-codex: run stopped on its deadline after ${elapsed} ms (budget ${deadlineMs} ms)\n`,
-        );
+        // The tree is stopped either way — a grandchild still holding stdio is exactly what
+        // the budget exists to end — but only a process that was still alive was killed by
+        // the deadline, and only that run may say so.
+        if (!exited) {
+          stoppedOnDeadline = true;
+          elapsedMs = elapsed;
+          stderrLog.write(
+            `\nrun-codex: run stopped on its deadline after ${elapsed} ms (budget ${deadlineMs} ms)\n`,
+          );
+        }
         stopCodex(child, onWindows);
       }, deadlineMs);
     }
-    child.on('close', (code) => {
+    // A stream that already failed never calls back from end(), so waiting on both callbacks in
+    // sequence hangs the worker until its own deadline — the run then costs a full budget and
+    // answers nothing. Closing is best-effort; the verdict is not.
+    const close = (stream) =>
+      new Promise((done) => {
+        if (stream.destroyed || stream.errored) {
+          stream.destroy();
+          done();
+          return;
+        }
+        stream.end(done);
+      });
+    child.on('close', async (code) => {
       if (deadlineTimer) clearTimeout(deadlineTimer);
-      log.end(() => resolve(failed || code === null ? 1 : code));
+      if (!stoppedOnDeadline) elapsedMs = Date.now() - startedAt;
+      const exit = failed || code === null ? 1 : code;
+      await close(stderrLog);
+      await close(eventsLog);
+      resolve({ exit, stoppedOnDeadline, elapsedMs });
     });
   });
 }
@@ -193,6 +278,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
   if (opts.agent === 'codex-scout') {
     return [
       'exec',
+      '--json',
       ...CLEAN_ENV,
       '--ignore-user-config',
       '-c',
@@ -216,6 +302,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
     // every edit is rejected ("writing is blocked by read-only sandbox").
     return [
       'exec',
+      '--json',
       ...CLEAN_ENV,
       '-c',
       effort,
@@ -246,6 +333,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
   // --ignore-user-config, same as scout: review never needs write access.
   return [
     'exec',
+    '--json',
     ...CLEAN_ENV,
     '--ignore-user-config',
     '-c',

package/src/runner/launcher.mjs

@@ -36,6 +36,7 @@ import { git, headSha, branchName, worktreeSnapshot, reviewScope } from './git-s
 import { codexArgs, requireCodex, runMode, unsafeForCmd } from './codex-cmd.mjs';
 import { runsRoot } from './runs-root.mjs';
 import { resolveProjectRunsDir } from './project-dir.mjs';
+import { cleanupRetention } from '../retention.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
@@ -166,6 +167,15 @@ export async function launcher() {
   // first one's edits, and an honest run gets failed for work it never did.
   const busy = opts.agent === 'codex-build' ? activeRun(projectRunsRoot, repoRoot) : null;
 
+  let retention = null;
+  try {
+    retention = cleanupRetention(projectRunsRoot, RUN_ENV?.retention);
+  } catch {
+    // Plan_17 step 4 makes retention advisory housekeeping: one broken filesystem call must never
+    // block a new run.
+    retention = null;
+  }
+
   const runDir = makeRunDir(path.join(projectRunsRoot, `${stamp()}_${opts.slug}`));
   setRun(runDir, opts.agent);
 
@@ -194,6 +204,7 @@ export async function launcher() {
     ...(chain.length ? { continues: chain[0] } : {}),
     // `continued_from` is the exact run the orchestrator named; `continues` above remains the chain base.
     ...(continuationGrant ? { continued_from: continuationGrant.run } : {}),
+    ...(retention ? { retention } : {}),
   });
 
   // Printed before anything can go wrong: even a dispatcher that dies mid-run leaves the

package/src/runner/worker.mjs

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { collect, exitCodeFor, AGENTS } from '../write-meta.mjs';
+import { writeStatus } from '../meta/run-state.mjs';
 import { setRun, emitReply } from './run-context.mjs';
 import { git, headSha, branchName, worktreeSnapshot, findFakeDone } from './git-state.mjs';
 import { runCodex } from './codex-cmd.mjs';
@@ -26,12 +27,19 @@ export async function worker(runDir) {
   const repoRoot = cfg.repo;
   setRun(runDir, cfg.agent);
 
-  const exit = await runCodex(
+  const run = await runCodex(
     cfg.args,
     fs.readFileSync(path.join(runDir, 'task.md'), 'utf8'),
-    path.join(runDir, 'raw.log'),
+    path.join(runDir, 'events.jsonl'),
     cfg.budget_minutes,
   );
+  // This runner-owned fact cannot be forged through events.jsonl, which Codex can write.
+  // Written even when no deadline fired: `false` is the marker that a runner was watching,
+  // and an archived run with no field at all must stay distinguishable from a run that lived.
+  writeStatus(runDir, {
+    stopped_on_deadline: run.stoppedOnDeadline,
+    elapsed_ms: run.elapsedMs,
+  });
 
   if (cfg.agent === 'codex-build') {
     fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${cfg.is_git_repo ? headSha(repoRoot) : ''}\n`);
@@ -56,7 +64,7 @@ export async function worker(runDir) {
 
   // collect() writes meta.json and closes status.json; reply.txt comes last, so the launcher
   // seeing a reply is proof the verdict behind it is already on disk.
-  const { meta, reply } = collect(runDir, cfg.agent, exit);
+  const { meta, reply } = collect(runDir, cfg.agent, run.exit);
   emitReply(reply);
   process.exit(exitCodeFor(meta.status));
 }

package/src/write-meta.mjs

@@ -3,9 +3,9 @@
  * Turns one Codex run directory into accounting plus a verdict:
  *   node write-meta.mjs <runDir> <agent> <exitCode>
  *
- * This is the only entry point that reads a run's artifacts. It writes meta.json — quota
- * accounting that survives deletion of the gitignored raw.log — and derives the run
- * status from what is actually on disk: exit code, log size, result file, git state.
+ * This is the only entry point that reads a run's artifacts. It writes meta.json — accounting
+ * for the two transport files — and derives the run status from what is actually on disk:
+ * exit code, structured events, result file, git state.
  * A dispatcher agent therefore cannot report an outcome its own run does not support.
  *
  * The reply lines printed here ARE the reply. Agents forward this stdout verbatim
@@ -24,6 +24,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { changedPaths, readJson, readText, size } from './meta/paths.mjs';
 import { splitRunChanges } from './meta/environment.mjs';
+import { readEvents } from './meta/events.mjs';
 import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
 import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
@@ -49,24 +50,30 @@ export function collect(runDir, agent, exitCode) {
   const cfg = AGENTS[agent];
   if (!cfg) throw new Error(`unknown agent: ${agent} (expected one of ${Object.keys(AGENTS).join(', ')})`);
 
-  const logPath = path.join(runDir, 'raw.log');
+  const eventsPath = path.join(runDir, 'events.jsonl');
+  const stderrPath = path.join(runDir, 'stderr.log');
   const resultPath = path.join(runDir, cfg.result);
-  const log = readText(logPath);
-  const logBytes = size(logPath);
+  const eventsBytes = size(eventsPath);
+  const stderrBytes = size(stderrPath);
   const result = readJson(resultPath);
   const resultOk = Boolean(result) && cfg.filled(result);
   const exit = exitCode === undefined || exitCode === null ? null : Number(exitCode);
+  const events = readEvents(runDir);
+  const worker = readJson(path.join(runDir, 'worker.json'));
 
-  // "tokens used" is followed by the count on the next line, with a non-breaking
-  // thousands separator — strip every non-digit rather than trusting the spacing.
-  const usage = [...log.matchAll(/tokens used[\r\n]+([^\r\n]+)/g)].pop();
-
-  // `codex exec review` reports no usage at all. Null, never 0: a zero would silently
-  // understate the total in /codex:usage.
-  const tokens = usage ? parseInt(usage[1].replace(/\D/g, ''), 10) || null : null;
-
-  const pick = (re) => (log.match(re) || [])[1] || null;
-  const { status, reason, carried } = resolveStatus({ log, logBytes, resultOk, exit, agent, result, runDir });
+  const args = Array.isArray(worker?.args) ? worker.args : [];
+  const argValue = (flag) => {
+    const index = args.indexOf(flag);
+    return index >= 0 && typeof args[index + 1] === 'string' ? args[index + 1] : null;
+  };
+  const { status, reason, carried } = resolveStatus({
+    resultOk,
+    exit,
+    agent,
+    result,
+    runDir,
+    events,
+  });
 
   const meta = {
     agent,
@@ -88,14 +95,16 @@ export function collect(runDir, agent, exitCode) {
       changedPaths(readText(path.join(runDir, 'state-before.txt')), readText(path.join(runDir, 'state-after.txt'))),
     ).environment,
     result_ok: resultOk,
-    log_bytes: logBytes,
-    tokens,
-    tokens_reported: tokens !== null,
-    model: pick(/^model:\s*(\S+)/m),
-    sandbox: pick(/^sandbox:\s*(\S+)/m),
+    events_bytes: eventsBytes,
+    stderr_bytes: stderrBytes,
+    tokens: events.tokens,
+    tokens_reported: events.tokens !== null,
+    usage: events.usage,
+    model: argValue('-m'),
+    sandbox: argValue('--sandbox'),
     // Null for runs made before env.json existed: absence is not the same as "both off".
     env: readJson(path.join(runDir, 'env.json')),
-    session_id: pick(/^session id:\s*(\S+)/m),
+    session_id: events.session_id,
   };
 
   fs.writeFileSync(path.join(runDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);