@lyupro/codex-bridge 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.1] - 2026-08-07
+
+### Added
+
+- The CLI answers to `codexb` as well as `codex-bridge`, and README now documents the global install that puts both names on `PATH`. Every spelling that can reach deletion comes from one frozen list, and the prune guard builds its matcher from that list rather than repeating the names — two independent lists drift silently, which is exactly how the installer and test hook lists had already drifted. The full name stays primary: the docs, checklists and three agent prompts are written with it.
+- Every run carries the rules it is judged by. A seeded `conventions.md` beside `run-config.json` and an optional `.codex-conventions.md` in the repository being worked on are pasted into `task.md` verbatim, under one `## Conventions` section. Either file missing is not an error, and a blank one produces no section at all — rules handed over as an empty heading read as rules ignored. Until now project rules reached a run only when the orchestrator remembered to write "read CLAUDE.md" into the task, and six acceptance passes in a row caught the same class of violation: the rule existed, applied, and had not travelled. Pasting rather than referencing is the point — "read file X" is hope, and a run is free not to.
+- `doctor` opens with the path of the package copy answering, marked `clone` or `installed package`, and reports whether the host conventions file was found, warning when it exists but is empty. A global install puts a second copy of the package beside any clone, and `update` copies host files from whichever copy launched it — so two diagnoses of the same host were previously indistinguishable.
+
+### Fixed
+
+- `codex-bridge projects` printed the `last run` column on two clocks. Folder names are written in local time and `meta.finished_at` is an ISO stamp in UTC, and each reached the column through its own branch, so a run whose folder says `144243` was listed as `12:46` — the operator's own zone offset, indistinguishable from a different run. Which run is newest was never affected, only how it printed.
+
+## [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

@@ -7,7 +7,10 @@ subscription instead of the Claude one.
 ## Install
 
 ```bash
-npx @lyupro/codex-bridge install        # into ~/.claude
+npx @lyupro/codex-bridge install        # one-off, into ~/.claude
+npm i -g @lyupro/codex-bridge           # install both command names globally
+codex-bridge install                    # full name, from any directory
+codexb install                          # short name, same command
 node bin/codex-bridge.mjs install       # from a clone, same thing
 node bin/codex-bridge.mjs install --scope project   # into <repo>/.claude
 node bin/codex-bridge.mjs update        # bring an installation up to the current version
@@ -17,8 +20,13 @@ 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
 ```
 
+When a global install and a clone coexist, there are two copies of the package. `codex-bridge update`
+and `codexb update` copy host files from whichever copy launched the command, so `codexb update`
+from `PATH` can silently revert a host that `npm run dev:install` from the clone just updated.
+
 `install` copies the package into the host's `agents/codex/`, its slash commands into
 `commands/codex/`, and registers its four hooks in `settings.json` — **merged**, so hooks that
 are already there survive, and the file is backed up before every write. Run it twice and the
@@ -54,6 +62,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,8 +24,10 @@ 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>
+  codexb <same command forms as codex-bridge>
   codex-bridge --help
   codex-bridge --version
 
@@ -35,6 +38,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 +109,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/doctor.mjs

@@ -1,6 +1,7 @@
 /** Diagnoses a Claude Code host without modifying it. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import {
   fileFingerprint,
@@ -47,6 +48,34 @@ function retentionCheck(host) {
   }
 }
 
+async function conventionsCheck(host) {
+  const file = path.join(host.agentsDir, 'conventions.md');
+  let content;
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
+    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
+  }
+  return content.trim()
+    ? check('conventions', 'ok', `${file} (found)`)
+    : check('conventions', 'warn', `${file} (found but empty)`);
+}
+
+/**
+ * Which copy of the package is answering. Plan_19 gives the CLI a second name, and a global install
+ * puts a second copy of the package on the machine beside any clone. `update` copies host files
+ * from whichever copy launched it, so `codexb update` from PATH silently reverts a host that
+ * `npm run dev:install` from the clone had just refreshed — and every line below this one describes
+ * the host as seen by THIS copy. An operator comparing two diagnoses has no other way to tell them
+ * apart.
+ */
+function sourceCheck() {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const installed = root.split(/[\\/]/).includes('node_modules');
+  return check('source', 'ok', `${root} (${installed ? 'installed package' : 'clone'})`);
+}
+
 /**
  * The runner asks git for the repository root before it picks a runs folder, so doctor has to
  * ask the same question: run from `src/runner`, a plain cwd would name the folder `runner` and
@@ -134,7 +163,7 @@ async function rulesCheck(host, record) {
 }
 
 export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
-  const checks = [];
+  const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
   checks.push(check('host', hostExists ? 'ok' : 'warn', `${host.root} (${host.scope}, ${hostExists ? 'exists' : 'absent'})`));
 
@@ -173,6 +202,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   checks.push(...await hookChecks(host, record));
   const retention = retentionCheck(host);
   checks.push(retention);
+  const conventions = await conventionsCheck(host);
+  checks.push(conventions);
 
   const codex = codexProbe();
   checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));
@@ -184,7 +215,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 
   return {
     exitCode: !record || recordBroken || missingFiles.length || rules.status === 'fail'
-      || retention.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
+      || retention.status === 'fail' || conventions.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
     checks,
     record,
     missingFiles,
@@ -194,6 +225,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 export function renderDoctor(result) {
   return result.checks.map(({ key, status, value }) => {
     const rendered = `[${status}] ${key}: ${value}`;
-    return key === 'retention' && status === 'warn' ? `${WARNING}${rendered}${RESET}` : rendered;
+    return ['retention', 'conventions'].includes(key) && status === 'warn'
+      ? `${WARNING}${rendered}${RESET}`
+      : rendered;
   }).join('\n');
 }

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 };
 
@@ -21,10 +22,11 @@ const RULES_SOURCE = `src/rules/${RULES_NAME}`;
 /**
  * Files the operator owns once they exist. Seeded on first install so the defaults are
  * visible and editable, then never written, never compared, never removed: run-config.json
- * is where a host states which model each mode runs on, and an installer that overwrites it
- * would erase that on the next update — the same way overwriting a .env would.
+ * is where a host states which model each mode runs on, conventions.md is the rule set it hands
+ * every run, and an installer that overwrites either would erase host decisions on the next
+ * update — the same way overwriting a .env would.
  */
-export const SEEDED_SOURCES = Object.freeze(['src/run-config.json']);
+export const SEEDED_SOURCES = Object.freeze(['src/run-config.json', 'src/conventions.md']);
 const seededTargets = (host) =>
   new Set(SEEDED_SOURCES.map((source) => posix(
     path.relative(host.root, path.join(host.agentsDir, path.relative('src', source))),
@@ -42,7 +44,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/projects.mjs

@@ -15,13 +15,26 @@ function formatSize(bytes) {
   return `${bytes} B`;
 }
 
-/** Both timestamp shapes in the store: an ISO stamp from artifacts, a folder name otherwise. */
+const pad = (value) => String(value).padStart(2, '0');
+
+/**
+ * Both timestamp shapes in the store, printed on one clock. A run folder is named in local time
+ * (`2026-08-07_144243`); `meta.finished_at` is an ISO stamp in UTC. Reading the ISO one with a
+ * regular expression printed its UTC hours in the same column as local ones, and the 2026-08-07
+ * live check (Plan_17-1 §1) saw the run whose folder says `144243` listed as `12:46` — the
+ * operator's own zone offset, looking exactly like a different run. Slicing a timestamp is cheaper
+ * than parsing it only until the value carries a zone. The folder name stays text because it is
+ * already local; parsing it would invent a zone it never had.
+ */
 function formatStamp(value) {
   if (typeof value !== 'string' || !value.trim()) return null;
-  const iso = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(value);
-  if (iso) return `${iso[1]} ${iso[2]}`;
   const folder = /^(\d{4}-\d{2}-\d{2})_(\d{2})(\d{2})/.exec(value);
-  return folder ? `${folder[1]} ${folder[2]}:${folder[3]}` : value;
+  if (folder) return `${folder[1]} ${folder[2]}:${folder[3]}`;
+  const moment = Date.parse(value);
+  if (Number.isNaN(moment)) return value;
+  const at = new Date(moment);
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`
+    + ` ${pad(at.getHours())}:${pad(at.getMinutes())}`;
 }
 
 const PROJECT_COLUMNS = [

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.1",
   "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",
@@ -23,7 +23,8 @@
   "homepage": "https://github.com/lyupro/codex-bridge#readme",
   "type": "module",
   "bin": {
-    "codex-bridge": "./bin/codex-bridge.mjs"
+    "codex-bridge": "./bin/codex-bridge.mjs",
+    "codexb": "./bin/codex-bridge.mjs"
   },
   "engines": {
     "node": ">=24.0.0"

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/cli-names.mjs

@@ -0,0 +1,6 @@
+/** Names this CLI answers to. */
+
+// Plan_17 §5 found installer and test hook lists drifting; keep executable spellings here so a
+// new alias cannot silently bypass the prune guard. Under src/ because the installed guard reads
+// it too, and cli/ is not copied into the host.
+export const CLI_NAMES = Object.freeze(['codex-bridge', 'codexb']);

package/src/conventions.md

@@ -0,0 +1,44 @@
+# Delegated-run conventions
+
+These are the host conventions for every Codex run. Each block records a real acceptance
+violation caught in this repository and turns it into a guard for the next run.
+
+## Task boundaries - Plan_16 acceptance incident
+
+- Do not refactor code the task did not ask to change.
+- Do not delete code on your own initiative.
+- Do not change behavior branches whose behavior the task does not mention, even inside an
+  allowed file.
+
+The 2026-08-06 Plan_16 acceptance finding applied a new reason order to a transport branch that
+already named its reason. Preserve existing branches unless the task explicitly changes them.
+
+## Contracts without silent defaults - Plan_16 reasonFrom incident
+
+- Require arguments that the contract needs instead of supplying a default.
+- Fail loud when a required value is absent; do not silently fall back.
+- Keep volatile identifiers such as model IDs and API versions in configuration, not runtime code.
+
+The 2026-08-06 `reasonFrom(runDir, eventData = {})` finding replaced a required contract with a
+silent default. Missing inputs must remain visible at the boundary that can explain them.
+
+## Structure and size - 2026-08-06 projects reload incident
+
+- Keep every source file at or below 400 lines.
+- Give each module one responsibility.
+- Do not create `utils.mjs` dumping grounds.
+- Never split coherent pieces solely to reach the line limit.
+
+The 2026-08-06 `projects` reload finding exposed pseudo-duplicate exports and just-in-case code.
+Keep related code together, but remove a real responsibility or create a focused module when a
+boundary is needed.
+
+## Tests and comments - 2026-08-05 step 2b incident
+
+- Add a guard test for every invariant accepted by the task.
+- Splitting a file must delete no test case.
+- Comments explain WHY and name the incident or decision that makes the rule necessary.
+
+The 2026-08-05 step 2b acceptance found the abandoned-run check below the commit check. Test the
+ordering invariant itself, and leave the incident in the comment so a later cleanup does not
+silently undo it.

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/prune-guard.mjs

@@ -11,6 +11,7 @@
  * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
  */
 import fs from 'node:fs';
+import { CLI_NAMES } from '../cli-names.mjs';
 import { SHELL_TOOLS } from '../hook-definitions.mjs';
 
 const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
@@ -18,10 +19,17 @@ const pass = () => process.exit(0);
 
 // The binary, then the verb, with any path in front of it: an agent reaches the CLI as
 // `codex-bridge`, as `node bin/codex-bridge.mjs`, or through an absolute path, and a guard that
-// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Matching
-// a lone `prune` is not an option either — `git prune` and `npm prune` are not this package's
-// business, and a guard that breaks unrelated work is a guard that gets uninstalled.
-const PRUNE_CALL = /(^|[\s;&|(`])(\S*[\\/])?codex-bridge(\.mjs)?\s+prune(\s|$)/;
+// only knew the bare name would be bypassed by the spelling everyone uses inside a clone. Plan_19
+// adds a second executable spelling, so build this matcher from the shared list instead of
+// repeating names here. Matching a lone `prune` is not an option either — `git prune` and
+// `npm prune` are not this package's business, and a guard that breaks unrelated work is a guard
+// that gets uninstalled.
+const escapeRegex = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const CLI_NAME_PATTERN = CLI_NAMES.map(escapeRegex).join('|');
+const PRUNE_CALL = new RegExp(
+  '(^|[\\s;&|(`])(\\S*[\\\\/])?(?:' + CLI_NAME_PATTERN
+    + ')(\\.mjs)?\\s+prune(\\s|$)',
+);
 
 let input;
 try {

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/conventions.mjs

@@ -0,0 +1,39 @@
+/** Renders the host and repository conventions that a run must carry in its task artifact. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_PATH } from '../run-config.mjs';
+
+const HOST_FILE = path.join(path.dirname(CONFIG_PATH), 'conventions.md');
+const REPOSITORY_FILE = '.codex-conventions.md';
+
+function readOptional(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Reads both convention layers at the point of use. Plan_13 showed that a reference to a required
+ * file is not enforcement: the task must contain the bytes the run was given.
+ *
+ * A layer that is present but blank is dropped rather than rendered as an empty heading, for the
+ * same reason doctor warns about it — an empty rules file looks like a working mechanism and is
+ * not one, and in the artifact it would look like rules that were given and ignored.
+ *
+ * Duplication is impossible by construction and deliberately not guarded against: `sections`
+ * starts empty on every launch and task.md is written into a folder that is never reused, so
+ * there is nothing to append to. A guard reading the operator's task text for this heading would
+ * only find the word in a task that talks ABOUT conventions, and silently drop the section from
+ * the one run that most obviously needed it.
+ */
+export function renderConventions(repoRoot, hostFile = HOST_FILE) {
+  const layers = [];
+  const host = readOptional(hostFile);
+  if (host?.trim()) layers.push(`### Host conventions\n\n${host}`);
+  const repository = readOptional(path.join(repoRoot, REPOSITORY_FILE));
+  if (repository?.trim()) layers.push(`### Repository conventions\n\n${repository}`);
+  return layers.length ? `## Conventions\n\n${layers.join('\n\n')}` : '';
+}

package/src/runner/launcher.mjs

@@ -37,6 +37,7 @@ 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';
+import { renderConventions } from './conventions.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
@@ -279,6 +280,8 @@ export async function launcher() {
       ].join('\n'),
     );
   }
+  const conventions = renderConventions(repoRoot);
+  if (conventions) sections.push(conventions);
   sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
   fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
   fs.writeFileSync(

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') {