@lyupro/codex-bridge 0.1.4 → 0.3.0

package/cli/runs-inventory.mjs

@@ -0,0 +1,173 @@
+/** Reads run-store directories into inventory data. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { liveRuns } from '../src/hooks/live-runs.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+function readRecord(file) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return record(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function directoryEntries(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch {
+    return [];
+  }
+}
+
+function measure(target) {
+  let stat;
+  try {
+    stat = fs.lstatSync(target);
+  } catch {
+    return { bytes: null, complete: false };
+  }
+  if (!stat.isDirectory()) return { bytes: stat.isFile() ? stat.size : 0, complete: true };
+
+  let entries;
+  try {
+    entries = fs.readdirSync(target, { withFileTypes: true });
+  } catch {
+    return { bytes: null, complete: false };
+  }
+
+  let bytes = 0;
+  let complete = true;
+  for (const entry of entries) {
+    const child = measure(path.join(target, entry.name));
+    if (child.bytes !== null) bytes += child.bytes;
+    if (!child.complete) complete = false;
+  }
+  return { bytes: complete ? bytes : null, complete };
+}
+
+/** Measures every readable regular file beneath a path. */
+export function recursiveSize(target) {
+  return measure(target).bytes;
+}
+
+const normalizeRoot = (value) => typeof value === 'string' && value.trim() ? value : runsRoot();
+
+const text = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+
+const number = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+
+function runTimestamp(name, meta, status) {
+  return text(meta?.finished_at)
+    || text(status?.finished_at)
+    || text(status?.started_at)
+    || /^\d{4}-\d{2}-\d{2}_\d{6}/.exec(name)?.[0]
+    || null;
+}
+
+function timestampOrder(value) {
+  const candidate = String(value).replace(
+    /^(\d{4}-\d{2}-\d{2})_(\d{2})(\d{2})(\d{2})$/,
+    '$1T$2:$3:$4',
+  );
+  const parsed = Date.parse(candidate);
+  return Number.isNaN(parsed) ? candidate : parsed;
+}
+
+function newer(left, right) {
+  if (!left) return right;
+  if (!right) return left;
+  const leftOrder = timestampOrder(left);
+  const rightOrder = timestampOrder(right);
+  if (typeof leftOrder === 'number' && typeof rightOrder === 'number') {
+    return rightOrder > leftOrder ? right : left;
+  }
+  if (typeof leftOrder === 'number') return left;
+  if (typeof rightOrder === 'number') return right;
+  return rightOrder > leftOrder ? right : left;
+}
+
+function pathKey(value) {
+  const resolved = path.resolve(value);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function readRun(runDir, livePaths) {
+  // A damaged folder still gets its row. An inventory that hides what it cannot parse is at its
+  // least useful exactly when something is wrong, which is when the operator opens it.
+  const meta = readRecord(path.join(runDir, 'meta.json'));
+  const status = readRecord(path.join(runDir, 'status.json'));
+  const facts = meta || status;
+  const live = livePaths.has(pathKey(runDir));
+  return {
+    run: path.basename(runDir),
+    agent: text(facts?.agent),
+    verdict: live ? 'running' : text(meta ? meta.status : status?.state),
+    tokens: meta ? number(meta.tokens) : null,
+    size: recursiveSize(runDir),
+    timestamp: runTimestamp(path.basename(runDir), meta, status),
+    live,
+  };
+}
+
+function publicRun(run) {
+  return {
+    run: run.run,
+    agent: run.agent,
+    verdict: run.verdict,
+    tokens: run.tokens,
+    size: run.size,
+    // Liveness travels with the row because a caller must not re-derive it: an abandoned run also
+    // says `running` in its status.json, and only the pid probe tells the two apart.
+    live: run.live,
+  };
+}
+
+function buildProject(projectDir) {
+  const runDirs = directoryEntries(projectDir).map((entry) => path.join(projectDir, entry.name));
+  // live-runs owns PID and status interpretation after the 2026-08-05 live probe incident;
+  // this module only maps its result back to the corresponding inventory row.
+  const livePaths = new Set(liveRuns(projectDir).map(({ dir }) => pathKey(dir)));
+  const details = runDirs.map((runDir) => readRun(runDir, livePaths));
+  // Sum what is known instead of blanking the column. One archived run without accounting used to
+  // erase the total of every run beside it, which reads as "spent nothing" — the opposite of true.
+  const counted = details.filter((run) => run.tokens !== null);
+  const latest = details.reduce((current, run) => newer(current, run.timestamp), null);
+  return {
+    summary: {
+      project: path.basename(projectDir),
+      runs: details.length,
+      size: recursiveSize(projectDir),
+      totalTokens: counted.length ? counted.reduce((sum, run) => sum + run.tokens, 0) : null,
+      liveNow: details.filter((run) => run.live).length,
+      lastRun: latest,
+    },
+    details,
+  };
+}
+
+function projectDirectory(root, name) {
+  return directoryEntries(root)
+    .find((entry) => entry.name === name)
+    ? path.join(root, name)
+    : null;
+}
+
+/** Lists one summary row per project directory. */
+export function listProjects(runsRootPath = runsRoot()) {
+  const root = normalizeRoot(runsRootPath);
+  return directoryEntries(root).map((entry) => buildProject(path.join(root, entry.name)).summary);
+}
+
+/** Lists one detail row per run directory in a named project, or null when there is no such project. */
+export function listProjectRuns(runsRootPath = runsRoot(), projectName) {
+  const root = normalizeRoot(runsRootPath);
+  const projectDir = projectDirectory(root, projectName);
+  if (!projectDir) return null;
+  return buildProject(projectDir).details.map(publicRun);
+}

package/cli/stop.mjs

@@ -1,35 +1,16 @@
 /** Stops a live run and records the same abandoned FAIL artifacts as the normal sweep. */
-import fs from 'node:fs';
 import path from 'node:path';
 import { stopCodex } from '../src/runner/codex-cmd.mjs';
 import { git, worktreeSnapshot } from '../src/runner/git-state.mjs';
 import { markAbandoned, readJson } from '../src/write-meta.mjs';
-import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
+import { resolveRunFolder } from './run-lookup.mjs';
 
 const EXIT_POLL_MS = 25;
 const EXIT_WAIT_MS = 2000;
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-function projectRoot(cwd) {
-  const result = git(cwd, ['rev-parse', '--show-toplevel']);
-  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : cwd;
-}
-
-function resolveRunFolder(run, cwd, runsRootPath) {
-  const value = String(run ?? '').trim();
-  if (!value || value === '.' || value === '..') {
-    throw new Error('stop requires a run folder (full path or bare folder name)');
-  }
-  if (path.isAbsolute(value)) return path.resolve(value);
-  if (path.dirname(value) !== '.') {
-    throw new Error('a bare run folder name or a full path is required');
-  }
-  const projectRuns = resolveProjectRunsDir(runsRootPath, projectRoot(cwd), { create: false });
-  return path.join(projectRuns.dir, value);
-}
-
 /** The stopped run's worktree as it stands now, or undefined when the repo is not a git one. */
 function treeOf(repo) {
   const root = String(repo ?? '').trim();
@@ -72,23 +53,9 @@ function result(exitCode, output) {
 }
 
 export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
-  let runDir;
-  try {
-    runDir = resolveRunFolder(run, cwd, runsRootPath);
-  } catch (err) {
-    return result(1, `codex-bridge stop: ${err.message}`);
-  }
-
-  let isDirectory = false;
-  try {
-    isDirectory = fs.statSync(runDir).isDirectory();
-  } catch {}
-  if (!isDirectory) {
-    return result(
-      1,
-      `Run folder not found: ${runDir}. Pass a full path or a bare run folder name from the current project's runs directory.`,
-    );
-  }
+  const lookup = resolveRunFolder({ command: 'stop', run, cwd, runsRootPath });
+  if (lookup.error) return result(1, lookup.error);
+  const { runDir } = lookup;
 
   const status = readJson(path.join(runDir, 'status.json'));
   const meta = readJson(path.join(runDir, 'meta.json'));

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

@@ -0,0 +1,110 @@
+/** Renders generic rows within terminal width. */
+
+const asText = (value) => {
+  if (value === null || value === undefined || value === '') return '-';
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+};
+
+/** Counts printable code points without imposing a dependency on terminal libraries. */
+export const displayWidth = (value) => Array.from(String(value)).length;
+
+/** Keeps the right side of a name when a flexible column must shrink. */
+export function truncateStart(value, width) {
+  const text = String(value);
+  if (displayWidth(text) <= width) return text;
+  if (width <= 1) return '…';
+  return `…${Array.from(text).slice(-(width - 1)).join('')}`;
+}
+
+function fit(value, width, mode) {
+  if (displayWidth(value) <= width) return value;
+  if (mode === 'start') return truncateStart(value, width);
+  if (mode === 'end') return `${Array.from(value).slice(0, Math.max(0, width - 1)).join('')}…`;
+  return value;
+}
+
+function normalizeColumn(column) {
+  const kind = column.kind || 'text';
+  const fixed = column.fixed === true || kind === 'number' || kind === 'date';
+  return {
+    ...column,
+    key: String(column.key ?? column.label ?? column.header),
+    header: String(column.header ?? column.label ?? column.key),
+    kind,
+    align: column.align || (kind === 'number' ? 'right' : 'left'),
+    mode: column.truncate === undefined ? (fixed ? null : 'start') : column.truncate,
+  };
+}
+
+function optionsWidth(options) {
+  if (typeof options === 'number') return options;
+  const value = options?.width ?? options?.terminalWidth ?? process.stdout.columns;
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 80;
+}
+
+function rowValue(row, column) {
+  return asText(typeof column.value === 'function' ? column.value(row) : row?.[column.key]);
+}
+
+function columnWidths(columns, rows, width) {
+  const values = columns.map((column) => [
+    column.header,
+    ...rows.map((row) => rowValue(row, column)),
+  ]);
+  const widths = values.map((items) => Math.max(...items.map(displayWidth), 1));
+  const gaps = Math.max(0, columns.length - 1);
+  let spare = width - gaps - widths.reduce((sum, item) => sum + item, 0);
+  if (spare >= 0) return widths;
+
+  const flexible = columns
+    .map((column, index) => ({ column, index }))
+    .filter(({ column }) => column.mode === 'start' || column.mode === 'end');
+  while (spare < 0) {
+    let changed = false;
+    for (const { column, index } of flexible) {
+      const minimum = Math.max(1, Number(column.minWidth) || 1);
+      if (widths[index] <= minimum) continue;
+      widths[index] -= 1;
+      spare += 1;
+      changed = true;
+      if (spare === 0) break;
+    }
+    if (!changed) break;
+  }
+  return widths;
+}
+
+function renderRow(row, columns, widths, header = false) {
+  return columns.map((column, index) => {
+    const value = header ? column.header : rowValue(row, column);
+    const rendered = fit(value, widths[index], header ? null : column.mode);
+    const padding = Math.max(0, widths[index] - displayWidth(rendered));
+    if (index === columns.length - 1) {
+      return column.align === 'right' ? `${' '.repeat(padding)}${rendered}` : rendered;
+    }
+    return column.align === 'right'
+      ? `${' '.repeat(padding)}${rendered}`
+      : `${rendered}${' '.repeat(padding)}`;
+  }).join(' ');
+}
+
+// Columns first, rows second, always. Sniffing which argument is which would let a caller with an
+// empty column list silently render the wrong shape instead of failing where the mistake is.
+/** Renders column descriptors plus object rows as a plain table. */
+export function renderTable(columns, rows, options = {}) {
+  const normalized = (columns || []).map(normalizeColumn);
+  if (!normalized.length) return '';
+  const values = Array.isArray(rows) ? rows : [];
+  const widths = columnWidths(normalized, values, optionsWidth(options));
+  return [
+    renderRow(null, normalized, widths, true),
+    ...values.map((row) => renderRow(row, normalized, widths)),
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.4",
+  "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
@@ -154,8 +155,8 @@ orchestrator.
 ## The script determines status, not you
 
 - `OK` — `result.json` is filled, the return code is zero, and the report matches the worktree.
-- `FAIL` — the result is empty, the return code is nonzero, `raw.log` is empty (the run was
-  abandoned at startup:
+- `FAIL` — the result is empty, the return code is nonzero, the run left no event and a silent
+  `stderr.log` (abandoned at startup:
   there was no Codex process), or **the wrong work was done**: no file in `changes[]` matches
   what actually changed between the worktree snapshots. The schema cannot catch this — a report
   about
@@ -204,7 +205,7 @@ OK — Added retry to the fetch helper and a timeout test
 Files: 2 changed · src/net/fetch.ts, src/net/fetch.test.ts
 Verification: npm test — pass
 Flags: none
-Report: ...\report.md · Log: ...\raw.log
+Report: ...\report.md · Log: codex-bridge read ...\2026-08-05_120000_slug
 ```
 
 Incorrect — "Codex failed, so I finished it myself," followed by a retelling of the diff.

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
@@ -129,9 +130,8 @@ and the wait can be repeated for free, so neither has any reason to restart anyt
 ## The script determines status, not you
 
 - `OK` — `review.json` is filled, and the return code is zero.
-- `FAIL` — the result is empty, the return code is nonzero, or `raw.log` is empty (the run was
-  abandoned
-  at startup: there was no Codex process).
+- `FAIL` — the result is empty, the return code is nonzero, or the run left no event and a
+  silent `stderr.log` (abandoned at startup: there was no Codex process).
 - `LIMIT` — the result is empty and the log signals a limit. The ChatGPT quota is exhausted, and the
   review was not
   completed; this is not a review failure and not a reason to restart.
@@ -163,7 +163,7 @@ ATTACH=<artifact root>\myproject\2026-07-30_1412_review-auth started=2026-07-30T
 OK — verdict needs-attention
 Findings: critical 0 · high 1 · medium 2 · low 3
 Top: high src/api/auth.ts:88 — The promise is not awaited, and the error is lost
-Report: ...\review.json · Log: ...\raw.log
+Report: ...\review.json · Log: codex-bridge read ...\2026-08-05_120000_slug
 ```
 
 Incorrect — "I analyzed the changes manually because Codex did not perform the review correctly,"
@@ -175,4 +175,4 @@ the status from the runner and stop.
 
 Incorrect — "The review started in the background; I will notify you when it finishes." There will
 be no notification: the agent
-terminates with the response, and an abandoned run leaves an empty `raw.log` — this is FAIL.
+terminates with the response, and an abandoned run leaves no event at all — this is FAIL.

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
@@ -137,9 +139,8 @@ An empty `answer` is FAIL with a path to the log, not a reason to choose differe
 ## The script determines status, not you
 
 - `OK` — `result.json` is filled, and the return code is zero.
-- `FAIL` — the result is empty, the return code is nonzero, or `raw.log` is empty (the run was
-  abandoned
-  at startup: there was no Codex process).
+- `FAIL` — the result is empty, the return code is nonzero, or the run left no event and a
+  silent `stderr.log` (abandoned at startup: there was no Codex process).
 - `LIMIT` — the result is empty and the log signals a limit. The ChatGPT quota is exhausted, and the
   task was not
   completed; this is not a task failure and not a reason to restart.
@@ -172,7 +173,7 @@ ATTACH=<artifact root>\myproject\2026-07-30_1412_hooks started=2026-07-30T14:12:
 OK — The settings.json hook loads twice: from the plugin and the local config
 Key finding: duplicate loader (src/hooks/loader.ts:42)
 Unresolved: why the second load is needed
-Report: ...\report.md · Log: ...\raw.log
+Report: ...\report.md · Log: codex-bridge read ...\2026-08-05_120000_slug
 ```
 
 Incorrect — "Codex started in the background (PID recorded). Waiting for scouting to finish — it

package/src/commands/usage.md

@@ -16,9 +16,10 @@ The root of the run folders comes from `CODEX_RUNS_ROOT` when it is set, otherwi
 would stop seeing runs whenever the root is overridden.
 
 The source is the `meta.json` in each run folder: it holds the spending, the model and the sandbox.
-The `raw.log` itself is not kept in git and may be deleted, so parsing it is not allowed — the
-accounting has to survive a transcript cleanup. For older runs without `meta.json` there is a
-fallback log parser.
+Transport files are not kept in git and may be deleted, so parsing them is not allowed — the
+accounting has to survive a transcript cleanup. Runs from before `meta.json` existed keep a
+fallback parser for the `raw.log` those folders still contain; current runs no longer write that
+file, and their spending comes from the CLI's own `turn.completed` events.
 
 `codex exec review` prints no spending at all, so such runs land in the "unaccounted" line. Counting
 them as zero is not allowed — that would silently understate the total.