@lyupro/codex-bridge 0.6.5 → 0.6.7

package/cli/host-contract.mjs

@@ -1,135 +1,136 @@
-/**
- * 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}.`,
-  };
-}
+/**
+ * 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,
+      windowsHide: true,
+    });
+    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/install.mjs

@@ -15,11 +15,10 @@ 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,
@@ -42,12 +41,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;
@@ -128,7 +121,7 @@ async function installInRun({
   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 +161,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 +193,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 +237,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

@@ -8,12 +8,15 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { detectHostVersion, 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';
 
 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,63 +58,6 @@ 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(),
@@ -126,34 +72,55 @@ export async function probeContract({
       version: null,
       message: 'The host version could not be read, so no contract probe was run.',
       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', [
         '--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;
+    }
     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 && version != null && !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0) {
+      await writeDispatcherContract({ stateDir: brandStateDir(host.brandRoot), version, verdicts: dispatcher, now });
+    }
     if (verdict.result == null) {
       return {
         state: 'inconclusive',
@@ -161,6 +128,7 @@ export async function probeContract({
         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.' }])),
       };
     }
 
@@ -171,6 +139,7 @@ export async function probeContract({
       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/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);
+}