@lyupro/codex-bridge 0.5.2 → 0.5.3

package/cli/settings-merge.mjs

@@ -134,29 +134,41 @@ const hasOwnCommand = (group, commands) => {
 };
 
 /**
- * Presence is decided by the command, not by the matcher it currently sits under.
+ * Presence is decided by the command, not by the matcher it currently sits under; writing then
+ * places that command under the matcher the package declares. These are two halves of one rule.
  *
  * The matcher is generated from the tool list in hook-definitions.mjs, so it changes whenever a
  * host spelling is added — `Agent` became `Agent|Task` in one release, and the write-tool matcher
  * will grow the same way. A host installed under the old matcher would then be invisible to the
  * new lookup: update would register a duplicate and uninstall would leave a hook pointing at a
- * deleted file. The command is this package's own absolute path, so it identifies our entry
- * wherever the group ended up.
+ * deleted file. Conversely, the 2026-08-17 host proved that finding alone is insufficient: its
+ * worktree lock stayed under the pre-shell matcher, so Bash never reached the guard. The command
+ * is this package's own absolute path, so it identifies our entry wherever the group ended up,
+ * and merge can move it without creating a duplicate.
  */
 export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
   const spec = normalizeSpec(specOrPath);
   const commands = [spec.command, ...spec.alternateCommands];
   let matchedCommand;
+  let matchedMatcher;
+  let requiresMove = false;
   for (const group of groups(state.settings, spec.event)) {
-    const hook = groupHooks(group).find((entry) =>
-      entry?.type === 'command' && commands.includes(entry.command));
-    if (hook) {
-      matchedCommand = hook.command;
-      break;
+    for (const hook of groupHooks(group)) {
+      if (hook?.type !== 'command' || !commands.includes(hook.command)) continue;
+      matchedCommand ??= hook.command;
+      matchedMatcher ??= group?.matcher;
+      if (group?.matcher !== spec.matcher) requiresMove = true;
     }
   }
-  return { ...state, ...spec, present: Boolean(matchedCommand), matchedCommand };
+  return {
+    ...state,
+    ...spec,
+    present: Boolean(matchedCommand),
+    matchedCommand,
+    matchedMatcher,
+    requiresMove,
+  };
 }
 
 function backupName(settingsPath) {
@@ -227,10 +239,43 @@ export async function mergeHook(settingsPath, specOrPath, inspected) {
   return withMutationRun(settingsPath, async () => {
     const spec = normalizeSpec(specOrPath);
     const state = inspected || await inspectHook(settingsPath, spec);
-    if (state.present) return { changed: false, createdGroup: false };
+    if (state.present && !state.requiresMove) return { changed: false, createdGroup: false };
     const settings = structuredClone(state.settings);
     settings.hooks ??= {};
     if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
+    if (state.present) {
+      const eventGroups = settings.hooks[spec.event];
+      const commands = [spec.command, ...spec.alternateCommands];
+      let hookToMove;
+      let keptDeclaredHook = false;
+      for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
+        const group = eventGroups[index];
+        if (!Array.isArray(group?.hooks)) continue;
+        const hadOwnHook = hasOwnCommand(group, commands);
+        group.hooks = group.hooks.filter((hook) => {
+          if (hook?.type !== 'command' || !commands.includes(hook.command)) return true;
+          hookToMove ??= hook;
+          if (group.matcher === spec.matcher && !keptDeclaredHook) {
+            keptDeclaredHook = true;
+            return true;
+          }
+          return false;
+        });
+        if (hadOwnHook && group.hooks.length === 0) eventGroups.splice(index, 1);
+      }
+      let group = eventGroups.find((entry) => entry?.matcher === spec.matcher);
+      const createdGroup = !group;
+      if (!keptDeclaredHook) {
+        if (!group) {
+          group = { matcher: spec.matcher, hooks: [] };
+          eventGroups.push(group);
+        }
+        if (!Array.isArray(group.hooks)) group.hooks = [];
+        group.hooks.push(hookToMove);
+      }
+      await atomicWrite(settingsPath, settings, state);
+      return { changed: true, createdGroup, moved: true };
+    }
     let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
     const createdGroup = !group;
     if (!group) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.5.2",
-  "description": "Claude Code-to-Codex delegation with 5 guards, 604 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.5.3",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 757 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/scripts/run-tests.mjs

@@ -16,21 +16,50 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { ISOLATED_ROOTS } from './isolated-roots.mjs';
+import { readmeText, suiteCountMismatch } from './suite-count.mjs';
 
 const created = ISOLATED_ROOTS.map((name) => [
   name,
   fs.mkdtempSync(path.join(os.tmpdir(), `codex-bridge-test-${name.toLowerCase()}-`)),
 ]);
 const pattern = process.argv[2] || 'tests/**/*.test.mjs';
+// Only a whole-suite run can judge the README's number; a single file legitimately reports two.
+const wholeSuite = !process.argv[2];
+const tapFile = wholeSuite
+  ? path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'codex-bridge-test-summary-')), 'summary.tap')
+  : null;
+const repositoryRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+// The spec reporter is named explicitly because the second reporter would otherwise replace it,
+// and the operator would lose the live output this command exists to show.
+const reporters = tapFile
+  ? ['--test-reporter=spec', '--test-reporter-destination=stdout',
+    '--test-reporter=tap', `--test-reporter-destination=${tapFile}`]
+  : [];
 
 try {
-  const result = spawnSync(process.execPath, ['--test', pattern], {
+  const result = spawnSync(process.execPath, ['--test', ...reporters, pattern], {
     stdio: 'inherit',
     env: { ...process.env, ...Object.fromEntries(created) },
   });
   process.exitCode = result.status ?? 1;
+  if (tapFile && process.exitCode === 0) {
+    let tap = null;
+    try {
+      tap = fs.readFileSync(tapFile, 'utf8');
+    } catch {
+      tap = null;
+    }
+    const mismatch = suiteCountMismatch(readmeText(path.join(repositoryRoot, 'README.md')), tap);
+    if (mismatch) {
+      process.stderr.write(`\nsuite-count: ${mismatch}\n`);
+      process.exitCode = 1;
+    }
+  }
 } finally {
   for (const [, directory] of created) fs.rmSync(directory, { recursive: true, force: true });
+  if (tapFile) fs.rmSync(path.dirname(tapFile), { recursive: true, force: true });
 }

package/scripts/suite-count.mjs

@@ -0,0 +1,65 @@
+/**
+ * Compares the README's advertised suite size with what the suite actually reported.
+ *
+ * The number is prose, so nothing checked it: README said 705 tests while the suite ran 751, and
+ * package.json still advertised 604 from three releases earlier. Both were found by eye during
+ * the 0.5.3 release, which is the third release in a row where a shipped number was wrong. The
+ * count is the first thing a reader judges the package by, and it goes stale silently with every
+ * test added — so the runner that knows the real number is the place the claim is verified.
+ */
+import fs from 'node:fs';
+
+export const SUITE_CLAIM =
+  /\*\*(\d+) automated tests: (\d+) passing and (\d+) skipped\*\*/;
+
+/** Read the TAP summary a second reporter wrote; null when the file says nothing usable. */
+export function reportedCounts(tapOutput) {
+  if (typeof tapOutput !== 'string' || !tapOutput.trim()) return null;
+  const read = (key) => {
+    const found = tapOutput.match(new RegExp(`^# ${key} (\\d+)$`, 'm'));
+    return found ? Number(found[1]) : null;
+  };
+  const tests = read('tests');
+  const pass = read('pass');
+  const skipped = read('skipped');
+  if (tests === null || pass === null || skipped === null) return null;
+  return { tests, pass, skipped };
+}
+
+/** Read the claim out of README text; null when the sentence is absent. */
+export function claimedCounts(readmeText) {
+  const found = typeof readmeText === 'string' ? readmeText.match(SUITE_CLAIM) : null;
+  if (!found) return null;
+  return { tests: Number(found[1]), pass: Number(found[2]), skipped: Number(found[3]) };
+}
+
+/**
+ * Return the message a mismatch should print, or null when the claim holds. A missing claim is a
+ * mismatch too: the sentence is what the gate protects, and deleting it must not silence the gate.
+ */
+export function suiteCountMismatch(readmeText, tapOutput) {
+  const reported = reportedCounts(tapOutput);
+  if (!reported) return null;
+  const claimed = claimedCounts(readmeText);
+  if (!claimed) {
+    return 'README no longer states the suite size. Restore the sentence: '
+      + `**${reported.tests} automated tests: ${reported.pass} passing and ${reported.skipped} skipped**.`;
+  }
+  if (claimed.tests === reported.tests
+    && claimed.pass === reported.pass
+    && claimed.skipped === reported.skipped) {
+    return null;
+  }
+  return 'README states the wrong suite size. '
+    + `It says ${claimed.tests} tests (${claimed.pass} passing, ${claimed.skipped} skipped); `
+    + `this run had ${reported.tests} (${reported.pass} passing, ${reported.skipped} skipped). `
+    + 'Update the sentence in README.md before the release.';
+}
+
+export function readmeText(readmePath) {
+  try {
+    return fs.readFileSync(readmePath, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/home/hooks/shell-write-intent.mjs

@@ -0,0 +1,120 @@
+/**
+ * Reports whether a shell command plainly intends to write files and the target paths it names.
+ *
+ * This is deliberately not a complete list, and it cannot become one. Enumerating every way a
+ * shell can write would reproduce the original defect one level up: the 2026-08-16 incident is
+ * why the worktree witness hook exists beside this cheap prevention check.
+ */
+
+const COMMANDS = new Set(['cp', 'mv', 'rm', 'touch', 'truncate', 'tee', 'sed']);
+const INTERPRETERS = /\b(?:python(?:\d+(?:\.\d+)?)?|node|perl|ruby)(?:\.exe)?\b/i;
+
+function unquote(value) {
+  const trimmed = value.trim().replace(/[;,]+$/, '');
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"'))
+    || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+// A candidate holding a character no file name may contain is not a file name. The redirection
+// pattern cannot tell `>` the operator from `>` the redirect, so `node -e "i>0?'yes':'no'"` was
+// refused on 2026-08-23 naming the path `0?'yes` — a false refusal on a command that writes
+// nothing. Narrowing here costs nothing the witness does not already cover.
+const IMPOSSIBLE_IN_A_NAME = /[?*<>|"]/;
+
+function addPath(paths, value) {
+  const candidate = unquote(value);
+  if (candidate
+    && !['&', '$', '%', '`'].includes(candidate[0])
+    && !IMPOSSIBLE_IN_A_NAME.test(candidate)
+    && !paths.includes(candidate)) paths.push(candidate);
+}
+
+function tokens(segment) {
+  return segment.match(/"(?:\\.|[^"])*"|'[^']*'|[^\s]+/g) ?? [];
+}
+
+function positional(args) {
+  return args.filter((arg) => !arg.startsWith('-'));
+}
+
+/**
+ * Strip the directory and the Windows executable suffix before matching the command name.
+ * `INTERPRETERS` has always allowed `python.exe`; the command list did not, so `sed.exe -i` —
+ * the spelling Git Bash and PowerShell hand over on this platform — walked past the guard while
+ * the identical `sed -i` was refused (found accepting the 2026-08-17 smoke run, which had recorded
+ * that gap as intended behaviour).
+ */
+function commandName(token) {
+  return token.replace(/^.*[\\/]/, '').replace(/\.exe$/i, '').toLowerCase();
+}
+
+/**
+ * Split a heredoc command into the shell around it and the document inside it.
+ *
+ * `shell` is everything the shell itself runs — the line opening the document AND every command
+ * after its closing marker. Dropping that tail hid `… <<EOF … EOF; echo x >> README.md` from the
+ * guard completely, and a live probe on 2026-08-23 wrote to a tracked file during a held run
+ * exactly that way. `paths` holds only what the document body names, which the caller uses just
+ * when the interpreter is itself the writer.
+ */
+function heredoc(command) {
+  const header = command.match(/^(.*?<<-?\s*(['"]?)([A-Za-z_][\w-]*)\2[^\r\n]*)[\r\n]/s);
+  if (!header) return null;
+  const paths = [];
+  const marker = header[3];
+  const body = command.slice(header[0].length).split(/\r?\n/);
+  const end = body.findIndex((line) => line.trim() === marker);
+  const shell = [header[1], ...(end < 0 ? [] : body.slice(end + 1))].join('\n');
+  if (!INTERPRETERS.test(header[1])) return { shell, paths, writes: false };
+  const source = body.slice(0, end < 0 ? body.length : end).join('\n');
+  for (const match of source.matchAll(/(['"])(.*?)\1/g)) {
+    const value = match[2];
+    if (/^(?:[A-Za-z]:[\\/]|[\\/]|\.\.?[\\/])/.test(value)
+      || /[\\/]/.test(value)
+      || /(?:^|[\\/])[^\\/]+\.[A-Za-z0-9_-]+$/.test(value)) addPath(paths, value);
+  }
+  return { header: header[1], paths, writes: true };
+}
+
+/** Returns `{ writes, paths }` for the deliberately obvious write forms this guard recognises. */
+export function shellWriteIntent(command) {
+  if (typeof command !== 'string' || !command.trim()) return { writes: false, paths: [] };
+  const paths = [];
+  const document = heredoc(command);
+  const shell = document?.header ?? command;
+  let writes = document?.writes ?? false;
+
+  for (const match of shell.matchAll(/(?<![<>=])(?:\d*)>>?(?![=>&])\s*("(?:\\.|[^"])*"|'[^']*'|[^\s;|&]+)/g)) {
+    writes = true;
+    addPath(paths, match[1]);
+  }
+
+  // A real output redirect identifies the writer's destination. Body text is only evidence when
+  // the interpreter itself is the writer, as in the 2026-08-16 python heredoc incident.
+  if (!paths.length && document?.writes) {
+    for (const candidate of document.paths) addPath(paths, candidate);
+  }
+
+  for (const segment of shell.split(/(?:&&|\|\||[;|\r\n])/)) {
+    const parts = tokens(segment);
+    const index = parts.findIndex((part) => COMMANDS.has(commandName(part)));
+    if (index < 0) continue;
+    const name = commandName(parts[index]);
+    const args = parts.slice(index + 1);
+    if (name === 'sed' && !args.some((arg) => /^-.*i/.test(arg))) continue;
+    writes = true;
+    const values = positional(args);
+    if (name === 'cp' || name === 'mv') {
+      if (values.length > 1) addPath(paths, values.at(-1));
+    } else if (name === 'sed') {
+      for (const value of values.slice(1)) addPath(paths, value);
+    } else {
+      for (const value of values) addPath(paths, value);
+    }
+  }
+
+  return { writes, paths };
+}

package/src/home/hooks/worktree-lock.mjs

@@ -1,77 +1,109 @@
-#!/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 { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
-import { WRITE_TOOLS } from '../lib/hook-definitions.mjs';
-import { runsRoot } from '../lib/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}). `
-      // "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)}.`,
-  },
-}));
+#!/usr/bin/env node
+/**
+ * PreToolUse lock for file tools and plainly recognisable shell writes 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 { spawnSync } from 'node:child_process';
+import { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
+import { SHELL_TOOLS, WRITE_TOOLS } from '../lib/hook-definitions.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+import { shellWriteIntent } from './shell-write-intent.mjs';
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
+const SHELL_TOOL_NAMES = new Set(SHELL_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) && !SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+
+const toolInput = input.tool_input;
+if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
+let rawPaths;
+if (WRITE_TOOL_NAMES.has(input.tool_name)) {
+  const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+  const rawPath = toolInput[pathField];
+  if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
+  rawPaths = [rawPath];
+} else {
+  const intent = shellWriteIntent(toolInput.command);
+  if (!intent.writes || !intent.paths.length) pass();
+  rawPaths = intent.paths;
+}
+
+let liveRuns;
+try {
+  liveRuns = allLiveRuns(runsRoot());
+} catch {
+  pass();
+}
+let match;
+for (const rawPath of rawPaths) {
+  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 continue;
+  } catch {
+    continue;
+  }
+  const target = normalizePath(targetPath);
+  if (!target) continue;
+  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) {
+    match = { owner, targetPath };
+    break;
+  }
+}
+if (!match) pass();
+
+const { status, dir } = match.owner;
+// A run is only ever failed for what `git status --porcelain` reports, and an ignored path never
+// appears there — the witness that grades a run does not see it either. Meanwhile the working
+// order for a live run is to touch exactly those files: plans and checklists live in ignored
+// folders. On 2026-08-23 this guard refused four such edits in five minutes, which is worse than
+// a miss: a miss has the witness behind it, a false refusal has nothing and reads as a broken
+// tool. Only a proven `ignored` passes — anything else (not a repository, git absent, any other
+// error) keeps the refusal, because "no proof it is ignored" is not "proof it is harmless".
+const repository = normalizePath(status.repo);
+const target = normalizePath(match.targetPath);
+const gitMetadata = target === `${repository}/.git` || target.startsWith(`${repository}/.git/`);
+if (!gitMetadata) {
+  const ignored = spawnSync('git', ['-C', status.repo, 'check-ignore', '--quiet', '--', match.targetPath], {
+    stdio: 'ignore',
+  });
+  if (ignored.status === 0) pass();
+}
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${match.targetPath} is inside repository `
+      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
+      // "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/home/hooks/worktree-witness.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse witness for shell writes into a live codex-build repository.
+ *
+ * A shell can write through Python, redirection, or any other command while bypassing the
+ * file-tool lock. That is how the orchestrator changed CHANGELOG.md during the 2026-08-16
+ * split-guard run and made an honest build appear out of scope. This hook compares the live
+ * run's recorded git state with the repository after every shell tool and directs the
+ * orchestrator to undo any change outside the run's declared scope.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SHELL_TOOLS } from '../lib/hook-definitions.mjs';
+import { parseJsonText } from '../lib/json-file.mjs';
+import { globToRegExp } from '../lib/meta/paths.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
+import { allLiveRuns, normalizePath } from './live-runs.mjs';
+
+const SHELL_TOOL_NAMES = new Set(SHELL_TOOLS);
+const pass = () => process.exit(0);
+
+function readRequired(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function statusMap(text) {
+  if (typeof text !== 'string') return null;
+  const result = new Map();
+  for (const line of text.split(/\r?\n/).filter(Boolean)) {
+    if (!/^.. /.test(line)) return null;
+    const rawPath = line.slice(3);
+    const file = rawPath.includes(' -> ') ? rawPath.slice(rawPath.lastIndexOf(' -> ') + 4) : rawPath;
+    if (!file.trim()) return null;
+    result.set(file, line.slice(0, 2));
+  }
+  return result;
+}
+
+let input;
+try {
+  input = parseJsonText('stdin', fs.readFileSync(0, 'utf8'));
+} catch {
+  pass();
+}
+
+if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
+if (!SHELL_TOOL_NAMES.has(input.tool_name)) pass();
+const cwd = normalizePath(input.cwd);
+if (!cwd) 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) && (cwd === repository || cwd.startsWith(`${repository}/`));
+});
+if (!owner) pass();
+
+const { dir, status } = owner;
+const beforeText = readRequired(path.join(dir, 'git-before.txt'));
+const scopeText = readRequired(path.join(dir, 'scope.txt'));
+if (beforeText === null || scopeText === null) pass();
+
+const before = statusMap(beforeText);
+let allowed;
+try {
+  const patterns = scopeText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (!patterns.length) pass();
+  allowed = patterns.map(globToRegExp);
+} catch {
+  pass();
+}
+if (!before) pass();
+
+let currentResult;
+try {
+  currentResult = spawnSync('git', ['-C', status.repo, 'status', '--porcelain'], {
+    encoding: 'utf8',
+  });
+} catch {
+  pass();
+}
+if (currentResult.error || currentResult.status !== 0 || typeof currentResult.stdout !== 'string') pass();
+const current = statusMap(currentResult.stdout);
+if (!current) pass();
+
+const changed = [];
+for (const [file, state] of current) if (before.get(file) !== state) changed.push(file);
+for (const file of before.keys()) if (!current.has(file)) changed.push(file);
+const outside = [...new Set(changed)].filter((file) => !allowed.some((pattern) => pattern.test(file)));
+if (!outside.length) pass();
+
+const folder = path.basename(dir);
+const paths = outside.join(', ');
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PostToolUse',
+    additionalContext: `WORKTREE WITNESS — act now: the shell changed paths outside the scope of `
+      + `live run folder ${dir} (agent ${status.agent}, slug ${status.slug}): ${paths}. `
+      + `Revert those paths now, or run codex-bridge stop ${folder} to take the repository back `
+      + `before making further changes.`,
+  },
+}));

package/src/home/lib/heartbeat.mjs

@@ -2,7 +2,10 @@
  * 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.
+ * the timer stops at exit. The file's modification time is the run's best-effort sign of recent
+ * progress. A failed stamp is swallowed so this hint cannot prevent the run's normal verdict and
+ * artifacts. For an old record, a missing file is a legacy state that keeps its lock until its pid
+ * dies.
  */
 import fs from 'node:fs';
 import path from 'node:path';