@lyupro/codex-bridge 0.6.6 → 0.6.8

package/cli/install.mjs

@@ -15,18 +15,20 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { hookTargets } from './hook-targets.mjs';
+import { hookTargets, recordHasHooks } from './hook-targets.mjs';
 import { fingerprintFor, INSTALL_METHOD_COPY, INSTALL_METHOD_KEY } from './install-record.mjs';
 import {
   commandFor,
-  hookRegistration,
   inspectHook,
   mergeHook,
   withSettingsRun,
 } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { addPermissionRules, inspectPermissions } from './permissions.mjs';
-import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
+import { contractStatus, readHostContract } from './host-contract.mjs';
+import { readHostObservations } from '../src/home/lib/host-observations.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { sessionHostVersions } from './session-hosts.mjs';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 
 const WARNING = '\u001b[33m';
@@ -42,12 +44,6 @@ async function targetExists(target) {
   }
 }
 
-function recordHasHooks(record, targets) {
-  return Boolean(record)
-    && targets.every(({ definition, relative }) => record.hooks?.some((hook) =>
-      hook.event === definition.event && hook.root === 'brand' && hook.path === relative));
-}
-
 function retentionLine(host) {
   const notice = retentionNotice(readRunConfig(host.brandConfigPath));
   return notice.enabled ? `${WARNING}${notice.text}${RESET}` : notice.text;
@@ -116,19 +112,27 @@ async function installInRun({
   env = process.env,
   contractRecord,
   hostVersion,
+  observations,
 } = {}) {
   // 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({
+  const hostObservations = observations === undefined
+    ? readHostObservations({ stateDir: brandStateDir(host.brandRoot) }) : observations;
+  const observedVersion = sessionHostVersions(hostObservations)[0] ?? null;
+  const currentHostVersion = hostVersion === undefined ? observedVersion : hostVersion;
+  let hostContract = contractStatus({
     record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
-    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+    version: currentHostVersion,
   });
+  const noObservedHostMessage = currentHostVersion === null
+    ? 'Host contracts are judged once a session has run a shell command; then run codex-bridge doctor.' : null;
+  if (noObservedHostMessage) hostContract = { ...hostContract, message: noObservedHostMessage };
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
   const record = await readInstallRecord(host);
-  const targets = hookTargets(host, env, currentPackage.version);
+  const targets = hookTargets(host, env);
   for (const target of targets) {
     if (!plan.some((item) => item.root === 'brand' && item.relativeToRoot === target.relative)) {
       throw new Error(`install plan does not contain hooks/${target.definition.file}`);
@@ -168,7 +172,7 @@ async function installInRun({
   const sameRecord = recordMatchesPackage(record, plan, currentPackage,
     new Map(states.map((state) => [recordFileKey(state.item), state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
-  if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
+  if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.current)
     && recordHasHooks(record, targets) && sameRecord) {
     if (!dryRun) {
       await addRulesOwner(host);
@@ -200,9 +204,11 @@ async function installInRun({
     }
     inspectedHooks.forEach((state, index) => {
       const { definition, registration } = targets[index];
-      lines.push(state.present
-        ? `${definition.event} hook is already registered (${registration.form} command).`
-        : `Would register ${definition.event} hook for matcher ${definition.matcher} with ${registration.form} command.`);
+      lines.push(state.present && !state.current
+        ? `Would rewrite ${definition.event} hook ${definition.name} for matcher ${definition.matcher} to ${registration.form} command: ${registration.reason}.`
+        : state.present
+          ? `${definition.event} hook is already registered (${registration.form} command).`
+        : `Would register ${definition.event} hook ${definition.name} for matcher ${definition.matcher} with ${registration.form} command.`);
     });
     lines.push('Would write installation record in the brand root.');
     return { exitCode: 0, output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, lines.join('\n'))) };
@@ -242,7 +248,7 @@ async function installInRun({
     const prior = record?.hooks?.find((hook) => hook.event === definition.event
       && hook.root === 'brand' && hook.path === relative);
     const createdGroup = hookResults[index].createdGroup || prior?.createdGroup === true;
-    const command = inspectedHooks[index].matchedCommand || registration.command;
+    const command = registration.command;
     return {
       event: definition.event,
       root: 'brand',

package/cli/launcher-probe.mjs

@@ -0,0 +1,38 @@
+/** Proves the PATH launcher dispatches guards from the home being installed. */
+import path from 'node:path';
+import { HOOK_LAUNCHER_PROTOCOL } from './hook.mjs';
+import { runReachableCommand } from './settings-merge.mjs';
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+
+function normalizeRoot(root) {
+  let normalized = root.replaceAll('\\', '/').replace(/\/+$/, '');
+  if (process.platform === 'win32') normalized = normalized.toLowerCase();
+  return normalized;
+}
+
+export function probeHookLauncher({ env, brandRoot }) {
+  const result = runReachableCommand('codex-bridge', ['hook', '--home'], env);
+  if (!result) return { ok: false, reason: 'codex-bridge is not on PATH' };
+  if (result.status !== 0) {
+    return { ok: false, reason: 'codex-bridge on PATH is not a launcher (hook --home failed)' };
+  }
+  let answer;
+  try {
+    answer = parseJsonText('codex-bridge hook --home', result.stdout);
+  } catch {
+    return { ok: false, reason: 'malformed launcher answer' };
+  }
+  if (!answer || typeof answer !== 'object' || Array.isArray(answer)) {
+    return { ok: false, reason: 'malformed launcher answer' };
+  }
+  if (answer.protocol !== HOOK_LAUNCHER_PROTOCOL) {
+    return { ok: false, reason: `unsupported launcher protocol ${String(answer.protocol)}` };
+  }
+  if (answer.dispatch !== 'home' || typeof answer.homeRoot !== 'string' || !answer.homeRoot.trim()) {
+    return { ok: false, reason: 'malformed launcher answer' };
+  }
+  if (normalizeRoot(answer.homeRoot) !== normalizeRoot(path.resolve(brandRoot))) {
+    return { ok: false, reason: `launcher runs from ${answer.homeRoot}, not ${brandRoot}` };
+  }
+  return { ok: true, commandPath: result.path, homeRoot: answer.homeRoot };
+}

package/cli/probe-contract.mjs

@@ -7,13 +7,17 @@ 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';
+import { writeHostContract } from './host-contract.mjs';
+import { buildRig } from './probe-rig.mjs';
+import { DISPATCHER_CONTRACTS, judgeDispatcherContracts } from './dispatcher-contract.mjs';
+import { writeDispatcherContract } from './dispatcher-contract-record.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+import { randomUUID } from 'node:crypto';
+import { transcriptHostVersion } from '../src/home/lib/host-version.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);
@@ -55,122 +59,103 @@ export function judgeProbe({ markerExists, hookFired, hostResult }) {
   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(),
+  target,
   runHost = spawnSync,
   rigRoot = os.tmpdir(),
   now = new Date(),
 }) {
-  if (version == null) {
+  if (target?.error || !target?.version || !target?.executable) {
+    const message = target?.error ?? 'The probe target is unavailable.';
     return {
       state: 'inconclusive',
       result: null,
       version: null,
-      message: 'The host version could not be read, so no contract probe was run.',
+      message,
       recorded: false,
+      dispatcher: Object.fromEntries(DISPATCHER_CONTRACTS.map((name) => [name, { result: 'inconclusive', detail: 'Host version is unavailable.' }])),
     };
   }
 
   await fs.mkdir(rigRoot, { recursive: true });
   const dir = await fs.mkdtemp(path.join(rigRoot, `${PROBE_MARKER}-`));
   try {
-    const rig = await buildRig(dir);
+    const token = randomUUID().slice(0, 8);
+    const rig = await buildRig(dir, token);
     let hostResult;
     try {
-      hostResult = runHost('claude', [
+      hostResult = runHost(target.executable, [
         '--setting-sources', 'project',
-        '--allowedTools', 'Bash',
+        '--allowedTools', 'Bash,Agent',
         '-p', rig.prompt,
       ], {
         cwd: rig.dir,
         encoding: 'utf8',
         shell: false,
         timeout: 120000,
+        windowsHide: true,
       });
     } catch (error) {
       hostResult = { error };
     }
 
+    let entries = [];
+    let malformed = false;
+    try {
+      const source = await fs.readFile(rig.dispatcherJournalPath, 'utf8');
+      entries = source.split(/\r?\n/).filter(Boolean).map((line) => parseJsonText(rig.dispatcherJournalPath, line));
+    } catch (error) {
+      if (error.code !== 'ENOENT') malformed = true;
+    }
+    // Only a host that completed the run can be asked who it was; a spawn failure or timeout keeps its own
+    // reason below instead of reading as "ran on host unknown".
+    const hostCompleted = !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0;
+    let seen = null;
+    const transcriptPath = entries.find((entry) => typeof entry?.payload?.transcript_path === 'string')?.payload.transcript_path;
+    if (transcriptPath) seen = await transcriptHostVersion(transcriptPath);
+    if (hostCompleted && seen !== target.version) {
+      return {
+        state: 'inconclusive', result: null, version: target.version,
+        message: `The probe ran on host ${seen ?? 'unknown'}, not on ${target.version}; nothing was recorded.`,
+        recorded: false,
+        dispatcher: Object.fromEntries(DISPATCHER_CONTRACTS.map((name) => [name, { result: 'inconclusive', detail: 'Probe host version did not match target.' }])),
+      };
+    }
     const verdict = judgeProbe({
       markerExists: await exists(rig.markerPath),
       hookFired: await exists(rig.journalPath),
       hostResult,
     });
+    let dispatcher = judgeDispatcherContracts({
+      entries: malformed ? null : entries,
+      hostHealthy: !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0,
+      okCommand: rig.okCommand, failCommand: rig.failCommand, okOutput: rig.okOutput,
+      failOutput: rig.failOutput, agentType: 'probe-agent', promptToken: token,
+    });
+    if (verdict.result == null) dispatcher = Object.fromEntries(Object.keys(dispatcher).map((name) => [name, { result: 'inconclusive', detail: 'Refusal probe did not complete.' }]));
+    if (verdict.result != null && !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0) {
+      await writeDispatcherContract({ stateDir: brandStateDir(host.brandRoot), version: target.version, verdicts: dispatcher, now });
+    }
     if (verdict.result == null) {
       return {
         state: 'inconclusive',
         result: null,
-        version,
+        version: target.version,
         message: verdict.reason,
         recorded: false,
+        dispatcher: Object.fromEntries(Object.entries(dispatcher).map(([name, item]) => [name, { result: 'inconclusive', detail: 'Host did not complete the probe.' }])),
       };
     }
 
-    await writeHostContract(host, { version, result: verdict.result, now });
+    await writeHostContract(host, { version: target.version, result: verdict.result, now });
     return {
       state: 'probed',
       result: verdict.result,
-      version,
+      version: target.version,
       message: verdict.reason,
       recorded: true,
+      dispatcher,
     };
   } finally {
     // Windows can retain a just-written hook tree briefly; cleanup failure must not erase a valid

package/cli/probe-rig.mjs

@@ -0,0 +1,53 @@
+/** Builds one host run that measures refusal and dispatcher contracts together to avoid charging for separate probes. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PROBE_MARKER } from './probe-contract.mjs';
+
+const JOURNAL_NAME = 'probe-journal.log';
+const shellQuote = (value) => `"${value.replaceAll('\\', '/').replaceAll('"', '\\"')}"`;
+
+const hookSource = (refusalCommand) => `#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const base = path.dirname(fileURLToPath(import.meta.url));
+let payload;
+try { payload = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { payload = {}; }
+const event = process.argv[2];
+const entry = { event, payload };
+if (event === 'PreToolUse' && payload?.agent_id && payload?.transcript_path && payload?.session_id) {
+  const transcriptPath = path.join(path.dirname(payload.transcript_path), payload.session_id, 'subagents', 'agent-' + payload.agent_id + '.jsonl');
+  try { entry.transcript = { path: transcriptPath, firstLine: fs.readFileSync(transcriptPath, 'utf8').split(/\\r?\\n/, 1)[0] }; }
+  catch (error) { entry.transcript = { path: transcriptPath, error: error.code || error.message }; }
+}
+try { fs.appendFileSync(path.join(base, '..', 'dispatcher-journal.jsonl'), JSON.stringify(entry) + '\\n', 'utf8'); } catch {}
+const refusal = ${JSON.stringify(PROBE_MARKER)};
+if (event === 'PreToolUse' && payload?.tool_input?.command === ${JSON.stringify(refusalCommand)}) {
+  try { fs.appendFileSync(path.join(base, '..', '${JOURNAL_NAME}'), refusal + '\\n', 'utf8'); } catch {}
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: 'Contract probe refused its marker command.' } }));
+}
+`;
+
+export async function buildRig(dir, token) {
+  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, `${PROBE_MARKER}-${token}.marker`);
+  const journalPath = path.join(claudeDir, JOURNAL_NAME);
+  const dispatcherJournalPath = path.join(claudeDir, 'dispatcher-journal.jsonl');
+  const okCommand = `node -e "console.log('cb-probe-ok-${token}')"`;
+  const failCommand = `node -e "console.log('cb-probe-fail-${token}'); console.error('cb-probe-err-${token}'); process.exit(2)"`;
+  const refusalCommand = `touch ${PROBE_MARKER}-${token}.marker`;
+  const agentPrompt = `probe ${token}: run your two commands`;
+  const prompt = `Use the Agent tool with subagent_type "probe-agent" in the foreground and pass it exactly: ${agentPrompt}. Wait for its answer, then run exactly this Bash command and nothing else: ${refusalCommand}`;
+  const hook = (event) => ({ matcher: 'Bash', hooks: [{ type: 'command', command: `${shellQuote(process.execPath)} ${shellQuote(hookPath)} ${event}` }] });
+  const settings = { hooks: { PreToolUse: [hook('PreToolUse')], PostToolUse: [hook('PostToolUse')], PostToolUseFailure: [hook('PostToolUseFailure')] } };
+  const agent = `---\nname: probe-agent\ndescription: Run the dispatcher contract commands.\ntools: Bash\n---\nRun exactly two Bash commands, each as its own call, in the foreground, never retried: first ${okCommand}, then ${failCommand}. Reply with the literal outputs, nothing else.\n`;
+  await fs.mkdir(hooksDir, { recursive: true });
+  await fs.mkdir(path.join(claudeDir, 'agents'), { recursive: true });
+  await fs.writeFile(hookPath, hookSource(refusalCommand), 'utf8');
+  await fs.writeFile(path.join(claudeDir, 'agents', 'probe-agent.md'), agent, 'utf8');
+  await fs.writeFile(path.join(claudeDir, 'settings.json'), `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+  return { dir, markerPath, journalPath, dispatcherJournalPath, prompt, token, okCommand, failCommand, refusalCommand, okOutput: `cb-probe-ok-${token}`, failOutput: `cb-probe-fail-${token}` };
+}

package/cli/probe-target.mjs

@@ -0,0 +1,33 @@
+/** Resolves the session host after the 2026-09-25 PATH host identity incident. */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { detectHostVersion } from './host-contract.mjs';
+import { readHostObservations } from '../src/home/lib/host-observations.mjs';
+
+export function resolveProbeTarget({ stateDir, executable, env = process.env, run = spawnSync, exists = fs.existsSync }) {
+  if (executable) {
+    const version = detectHostVersion({ run, executable });
+    return version === null
+      ? { error: `Could not read the version of ${executable}.` }
+      : { executable, version, source: 'flag' };
+  }
+
+  const observations = readHostObservations({ stateDir });
+  const newest = Object.entries(observations.hosts)
+    .filter(([, entry]) => Number.isFinite(Date.parse(entry?.lastSeen)))
+    .sort((a, b) => Date.parse(b[1].lastSeen) - Date.parse(a[1].lastSeen))[0];
+  if (!newest) {
+    return { error: 'No Claude Code session has been observed by this installation yet; run any shell command in a session first, or pass --probe-executable <path>.' };
+  }
+  const [version] = newest;
+  const candidates = [];
+  if (env.CLAUDE_CODE_EXECPATH && exists(env.CLAUDE_CODE_EXECPATH)) candidates.push(env.CLAUDE_CODE_EXECPATH);
+  candidates.push('claude');
+  const checked = [];
+  for (const candidate of candidates) {
+    const candidateVersion = detectHostVersion({ run, executable: candidate });
+    checked.push(`${candidate} (${candidateVersion ?? 'unknown'})`);
+    if (candidateVersion === version) return { executable: candidate, version, source: 'observed' };
+  }
+  return { error: `No executable of the observed host ${version} was found (checked: ${checked.join(', ')}); pass --probe-executable <path>.` };
+}

package/cli/run-launcher.mjs

@@ -0,0 +1,17 @@
+/** Loads the installed runner because Plan_62 D17 makes the brand home the runtime source of truth. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
+
+export async function runCodex(args = [], io = console) {
+  const home = resolveBrandHome({ homedir: os.homedir(), env: process.env });
+  const entry = path.join(home.root, 'lib', 'run-codex.mjs');
+  if (!fs.existsSync(entry)) {
+    io.error(`codex-bridge run: codex-bridge is not installed in ${home.root}. Run codex-bridge install.`);
+    return 1;
+  }
+  const { runCodexCommand } = await import(pathToFileURL(entry).href);
+  return runCodexCommand(args);
+}

package/cli/session-hosts.mjs

@@ -0,0 +1,51 @@
+/** Judges every observed session host after the 2026-09-25 PATH host identity incident. */
+import { contractStatus, PROBE_COMMAND } from './host-contract.mjs';
+import { DISPATCHER_CONTRACTS, dispatcherContractStatus } from './dispatcher-contract.mjs';
+
+export function sessionHostVersions(observations) {
+  return Object.entries(observations?.hosts ?? {})
+    .map(([version, entry]) => ({ version, timestamp: Date.parse(entry?.lastSeen) }))
+    .filter(({ timestamp }) => Number.isFinite(timestamp))
+    .sort((a, b) => b.timestamp - a.timestamp)
+    .map(({ version }) => version);
+}
+
+export function sessionHostCheck(versions, observations) {
+  if (!versions.length) {
+    return {
+      key: 'sessionHost',
+      status: 'warn',
+      value: 'No Claude Code session has been observed by this installation yet; host contracts are judged once a session runs a shell command.',
+    };
+  }
+  const newest = versions[0];
+  const lastSeen = new Date(observations.hosts[newest].lastSeen).toISOString();
+  const others = versions.slice(1);
+  return {
+    key: 'sessionHost',
+    status: 'ok',
+    value: `Sessions run on host ${newest} (last seen ${lastSeen})${others.length ? `; also seen: ${others.join(', ')}` : ''}`,
+  };
+}
+
+export function otherHostCheck({ version, contractRecord, dispatcherRecord }) {
+  const refusal = contractStatus({ record: contractRecord, version });
+  const dispatchers = dispatcherContractStatus({ record: dispatcherRecord, version });
+  const key = `otherHost:${version}`;
+  if (refusal.state === 'ignored' || dispatchers.some(({ state }) => state === 'changed')) {
+    const changed = dispatchers.filter(({ state }) => state === 'changed').map(({ contract }) => contract);
+    return { key, status: 'fail', value: [refusal.state === 'ignored' ? 'refusal contract ignored' : '', ...changed].filter(Boolean).join('; ') };
+  }
+  if (refusal.state === 'verified' && dispatchers.every(({ state }) => state === 'verified')) {
+    return { key, status: 'ok', value: `Host ${version} refusal and dispatcher contracts are verified.` };
+  }
+  const missing = [];
+  if (refusal.state !== 'verified') missing.push('refusal');
+  missing.push(...dispatchers.filter(({ state }) => state !== 'verified').map(({ contract }) => contract));
+  const probe = `${PROBE_COMMAND} --probe-executable <path to a ${version} executable>`;
+  return {
+    key,
+    status: 'warn',
+    value: `Host ${version} contracts not yet measured: ${missing.join(', ')}; run ${probe}.`,
+  };
+}

package/cli/settings-merge.mjs

@@ -57,44 +57,45 @@ export function commandReachable(name = 'codex-bridge', env = process.env) {
  * could decide anything, and the host refused Bash, PowerShell, file edits and agent launches.
  */
 export function reachableCommandVersion(name = 'codex-bridge', env = process.env) {
+  const result = runReachableCommand(name, ['--version'], env);
+  if (!result || result.status !== 0) return null;
+  return String(result.stdout || '').trim().split(/\r?\n/).pop()?.trim() || null;
+}
+
+export function runReachableCommand(name, args, env = process.env) {
   const shimPath = resolveCommand(name, env);
   if (!shimPath) return null;
   // Node 24 warned with DEP0190 during update (2026-09-07): invoke cmd explicitly for npm shims.
   // Live probes covered plain, bin with space, Program Files (x86), weird & name, and caret^dir.
-  // /d /s /c with path and --version as separate arguments only passed the plain directory:
+  // /d /s /c with path and fixed arguments as separate arguments only passed the plain directory:
   // Node adds quotes, then cmd's /s strips the first and last quote of the whole command line.
   // /d /c without /s failed on & and ^. This single, double-wrapped verbatim command passed all
   // five. Keep native path separators: forward-slash Windows paths do not work through cmd.
   // The interpreter is a property of the machine, not of the PATH handed in: resolving cmd.exe
-  // through the caller's PATH would return null on any env whose PATH omits System32, and a null
-  // version is exactly the silent failure this function exists to prevent.
+  // through the caller's PATH would return null on any env whose PATH omits System32, hiding the
+  // exact command outcome this probe exists to report.
   const shell = envValue(env, 'comspec') || process.env.ComSpec || 'cmd.exe';
+  const fixedArgs = args.map((argument) => ` ${argument}`).join('');
   const result = process.platform === 'win32'
-    ? spawnSync(shell, ['/d', '/s', '/c', `""${shimPath}" --version"`], {
-      encoding: 'utf8', env, shell: false, windowsVerbatimArguments: true,
+    ? spawnSync(shell, ['/d', '/s', '/c', `""${shimPath}"${fixedArgs}"`], {
+      encoding: 'utf8', env, shell: false, windowsVerbatimArguments: true, windowsHide: true,
+      timeout: 10000, maxBuffer: 64 * 1024,
     })
-    : spawnSync(shimPath, ['--version'], { encoding: 'utf8', env, shell: false });
-  if (result.error || result.status !== 0) return null;
-  return String(result.stdout || '').trim().split(/\r?\n/).pop()?.trim() || null;
+    : spawnSync(shimPath, args, {
+      encoding: 'utf8', env, shell: false, windowsHide: true, timeout: 10000, maxBuffer: 64 * 1024,
+    });
+  return { path: shimPath, status: result.status, stdout: String(result.stdout || '') };
 }
 
-export function hookRegistration(name, target, env = process.env, packageVersion = null) {
-  // Requiring the versions to match is stricter than asking whether `hook` exists, deliberately:
-  // a command of another version would run code this install has never seen, which is the hazard
-  // README describes when a global install and a clone coexist. Anything short of a match falls
-  // back to the copy this install placed itself.
-  const reachable = reachableCommandVersion('codex-bridge', env);
-  if (reachable && packageVersion && reachable === packageVersion) {
+export function hookRegistration(name, target, probe) {
+  if (probe.ok) {
     return {
       command: shortCommandFor(name),
       form: 'short',
-      reason: `codex-bridge ${reachable} on PATH matches this package; the global command will execute`,
+      reason: `codex-bridge on PATH launches guards from this home (${probe.homeRoot})`,
     };
   }
-  const reason = reachable
-    ? `codex-bridge on PATH reports ${reachable}, not ${packageVersion}; the installed copy will execute`
-    : 'codex-bridge is not reachable from PATH; the installed copy will execute';
-  return { command: commandFor(target), form: 'path', reason };
+  return { command: commandFor(target), form: 'path', reason: `${probe.reason}; the installed copy will execute` };
 }
 
 export function commandForm(command) {
@@ -163,7 +164,9 @@ const hasOwnCommand = (group, commands) => {
  * 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.
+ * and merge can move it without creating a duplicate. Alternate commands identify our entry, but
+ * do not prove it is in the launcher form selected for this operation. Update must rewrite stale
+ * forms, or unsafe registrations already in settings.json would survive every future update.
  */
 export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
@@ -172,11 +175,15 @@ export async function inspectHook(settingsPath, specOrPath) {
   let matchedCommand;
   let matchedMatcher;
   let requiresMove = false;
+  let requiresRewrite = false;
+  let duplicates = 0;
   for (const group of groups(state.settings, spec.event)) {
     for (const hook of groupHooks(group)) {
       if (hook?.type !== 'command' || !commands.includes(hook.command)) continue;
       matchedCommand ??= hook.command;
       matchedMatcher ??= group?.matcher;
+      duplicates += 1;
+      if (hook.command !== spec.command) requiresRewrite = true;
       if (group?.matcher !== spec.matcher) requiresMove = true;
     }
   }
@@ -187,6 +194,9 @@ export async function inspectHook(settingsPath, specOrPath) {
     matchedCommand,
     matchedMatcher,
     requiresMove,
+    requiresRewrite,
+    duplicates: duplicates > 1,
+    current: Boolean(matchedCommand) && !requiresMove && !requiresRewrite && duplicates === 1,
   };
 }
 
@@ -258,15 +268,17 @@ 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 && !state.requiresMove) return { changed: false, createdGroup: false };
+    if (state.current) 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];
+      // The entry in the declared group wins, so a field the operator added there (a timeout)
+      // survives the rewrite; groups are walked from the end, which would otherwise pick a stale copy.
       let hookToMove;
-      let keptDeclaredHook = false;
+      let declaredHook;
       for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
         const group = eventGroups[index];
         if (!Array.isArray(group?.hooks)) continue;
@@ -274,26 +286,21 @@ export async function mergeHook(settingsPath, specOrPath, inspected) {
         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;
-          }
+          if (group.matcher === spec.matcher) declaredHook ??= hook;
           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);
+      if (!group) {
+        group = { matcher: spec.matcher, hooks: [] };
+        eventGroups.push(group);
       }
+      if (!Array.isArray(group.hooks)) group.hooks = [];
+      group.hooks.push({ ...(declaredHook || hookToMove), command: spec.command });
       await atomicWrite(settingsPath, settings, state);
-      return { changed: true, createdGroup, moved: true };
+      return { changed: true, createdGroup, ...(state.requiresMove ? { moved: true } : {}), ...(state.requiresRewrite ? { rewritten: true } : {}) };
     }
     let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
     const createdGroup = !group;