@lyupro/codex-bridge 0.1.3 → 0.2.0

package/src/hooks/live-runs.mjs

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Signal 0 tests existence without stopping the process; EPERM still means that it exists. */
+export const isPidAlive = (pid) => {
+  if (typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+/**
+ * Match the package's repository comparison without resolving symlinks: Windows realpath adds
+ * `\\?\\` and UNC spellings, turning equal paths into unequal ones. A null result is uncertainty,
+ * and callers must pass rather than deny on it.
+ */
+export function normalizePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    let normalized = path.resolve(value).replaceAll('\\', '/').replace(/\/+$/, '');
+    if (!normalized) normalized = '/';
+    if (process.platform === 'win32') normalized = normalized.toLowerCase();
+    return normalized;
+  } catch {
+    return null;
+  }
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && Boolean(value.trim());
+}
+
+function recognizedStatus(status) {
+  return Boolean(status)
+    && typeof status === 'object'
+    && !Array.isArray(status)
+    && status.state === 'running'
+    && typeof status.pid === 'number'
+    && isNonEmptyString(status.agent)
+    && isNonEmptyString(status.slug)
+    && isNonEmptyString(status.repo)
+    && isPidAlive(status.pid);
+}
+
+function readStatus(runDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(runDir, 'status.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Scan one project's direct run folders; unreadable or unfamiliar entries are ignored. */
+export function liveRuns(runsDir) {
+  if (typeof runsDir !== 'string' || !runsDir.trim()) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(runsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(runsDir, entry.name);
+    const status = readStatus(dir);
+    if (recognizedStatus(status)) result.push({ dir, status });
+  }
+  return result;
+}
+
+/** Scan every project under the configured runs root for worktree ownership. */
+export function allLiveRuns(runsRoot) {
+  if (typeof runsRoot !== 'string' || !runsRoot.trim()) return [];
+  let projects;
+  try {
+    projects = fs.readdirSync(runsRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result = [];
+  for (const project of projects) {
+    if (!project.isDirectory()) continue;
+    result.push(...liveRuns(path.join(runsRoot, project.name)));
+  }
+  return result;
+}

package/src/hooks/prune-guard.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard that keeps `codex-bridge prune` out of agent-issued shell commands.
+ *
+ * Deletion is an operator action. The command already refuses without a terminal, but a guard in
+ * front of it is the second rubezh Plan_17 asks for: the TTY check lives inside the very process an
+ * agent is asking to start, and a package that trusts one check has trusted prose twice before
+ * (Plan_13, Plan_14) and been wrong both times. Denying the call means no deleting process is
+ * created at all.
+ *
+ * Anything unrecognised passes. A guard that misreads its input must not break unrelated host work.
+ */
+import fs from 'node:fs';
+import { SHELL_TOOLS } from '../hook-definitions.mjs';
+
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+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|$)/;
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+
+/**
+ * Strips the parts of a command line that are data rather than instructions: heredoc bodies and
+ * quoted strings. Found the moment this guard existed — it denied the commit that introduced it,
+ * because the message text quoted the command name. Nothing was going to be deleted; the words
+ * were cargo. A guard that cannot tell an invocation from a mention refuses honest work, and a
+ * guard that refuses honest work is removed, after which it guards nothing.
+ */
+function withoutQuotedText(command) {
+  return command
+    .replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm, ' ')
+    .replace(/'[^']*'/g, ' ')
+    .replace(/"[^"]*"/g, ' ');
+}
+
+const command = input.tool_input?.command;
+if (typeof command !== 'string' || !command.trim()) pass();
+if (!PRUNE_CALL.test(withoutQuotedText(command))) pass();
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: 'codex-bridge prune deletes run artifacts and is an operator action, '
+      + 'not an agent one. There is deliberately no bypass flag. Ask the operator to run it in '
+      + 'their own terminal; `codex-bridge projects` shows the same store read-only.',
+  },
+}));

package/src/hooks/reply-guard.mjs

@@ -29,6 +29,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isPidAlive, liveRuns, normalizePath } from './live-runs.mjs';
 
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
@@ -168,8 +169,9 @@ const blockState = (reason, stopReason) => {
  * verdict is the stdout of the attaching call. Matching only `RUN=` would block every honest
  * answer given under the new contract as "did not delegate at all".
  */
-const runMatch = reply.match(/(?:RUN|ATTACH)=(.+?)(?:\r?\n|$)/);
-const runDir = runMatch ? runMatch[1].trim().replace(/\s+started=\S*$/, '').replace(/[`"'*]+$/g, '') : null;
+const cleanRunDir = (value) => value.trim().replace(/\s+started=\S*$/, '').replace(/[`"'*]+$/g, '');
+const runDirs = [...reply.matchAll(/(?:RUN|ATTACH)=(.+?)(?:\r?\n|$)/g)].map((match) => cleanRunDir(match[1]));
+const runDir = runDirs[0] || null;
 
 if (!runDir || !fs.existsSync(runDir)) {
   blockForm(
@@ -180,22 +182,6 @@ if (!runDir || !fs.existsSync(runDir)) {
   );
 }
 
-/**
- * Best-effort liveness probe: signal 0 sends nothing, it only tests that the pid exists.
- * EPERM means the process is there and owned by someone else — alive for our purposes, and
- * the same reading write-meta.mjs uses. Two answers to "is this run still going" would be
- * one answer too many.
- */
-const isPidAlive = (pid) => {
-  if (typeof pid !== 'number') return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
-};
-
 /**
  * The text the operator reads when the state budget is gone. Everything in it is quoted
  * from status.json — the operator is being told to stop, and a stop justified by guesswork
@@ -203,12 +189,12 @@ const isPidAlive = (pid) => {
  */
 const fact = (value) => (value === undefined || value === null || value === '' ? 'not recorded' : String(value));
 
-const stopText = (headline, observed, runStatus) =>
+const stopText = (headline, observed, runStatus, folder = runDir) =>
   [
     headline,
     `Run: slug ${fact(runStatus?.slug)}, agent ${fact(runStatus?.agent)}, repository ` +
       `${fact(runStatus?.repo)}, started ${fact(runStatus?.started_at)}.`,
-    `Run folder: ${runDir}. Read state from ${path.join(runDir, 'status.json')}; the verdict ` +
+    `Run folder: ${folder}. Read state from ${path.join(folder, 'status.json')}; the verdict ` +
       'will appear in the adjacent meta.json.',
     observed,
     `Worktree ${fact(runStatus?.repo)} is busy with this run: do not build, test, or commit until ` +
@@ -220,6 +206,43 @@ const stopText = (headline, observed, runStatus) =>
       'command with the same --order-id attaches to this run rather than starting another.',
   ].join(' ');
 
+/**
+ * The dispatcher must name every WRITING run the project has live, not just the one it chose to
+ * quote. The sibling scan is disk-only, so silence cannot hide a second runner; a scan failure
+ * remains fail-open because an uncertain diagnostic must never deny unrelated work.
+ *
+ * Only codex-build counts. Scout and review run in a read-only sandbox and leave the worktree
+ * alone, and launching them alongside other work is deliberate practice here — blocking a reply
+ * over a live reader would spend the state budget, and possibly the session, on a run that
+ * threatens nothing. What the 2026-08-05 incident cost was a hidden WRITER: the orchestrator
+ * edited files that landed in its before/after snapshot.
+ */
+const namedRunDirs = new Set(runDirs.map((dir) => normalizePath(dir)).filter(Boolean));
+let silentLiveSibling = null;
+try {
+  silentLiveSibling = liveRuns(path.dirname(runDir)).find((run) => {
+    if (run.status.agent !== 'codex-build') return false;
+    const normalized = normalizePath(run.dir);
+    return normalized && !namedRunDirs.has(normalized);
+  });
+} catch {
+  silentLiveSibling = null;
+}
+if (silentLiveSibling) {
+  const { dir, status } = silentLiveSibling;
+  blockState(
+    `Contract violated: the response names ${runDir} but omits live run folder ${dir}; report every `
+      + `live run with its agent ${status.agent}, slug ${status.slug}, and repository ${status.repo}.`,
+    stopText(
+      `The reply guard stopped the session: the dispatcher responded ${MAX_STATE_BLOCKS} times `
+        + 'while a live sibling Codex run was omitted from its reply.',
+      `status.json in ${dir} says state=running; process pid ${fact(status.pid)} is alive.`,
+      status,
+      dir,
+    ),
+  );
+}
+
 /**
  * status.json is written by run-codex.mjs before meta.json exists, so it catches the
  * dispatcher that reports before its own run is done — meta.json alone cannot, because a
@@ -261,7 +284,7 @@ if (fs.existsSync(statusPath)) {
           `status.json currently says state=running, but process pid ${fact(runStatus.pid)} is ` +
             'dead and meta.json is missing: an interrupted Bash call killed the runner. Codex ' +
             'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes ' +
-            'in 11+ files survived while raw.log and meta.json were never recorded.',
+            'in 11+ files survived while no run artifact and no meta.json were ever recorded.',
           runStatus,
         ),
       );
@@ -277,7 +300,7 @@ if (fs.existsSync(statusPath)) {
         `status.json currently says state=abandoned (${fact(runStatus.abandoned_reason)}, ` +
           `${fact(runStatus.abandoned_at)}): the runner died without recording a verdict. Codex ` +
           'survives the runner and keeps editing the tree — in run 2026-07-31_114736, changes in ' +
-          '11+ files survived while raw.log and meta.json were never recorded.',
+          '11+ files survived while no run artifact and no meta.json were ever recorded.',
         runStatus,
       ),
     );

package/src/hooks/worktree-lock.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse lock for file-writing tools in the Claude Code host.
+ *
+ * A live codex-build runner snapshots its repository before and after editing. Letting the
+ * orchestrator write during that window folds unrelated work into the runner's result, exactly
+ * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
+ * build run's repository; every malformed or unreadable input passes so diagnostics never break
+ * unrelated host work.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { WRITE_TOOLS } from '../hook-definitions.mjs';
+import { runsRoot } from '../runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
+const pass = () => process.exit(0);
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!WRITE_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+const rawPath = toolInput[pathField];
+if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
+
+let targetPath;
+try {
+  if (path.isAbsolute(rawPath)) targetPath = rawPath;
+  else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
+  else pass();
+} catch {
+  pass();
+}
+
+const target = normalizePath(targetPath);
+if (!target) pass();
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+const owner = liveRuns.find(({ status }) => {
+  if (status.agent !== 'codex-build') return false;
+  const repository = normalizePath(status.repo);
+  return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
+});
+if (!owner) pass();
+
+const { status, dir } = owner;
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    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.',
+  },
+}));

package/src/meta/deadline.mjs

@@ -0,0 +1,19 @@
+/**
+ * Reads the runner-owned deadline fact from status.json.
+ *
+ * stderr.log is diagnostic text and can contain a quoted copy of the runner's own message,
+ * so it cannot prove that the runner actually stopped the process (Plan_15).
+ */
+import path from 'node:path';
+import { readJson } from './paths.mjs';
+
+export function deadlineReason(runDir) {
+  const status = readJson(path.join(runDir, 'status.json'));
+  if (status?.stopped_on_deadline !== true) return null;
+  // How long the run lived, not the budget it was given: a field named for the budget and
+  // holding the elapsed time is read wrong by whoever opens the folder months later.
+  const elapsed = status.elapsed_ms;
+  return Number.isFinite(elapsed)
+    ? `run stopped on its deadline after ${elapsed} ms`
+    : 'run stopped on its deadline';
+}

package/src/meta/events.mjs

@@ -0,0 +1,166 @@
+/**
+ * Reads the runner's structured Codex transport and turns it into facts for metadata and
+ * verdicts. This is the only module that knows the file is JSONL: a model can quote a limit in
+ * its own item text, but only these runner-written error events are allowed to stop a retry.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Quota exhaustion, and nothing else that merely says "limit". A bare `limit` also appears in
+ * "context length limit" — an error about the content of the order, which the orchestrator is
+ * supposed to fix and re-send. Calling that LIMIT would forbid the one retry that would work.
+ */
+const LIMIT_RE = /rate[\s_-]*limit|usage[\s_-]*limit|quota|too many requests|\b429\b/i;
+
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+const compact = (value, max = 300) =>
+  String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+/**
+ * A broken final line is expected when the runner is stopped while Codex is writing.
+ *
+ * Whether the file was there at all is reported separately from what it held: a run killed
+ * before the CLI said one word leaves an empty stream, and telling the operator that such a
+ * run "predates the change" sends them looking for the wrong thing entirely.
+ */
+function readLines(runDir) {
+  if (!runDir) return { exists: false, events: [] };
+  let text;
+  try {
+    text = fs.readFileSync(path.join(runDir, 'events.jsonl'), 'utf8');
+  } catch {
+    return { exists: false, events: [] };
+  }
+  const events = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const source = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    if (!source.trim()) continue;
+    try {
+      const event = JSON.parse(source);
+      if (record(event)) events.push(event);
+    } catch {
+      // A line cut short by MAX_LOG or a killed process is not a transport verdict.
+    }
+  }
+  return { exists: true, events };
+}
+
+function usageOf(events) {
+  const completed = events.filter((event) => event.type === 'turn.completed' && record(event.usage));
+  if (!completed.length) return { tokens: null, usage: null };
+
+  const usage = {};
+  let tokens = 0;
+  for (const event of completed) {
+    for (const [key, value] of Object.entries(event.usage)) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        usage[key] = (usage[key] || 0) + value;
+      } else if (!(key in usage)) {
+        usage[key] = value;
+      }
+    }
+    if (typeof event.usage.input_tokens === 'number' && Number.isFinite(event.usage.input_tokens)) {
+      tokens += event.usage.input_tokens;
+    }
+    if (typeof event.usage.output_tokens === 'number' && Number.isFinite(event.usage.output_tokens)) {
+      tokens += event.usage.output_tokens;
+    }
+  }
+  return { tokens, usage };
+}
+
+/**
+ * Finds the last content error emitted by the model.
+ *
+ * The 2026-08-05 live probe put policy rejections in stderr on a healthy run, so the
+ * model's own complaint must stay separate from that noisy diagnostic stream.
+ *
+ * Only what follows the first `turn.started` is the model's. codex-cli 0.146.0 announces its
+ * own configuration warnings through the same `item.completed` error shape before the turn
+ * begins: on 2026-08-06 every run of this host carried "`[features].codex_hooks` is
+ * deprecated" as its first item, and a failed run would have named that as the reason it
+ * failed. A complaint about the order cannot predate the model's first thought — so a run
+ * that never opened a turn has no content error at all, and falls back to the transport
+ * error or stderr the way it did before this stream existed.
+ */
+export function contentErrorOf(events) {
+  const turn = events.findIndex((event) => event?.type === 'turn.started');
+  if (turn < 0) return null;
+  for (let index = events.length - 1; index > turn; index -= 1) {
+    const event = events[index];
+    if (event?.type !== 'item.completed' || !record(event.item) || event.item.type !== 'error') continue;
+    const value = typeof event.item.message === 'string' ? event.item.message : event.item.text;
+    return typeof value === 'string' ? compact(value) : '';
+  }
+  return null;
+}
+
+function payloadOf(event) {
+  const source =
+    event.type === 'error'
+      ? event.message ?? event.error
+      : event.error?.message ?? event.error ?? event.message;
+  if (typeof source === 'string') {
+    try {
+      const parsed = JSON.parse(source);
+      return record(parsed) ? parsed : { message: source };
+    } catch {
+      return { message: source };
+    }
+  }
+  return record(source) ? source : {};
+}
+
+function transportErrorOf(event) {
+  if (event.type !== 'error' && event.type !== 'turn.failed') return null;
+  const payload = payloadOf(event);
+  const nested = record(payload.error) ? payload.error : {};
+  const errorType =
+    (typeof nested.type === 'string' && nested.type) ||
+    (typeof payload.type === 'string' && payload.type !== 'error' && payload.type) ||
+    null;
+  const message =
+    (typeof nested.message === 'string' && nested.message) ||
+    (typeof payload.message === 'string' && payload.message) ||
+    null;
+  const status = payload.status ?? nested.status ?? null;
+  const marker = [errorType, message].join(' ');
+  const quota = Number(status) === 429 || LIMIT_RE.test(marker);
+  const reason = compact(
+    [errorType, message, status === null || status === undefined ? '' : `status ${status}`]
+      .filter(Boolean)
+      .join(': ') ||
+      (typeof event.message === 'string' ? event.message : '') ||
+      (typeof event.error?.message === 'string' ? event.error.message : '') ||
+      event.type,
+  );
+  return { event, payload, status, error_type: errorType, message, quota, reason };
+}
+
+/**
+ * Reads all usable events and derives accounting without letting unreadable JSONL poison a run.
+ * Numeric usage fields are summed across turns; with one turn this preserves the CLI object
+ * and its fields exactly, while tokens intentionally count input plus output only.
+ */
+export function readEvents(runDir) {
+  const { exists, events } = readLines(runDir);
+  const accounting = usageOf(events);
+  const started = events.find((event) => event.type === 'thread.started' && event.thread_id);
+  const errors = events.map(transportErrorOf).filter(Boolean);
+  const transport_error = errors.find((error) => error.quota) || errors[0] || null;
+  return {
+    events,
+    // The file was written, whatever it holds. Pass 2 judges a run by this: a stream the
+    // runner promised in its own arguments and did not leave behind is damaged evidence,
+    // not an archived run.
+    hasStream: exists,
+    hasEvents: events.length > 0,
+    tokens: accounting.tokens,
+    usage: accounting.usage,
+    session_id: started ? String(started.thread_id) : null,
+    content_error: contentErrorOf(events),
+    transport_error,
+  };
+}

package/src/meta/reason.mjs

@@ -0,0 +1,29 @@
+/**
+ * Resolves the ordered reason for a failed run.
+ *
+ * The 2026-08-05 live probe showed that stderr can contain policy noise during a healthy run,
+ * so diagnostic text is the final fallback rather than the primary verdict evidence.
+ */
+import path from 'node:path';
+import { contentErrorOf } from './events.mjs';
+import { line, readText } from './paths.mjs';
+
+/** Keeps the archived stderr heuristic intact for runs without a useful event message. */
+const stderrReason = (runDir) => {
+  const stderr = readText(path.join(runDir, 'stderr.log'));
+  const messages = [...stderr.matchAll(/"message"\s*:\s*"((?:[^"\\]|\\.)*)"/g)];
+  if (messages.length) return line(messages[messages.length - 1][1].replace(/\\"/g, '"'));
+  const lines = stderr.split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+  const errorLine = [...lines].reverse().find((value) => /error|failed|denied|refused/i.test(value));
+  return line(errorLine || lines[lines.length - 1] || '');
+};
+
+// eventData is required, not defaulted: a caller that forgets it would silently fall back to
+// stderr — the exact behaviour this module was written to replace, and a default would hide it.
+export function reasonFrom(runDir, eventData) {
+  const content = line(eventData.content_error ?? contentErrorOf(eventData.events || []));
+  if (content) return content;
+  const transport = line(eventData.transport_error?.reason || eventData.transport_error?.message);
+  if (transport) return transport;
+  return stderrReason(runDir);
+}