@lyupro/codex-bridge 0.1.4 → 0.3.0

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
@@ -11,10 +11,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { createHeartbeat, HEARTBEAT_INTERVAL_MS } from '../heartbeat.mjs';
 import { writeFailure } from '../write-meta.mjs';
 import { MAX_LOG } from './git-state.mjs';
 import { CLEAN_ENV, RUN_ENV } from './run-env.mjs';
 
+// Thirty seconds, not a fraction of one: after `exit` the pipe still holds whatever Codex wrote
+// last, and that tail carries `item.completed` — the result the verdict is read from. A quarter
+// of a second is enough to lose it on a loaded Windows host, turning a finished run into "the run
+// left no event". The grace exists to bound a grandchild holding stdio open forever (2026-08-06,
+// run 2026-08-06_204007_build waited 25 minutes), and thirty seconds bounds that just as well.
+const STDIO_DRAIN_GRACE_MS = 30_000;
+
 /**
  * An argument cmd.exe cannot be handed safely, or undefined. `%` is fatal because cmd
  * expands variables even inside quotes. The launcher asks first, so the refusal costs
@@ -47,36 +55,81 @@ 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, graceMs = STDIO_DRAIN_GRACE_MS) {
   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`);
+  let exited = false;
+  const heartbeat = createHeartbeat(path.dirname(eventsPath));
+  const stampHeartbeat = () => {
+    if (!exited) heartbeat.stamp();
+  };
+  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) => {
+      stampHeartbeat();
+      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) => {
+      stampHeartbeat();
+      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 +150,35 @@ export function runCodex(args, taskText, logPath, budgetMinutes) {
   return new Promise((resolve) => {
     let failed = false;
     let deadlineTimer;
+    let heartbeatTimer;
+    let stdioGraceTimer;
+    let stoppedOnDeadline = false;
+    let exitCode;
+    let settled = false;
+    let elapsedMs = 0;
     const startedAt = Date.now();
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
+    stampHeartbeat();
+    heartbeatTimer = setInterval(stampHeartbeat, HEARTBEAT_INTERVAL_MS);
+    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`);
     });
     // 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,16 +188,64 @@ 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);
+      });
+
+    // 'exit' fires when Codex is gone; 'close' waits for stdio, which the 2026-08-06 incident
+    // showed a grandchild can hold open forever. A bounded drain grace keeps normal logs intact,
+    // then closes the run with an explicit marker instead of waiting for an unbounded pipe.
+    const finish = async (code, stdioDrained) => {
+      if (settled) return;
+      settled = true;
+      if (deadlineTimer) clearTimeout(deadlineTimer);
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      if (stdioGraceTimer) clearTimeout(stdioGraceTimer);
+      if (!stoppedOnDeadline) elapsedMs = Date.now() - startedAt;
+      const exit = failed || code === null ? 1 : code;
+      appendEvents.finish();
+      if (!stdioDrained) {
+        try { child.stdout.destroy(); } catch {}
+        try { child.stderr.destroy(); } catch {}
+      }
+      await close(stderrLog);
+      await close(eventsLog);
+      resolve({ exit, stoppedOnDeadline, elapsedMs, stdioDrained });
+    };
+
+    child.on('exit', (code) => {
+      exited = true;
+      exitCode = code;
       if (deadlineTimer) clearTimeout(deadlineTimer);
-      log.end(() => resolve(failed || code === null ? 1 : code));
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      // The grace is an argument only so tests can prove the fallback without waiting it out;
+      // a run never passes one, because a per-run grace is a second place to configure a
+      // contract that must be identical for every run.
+      stdioGraceTimer = setTimeout(() => finish(exitCode, false), graceMs);
     });
+    child.on('close', (code) => finish(code, true));
   });
 }
 
@@ -193,6 +317,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
   if (opts.agent === 'codex-scout') {
     return [
       'exec',
+      '--json',
       ...CLEAN_ENV,
       '--ignore-user-config',
       '-c',
@@ -216,6 +341,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 +372,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,22 @@ 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.
+  // `stdio_drained: false` separately records an exit that needed the grace fallback because
+  // a grandchild kept a pipe open, the distinction the 2026-08-06 incident made necessary.
+  writeStatus(runDir, {
+    stopped_on_deadline: run.stoppedOnDeadline,
+    elapsed_ms: run.elapsedMs,
+    stdio_drained: run.stdioDrained,
+  });
 
   if (cfg.agent === 'codex-build') {
     fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${cfg.is_git_repo ? headSha(repoRoot) : ''}\n`);
@@ -56,7 +67,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`);