@lyupro/codex-bridge 0.5.3 → 0.5.4

package/cli/host-contract.mjs

@@ -0,0 +1,135 @@
+/**
+ * Records whether the installed Claude Code host still honours hook refusals.
+ *
+ * Every guard here refuses work with `permissionDecision: "deny"`, and the sibling key of that same
+ * object died quietly: a neighbouring package established that `"allow"` stopped being honoured
+ * somewhere between host 2.1.119 and 2.1.231, with no error printed on the way. Nothing in this
+ * package would notice `deny` going the same way — the suite checks that a hook RETURNED a refusal,
+ * never that the host APPLIED it. The record is bound to a host version because that is what
+ * changes underneath an installation: the host updates itself, the package does not.
+ */
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CLI_NAMES } from '../src/home/lib/cli-names.mjs';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
+
+export const HOST_CONTRACT_RECORD_NAME = '.host-contract.json';
+
+/**
+ * The command that runs the probe, kept here so every message gains it in one edit.
+ *
+ * It stayed unnamed in the messages until the command existed: a package that sends an operator to
+ * a command answering `unknown doctor option` has spent its credibility on the first line they
+ * read. The advice arrived in the same change as the command, and only in the states a probe can
+ * actually change — a message that advises a run which would tell you nothing new is noise.
+ *
+ * Derived rather than spelled out: Plan_17 §5 found installer and hook lists drifting apart once
+ * the same name lived in two places. `CLI_NAMES[0]` is the canonical spelling.
+ */
+export const PROBE_COMMAND = `${CLI_NAMES[0]} doctor --probe-contract`;
+
+export function hostContractPath(host) {
+  if (!host?.brandRoot) throw new Error('host has no brand installation root');
+  return path.join(host.brandRoot, HOST_CONTRACT_RECORD_NAME);
+}
+
+export async function readHostContract(host) {
+  const target = hostContractPath(host);
+  try {
+    const record = await readJsonFile(target);
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || typeof record.version !== 'string' || !record.version) return null;
+    return {
+      version: record.version,
+      checkedAt: record.checkedAt,
+      result: record.result,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeHostContract(host, { version, result, now = new Date() }) {
+  if (typeof version !== 'string' || !version) {
+    throw new Error('host contract version must be a non-empty string');
+  }
+  if (result !== 'honored' && result !== 'ignored') {
+    throw new Error('host contract result must be honored or ignored');
+  }
+
+  const target = hostContractPath(host);
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  const record = { version, result, checkedAt: now.toISOString() };
+  await fs.mkdir(host.brandRoot, { recursive: true });
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await fs.rename(temporary, target);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+
+export function parseHostVersion(text) {
+  if (typeof text !== 'string') return null;
+  return text.trim().match(/^(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
+}
+
+export function detectHostVersion({ run = spawnSync } = {}) {
+  try {
+    const result = run('claude', ['--version'], {
+      encoding: 'utf8',
+      shell: false,
+      timeout: 5000,
+    });
+    if (!result || result.error || result.status !== 0) return null;
+    return parseHostVersion(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+export function contractStatus({ record, version }) {
+  // Loose equality on purpose: a caller that forgot the field hands over `undefined`, and the
+  // stale branch below would then report "the current host is undefined" as if it had measured it.
+  if (version == null) {
+    return {
+      state: 'unknown-host',
+      message: 'The host version could not be read, so the refusal contract cannot be judged.',
+    };
+  }
+  if (!record) {
+    return {
+      state: 'unverified',
+      message: `The refusal contract has never been probed on this machine (host ${version}); run ${PROBE_COMMAND}.`,
+    };
+  }
+  if (record.version !== version) {
+    return {
+      state: 'stale',
+      message: `The refusal contract was probed on host ${record.version}, but the current host is ${version}; run ${PROBE_COMMAND}.`,
+    };
+  }
+  if (record.result === 'ignored') {
+    const guards = HOOK_DEFINITIONS
+      .filter((definition) => definition.event === 'PreToolUse')
+      .map((definition) => definition.name)
+      .join(', ');
+    return {
+      state: 'ignored',
+      message: `DANGER: Host ${version} does not honour hook refusals, so every guard is inert: ${guards}. Re-run ${PROBE_COMMAND} once the host updates.`,
+    };
+  }
+  if (record.result === 'honored') {
+    return {
+      state: 'verified',
+      message: `Host ${version} honours hook refusals (verified ${record.checkedAt}).`,
+    };
+  }
+  return {
+    state: 'unverified',
+    message: `The refusal contract record is invalid (host ${version}); run ${PROBE_COMMAND}.`,
+  };
+}

package/cli/hosts.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
 
 function repositoryRoot(start) {
   let current = path.resolve(start);
@@ -35,9 +36,9 @@ export function resolveHost({
   // Plan_25 moves package-owned runtime files out of foreign Claude settings, whose absolute
   // hook paths caused the package-file-layout incident. Keep the brand root overrideable so tests
   // and later installation steps never need to know the operator's home directory.
-  const resolvedBrandRoot = path.resolve(
-    brandRoot || process.env.CODEX_BRIDGE_HOME || path.join(homedir, '.lyupro', '.codex-bridge'),
-  );
+  const resolvedBrandRoot = brandRoot
+    ? path.resolve(brandRoot)
+    : resolveBrandHome({ homedir, env: process.env }).root;
   const brandPaths = {
     brandRoot: resolvedBrandRoot,
     brandHooksDir: path.join(resolvedBrandRoot, 'hooks'),

package/cli/install.mjs

@@ -26,6 +26,7 @@ import {
 } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { addPermissionRules } from './permissions.mjs';
+import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 
 const WARNING = '\u001b[33m';
@@ -56,6 +57,10 @@ function retentionOutput(line, output) {
   return `${output}\n${line}`;
 }
 
+function contractOutput(status, output) {
+  return status.state === 'verified' ? output : `${output}\n${status.message}`;
+}
+
 async function migrateLegacySeed(host, seed) {
   if (await targetExists(seed.target)) return;
   const legacyName = path.basename(seed.target) === 'config.json' ? 'run-config.json' : path.basename(seed.target);
@@ -73,10 +78,22 @@ async function migrateLegacySeed(host, seed) {
   await fs.rm(legacy, { force: true });
 }
 
-async function installInRun({ host, dryRun = false, force = false, packageRoot, env = process.env } = {}) {
+async function installInRun({
+  host,
+  dryRun = false,
+  force = false,
+  packageRoot,
+  env = process.env,
+  contractRecord,
+  hostVersion,
+} = {}) {
   // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
   await readRulesRegistry(host);
   const configuredRetentionLine = retentionLine(host);
+  const hostContract = contractStatus({
+    record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
+    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+  });
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
@@ -112,7 +129,7 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
     const files = conflicts.map(({ item }) => `  ${item.relativeToRoot || item.name}`).join('\n');
     return {
       exitCode: 1,
-      output: retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`),
+      output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`)),
     };
   }
 
@@ -124,7 +141,10 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
     && recordHasHooks(record, targets) && sameRecord) {
     if (!dryRun) await addRulesOwner(host);
-    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.') };
+    return {
+      exitCode: 0,
+      output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.')),
+    };
   }
 
   if (dryRun) {
@@ -140,7 +160,7 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
         : `Would register ${definition.event} hook for matcher ${definition.matcher} with ${registration.form} command.`);
     });
     lines.push('Would write installation record in the brand root.');
-    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, lines.join('\n')) };
+    return { exitCode: 0, output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, lines.join('\n'))) };
   }
 
   // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
@@ -196,10 +216,13 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   });
   return {
     exitCode: 0,
-    output: retentionOutput(
-      configuredRetentionLine,
-      `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`
-        + `\nGranted ${permissionResult.added} permission rule(s) in ${host.settingsPath} so the host runs the package command without asking.`,
+    output: contractOutput(
+      hostContract,
+      retentionOutput(
+        configuredRetentionLine,
+        `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`
+          + `\nGranted ${permissionResult.added} permission rule(s) in ${host.settingsPath} so the host runs the package command without asking.`,
+      ),
     ),
   };
 }

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/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "@lyupro/codex-bridge",
-  "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",
-    "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

@@ -25,6 +25,8 @@ 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];
@@ -43,7 +45,7 @@ const reporters = tapFile
 try {
   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) {
@@ -61,5 +63,6 @@ try {
   }
 } 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 });
 }