@lyupro/codex-bridge 0.5.2 → 0.5.4

package/cli/probe-contract.mjs

@@ -0,0 +1,174 @@
+/**
+ * Measures whether the installed host applies a PreToolUse refusal, not merely whether the hook
+ * returns one. The sibling `allow` decision silently stopped working between hosts 2.1.119 and
+ * 2.1.231, so a missing marker is trusted only when the hook fired and the host completed cleanly.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { detectHostVersion, writeHostContract } from './host-contract.mjs';
+
+export const PROBE_MARKER = 'codex-bridge-contract-probe';
+
+const MARKER_NAME = `${PROBE_MARKER}.marker`;
+const JOURNAL_NAME = 'probe-journal.log';
+
+const exists = async (target) => {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export function judgeProbe({ markerExists, hookFired, hostResult }) {
+  if (markerExists) {
+    return { result: 'ignored', reason: 'The marker command ran despite the hook refusal.' };
+  }
+  if (!hostResult) {
+    return { result: null, reason: 'The host could not be started.' };
+  }
+  if (hostResult.error) {
+    const timedOut = hostResult.error.code === 'ETIMEDOUT';
+    return {
+      result: null,
+      reason: timedOut ? 'The host timed out before the probe completed.' : 'The host process failed to start.',
+    };
+  }
+  if (hostResult.signal) {
+    return { result: null, reason: `The host was terminated by signal ${hostResult.signal}.` };
+  }
+  if (hostResult.status !== 0) {
+    return { result: null, reason: `The host exited with status ${String(hostResult.status)}.` };
+  }
+  if (!hookFired) {
+    return { result: null, reason: 'The probe hook never received the marker command.' };
+  }
+  return { result: 'honored', reason: 'The hook fired and the refused marker command did not run.' };
+}
+
+const hookSource = `#!/usr/bin/env node
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const marker = ${JSON.stringify(PROBE_MARKER)};
+const journalPath = fileURLToPath(new URL('../${JOURNAL_NAME}', import.meta.url));
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+if (typeof input?.tool_input?.command === 'string' && input.tool_input.command.includes(marker)) {
+  fs.appendFileSync(journalPath, \`${PROBE_MARKER}\\n\`, 'utf8');
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: 'Contract probe refused its marker command.',
+    },
+  }));
+}
+`;
+
+// Forward slashes on purpose: the host runs this hook command line through a POSIX shell, and a
+// Windows path handed over verbatim arrives carrying backslashes that shell may swallow. The
+// doubled form this replacement first carried matched nothing at all on a real path.
+const shellQuote = (value) => `"${value.replaceAll('\\', '/').replaceAll('"', '\\"')}"`;
+
+export async function buildRig(dir) {
+  const claudeDir = path.join(dir, '.claude');
+  const hooksDir = path.join(claudeDir, 'hooks');
+  const hookPath = path.join(hooksDir, 'probe-hook.mjs');
+  const markerPath = path.join(dir, MARKER_NAME);
+  const journalPath = path.join(claudeDir, JOURNAL_NAME);
+  const command = `touch ${MARKER_NAME}`;
+  const prompt = `Run exactly this Bash command and nothing else: ${command}`;
+  const settings = {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: `${shellQuote(process.execPath)} ${shellQuote(hookPath)}` }],
+      }],
+    },
+  };
+
+  await fs.mkdir(hooksDir, { recursive: true });
+  await fs.writeFile(hookPath, hookSource, 'utf8');
+  await fs.writeFile(
+    path.join(claudeDir, 'settings.json'),
+    `${JSON.stringify(settings, null, 2)}\n`,
+    'utf8',
+  );
+  return { dir, markerPath, journalPath, command, prompt };
+}
+
+export async function probeContract({
+  host,
+  version = detectHostVersion(),
+  runHost = spawnSync,
+  rigRoot = os.tmpdir(),
+  now = new Date(),
+}) {
+  if (version == null) {
+    return {
+      state: 'inconclusive',
+      result: null,
+      version: null,
+      message: 'The host version could not be read, so no contract probe was run.',
+      recorded: false,
+    };
+  }
+
+  await fs.mkdir(rigRoot, { recursive: true });
+  const dir = await fs.mkdtemp(path.join(rigRoot, `${PROBE_MARKER}-`));
+  try {
+    const rig = await buildRig(dir);
+    let hostResult;
+    try {
+      hostResult = runHost('claude', [
+        '--setting-sources', 'project',
+        '--allowedTools', 'Bash',
+        '-p', rig.prompt,
+      ], {
+        cwd: rig.dir,
+        encoding: 'utf8',
+        shell: false,
+        timeout: 120000,
+      });
+    } catch (error) {
+      hostResult = { error };
+    }
+
+    const verdict = judgeProbe({
+      markerExists: await exists(rig.markerPath),
+      hookFired: await exists(rig.journalPath),
+      hostResult,
+    });
+    if (verdict.result == null) {
+      return {
+        state: 'inconclusive',
+        result: null,
+        version,
+        message: verdict.reason,
+        recorded: false,
+      };
+    }
+
+    await writeHostContract(host, { version, result: verdict.result, now });
+    return {
+      state: 'probed',
+      result: verdict.result,
+      version,
+      message: verdict.reason,
+      recorded: true,
+    };
+  } finally {
+    // Windows can retain a just-written hook tree briefly; cleanup failure must not erase a valid
+    // measurement or prevent the result from being recorded.
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}

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,49 +1,49 @@
-{
-  "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.",
-  "keywords": [
-    "claude-code",
-    "codex",
-    "codex-cli",
-    "subagent",
-    "ai-agents",
-    "orchestration",
-    "hooks"
-  ],
-  "license": "MIT",
-  "author": "Lyu Pro <lyupro.dev@gmail.com> (https://lyupro.com)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lyupro/codex-bridge.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lyupro/codex-bridge/issues"
-  },
-  "homepage": "https://github.com/lyupro/codex-bridge#readme",
-  "type": "module",
-  "bin": {
-    "codex-bridge": "./bin/codex-bridge.mjs",
-    "codexb": "./bin/codex-bridge.mjs"
-  },
-  "engines": {
-    "node": ">=24.0.0"
-  },
-  "files": [
-    "bin",
-    "cli",
-    "src",
-    "scripts",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "dev:install": "node bin/codex-bridge.mjs update --force",
-    "test": "node scripts/run-tests.mjs",
-    "check:size": "node scripts/check-file-size.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@lyupro/codex-bridge",
+  "version": "0.5.4",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 809 tests, zero runtime dependencies, and zero build steps.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "codex-cli",
+    "subagent",
+    "ai-agents",
+    "orchestration",
+    "hooks"
+  ],
+  "license": "MIT",
+  "author": "Lyu Pro <lyupro.dev@gmail.com> (https://lyupro.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lyupro/codex-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lyupro/codex-bridge/issues"
+  },
+  "homepage": "https://github.com/lyupro/codex-bridge#readme",
+  "type": "module",
+  "bin": {
+    "codex-bridge": "./bin/codex-bridge.mjs",
+    "codexb": "./bin/codex-bridge.mjs"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "bin",
+    "cli",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev:install": "node bin/codex-bridge.mjs update --force",
+    "test": "node scripts/run-tests.mjs",
+    "check:size": "node scripts/check-file-size.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/run-tests.mjs

@@ -16,21 +16,53 @@
 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()}-`)),
 ]);
+// Fixtures created temporary trees no one removed, so keep them under one disposable root.
+const testTmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-bridge-test-tmp-'));
 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) },
+    env: { ...process.env, ...Object.fromEntries(created), CODEX_BRIDGE_TEST_TMP: testTmpRoot },
   });
   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 });
+  fs.rmSync(testTmpRoot, { 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;
+  }
+}