@lyupro/codex-bridge 0.6.7 → 0.6.9

package/cli/command-registry.mjs

@@ -0,0 +1,284 @@
+/**
+ * Lists commands and how each is invoked (Plan_71 D1, advice A1: registry-dispatch).
+ * model -h refused help and global help omitted its actions (2026-09-29) because
+ * dispatch and usage had separate sources. One registry keeps invocation and help together.
+ */
+import { diagnose, renderDoctor } from './doctor.mjs';
+import { probeContract } from './probe-contract.mjs';
+import { resolveProbeTarget } from './probe-target.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { hook } from './hook.mjs';
+import { resolveHost } from './hosts.mjs';
+import { install } from './install.mjs';
+import { model } from './model.mjs';
+import { projects } from './projects.mjs';
+import { read } from './read.mjs';
+import { runCodex } from './run-launcher.mjs';
+import { permissions } from './permissions.mjs';
+import { prune } from './prune.mjs';
+import { stop } from './stop.mjs';
+import { unlock } from './unlock.mjs';
+import { uninstall } from './uninstall.mjs';
+import { purge } from './uninstall-purge.mjs';
+import { update } from './update.mjs';
+
+export function commandOptions(command, argv) {
+  const options = {};
+  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
+    : command === 'uninstall' ? new Set(['--dry-run', '--purge'])
+      : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
+  const flagNames = new Map([
+    ['--dry-run', 'dryRun'],
+    ['--purge', 'purge'],
+    ['--force', 'force'],
+    ['--probe-contract', 'probeContract'],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (booleanFlags.has(arg)) {
+      options[flagNames.get(arg)] = true;
+      continue;
+    }
+    if (arg !== '--scope' && arg !== '--host' && !(command === 'doctor' && arg === '--probe-executable')) throw new Error(`unknown ${command} option "${arg}"`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+    options[arg === '--scope' ? 'scope' : arg === '--host' ? 'host' : 'probeExecutable'] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export const COMMANDS = [
+  {
+    name: 'install',
+    summary: 'Install codex-bridge into the selected Claude Code host',
+    usage: ['codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('install', argv);
+      const host = resolveHost(options);
+      const result = await install({ host, dryRun: options.dryRun, force: options.force });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'update',
+    summary: 'Update a recorded codex-bridge installation',
+    usage: ['codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('update', argv);
+      const host = resolveHost(options);
+      const result = await update({ host, dryRun: options.dryRun, force: options.force });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'permissions',
+    summary: 'Show, add, or remove optional shell permission rules',
+    usage: ['codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]'],
+    section: 'public',
+    actions: {
+      add: {
+        summary: 'Add optional shell permission rules',
+        usage: ['codex-bridge permissions add [--scope user|project] [--host <path>]'],
+      },
+      remove: {
+        summary: 'Remove optional shell permission rules',
+        usage: ['codex-bridge permissions remove [--scope user|project] [--host <path>]'],
+      },
+    },
+    async handler(argv, io) {
+      let action;
+      let optionArgs = argv;
+      if (argv[0] && !argv[0].startsWith('-')) {
+        action = argv[0];
+        optionArgs = argv.slice(1);
+      }
+      if (action && !['add', 'remove'].includes(action)) {
+        throw new Error(`unknown permissions action "${action}"`);
+      }
+      const options = commandOptions('permissions', optionArgs);
+      const host = resolveHost(options);
+      const result = await permissions({ host, action });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'uninstall',
+    summary: 'Remove installed files while preserving run artifacts',
+    usage: ['codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run] [--purge]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('uninstall', argv);
+      const host = resolveHost(options);
+      const result = options.purge
+        ? await purge({ host, dryRun: options.dryRun })
+        : await uninstall({ host, dryRun: options.dryRun });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'doctor',
+    summary: 'Diagnose the selected Claude Code host (--probe-contract measures on a live host)',
+    usage: ['codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract] [--probe-executable <path>]'],
+    section: 'public',
+    async handler(argv, io) {
+      const options = commandOptions('doctor', argv);
+      if (options.probeExecutable && !options.probeContract) throw new Error('--probe-executable requires --probe-contract');
+      const host = resolveHost(options);
+      // The probe runs BEFORE the diagnosis so the `hostContract` line below carries the verdict just
+      // measured. Printing the diagnosis first and the measurement after would answer one question
+      // twice in one output, with the older answer on top (Plan_52 D25).
+      let probe = null;
+      if (options.probeContract) {
+        const target = resolveProbeTarget({ stateDir: brandStateDir(host.brandRoot), executable: options.probeExecutable });
+        if (!target.error) io.log(`probe: target ${target.version} at ${target.executable} (${target.source})`);
+        probe = await probeContract({ host, target });
+        io.log(`probe: ${probe.message}`);
+        for (const [name, verdict] of Object.entries(probe.dispatcher ?? {})) {
+          io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);
+        }
+      }
+      const result = await diagnose({ host });
+      io.log(renderDoctor(result));
+      // An inconclusive probe wrote nothing and measured nothing; exiting 0 would let a failed
+      // measurement pass silently in a script (Plan_52 D26).
+      return probe && probe.state === 'inconclusive' ? 2 : result.exitCode;
+    },
+  },
+  {
+    name: 'run',
+    summary: 'Start or attach to a delegated Codex run',
+    usage: ['codex-bridge run <runner options> --task-file <path>'],
+    section: 'public',
+    async handler(argv, io) {
+      return runCodex(argv);
+    },
+  },
+  {
+    name: 'model',
+    summary: 'Show, set or list the models delegated roles run on',
+    usage: ['codex-bridge model'],
+    section: 'public',
+    actions: {
+      list: {
+        summary: 'List the live model catalogue',
+        usage: ['codex-bridge model list'],
+      },
+      set: {
+        summary: 'Set the model and optional effort for a role',
+        usage: [
+          'codex-bridge model set <role> <model> [effort]',
+          'codex-bridge model set <role> --model <model> [--effort <effort>]',
+        ],
+      },
+      unset: {
+        summary: 'Unset the model override for a role',
+        usage: ['codex-bridge model unset <role>'],
+      },
+      speed: {
+        summary: 'Preview, pin (confirm) or unpin the accelerated speed tier of a role',
+        usage: [
+          'codex-bridge model speed <role> <tier>',
+          'codex-bridge model speed <role> <tier> confirm',
+          'codex-bridge model speed <role> unset',
+        ],
+      },
+    },
+    async handler(argv, io) {
+      const result = await model(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'projects',
+    summary: 'List projects or runs from the run store',
+    usage: ['codex-bridge projects [<name>] [--json]'],
+    section: 'public',
+    async handler(argv, io) {
+      const result = projects(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'prune',
+    summary: 'Remove archived transport, or purge selected run folders',
+    usage: [
+      'codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]',
+      'codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]',
+    ],
+    section: 'public',
+    async handler(argv, io) {
+      const result = await prune(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'unlock',
+    summary: 'Close running records whose runner is gone, or show the lifecycle lock',
+    usage: ['codex-bridge unlock [<project>|--all]', 'codex-bridge unlock --lifecycle [--clear]'],
+    section: 'public',
+    async handler(argv, io) {
+      const result = await unlock(argv);
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'read',
+    summary: "Render a run's structured event stream",
+    usage: ['codex-bridge read <run>'],
+    section: 'public',
+    async handler(argv, io) {
+      if (argv.length !== 1) {
+        io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
+        return 2;
+      }
+      const result = read({ run: argv[0] });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'stop',
+    summary: 'Stop a running Codex run and record FAIL',
+    usage: ['codex-bridge stop <run>'],
+    section: 'public',
+    async handler(argv, io) {
+      if (argv.length !== 1) {
+        io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
+        return 2;
+      }
+      const result = await stop({ run: argv[0] });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'hook',
+    summary: 'Dispatch a registered guard with stdin unchanged',
+    usage: ['codex-bridge hook <name>'],
+    section: 'machine',
+    async handler(argv, io) {
+      return hook(argv, io);
+    },
+  },
+  {
+    name: 'sweep',
+    summary: 'Renamed to codex-bridge unlock',
+    usage: [],
+    section: 'renamed',
+    async handler(argv, io) {
+      io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+      return 2;
+    },
+  },
+];

package/cli/copy.mjs

@@ -2,6 +2,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { classifyHomePath } from '../src/home/lib/home-registry.mjs';
+import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { replacePlaceholders } from './manifest.mjs';
 
 export async function plannedContent(item, installationRoot) {
@@ -25,15 +27,50 @@ export async function targetMatches(item, installationRoot) {
   }
 }
 
-export async function copyPlannedFile(item, installationRoot) {
+/**
+ * Plan_65 D3: the install image is one registry entry whose exact members come from the plan, and
+ * seeds keep their own ids. One place decides which id a planned item writes under, so the
+ * installer and every fixture that copies a plan cannot disagree about it.
+ */
+export function planHomeWriter(brandRoot, plan) {
+  const imageMembers = plan.filter((item) => item.root === 'brand').map((item) => item.relativeToRoot);
+  const writer = createHomeWriter({ root: brandRoot, imageMembers });
+  const idFor = (item) => {
+    if (item.root !== 'brand') return undefined;
+    const id = classifyHomePath(item.relativeToRoot, { imageMembers })?.id;
+    if (!id) throw new Error(`brand install plan item is not a registered home artifact: ${item.relativeToRoot}`);
+    return id;
+  };
+  return { writer, idFor };
+}
+
+export async function copyPlannedFile(item, installationRoot, options = {}) {
+  const { writer, id } = options ?? {};
+  if (!writer) throw new Error('copyPlannedFile requires a home writer');
+  if (id !== undefined) await writer.assertArtifact(id, item.target);
+  else await writer.assertOutside(item.target);
+
   const content = await plannedContent(item, installationRoot);
-  await fs.mkdir(path.dirname(item.target), { recursive: true });
+  const operations = id === undefined
+    ? {
+      mkdir: (...args) => fs.mkdir(...args),
+      writeFile: (...args) => fs.writeFile(...args),
+      rename: (...args) => fs.rename(...args),
+      cleanup: (temporary) => fs.rm(temporary, { force: true }),
+    }
+    : {
+      mkdir: (...args) => writer.mkdir(id, ...args),
+      writeFile: (...args) => writer.writeFile(id, ...args),
+      rename: (...args) => writer.rename(id, ...args),
+      cleanup: (temporary) => writer.unlink(id, temporary),
+    };
+  await operations.mkdir(path.dirname(item.target), { recursive: true });
   const temporary = path.join(path.dirname(item.target), `.${path.basename(item.target)}.${randomUUID()}.tmp`);
   try {
-    await fs.writeFile(temporary, content, { flag: 'wx' });
-    await fs.rename(temporary, item.target);
+    await operations.writeFile(temporary, content, { flag: 'wx' });
+    await operations.rename(temporary, item.target);
   } catch (err) {
-    await fs.rm(temporary, { force: true }).catch(() => {});
+    await Promise.resolve().then(() => operations.cleanup(temporary)).catch(() => {});
     throw err;
   }
 }

package/cli/dispatcher-contract-record.mjs

@@ -1,11 +1,13 @@
 /**
- * Keeps the latest conclusive verdict per dispatcher host contract, each bound to the host version it was
- * measured on. Its own file rather than a field of .host-contract.json (Plan_62 D14, D19): the refusal
- * record is replaced whole by its writer, and an inconclusive probe must never erase an earlier verdict.
+ * Keeps the latest conclusive verdict per dispatcher host contract, per host version: on 2026-09-25 the
+ * VS Code host 2.1.282 ran beside the CLI host 2.1.281, and probing either must keep the other's verdict.
+ * Its own file rather than a field of .host-contract.json (Plan_62 D14, D19), and an inconclusive probe
+ * must never erase an earlier verdict.
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeJsonAtomic } from '../src/home/lib/atomic-json.mjs';
+import { writeHomeJsonAtomic } from '../src/home/lib/atomic-json.mjs';
+import { stateDirWriter } from '../src/home/lib/home-write.mjs';
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { DISPATCHER_CONTRACTS } from './dispatcher-contract.mjs';
 
@@ -19,9 +21,17 @@ export function readDispatcherContract({ stateDir }) {
   }
   try {
     const record = parseJsonText(file, source);
-    if (!record || typeof record !== 'object' || Array.isArray(record)
-      || !record.contracts || typeof record.contracts !== 'object' || Array.isArray(record.contracts)) return { corrupt: true };
-    return record;
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return { corrupt: true };
+    if (record.hosts && typeof record.hosts === 'object' && !Array.isArray(record.hosts)) return record;
+    if (!record.contracts || typeof record.contracts !== 'object' || Array.isArray(record.contracts)) return { corrupt: true };
+    const hosts = {};
+    for (const [name, item] of Object.entries(record.contracts)) {
+      if (!item || typeof item.version !== 'string' || !item.version) continue;
+      hosts[item.version] ??= { contracts: {} };
+      const { version: _version, ...entry } = item;
+      hosts[item.version].contracts[name] = entry;
+    }
+    return { hosts };
   } catch { return { corrupt: true }; }
 }
 
@@ -29,14 +39,14 @@ export function writeDispatcherContract({ stateDir, version, verdicts, now = new
   const file = path.join(stateDir, DISPATCHER_CONTRACT_FILE);
   const previous = readDispatcherContract({ stateDir });
   if (previous?.corrupt) throw new Error(`Cannot update corrupt dispatcher contract: ${file}`);
-  const contracts = { ...(previous?.contracts ?? {}) };
+  const contracts = { ...(previous?.hosts?.[version]?.contracts ?? {}) };
   for (const name of DISPATCHER_CONTRACTS) {
     const result = verdicts?.[name]?.result;
     if (result === 'honored' || result === 'changed') {
-      contracts[name] = { result, version, checkedAt: new Date(now).toISOString(), detail: verdicts[name].detail };
+      contracts[name] = { result, checkedAt: new Date(now).toISOString(), detail: verdicts[name].detail };
     }
   }
-  const record = { contracts };
-  writeJsonAtomic(file, record);
+  const record = { hosts: { ...(previous?.hosts ?? {}), [version]: { contracts } } };
+  writeHomeJsonAtomic(stateDirWriter(stateDir), 'dispatcher-contract', file, record);
   return record;
 }

package/cli/dispatcher-contract.mjs

@@ -1,4 +1,4 @@
-/** Judges dispatcher host behaviour so a silent regression cannot leave the Plan_62 D19 gate trusted. */
+/** Judges dispatcher host behaviour per version: the 2026-09-25 incident ran VS Code 2.1.282 beside CLI 2.1.281. */
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { PROBE_COMMAND } from './host-contract.mjs';
 
@@ -68,15 +68,16 @@ export function judgeDispatcherContracts({ entries, hostHealthy, okCommand, fail
 
 export function dispatcherContractStatus({ record, version }) {
   return DISPATCHER_CONTRACTS.map((contract) => {
-    const item = record?.contracts?.[contract];
+    const item = record?.hosts?.[version]?.contracts?.[contract];
     let state;
     let message;
     if (version == null) {
       state = 'unknown-host'; message = 'Host version is unknown; dispatcher contracts cannot be judged.';
     } else if (!item) {
-      state = 'unverified'; message = `Dispatcher contract ${contract} has never been probed on host ${version}; run ${PROBE_COMMAND}.`;
-    } else if (item.version !== version) {
-      state = 'stale'; message = `Dispatcher contract ${contract} was recorded for host ${item.version}; run ${PROBE_COMMAND}.`;
+      const other = Object.entries(record?.hosts ?? {}).filter(([, host]) => host?.contracts?.[contract])
+        .sort((a, b) => Date.parse(b[1].contracts[contract].checkedAt) - Date.parse(a[1].contracts[contract].checkedAt))[0];
+      if (other) { state = 'stale'; message = `Dispatcher contract ${contract} was recorded for host ${other[0]}; run ${PROBE_COMMAND}.`; }
+      else { state = 'unverified'; message = `Dispatcher contract ${contract} has never been probed on host ${version}; run ${PROBE_COMMAND}.`; }
     } else if (item.result === 'honored') {
       state = 'verified'; message = `Dispatcher contract ${contract} is verified on host ${version}.`;
     } else if (item.result === 'changed') {

package/cli/doctor-host-side.mjs

@@ -0,0 +1,110 @@
+/**
+ * Reports host marks separately from home ownership (Plan_65 D10 item 6): WHAT lies in a host
+ * comes from its marks, while WHO uses the home comes only from its owner rows. A single
+ * "installation: not installed" line hid a host that plainly carried our agents and hooks, and it
+ * never said which hosts the home record names or whether its inventory is complete.
+ * Owners in sync keeps lagging hosts visible because install/update named them only once (Plan_65 D11 item 3).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { check } from './doctor-format.mjs';
+import { hasPackageMarks } from './host-inspection.mjs';
+import { imageFingerprint, isFormat2 } from './install-owners.mjs';
+
+// Format 1 is not migrated here: asFormat2 would record this host as the owner, and doctor only reads.
+export function ownerEntry(rawRecord, host) {
+  if (rawRecord === null || !isFormat2(rawRecord)) return null;
+  return rawRecord.owners[normalizeRepoPath(host.root)] ?? null;
+}
+
+export function hostSideCheck(host, inspection) {
+  if (inspection.settingsError) {
+    return check('host files', 'fail', `settings could not be read: ${inspection.settingsError}`);
+  }
+  if (!hasPackageMarks(inspection)) {
+    return check('host files', 'warn', `no codex-bridge files or hooks in ${host.root}`);
+  }
+
+  const kept = inspection.files.filter((file) => file.disposition === 'keep'
+    && ['changed', 'unknown'].includes(file.reason));
+  const counts = `${inspection.files.length} package file(s) and ${inspection.hooks.length} own hook(s) in ${host.root}`;
+  const keptText = kept.map((file) => `${file.relativeToHost} (${file.reason})`).join(', ');
+  return kept.length
+    ? check('host files', 'warn', `${counts}; kept by uninstall: ${keptText}`)
+    : check('host files', 'ok', counts);
+}
+
+async function homeImageExists(host) {
+  try {
+    await fs.access(path.join(host.brandRoot, 'lib'));
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function homeOwnersCheck(host, rawRecord, inspection) {
+  if (rawRecord === null) {
+    return await homeImageExists(host)
+      ? check('home owners', 'warn', `no installation record in ${host.brandRoot}; the image has no record`)
+      : check('home owners', 'ok', `no installation record in ${host.brandRoot}`);
+  }
+  if (!isFormat2(rawRecord)) {
+    return check(
+      'home owners',
+      'warn',
+      'old record format; the hosts using this home are unknown until the next install or update',
+    );
+  }
+
+  const roots = Object.values(rawRecord.owners).map((owner) => owner.root);
+  const inventoryComplete = rawRecord.inventory === 'complete' && rawRecord.legacy === undefined;
+  const hostRecorded = Object.hasOwn(rawRecord.owners, normalizeRepoPath(host.root));
+  const unrecordedMarks = hasPackageMarks(inspection) && !hostRecorded;
+  const parts = [
+    `recorded: ${roots.length ? roots.join(', ') : 'none'}`,
+    inventoryComplete ? 'inventory complete' : 'inventory incomplete: an old record did not name every host',
+    ...(unrecordedMarks
+      ? [`${host.root} has package files or hooks but is not recorded: run codex-bridge install --host "${host.root}"`]
+      : []),
+  ];
+  return check('home owners', inventoryComplete && !unrecordedMarks ? 'ok' : 'warn', parts.join('; '));
+}
+
+export function ownersInSyncCheck(rawRecord) {
+  if (rawRecord === null || !isFormat2(rawRecord)) {
+    return check('owners in sync', 'ok', 'no format-2 record; nothing to compare');
+  }
+
+  const owners = Object.values(rawRecord.owners);
+  const inventoryComplete = rawRecord.inventory === 'complete' && rawRecord.legacy === undefined;
+  if (!owners.length) {
+    return check('owners in sync', 'warn',
+      `no recorded owners${inventoryComplete ? '' : '; inventory incomplete'}`);
+  }
+
+  const fingerprint = imageFingerprint(rawRecord.image);
+  const parts = [];
+  const unstamped = [];
+  for (const owner of owners) {
+    if (owner.imageFingerprint != null) {
+      if (owner.imageFingerprint === fingerprint) continue;
+    } else if (owner.version === rawRecord.image.version) {
+      unstamped.push(owner.root);
+      continue;
+    }
+    // The same version on both sides is the clone case the stamp exists for; say so instead of "0.6.9, image 0.6.9".
+    const why = owner.version === rawRecord.image.version
+      ? `verified against an earlier image of ${owner.version}`
+      : `recorded ${owner.version}, image ${rawRecord.image.version}`;
+    parts.push(`${owner.root} (${why}): run codex-bridge update --host "${owner.root}"`);
+  }
+  if (unstamped.length) parts.push(`not yet verified by image fingerprint: ${unstamped.join(', ')}`);
+  if (!inventoryComplete) parts.push('inventory incomplete');
+  const warning = parts.length > 0;
+  if (!warning) parts.push(`all ${owners.length} owner(s) verified against the current image`);
+  return check('owners in sync', warning ? 'warn' : 'ok',
+    `${parts.join('; ')} (recorded verification; host files and reachability not inspected)`);
+}