@lyupro/codex-bridge 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-07
+
+### Added
+
+- `codex-bridge sweep [<project>]` closes running records whose runner pid is dead, across the whole store or one project. It changes state but deletes no run folder or transport, never touches a live pid, and lists every stalled-but-live run with the exact `codex-bridge stop <run>` line that ends it. A dead record can therefore be cleared without paying for another run, while a live worker remains the sole writer until `stop` kills it first.
+- Every new run folder carries a `heartbeat` file, and `status.json` carries `stdio_drained`. The heartbeat records movement from Codex output and the still-running child rather than a timer that would keep an orphan alive; `stdio_drained` says whether stdout/stderr closed normally or the bounded drain grace had to end the run.
+
+### Changed
+
+- Hook liveness now requires `state: running`, a live runner pid and a heartbeat no older than five minutes. A stalled run therefore stops holding the worktree lock instead of holding it until the deadline; the refusal that remains — always about a working run — says how long ago it last made progress and prints `codex-bridge stop <run>` for taking the repository back early. Record cleanup and the second-writing-run check still judge by pid alone, so a stale but live run is released to the operator, not closed underneath its worker.
+- The worker closes a run after `exit` with a bounded 30-second grace for stdio drain instead of waiting for `close`, which a grandchild can hold open forever. Healthy runs keep the event tail that carries their result and record `stdio_drained: true`; only the fallback records `false`.
+- The three dispatcher prompts now open with one shared no-self-execution block rendered through `{{CODEX_NO_SELF_EXECUTION}}`. If `run-codex.mjs` does not start a run, the dispatcher must return `FAIL` and stop, and a reply with no run folder is blocked by the guard. The installed prompts change only when the host runs `codex-bridge update`; a host that does not update keeps the old prompts.
+
+### Fixed
+
+- A dispatcher that cannot start Codex can no longer read the code, write the files or fix the tests itself and claim a result. The guard also rejects a made-up reply with no `RUN=` or `ATTACH=` behind it: no run, no result.
+
 ## [0.2.0] - 2026-08-06
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ node bin/codex-bridge.mjs stop <run>    # close a hanging run by hand, without h
 node bin/codex-bridge.mjs read <run>   # read a run: its events rendered as text, on demand
 node bin/codex-bridge.mjs projects     # what the run store holds: projects, runs, weight, tokens
 node bin/codex-bridge.mjs prune <project>   # reclaim disk space, transport only unless told otherwise
+node bin/codex-bridge.mjs sweep [<project>] # close running records whose runner is gone
 ```
 
 `install` copies the package into the host's `agents/codex/`, its slash commands into
@@ -54,6 +55,12 @@ accounting, reports and worktree snapshots alone; `--purge` is what takes a fold
 The same transport is dropped automatically from runs older than 30 days when a new run starts,
 which the reply says out loud; `retention` in `run-config.json` changes the age or turns it off.
 
+`sweep` is housekeeping for records left by a dead runner. With no project it scans the whole
+store; with one project it limits the scan to that folder. It uses the same dead-pid decision as
+start-of-run cleanup, never closes a live pid even when its heartbeat is stale, and never deletes
+run artifacts. A stale live-pid record is named with the exact `codex-bridge stop <run>` command
+needed to close it.
+
 ## What it gives you
 
 - **Three dispatcher agents** for Claude Code — reconnaissance (read-only), implementation

package/bin/codex-bridge.mjs

@@ -10,6 +10,7 @@ import { read } from '../cli/read.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
 import { prune } from '../cli/prune.mjs';
 import { stop } from '../cli/stop.mjs';
+import { sweep } from '../cli/sweep.mjs';
 import { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
 
@@ -23,6 +24,7 @@ Usage:
   codex-bridge projects [<name>] [--json]
   codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
   codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
+  codex-bridge sweep [<project>]
   codex-bridge read <run>
   codex-bridge stop <run>
   codex-bridge --help
@@ -35,6 +37,7 @@ Commands:
   doctor    Diagnose the selected Claude Code host
   projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
+  sweep     Close running records whose runner is gone
   read      Render a run's structured event stream
   stop      Stop a running Codex run and record FAIL`;
 
@@ -105,6 +108,11 @@ export async function main(argv, io = console) {
     io.log(result.output);
     return result.exitCode;
   }
+  if (command === 'sweep') {
+    const result = sweep(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
   if (command === 'install' || command === 'update' || command === 'uninstall') {
     const options = commandOptions(command, rest);
     const host = resolveHost(options);

package/cli/manifest.mjs

@@ -10,6 +10,7 @@ import {
   renderRequiredInputSummary,
   renderRequiredInputs,
 } from '../src/required-inputs.mjs';
+import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
 
 export { HOOK_DEFINITIONS };
 
@@ -42,7 +43,8 @@ export function replacePlaceholders(content, agentsDir) {
   return content
     .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)))
     .replaceAll('{{CODEX_REQUIRED_INPUTS_SUMMARY}}', renderRequiredInputSummary(agentType))
-    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType));
+    .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType))
+    .replaceAll('{{CODEX_NO_SELF_EXECUTION}}', renderNoSelfExecution());
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {

package/cli/sweep.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/** Closes dead-pid running records without deleting any run artifacts. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatSilence, heartbeatAge, isHeartbeatFresh } from '../src/heartbeat.mjs';
+import { markAbandoned, pidAlive } from '../src/meta/run-state.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { readJson } from '../src/write-meta.mjs';
+import { renderTable } from './table.mjs';
+
+const CLOSED_COLUMNS = [
+  { key: 'project', label: 'project' },
+  { key: 'run', label: 'run' },
+  { key: 'state', label: 'state' },
+];
+const STALE_COLUMNS = [
+  { key: 'project', label: 'project' },
+  { key: 'run', label: 'run' },
+  { key: 'silence', label: 'silent for' },
+];
+
+function result(exitCode, output) {
+  return { exitCode, output };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  for (const arg of argv) {
+    if (typeof arg !== 'string' || arg.startsWith('-')) {
+      return { error: `codex-bridge sweep: unknown option "${arg}".` };
+    }
+    positional.push(arg);
+  }
+  if (positional.length > 1) {
+    return { error: 'codex-bridge sweep accepts at most one project name.' };
+  }
+  const project = positional[0] || null;
+  if (project && (path.isAbsolute(project) || path.dirname(project) !== '.')) {
+    return { error: 'codex-bridge sweep requires a bare project name.' };
+  }
+  return { project };
+}
+
+function directories(root) {
+  try {
+    return fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch {
+    return [];
+  }
+}
+
+function selectedProjects(root, projectName) {
+  const entries = directories(root);
+  if (!projectName) {
+    return entries.map((entry) => ({ name: entry.name, dir: path.join(root, entry.name) }));
+  }
+  const entry = entries.find((candidate) => candidate.name === projectName);
+  if (!entry) return { error: `codex-bridge sweep: unknown project "${projectName}".` };
+  return [{ name: entry.name, dir: path.join(root, entry.name) }];
+}
+
+function staleLiveRuns(project) {
+  // The 2026-08-06 incident showed why stale heartbeat is report-only: a live worker remains
+  // the sole writer until stop kills it and records the outcome.
+  const stale = [];
+  for (const entry of directories(project.dir)) {
+    const dir = path.join(project.dir, entry.name);
+    const status = readJson(path.join(dir, 'status.json'));
+    if (!status || status.state !== 'running' || !pidAlive(status.pid) || isHeartbeatFresh(dir)) continue;
+    stale.push({
+      project: project.name,
+      run: entry.name,
+      silence: formatSilence(heartbeatAge(dir)),
+    });
+  }
+  return stale;
+}
+
+export function sweepPlan(argv = [], options = {}) {
+  const parsed = parseArgs(argv);
+  if (parsed.error) return parsed;
+  const root = path.resolve(options.runsRootPath || runsRoot());
+  const projects = selectedProjects(root, parsed.project);
+  if (projects.error) return projects;
+  return { root, project: parsed.project, projects };
+}
+
+function closeDeadRuns(plan) {
+  const closed = [];
+  const failures = [];
+  for (const project of plan.projects) {
+    try {
+      // No worktree snapshot is passed, and that is the choice rather than an omission: `stop`
+      // closes one named run and knows which repository to look at, while a sweep of the whole
+      // store would have to run git in every repository every project ever pointed at. The runs
+      // it closes died long ago, so that list would describe today's tree, not their work — the
+      // reason text already says a file list is unavailable, which is the honest answer here.
+      for (const change of markAbandoned(project.dir)) {
+        closed.push({ project: project.name, run: change.run, state: change.state });
+      }
+    } catch (error) {
+      failures.push({ project: project.name, message: error.message });
+    }
+  }
+  return { closed, failures };
+}
+
+function renderReport(plan, closed, stale, failures, options) {
+  const scope = plan.project ? `project "${plan.project}"` : 'all projects';
+  const lines = [`Sweep of ${scope} completed.`];
+  if (closed.length) {
+    lines.push(`Closed ${closed.length} running record${closed.length === 1 ? '' : 's'}:`);
+    lines.push(renderTable(CLOSED_COLUMNS, closed, options));
+  } else {
+    lines.push('Nothing to close; the store is unchanged.');
+  }
+  if (stale.length) {
+    lines.push(`Left ${stale.length} live-pid run${stale.length === 1 ? '' : 's'} with stale heartbeats untouched:`);
+    lines.push(renderTable(STALE_COLUMNS, stale, options));
+    lines.push('End each one explicitly:');
+    for (const run of stale) lines.push(`  codex-bridge stop ${run.run}`);
+  } else {
+    lines.push('Live-pid runs with stale heartbeats left untouched: none.');
+  }
+  if (failures.length) {
+    lines.push('Some project records could not be swept:');
+    for (const failure of failures) lines.push(`  ${failure.project}: ${failure.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function sweep(argv = [], options = {}) {
+  const plan = sweepPlan(argv, options);
+  if (plan.error) return result(2, plan.error);
+  const { closed, failures } = closeDeadRuns(plan);
+  // This is a report-only probe. markAbandoned owns the closure decision and is the only writer.
+  const stale = plan.projects.flatMap((project) => staleLiveRuns(project));
+  return result(
+    failures.length ? 1 : 0,
+    renderReport(plan, closed, stale, failures, options),
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
   "keywords": [
     "claude-code",

package/src/agents/codex-build.md

@@ -5,9 +5,10 @@ model: haiku
 tools: Bash
 ---
 
-You are the build dispatcher. You do not write code yourself: one command starts Codex with write
-access,
-and its output is your answer.
+{{CODEX_NO_SELF_EXECUTION}}
+
+You are the build dispatcher. One command starts Codex with write access, and its output is your
+answer.
 
 **Why you exist.** The orchestrator runs on a Claude Max subscription, while Codex runs on a
 ChatGPT subscription. Implementation must burn someone else's quota, not yours. Every extra line you

package/src/agents/codex-review.md

@@ -5,9 +5,10 @@ model: haiku
 tools: Bash
 ---
 
-You are the independent review dispatcher. You do not read code or form opinions yourself: one
-command
-starts a review by Codex, and its output is your answer.
+{{CODEX_NO_SELF_EXECUTION}}
+
+You are the independent review dispatcher. Forming an opinion about the diff yourself is the shape
+self-execution takes here: one command starts a review by Codex, and its output is your answer.
 
 **Why you exist.** A model that wrote code is bad at seeing its own mistakes, so a view
 from another model is needed. Codex runs on a ChatGPT subscription, so its opinion costs nothing

package/src/agents/codex-scout.md

@@ -5,8 +5,10 @@ model: haiku
 tools: Bash
 ---
 
-You are the scout dispatcher. You do not investigate anything yourself: one command starts Codex,
-and its output is your answer.
+{{CODEX_NO_SELF_EXECUTION}}
+
+You are the scout dispatcher. Investigating anything yourself is the shape self-execution takes
+here: one command starts Codex, and its output is your answer.
 
 **Why you exist.** The orchestrator runs on a Claude Max subscription, while Codex runs on a
 ChatGPT subscription. All heavy work (reading files, reasoning, generating the report) must happen

package/src/heartbeat.mjs

@@ -0,0 +1,80 @@
+/**
+ * The one definition of run progress: a heartbeat file in the run folder, its age, and the
+ * stale threshold. On 2026-08-06 run 2026-08-06_204007_build left a live worker waiting on
+ * Codex's grandchild; a worker timer alone would have kept that dead run looking alive, so
+ * the timer stops at exit.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const HEARTBEAT_FILE = 'heartbeat';
+// Ten seconds bounds metadata writes when a 300KB stream arrives as many chunks; output still
+// proves movement immediately in memory, while the periodic worker stamp keeps silence fresh.
+export const HEARTBEAT_WRITE_INTERVAL_MS = 10_000;
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+// Five minutes leaves a wide margin over the longest model-thinking silence seen in healthy
+// runs. The active-child timer refreshes below it; the margin is safer than unlocking a tree
+// while a working build is silent, which is the failure this heartbeat exists to prevent.
+export const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+
+export function heartbeatPath(runDir) {
+  return path.join(runDir, HEARTBEAT_FILE);
+}
+
+/** A failed stamp is deliberately swallowed: the verdict must not depend on this hint file. */
+export function createHeartbeat(runDir) {
+  let lastStamp = Number.NEGATIVE_INFINITY;
+  return {
+    stamp(now = Date.now()) {
+      if (!Number.isFinite(now)) return;
+      if (now >= lastStamp && now - lastStamp < HEARTBEAT_WRITE_INTERVAL_MS) return;
+      lastStamp = now;
+      try {
+        fs.writeFileSync(heartbeatPath(runDir), `${now}\n`);
+      } catch {
+        // A read-only or full run folder must still produce its normal verdict and artifacts.
+      }
+    },
+  };
+}
+
+/** Missing is an explicit legacy state: old live records keep their lock until their pid dies. */
+export function heartbeatAge(runDir, now = Date.now()) {
+  try {
+    const stat = fs.statSync(heartbeatPath(runDir));
+    if (!stat.isFile() || !Number.isFinite(now)) return Number.POSITIVE_INFINITY;
+    return Math.max(0, now - stat.mtimeMs);
+  } catch (err) {
+    return err.code === 'ENOENT' ? null : Number.POSITIVE_INFINITY;
+  }
+}
+
+/**
+ * How long a run has been silent, in words. It lives beside the age it formats because both the
+ * worktree lock's refusal and `sweep`'s report have to name the same silence to the same operator;
+ * two copies of this drifted apart the moment they were written.
+ */
+export function formatSilence(age) {
+  if (age === null || !Number.isFinite(age)) return 'an unknown duration';
+  const seconds = Math.floor(Math.max(0, age) / 1000);
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? '' : 's'}`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) {
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`
+      + (remainingSeconds ? ` ${remainingSeconds} second${remainingSeconds === 1 ? '' : 's'}` : '');
+  }
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours} hour${hours === 1 ? '' : 's'}`
+    + (remainingMinutes ? ` ${remainingMinutes} minute${remainingMinutes === 1 ? '' : 's'}` : '');
+}
+
+/**
+ * A running record is live when its heartbeat is fresh. Missing heartbeats remain live only for
+ * pre-Plan_20 records, an explicit fail-closed compatibility choice that preserves their lock.
+ */
+export function isHeartbeatFresh(runDir, now = Date.now()) {
+  const age = heartbeatAge(runDir, now);
+  return age === null || age <= HEARTBEAT_STALE_MS;
+}

package/src/hooks/live-runs.mjs

@@ -2,12 +2,18 @@
  * Shared, fail-open knowledge of live Codex runs.
  *
  * The reply guard and the worktree lock must answer the same question: a status.json is live
- * only while it says `running` and its runner pid accepts signal 0. Keeping that probe and the
- * directory scan here prevents the two protections from disagreeing about a run, which would
- * recreate the incident where the dispatcher reported while another run still edited the tree.
+ * only while it says `running`, its runner pid accepts signal 0, and its progress heartbeat is
+ * fresh. Keeping those probes and the directory scan here prevents the two protections from
+ * disagreeing about a run, which would recreate the 2026-08-06 incident where a dead Codex
+ * child left its worker and lock looking live through a grandchild-held stdio pipe.
+ *
+ * The heartbeat is required here and deliberately NOT in meta/run-state.mjs: releasing a lock
+ * early costs an operator one knowing edit, while closing a record early makes a second writer
+ * of its meta.json. See the comment above pidAlive() there.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { isHeartbeatFresh } from '../heartbeat.mjs';
 
 /** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
 export const isPidAlive = (pid) => {
@@ -41,7 +47,7 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && Boolean(value.trim());
 }
 
-function recognizedStatus(status) {
+function recognizedStatus(runDir, status) {
   return Boolean(status)
     && typeof status === 'object'
     && !Array.isArray(status)
@@ -50,7 +56,8 @@ function recognizedStatus(status) {
     && isNonEmptyString(status.agent)
     && isNonEmptyString(status.slug)
     && isNonEmptyString(status.repo)
-    && isPidAlive(status.pid);
+    && isPidAlive(status.pid)
+    && isHeartbeatFresh(runDir);
 }
 
 function readStatus(runDir) {
@@ -75,7 +82,7 @@ export function liveRuns(runsDir) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(runsDir, entry.name);
     const status = readStatus(dir);
-    if (recognizedStatus(status)) result.push({ dir, status });
+    if (recognizedStatus(dir, status)) result.push({ dir, status });
   }
   return result;
 }

package/src/hooks/worktree-lock.mjs

@@ -10,6 +10,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { formatSilence, heartbeatAge } from '../heartbeat.mjs';
 import { WRITE_TOOLS } from '../hook-definitions.mjs';
 import { runsRoot } from '../runner/runs-root.mjs';
 import { allLiveRuns, normalizePath } from './live-runs.mjs';
@@ -65,6 +66,12 @@ process.stdout.write(JSON.stringify({
     permissionDecision: 'deny',
     permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${targetPath} is inside repository `
       + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
-      + 'Wait for status.json to change state before editing this repository.',
+      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
+      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
+      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
+      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
+      // work they meant to keep.
+      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
+      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
   },
 }));

package/src/meta/run-state.mjs

@@ -25,6 +25,22 @@ export const pidAlive = (pid) => {
   }
 };
 
+/**
+ * This module deliberately judges by the pid alone, while hooks/live-runs.mjs also requires a
+ * fresh progress heartbeat. The two answer different questions, and merging them broke both:
+ *
+ * - a hook asks "may the operator edit this tree", and a stalled run must stop holding that
+ *   lock — the operator is editing knowingly, and a stale run should not cost them 25 minutes;
+ * - this module asks "may a second paid run write into this tree" and "is this folder finished".
+ *   Closing a run whose pid still lives makes markAbandoned the second writer of its meta.json:
+ *   the live worker reaches collect() afterwards and overwrites the verdict, so the documented
+ *   artifact order stops being a contract. Letting activeRun() past a live pid starts a second
+ *   writing run in one worktree, which is the 2026-08-05 incident this whole lock exists for.
+ *
+ * A stalled-but-live run is closed by `stop`, which kills the process first and only then
+ * records the verdict — one writer, in the right order.
+ */
+
 /**
  * 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
@@ -131,7 +147,8 @@ export function activeRun(runsRoot, repo, agent = 'codex-build') {
   const wanted = normalizePath(repo);
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const status = readJson(path.join(runsRoot, entry.name, 'status.json'));
+    const runDir = path.join(runsRoot, entry.name);
+    const status = readJson(path.join(runDir, 'status.json'));
     if (!status || status.state !== 'running' || status.agent !== agent) continue;
     if (normalizePath(status.repo) !== wanted) continue;
     if (pidAlive(status.pid)) return entry.name;

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/runner/codex-cmd.mjs

@@ -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
@@ -56,18 +64,24 @@ export function stopCodex(child, onWindows = process.platform === 'win32') {
  * 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, eventsPath, 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;
+  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) {
@@ -88,6 +102,7 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes) {
     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;
@@ -135,10 +150,15 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes) {
   return new Promise((resolve) => {
     let failed = false;
     let deadlineTimer;
+    let heartbeatTimer;
+    let stdioGraceTimer;
     let stoppedOnDeadline = false;
-    let exited = false;
+    let exitCode;
+    let settled = false;
     let elapsedMs = 0;
     const startedAt = Date.now();
+    stampHeartbeat();
+    heartbeatTimer = setInterval(stampHeartbeat, HEARTBEAT_INTERVAL_MS);
     child.stdout.on('data', appendEvents.append);
     child.stdout.on('end', appendEvents.finish);
     child.stderr.on('data', (chunk) => {
@@ -160,12 +180,6 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes) {
       failed = true;
       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
     // a crash of the runner.
@@ -199,14 +213,39 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes) {
         }
         stream.end(done);
       });
-    child.on('close', async (code) => {
+
+    // '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 });
+      resolve({ exit, stoppedOnDeadline, elapsedMs, stdioDrained });
+    };
+
+    child.on('exit', (code) => {
+      exited = true;
+      exitCode = code;
+      if (deadlineTimer) clearTimeout(deadlineTimer);
+      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));
   });
 }
 

package/src/runner/worker.mjs

@@ -36,9 +36,12 @@ export async function worker(runDir) {
   // 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') {