@lyupro/codex-bridge 0.6.7 → 0.6.9

package/cli/lifecycle-transaction.mjs

@@ -0,0 +1,57 @@
+/**
+ * Runs one install, update or uninstall of a shared package home as a single transaction under
+ * the home's lifecycle lock (Plan_65 D8).
+ *
+ * Two installs into one home used to interleave their image copies and their record writes, and
+ * uninstall removed permission rules from settings.json before it had read anything — so a
+ * refused uninstall would already have changed the host. The lock is therefore taken before the
+ * first read, outside the settings backup scope (backup bookkeeping is not exclusion). `update`
+ * nests `install`, and a second acquire inside one process is refused by design (the lock's own
+ * self-check), so the outer transaction hands the nested call a ticket instead: live only while
+ * the transaction runs, and bound to its home.
+ *
+ * Only install may bring a home into existence: the lock needs the directory, and an update or an
+ * uninstall that created an empty home folder just to lock it would leave debris behind a removal.
+ * A home that does not exist has nothing shared to protect, so those run without the lock.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { acquireLifecycleLock } from './lifecycle-lock.mjs';
+
+const liveTickets = new WeakMap();
+
+/**
+ * Throws unless `ticket` belongs to a transaction still running on this host's home. The purge authorization
+ * (Plan_65 D14) binds itself to the ticket through this check, so the two can never disagree about "live".
+ */
+export function assertLiveTicket(ticket, host) {
+  if (!ticket || typeof ticket !== 'object' || !liveTickets.has(ticket)) {
+    throw new Error('lifecycle ticket is no longer active');
+  }
+  if (typeof host?.brandRoot !== 'string' || path.resolve(host.brandRoot) !== liveTickets.get(ticket)) {
+    throw new Error('lifecycle ticket belongs to a different home');
+  }
+}
+
+export async function withLifecycle(host, command, action, { ticket, waitMs, createHome = false } = {}) {
+  if (typeof action !== 'function') throw new TypeError('lifecycle action must be a function');
+
+  if (ticket !== undefined) {
+    assertLiveTicket(ticket, host);
+    return action(ticket);
+  }
+
+  if (!createHome && !fs.existsSync(host.brandRoot)) return action(undefined);
+
+  const lockOptions = { command, hostRoot: host.root };
+  if (waitMs !== undefined) lockOptions.waitMs = waitMs;
+  const lock = await acquireLifecycleLock(host.brandRoot, lockOptions);
+  const transactionTicket = Object.freeze({});
+  liveTickets.set(transactionTicket, path.resolve(host.brandRoot));
+  try {
+    return await action(transactionTicket);
+  } finally {
+    liveTickets.delete(transactionTicket);
+    await lock.release();
+  }
+}

package/cli/link-segments.mjs

@@ -0,0 +1,45 @@
+/**
+ * Says whether a delete target is reached only through real directories below a trusted root.
+ *
+ * Lexical containment alone is satisfiable: independent review replaced `<root>/<project>` with a
+ * junction to an outside directory, and a target that still spelled out as inside the root deleted
+ * what was outside it. Paths are deliberately never resolved (`realpath` returns `\\?\` and UNC
+ * forms on Windows and creates a new class of mismatch), so every segment is checked with lstat,
+ * top-down, right before deletion. Plan_65 D4 made this one module for prune and the coming purge
+ * after prune's own copy was found wrong twice: it walked from the leaf up, touching paths under a
+ * link before reaching the link, and it read every lstat error as a clear path. Only ENOENT means
+ * gone here; any other error is a finding, and the caller keeps the entry. The root itself is taken
+ * as written, because relocating the runs root or the home through a link is legitimate.
+ * Containment compares through normalizePath, which folds Windows case: a root spelled `C:\Users`
+ * against a target resolved as `c:\users` must not read as "outside".
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizePath } from '../src/home/hooks/live-runs.mjs';
+
+export function inspectSegments(target, root, { lstat = (file) => fs.lstatSync(file) } = {}) {
+  const normalizedRoot = normalizePath(root);
+  const normalizedTarget = normalizePath(target);
+  if (!normalizedRoot || !normalizedTarget) return { kind: 'outside' };
+
+  const rootPrefix = normalizedRoot.endsWith('/') ? normalizedRoot : `${normalizedRoot}/`;
+  if (normalizedTarget === normalizedRoot || !normalizedTarget.startsWith(rootPrefix)) {
+    return { kind: 'outside' };
+  }
+
+  const rootPath = path.resolve(root);
+  const relativeTarget = path.relative(rootPath, path.resolve(target));
+  let current = rootPath;
+  for (const segment of relativeTarget.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    let entry;
+    try {
+      entry = lstat(current);
+    } catch (error) {
+      if (error.code === 'ENOENT') return { kind: 'missing', at: current };
+      return { kind: 'error', at: current, code: error.code };
+    }
+    if (entry.isSymbolicLink()) return { kind: 'link', at: current };
+  }
+  return { kind: 'clear' };
+}

package/cli/model-set.mjs

@@ -5,6 +5,7 @@ import { ROLES, validateRunConfig } from '../src/home/lib/config-validate.mjs';
 import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
 import { editRunConfig } from '../src/home/lib/config-edit.mjs';
 import { fetchCatalogue, parseCatalogue } from './model-catalogue.mjs';
+import { withCommandHelp } from './command-help.mjs';
 
 const failure = (exitCode, message) => ({ exitCode, output: `codex-bridge model: ${message}` });
 const refusal = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -17,14 +18,14 @@ function parseChanges(args) {
     let value = argument;
     if (argument.startsWith('-')) {
       if (argument !== '--model' && argument !== '--effort') {
-        throw new Error(`unexpected argument "${argument}".`);
+        throw new Error(withCommandHelp('model set', `unexpected argument "${argument}".`));
       }
       field = argument.slice(2);
       value = args[++index];
       if (value === undefined || value.startsWith('-')) throw new Error(`missing value for ${argument}.`);
     } else {
       field = ['model', 'effort'].find((key) => changes[key] === undefined);
-      if (!field) throw new Error(`unexpected argument "${argument}".`);
+      if (!field) throw new Error(withCommandHelp('model set', `unexpected argument "${argument}".`));
     }
     if (changes[field] !== undefined) throw new Error(`${field} was supplied more than once.`);
     if (!value || /\s/.test(value)) {
@@ -65,7 +66,7 @@ export async function editModelProfile(action, argv, options) {
   }
   let changes;
   try {
-    if (action === 'unset' && args.length) throw new Error(`unexpected argument "${args[0]}".`);
+    if (action === 'unset' && args.length) throw new Error(withCommandHelp('model unset', `unexpected argument "${args[0]}".`));
     if (action === 'set') changes = parseChanges(args);
   } catch (error) {
     return failure(2, error.message);

package/cli/model-speed.mjs

@@ -5,12 +5,19 @@ import { ROLES, validateRunConfig } from '../src/home/lib/config-validate.mjs';
 import { editRunConfig } from '../src/home/lib/config-edit.mjs';
 import { fetchCatalogue, parseCatalogue } from './model-catalogue.mjs';
 import { describe, readProfiles } from './model-set.mjs';
+import { withCommandHelp } from './command-help.mjs';
 
 const failure = (exitCode, message) => ({ exitCode, output: `codex-bridge model: ${message}` });
 const refusal = (message) => Object.assign(new Error(message), { exitCode: 2 });
+const unexpected = (argument) => {
+  const result = failure(2, `unexpected argument "${argument}".`);
+  return { ...result, output: withCommandHelp('model speed', result.output) };
+};
 
 export async function editModelSpeed(argv, options) {
   const [role, speed, confirmation, ...extra] = argv;
+  const dashArgument = argv.find((arg) => typeof arg === 'string' && arg.startsWith('-'));
+  if (dashArgument !== undefined) return unexpected(dashArgument);
   if (!ROLES.includes(role)) {
     return failure(2, `${role ? `unknown role "${role}"` : 'role is required'}. Allowed roles: ${ROLES.join(', ')}.`);
   }
@@ -18,9 +25,9 @@ export async function editModelSpeed(argv, options) {
     return failure(2, 'speed requires a tier identifier: a non-empty single word with no whitespace, or unset.');
   }
   if (confirmation !== undefined && (speed === 'unset' || confirmation !== 'confirm')) {
-    return failure(2, `unexpected argument "${confirmation}".`);
+    return unexpected(confirmation);
   }
-  if (extra.length) return failure(2, `unexpected argument "${extra[0]}".`);
+  if (extra.length) return unexpected(extra[0]);
 
   try {
     const configPath = path.resolve(options.configPath ?? CONFIG_PATH);

package/cli/model.mjs

@@ -8,6 +8,7 @@ import { editModelProfile } from './model-set.mjs';
 import { editModelSpeed } from './model-speed.mjs';
 import { readCodexUserTier } from './codex-user-config.mjs';
 import { renderTable } from './table.mjs';
+import { withCommandHelp } from './command-help.mjs';
 
 const PROFILE_COLUMNS = ['role', 'model', 'effort', 'speed', 'source']
   .map((key) => ({ key, header: key, fixed: true }));
@@ -43,10 +44,10 @@ export async function model(argv = [], options = {}) {
   }
   if (action === 'speed') return editModelSpeed(optionArgs, options);
   if (action && action !== 'list') {
-    return { exitCode: 2, output: `codex-bridge model: unknown action "${action}". Use model, model list, model set, model unset or model speed.` };
+    return { exitCode: 2, output: withCommandHelp('model', `codex-bridge model: unknown action "${action}". Use model, model list, model set, model unset or model speed.`) };
   }
   if (optionArgs.length) {
-    return { exitCode: 2, output: `codex-bridge model: unexpected argument "${optionArgs[0]}".` };
+    return { exitCode: 2, output: withCommandHelp('model', `codex-bridge model: unexpected argument "${optionArgs[0]}".`) };
   }
 
   try {
@@ -75,7 +76,8 @@ export async function model(argv = [], options = {}) {
     return {
       exitCode: 0,
       output: `${renderTable(PROFILE_COLUMNS, rows, options.terminalWidth)}\n\nConfig file: ${configPath}\n`
-        + 'Machine-wide: shared by every project on this machine, not per-project.',
+        + 'Machine-wide: shared by every project on this machine, not per-project.\n'
+        + 'Set: codex-bridge model set <role> <model> [effort] · catalogue: codex-bridge model list',
     };
   } catch (error) {
     const subject = action === 'list' ? 'live catalogue unavailable; refusing to list models' : 'cannot read profile';

package/cli/owner-record.mjs

@@ -0,0 +1,40 @@
+/**
+ * Builds one owner's installation-record row from what is on disk after its files and hooks were written.
+ * Install and the owner sync (Plan_65 D7) both advance a row; two copies of this construction would let
+ * a synced owner carry fingerprints or `createdGroup` flags that its own install would never write.
+ */
+import { fileFingerprint } from './manifest.mjs';
+import { INSTALL_METHOD_COPY, INSTALL_METHOD_KEY } from './install-record.mjs';
+
+export async function ownerRecord({ plan, rule, targets, hookResults, prior, currentPackage }) {
+  const fingerprints = {};
+  for (const item of plan) {
+    fingerprints[item.root] ??= {};
+    fingerprints[item.root][item.relativeToRoot] = await fileFingerprint(item.target);
+  }
+  const hooks = targets.map(({ definition, relative, registration }, index) => {
+    const recorded = prior?.hooks?.find((hook) => hook.event === definition.event
+      && hook.root === 'brand' && hook.path === relative);
+    // A group we created stays ours after a later run merely joins it; losing the flag would make
+    // uninstall leave behind an empty group that only this package ever put there.
+    const createdGroup = hookResults[index].createdGroup || recorded?.createdGroup === true;
+    const command = registration.command;
+    return {
+      event: definition.event,
+      root: 'brand',
+      path: relative,
+      command,
+      form: command.startsWith('codex-bridge hook ') ? 'short' : 'path',
+      ...(createdGroup ? { createdGroup: true } : {}),
+    };
+  });
+  return {
+    ...currentPackage,
+    installedAt: new Date().toISOString(),
+    [INSTALL_METHOD_KEY]: INSTALL_METHOD_COPY,
+    files: plan.map((item) => ({ root: item.root, path: item.relativeToRoot })),
+    fingerprints,
+    rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
+    hooks,
+  };
+}

package/cli/owner-sync-apply.mjs

@@ -0,0 +1,108 @@
+/**
+ * Applies other owners' host updates under the initiator's lifecycle lock (Plan_65 D7, advice A6).
+ * Replacing the shared image must bring eligible owners' files and hooks along, without extending
+ * the initiator's force to their edits, permissions, seeds, or Codex rules registry. An owner row
+ * advances only after its whole host update verifies; failures must not stop the remaining owners.
+ * In-sync rows are stamped with the image fingerprint too (D11): clones of one version ship different
+ * images (A6), so only the stamp tells doctor which image a host was last verified against.
+ */
+import fs from 'node:fs/promises';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { buildInstallPlan, packageInfo, rulesPlan } from './manifest.mjs';
+import { copyPlannedFile, planHomeWriter } from './copy.mjs';
+import { readInstallRecordFile, writeInstallRecord } from './install-record.mjs';
+import { imageFingerprint, ownerView } from './install-owners.mjs';
+import { ownerRecord } from './owner-record.mjs';
+import { ownerHost, ownerSyncLines, planOwner, planOwnerSync } from './owner-sync.mjs';
+import { mergeHook } from './settings-merge.mjs';
+
+async function applyOwner(owner, initiator, { packageRoot, env }) {
+  const host = ownerHost(owner, initiator);
+  // D7: a root lost after planning must not be recreated by the copy or settings writers.
+  if (!(await fs.stat(host.root)).isDirectory()) throw new Error('owner root is not a directory');
+  const record = await readInstallRecordFile(host);
+  const prior = ownerView(record, host);
+  if (!prior) throw new Error('owner is not recorded');
+  const plan = await buildInstallPlan(host, packageRoot);
+  const { writer } = planHomeWriter(host.brandRoot, plan);
+  let files = 0;
+  for (const { item, state } of owner.files) {
+    if (state !== 'replace' && state !== 'create') continue;
+    await copyPlannedFile(item, host.brandRoot, { writer });
+    files += 1;
+  }
+  const hookResults = [];
+  let hooks = 0;
+  for (const { item, state } of owner.hooks) {
+    if (state === 'register') {
+      hookResults.push(await mergeHook(host.settingsPath, item.spec));
+      hooks += 1;
+    } else {
+      hookResults.push({ createdGroup: false });
+    }
+  }
+  const verified = await planOwner(record, record.owners[normalizeRepoPath(host.root)], initiator,
+    { packageRoot, env });
+  // A bare status word made the operator line read "Left <root> behind: conflict", naming no cause.
+  if (verified.status !== 'in-sync') throw new Error(`verification after the update found ${verified.status}`);
+  // D7: resolving an explicit root must not relabel a recorded user/project owner as host.
+  await writeInstallRecord({ ...host, scope: owner.scope }, await ownerRecord({
+    plan,
+    rule: rulesPlan(host, packageRoot),
+    targets: owner.hooks.map(({ item }) => item),
+    hookResults,
+    prior,
+    currentPackage: await packageInfo(packageRoot),
+  }), {});
+  return { root: owner.root, status: 'updated', files, hooks };
+}
+
+export async function applyOwnerSync(plan, initiator, { packageRoot, env } = {}) {
+  const record = await readInstallRecordFile(initiator);
+  const fingerprint = imageFingerprint(record.image);
+  const owners = [];
+  for (const owner of plan.owners) {
+    if (owner.status === 'in-sync'
+      // An image without fingerprints yields null; a row can then never carry a stamp to match.
+      && (record.owners[normalizeRepoPath(owner.root)]?.imageFingerprint ?? null) === fingerprint) {
+      owners.push({ root: owner.root, status: 'in-sync' });
+    } else if (owner.status !== 'eligible' && owner.status !== 'in-sync') {
+      owners.push(owner);
+    } else {
+      try {
+        const applied = await applyOwner(owner, initiator, { packageRoot, env });
+        owners.push(owner.status === 'in-sync' && applied.files === 0 && applied.hooks === 0
+          ? { root: owner.root, status: 'in-sync' } : applied);
+      } catch (error) {
+        owners.push({ root: owner.root, status: 'failed', reason: error.message });
+      }
+    }
+  }
+  return { owners, complete: owners.every(({ status }) => status === 'in-sync' || status === 'updated') };
+}
+
+/**
+ * One entrance for every command that replaced the image: install and update both call it, so neither
+ * can sync the other owners differently. A dry run only plans; it never counts as incomplete.
+ */
+export async function syncOtherOwners(initiator, { packageRoot, env, dryRun = false } = {}) {
+  const record = await readInstallRecordFile(initiator);
+  if (record?.format !== 2) return { complete: true, lines: [] };
+  const plan = await planOwnerSync(record, initiator, { packageRoot, env });
+  if (dryRun) return { complete: true, lines: ownerSyncLines(plan) };
+  // Plan_65 D7: the initiator's force never authorizes another owner's edits.
+  const result = await applyOwnerSync(plan, initiator, { packageRoot, env });
+  return { complete: result.complete, lines: ownerApplyLines(result) };
+}
+
+export function ownerApplyLines(result) {
+  return result.owners.flatMap((owner) => {
+    if (owner.status === 'updated') {
+      return [`Updated ${owner.files} file(s) and ${owner.hooks} hook(s) of ${owner.root}.`];
+    }
+    if (owner.status === 'failed') {
+      return [`Left ${owner.root} behind: ${owner.reason}; run codex-bridge update --host "${owner.root}".`];
+    }
+    return ownerSyncLines({ owners: [owner] });
+  });
+}

package/cli/owner-sync.mjs

@@ -0,0 +1,115 @@
+/**
+ * Plans other owners' host updates without writes or locks (Plan_65 D7, advice A6).
+ * Replacing the shared image leaves their agents, commands, and guards behind. Only an owner's
+ * recorded, unedited files may catch up; the initiator's force never authorizes another owner's
+ * conflicts, permissions, seeds, or unrelated settings. B13e2 applies and verifies this plan.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { resolveHost } from './hosts.mjs';
+import { buildInstallPlan, fileFingerprint } from './manifest.mjs';
+import { targetMatches } from './copy.mjs';
+import { fingerprintFor, recordFileKey } from './install-record.mjs';
+import { ownerView, validateFormat2 } from './install-owners.mjs';
+import { hookTargets } from './hook-targets.mjs';
+import { inspectHook } from './settings-merge.mjs';
+
+async function fileState(item, host, view) {
+  let target;
+  try {
+    target = await fs.lstat(item.target);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  // D7: lstat must precede content reads, including for dangling links and Windows junctions.
+  if (target?.isSymbolicLink()) return { item, state: 'conflict', reason: 'link' };
+  if (!target) {
+    const recorded = view.files.some((file) => recordFileKey(file) === recordFileKey(item));
+    return recorded
+      ? { item, state: 'conflict', reason: 'missing' }
+      : { item, state: 'create' };
+  }
+  if (target.isFile()) {
+    if (await targetMatches(item, host.brandRoot)) return { item, state: 'current' };
+    const recorded = fingerprintFor(view, item);
+    if (recorded !== undefined && await fileFingerprint(item.target) === recorded) {
+      return { item, state: 'replace' };
+    }
+  }
+  return { item, state: 'conflict', reason: 'changed' };
+}
+
+/** The owner's host seen from the initiator: same home and Codex home, the owner's own root and scope. */
+export function ownerHost(owner, initiator) {
+  return resolveHost({
+    host: owner.root,
+    scope: owner.scope,
+    brandRoot: initiator.brandRoot,
+    // A resolved host has no codexHome field; it keeps the Codex home only as `<home>/rules`.
+    codexHome: path.dirname(initiator.codexRulesDir),
+  });
+}
+
+export async function planOwner(record2, owner, initiator, { packageRoot, env }) {
+  const entry = { root: owner.root, scope: owner.scope, version: owner.version, files: [], hooks: [] };
+  const host = ownerHost(owner, initiator);
+  try {
+    if (!(await fs.stat(host.root)).isDirectory()) {
+      return { ...entry, status: 'unreachable', reason: 'ENOTDIR' };
+    }
+    await fs.readdir(host.root);
+  } catch (error) {
+    return { ...entry, status: 'unreachable', reason: error.code === 'ENOENT' ? 'absent' : error.code };
+  }
+
+  const view = ownerView(record2, host);
+  const items = (await buildInstallPlan(host, packageRoot)).filter((item) => item.root === 'claude');
+  try {
+    for (const item of items) entry.files.push(await fileState(item, host, view));
+  } catch (error) {
+    return { ...entry, status: 'unreachable', reason: error.code ?? error.message };
+  }
+  const targets = hookTargets(host, env);
+  try {
+    for (const item of targets) {
+      const inspected = await inspectHook(host.settingsPath, item.spec);
+      entry.hooks.push({ item, state: inspected.current ? 'current' : 'register' });
+    }
+  } catch (error) {
+    return { ...entry, status: 'unreachable', reason: `settings unreadable: ${error.message}` };
+  }
+  const conflict = entry.files.some(({ state }) => state === 'conflict');
+  const pending = entry.files.some(({ state }) => state === 'replace' || state === 'create')
+    || entry.hooks.some(({ state }) => state === 'register');
+  return { ...entry, status: conflict ? 'conflict' : pending ? 'eligible' : 'in-sync' };
+}
+
+export async function planOwnerSync(record2, initiator, { packageRoot, env } = {}) {
+  validateFormat2(record2);
+  const key = normalizeRepoPath(initiator.root);
+  const others = Object.values(record2.owners)
+    .filter((owner) => normalizeRepoPath(owner.root) !== key)
+    .sort((a, b) => a.root.localeCompare(b.root));
+  const owners = [];
+  for (const owner of others) owners.push(await planOwner(record2, owner, initiator, { packageRoot, env }));
+  return { owners };
+}
+
+export function ownerSyncLines(plan) {
+  const lines = [];
+  for (const owner of plan.owners) {
+    if (owner.status === 'eligible') {
+      const files = owner.files.filter(({ state }) => state === 'replace' || state === 'create').length;
+      const hooks = owner.hooks.filter(({ state }) => state === 'register').length;
+      lines.push(`Would update ${files} file(s) and ${hooks} hook(s) of ${owner.root}.`);
+    } else if (owner.status === 'conflict') {
+      const conflicts = owner.files.filter(({ state }) => state === 'conflict')
+        .map(({ item, reason }) => `${item.relativeToRoot} (${reason})`).join(', ');
+      lines.push(`Left ${owner.root} behind: ${conflicts}; run codex-bridge update --host "${owner.root}" after resolving it.`);
+    } else if (owner.status === 'unreachable') {
+      lines.push(`Left ${owner.root} behind: ${owner.reason}; run codex-bridge update --host "${owner.root}" when it is available.`);
+    }
+  }
+  return lines;
+}

package/cli/probe-contract.mjs

@@ -7,13 +7,14 @@ 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';
 
@@ -60,17 +61,18 @@ export function judgeProbe({ markerExists, hookFired, hostResult }) {
 
 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.' }])),
     };
@@ -83,7 +85,7 @@ export async function probeContract({
     const rig = await buildRig(dir, token);
     let hostResult;
     try {
-      hostResult = runHost('claude', [
+      hostResult = runHost(target.executable, [
         '--setting-sources', 'project',
         '--allowedTools', 'Bash,Agent',
         '-p', rig.prompt,
@@ -106,6 +108,20 @@ export async function probeContract({
     } 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),
@@ -118,25 +134,25 @@ export async function probeContract({
       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 && !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,

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/projects.mjs

@@ -1,4 +1,5 @@
 /** Implements the projects command. */
+import { withCommandHelp } from './command-help.mjs';
 import { listProjectRuns, listProjects } from './runs-inventory.mjs';
 import { renderTable } from './table.mjs';
 import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
@@ -69,11 +70,13 @@ function parseArgs(args) {
       json = true;
       continue;
     }
-    if (arg.startsWith('-')) return { error: `codex-bridge projects: unknown option "${arg}"` };
+    if (arg.startsWith('-')) {
+      return { error: withCommandHelp('projects', `codex-bridge projects: unknown option "${arg}"`) };
+    }
     positional.push(arg);
   }
   if (positional.length > 1) {
-    return { error: 'codex-bridge projects accepts at most one project name.' };
+    return { error: withCommandHelp('projects', 'codex-bridge projects accepts at most one project name.') };
   }
   return { json, projectName: positional[0] || null };
 }