@lyupro/codex-bridge 0.4.0 → 0.5.1

package/cli/manifest.mjs

@@ -1,38 +1,52 @@
-/** Defines install mappings and validates the persisted installation record. */
+/** Defines the package install mappings and renders files before they are copied. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-// The hook table lives under src/ because the installed gate reads it too: cli/ is not copied
-// into a host, so a definition kept here would be invisible to the very hook it describes.
 import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
 import {
   renderRequiredInputSummary,
   renderRequiredInputs,
 } from '../src/required-inputs.mjs';
 import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
+import { renderStopSummary } from '../src/stop-contract.mjs';
 import { readJsonFile } from '../src/json-file.mjs';
-
-export { HOOK_DEFINITIONS };
-
-/**
- * Finds the definition a recorded hook belongs to. The event alone does not identify one: three of
- * the four hooks are PreToolUse, so `find(d => d.event === hook.event)` returns the order gate for
- * all three. `doctor` was fixed for exactly this and kept its own inline matching; `uninstall` was
- * not, and its dry-run announced matcher `Agent|Task` for the worktree lock and the prune guard —
- * the operator's only view of what a removal is about to touch. One function, so a third caller
- * cannot repeat it.
- */
-export function definitionForRecordedHook(hook) {
-  return HOOK_DEFINITIONS.find((definition) => definition.event === hook?.event
-    && path.basename(String(hook?.path ?? '')) === definition.file);
-}
+import {
+  INSTALL_RECORD_NAME,
+  RULES_NAME,
+  definitionForRecordedHook,
+  fileEntry,
+  installRecordPath,
+  legacyInstallRecordPath,
+  normalizeInstallRecord,
+  readInstallRecord,
+  recordFileKey,
+  recordMatchesPackage,
+  recordTarget,
+  validateInstallRecord,
+  writeInstallRecord,
+} from './install-record.mjs';
+
+export {
+  HOOK_DEFINITIONS,
+  INSTALL_RECORD_NAME,
+  RULES_NAME,
+  definitionForRecordedHook,
+  installRecordPath,
+  legacyInstallRecordPath,
+  normalizeInstallRecord,
+  readInstallRecord,
+  recordFileKey,
+  recordMatchesPackage,
+  recordTarget,
+  validateInstallRecord,
+  writeInstallRecord,
+};
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(HERE, '..');
-export const INSTALL_RECORD_NAME = '.codex-bridge-install.json';
-export const RULES_NAME = 'codex-bridge.rules';
 const RULES_SOURCE = `src/rules/${RULES_NAME}`;
+
 /**
  * Files the operator owns once they exist. Seeded on first install so the defaults are
  * visible and editable, then never written, never compared, never removed: run-config.json
@@ -41,25 +55,29 @@ const RULES_SOURCE = `src/rules/${RULES_NAME}`;
  * update — the same way overwriting a .env would.
  */
 export const SEEDED_SOURCES = Object.freeze(['src/run-config.json', 'src/conventions.md']);
-const seededTargets = (host) =>
-  new Set(SEEDED_SOURCES.map((source) => posix(
-    path.relative(host.root, path.join(host.agentsDir, path.relative('src', source))),
-  )));
+
 export const INSTALL_TABLE = Object.freeze([
-  { source: 'src/agents/*.md', target: 'agentsDir', processing: 'placeholders' },
-  { source: 'src/commands/*.md', target: 'commandsDir', processing: 'placeholders' },
-  { source: 'src/**', target: 'agentsDir', processing: 'copy' },
+  { source: 'src/agents/*.md', root: 'claude', target: 'agentsDir', processing: 'placeholders' },
+  { source: 'src/commands/*.md', root: 'claude', target: 'commandsDir', processing: 'placeholders' },
+  { source: 'src/hooks/**', root: 'brand', target: 'brandHooksDir', processing: 'copy' },
+  { source: 'src/**', root: 'brand', target: 'brandRunnerDir', processing: 'copy' },
+  // The runner reads its own version out of the package.json beside it, so meta.json can say
+  // which code wrote a run (Plan_34). In the clone that file sits one level above src/; without
+  // this line the installed layout has nothing one level above lib/, and every run on a real host
+  // would die on import while the whole suite stayed green against the clone.
+  { source: 'package.json', root: 'brand', target: 'brandRoot', processing: 'copy' },
 ]);
 
 const posix = (value) => value.split(path.sep).join('/');
 
-export function replacePlaceholders(content, agentsDir) {
+export function replacePlaceholders(content, installationRoot) {
   const agentType = content.match(/^name:\s*([^\r\n]+)$/m)?.[1].trim();
   return content
-    .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)))
+    .replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(installationRoot)))
     .replaceAll('{{CODEX_REQUIRED_INPUTS_SUMMARY}}', renderRequiredInputSummary(agentType))
     .replaceAll('{{CODEX_REQUIRED_INPUTS}}', renderRequiredInputs(agentType))
-    .replaceAll('{{CODEX_NO_SELF_EXECUTION}}', renderNoSelfExecution());
+    .replaceAll('{{CODEX_NO_SELF_EXECUTION}}', renderNoSelfExecution())
+    .replaceAll('{{CODEX_STOP_SUMMARY}}', renderStopSummary());
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {
@@ -67,21 +85,24 @@ export async function packageInfo(packageRoot = PACKAGE_ROOT) {
   return { name: parsed.name, version: parsed.version };
 }
 
-export function installRecordPath(host) {
-  return path.join(host.agentsDir, INSTALL_RECORD_NAME);
-}
-
 export function installedHookPath(host, definition) {
-  return path.join(host.agentsDir, 'hooks', definition.file);
+  return path.join(host.brandHooksDir, definition.file);
 }
 
 /** Where each seeded file comes from and where it goes; contents are copied verbatim. */
 export function seedPlan(host, packageRoot = PACKAGE_ROOT) {
-  return SEEDED_SOURCES.map((source) => ({
-    source: path.join(packageRoot, source),
-    target: path.join(host.agentsDir, path.relative('src', source)),
-    processing: 'copy',
-  }));
+  return SEEDED_SOURCES.map((source) => {
+    const target = source.endsWith('run-config.json')
+      ? host.brandConfigPath
+      : host.brandConventionsPath;
+    return {
+      source: path.join(packageRoot, source),
+      target,
+      root: 'brand',
+      relativeToRoot: posix(path.relative(host.brandRoot, target)),
+      processing: 'copy',
+    };
+  });
 }
 
 export function rulesPlan(host, packageRoot = PACKAGE_ROOT) {
@@ -101,137 +122,24 @@ export async function fileFingerprint(absolutePath) {
   }
 }
 
-/**
- * Whether the recorded installation is exactly what this package would install right now. Install
- * and update both decide "nothing to do" by this question, so it is answered in one place: two
- * copies of the condition would drift the first time a field is added to the record.
- */
-export function recordMatchesPackage(record, plan, currentPackage, fingerprints, ruleState) {
-  return Boolean(record)
-    && record.name === currentPackage.name
-    && record.version === currentPackage.version
-    && record.files.length === plan.length
-    && record.files.every((file, index) => file === plan[index].relativeToHost)
-    && Boolean(record.fingerprints)
-    && plan.every((item) => record.fingerprints[item.relativeToHost] === fingerprints.get(item.relativeToHost))
-    && (!ruleState || (record.rules?.path === ruleState.path
-      && record.rules.fingerprint === ruleState.fingerprint));
-}
-
-export function validateInstallRecord(record) {
-  if (!record || typeof record !== 'object' || Array.isArray(record)) {
-    throw new Error('installation record must be an object');
-  }
-  const strings = ['name', 'version', 'installedAt', 'mode'];
-  for (const key of strings) {
-    if (typeof record[key] !== 'string' || !record[key]) throw new Error(`installation record has invalid ${key}`);
-  }
-  if (record.mode !== 'copy') throw new Error('installation record mode must be copy');
-  if (Number.isNaN(Date.parse(record.installedAt))) throw new Error('installation record installedAt is invalid');
-  if (!Array.isArray(record.files) || !record.files.length || record.files.some((file) => typeof file !== 'string' || !file)) {
-    throw new Error('installation record files must be a non-empty list of strings');
-  }
-  if (record.files.some((file) => path.isAbsolute(file) || file.split(/[\\/]/).some((part) => part === '..' || part === '.'))) {
-    throw new Error('installation record files must stay relative to the host root');
-  }
-  if (new Set(record.files).size !== record.files.length) {
-    throw new Error('installation record files must not contain duplicates');
-  }
-  // Run artifacts are the user's data, not ours. Refusing them here means neither uninstall nor
-  // update needs its own guard against deleting a run folder someone listed as an installed file.
-  if (record.files.some((file) => file === 'codex-runs' || file.split(/[\\/]/)[0] === 'codex-runs')) {
-    throw new Error('installation record files must not name run artifacts under codex-runs');
-  }
-  if (record.fingerprints !== undefined) {
-    if (!record.fingerprints || typeof record.fingerprints !== 'object' || Array.isArray(record.fingerprints)) {
-      throw new Error('installation record fingerprints must be an object');
-    }
-    const fingerprintKeys = Object.keys(record.fingerprints);
-    if (fingerprintKeys.length !== record.files.length || fingerprintKeys.some((file) => !record.files.includes(file))) {
-      throw new Error('installation record fingerprints keys must exactly match files');
-    }
-    if (Object.values(record.fingerprints).some((fingerprint) =>
-      typeof fingerprint !== 'string' || !/^[a-f0-9]{64}$/i.test(fingerprint))) {
-      throw new Error('installation record fingerprints must be 64-character hexadecimal SHA256 strings');
-    }
-  }
-  if (record.rules !== undefined) {
-    if (!record.rules || typeof record.rules !== 'object' || Array.isArray(record.rules)) {
-      throw new Error('installation record rules must be an object');
-    }
-    if (typeof record.rules.path !== 'string' || !record.rules.path) {
-      throw new Error('installation record rules path must be a non-empty string');
-    }
-    if (path.basename(record.rules.path) !== RULES_NAME) {
-      throw new Error(`installation record rules path must name ${RULES_NAME}`);
-    }
-    if (typeof record.rules.fingerprint !== 'string'
-      || !/^[a-f0-9]{64}$/i.test(record.rules.fingerprint)) {
-      throw new Error('installation record rules fingerprint must be a 64-character hexadecimal SHA256 string');
-    }
-  }
-  if (record.hooks !== undefined && record.hook !== undefined) {
-    throw new Error('installation record must use hooks instead of hook');
-  }
-  const hooks = record.hooks !== undefined ? record.hooks : record.hook !== undefined ? [record.hook] : null;
-  if (!Array.isArray(hooks) || !hooks.length) {
-    throw new Error('installation record hooks must be a non-empty list');
-  }
-  for (const hook of hooks) {
-    if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
-      throw new Error('installation record hook must be an object');
-    }
-    const definitions = HOOK_DEFINITIONS.filter((entry) => entry.event === hook.event);
-    if (!definitions.length || typeof hook.path !== 'string' || !hook.path) {
-      throw new Error('installation record hook must identify a supported event and its path');
-    }
-    if (path.isAbsolute(hook.path) || hook.path.split(/[\\/]/).includes('..')) {
-      throw new Error('installation record hook path must stay relative to the host root');
-    }
-    const definition = definitions.find((entry) => path.basename(hook.path) === entry.file);
-    if (!definition || !record.files.includes(hook.path)) {
-      const files = definitions.map((entry) => entry.file).join(' or ');
-      throw new Error(`installation record hook path must name the installed ${files}`);
-    }
-  }
-  return record;
+function targetBase(host, mapping) {
+  const base = host[mapping.target];
+  if (!base) throw new Error(`host has no ${mapping.target} install target`);
+  return base;
 }
 
-export function normalizeInstallRecord(record) {
-  validateInstallRecord(record);
-  if (record.hooks !== undefined) return record;
-  const { hook, ...withoutLegacyHook } = record;
-  return { ...withoutLegacyHook, hooks: [hook] };
+function rootFor(host, mapping) {
+  return mapping.root === 'brand' ? host.brandRoot : host.root;
 }
 
-export async function readInstallRecord(host) {
-  let parsed;
-  try {
-    parsed = await readJsonFile(installRecordPath(host));
-  } catch (err) {
-    if (err.code === 'ENOENT') return null;
-    if (err.cause) {
-      throw new Error(`invalid installation record JSON: ${err.cause.message}`, { cause: err.cause });
-    }
-    throw err;
+function targetRelative(packageRoot, source, mapping) {
+  if (mapping.processing === 'placeholders' || mapping.source === 'package.json') {
+    return path.basename(source);
   }
-  const record = normalizeInstallRecord(parsed);
-  // Earlier versions installed the config as a package file and recorded it. Dropping it here
-  // is what stops the next update from calling the operator's edited config an orphan and
-  // deleting it, and it needs no migration step: the record is rewritten on the next write.
-  const seeded = seededTargets(host);
-  record.files = record.files.filter((file) => !seeded.has(file));
-  if (record.fingerprints) {
-    record.fingerprints = Object.fromEntries(
-      Object.entries(record.fingerprints).filter(([file]) => !seeded.has(file)),
-    );
-  }
-  return record;
-}
-
-export async function writeInstallRecord(host, record) {
-  const normalized = normalizeInstallRecord(record);
-  await fs.writeFile(installRecordPath(host), `${JSON.stringify(normalized, null, 2)}\n`);
+  const sourceRoot = mapping.source === 'src/hooks/**'
+    ? path.join(packageRoot, 'src', 'hooks')
+    : path.join(packageRoot, 'src');
+  return path.relative(sourceRoot, source);
 }
 
 export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {
@@ -239,22 +147,29 @@ export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {
   const claimedSources = [];
   for (const mapping of INSTALL_TABLE) {
     for await (const relative of fs.glob(mapping.source, { cwd: packageRoot, exclude: claimedSources })) {
-      if (posix(relative) === RULES_SOURCE) continue;
-      if (SEEDED_SOURCES.includes(posix(relative))) continue;
+      if (posix(relative) === RULES_SOURCE || SEEDED_SOURCES.includes(posix(relative))) continue;
       const source = path.join(packageRoot, relative);
       if (!(await fs.stat(source)).isFile()) continue;
-      const targetRelative = mapping.processing === 'copy'
-        ? path.relative(path.join(packageRoot, 'src'), source)
-        : path.basename(source);
-      const target = path.join(host[mapping.target], targetRelative);
+      const relativeToTarget = posix(targetRelative(packageRoot, source, mapping));
+      const target = path.join(targetBase(host, mapping), relativeToTarget);
+      const relativeToRoot = posix(path.relative(rootFor(host, mapping), target));
       files.push({
         source,
         target,
+        root: mapping.root,
+        relativeToRoot,
         relativeToHost: posix(path.relative(host.root, target)),
         processing: mapping.processing,
+        installationRoot: mapping.processing === 'placeholders'
+          ? host.brandRunnerDir
+          : rootFor(host, mapping),
       });
     }
     claimedSources.push(mapping.source);
   }
-  return files.sort((a, b) => a.relativeToHost.localeCompare(b.relativeToHost));
+  return files.sort((a, b) => recordFileKey(a).localeCompare(recordFileKey(b)));
+}
+
+export function targetForPlanItem(host, item) {
+  return recordTarget(host, fileEntry({ root: item.root, path: item.relativeToRoot }));
 }

package/cli/projects.mjs

@@ -1,6 +1,9 @@
 /** Implements the projects command. */
 import { listProjectRuns, listProjects } from './runs-inventory.mjs';
 import { renderTable } from './table.mjs';
+import { allLiveRuns } from '../src/hooks/live-runs.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { STOP_COMMAND_TEMPLATE } from '../src/stop-contract.mjs';
 
 // The table renders whatever it is given; how a byte count or a timestamp reads is this command's
 // business. Raw bytes and ISO milliseconds are technically exact and practically unreadable — an
@@ -75,9 +78,21 @@ function parseArgs(args) {
   return { json, projectName: positional[0] || null };
 }
 
-function output(rows, columns, options) {
+/**
+ * Silence when nothing is running: this line exists to interrupt the operator who believes every
+ * run is stopped, and a "0 runs" line printed under every listing is the fastest way to teach them
+ * not to read it.
+ */
+function workingRunsLine(root) {
+  const count = allLiveRuns(root, { requireConfirmedIdentity: true }).length;
+  if (!count) return '';
+  const noun = count === 1 ? 'run' : 'runs';
+  return `\n${count} ${noun} working right now; stop with ${STOP_COMMAND_TEMPLATE}`;
+}
+
+function output(rows, columns, options, root) {
   if (options.json) return JSON.stringify(rows, null, 2);
-  return renderTable(columns, rows, options.terminalWidth);
+  return `${renderTable(columns, rows, options.terminalWidth)}${workingRunsLine(root)}`;
 }
 
 /** Lists projects or runs for one project. */
@@ -86,7 +101,7 @@ export function projects(argv = [], options = {}) {
   if (parsed.error) return { exitCode: 2, output: parsed.error };
 
   const { projectName } = parsed;
-  const root = options.runsRootPath;
+  const root = options.runsRootPath || runsRoot();
   const renderOptions = { json: parsed.json, terminalWidth: options.terminalWidth };
 
   if (projectName) {
@@ -97,9 +112,9 @@ export function projects(argv = [], options = {}) {
         output: `codex-bridge projects: unknown project "${projectName}"`,
       };
     }
-    return { exitCode: 0, output: output(rows, RUN_COLUMNS, renderOptions) };
+    return { exitCode: 0, output: output(rows, RUN_COLUMNS, renderOptions, root) };
   }
 
   const rows = listProjects(root);
-  return { exitCode: 0, output: output(rows, PROJECT_COLUMNS, renderOptions) };
+  return { exitCode: 0, output: output(rows, PROJECT_COLUMNS, renderOptions, root) };
 }

package/cli/remove-layout.mjs

@@ -0,0 +1,59 @@
+/** Removes emptied directories of an installed layout without walking out of the package's own. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * These four helpers existed as two copies — one in uninstall.mjs, one in update.mjs — and the
+ * copies had already drifted before this file was written: update's removeEmptyParents inlined the
+ * readdir/rmdir pair instead of calling removeEmpty, and only uninstall's removeEmptyLayout
+ * guarded a missing directory. Nothing failed, which is exactly the problem: the same divergence
+ * between the installer's file list and the hook's list went unnoticed until Plan_19 had to
+ * reconcile them. Removal logic decides what disappears from the operator's ~/.claude, so it gets
+ * one definition.
+ */
+
+export async function removeEmpty(directory) {
+  try {
+    if ((await fs.readdir(directory)).length === 0) await fs.rmdir(directory);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+export async function removeEmptyParents(target, boundary) {
+  let current = path.dirname(target);
+  while (current !== boundary && current.startsWith(`${boundary}${path.sep}`)) {
+    await removeEmpty(current);
+    current = path.dirname(current);
+  }
+}
+
+/**
+ * The directory an emptied-parent walk must stop at. Plan_25 gave the host four package-owned
+ * directories at once — the current agents and commands subdirectories and the two the previous
+ * layout used — and a walk that started inside one of them but stopped at host.root would delete
+ * the operator's own emptied directories on the way up.
+ */
+export function claudeBoundary(host, target) {
+  const directories = [
+    host.agentsDir,
+    host.commandsDir,
+    host.legacyAgentsDir,
+    host.legacyCommandsDir,
+  ].filter(Boolean);
+  return directories.find((directory) => target === directory
+    || target.startsWith(`${directory}${path.sep}`)) || host.root;
+}
+
+/**
+ * Takes down one emptied package-owned layout directory — and stops there.
+ *
+ * It deliberately does not walk into the parent: the parents here are `~/.claude/agents` and
+ * `~/.claude/commands`, which belong to Claude Code and are shared with every other agent the
+ * operator has. An operator whose only agents were ours would have had those directories deleted
+ * out from under Claude Code by an uninstall that was asked to remove our files. Directories
+ * *inside* our own are a different case and are still walked, bounded by claudeBoundary().
+ */
+export async function removeEmptyLayout(directory) {
+  await removeEmpty(directory);
+}

package/cli/rules-owners.mjs

@@ -99,19 +99,41 @@ async function dropStaleLock(lockPath) {
   }
 }
 
+/**
+ * Windows answers a taken lock with three different codes, and only one of them is EEXIST. A file
+ * whose last handle closed while a delete was pending stays visible but refuses to be opened:
+ * `open(..., 'wx')` comes back EPERM, and a file another process still holds comes back EBUSY.
+ * Treating those as fatal is what made `tests/cli/rules-owners.test.mjs` fail twice on 2026-08-11
+ * with EPERM on the lock file — the suite went red over a lock that was simply busy for one more
+ * millisecond. All three mean the same thing to a caller waiting for a lock: not yours yet.
+ */
+const LOCK_TAKEN_CODES = new Set(['EEXIST', 'EPERM', 'EBUSY']);
+
+/** Exported so the retry contract is asserted directly; the race itself reproduces only by luck. */
+export function isLockTaken(err) {
+  return LOCK_TAKEN_CODES.has(err?.code);
+}
+
 async function acquireRegistryLock(host) {
   await fs.mkdir(host.codexRulesDir, { recursive: true });
   const lockPath = registryLockPath(host);
+  let lastTaken;
   for (let attempt = 0; attempt < REGISTRY_LOCK_RETRIES; attempt += 1) {
     try {
       const handle = await fs.open(lockPath, 'wx');
       return { handle, lockPath };
     } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
+      if (!isLockTaken(err)) throw err;
+      lastTaken = err;
       if (!(await dropStaleLock(lockPath))) await waitForRegistryLock();
     }
   }
-  throw new Error(`timed out waiting for rules ownership registry lock: ${lockPath}`);
+  // The code is part of the message: a timeout on EPERM points at a delete that never completed,
+  // a timeout on EEXIST at an owner that never released.
+  throw new Error(
+    `timed out waiting for rules ownership registry lock: ${lockPath} (last attempt: ${lastTaken.code})`,
+    { cause: lastTaken },
+  );
 }
 
 async function withRegistryLock(host, action) {

package/cli/settings-merge.mjs

@@ -1,5 +1,7 @@
 /** Merges and removes named codex-bridge hooks without disturbing host settings. */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -12,6 +14,74 @@ export function commandFor(guardPath) {
   return `node "${path.resolve(guardPath)}"`;
 }
 
+export function shortCommandFor(name) {
+  return `codex-bridge hook ${name}`;
+}
+
+function pathValue(env) {
+  const key = Object.keys(env).find((entry) => entry.toLowerCase() === 'path');
+  return key ? env[key] : '';
+}
+
+export function commandReachable(name = 'codex-bridge', env = process.env) {
+  const extensions = process.platform === 'win32'
+    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  return pathValue(env).split(path.delimiter).filter(Boolean).some((directory) =>
+    extensions.some((extension) => {
+      const candidate = path.join(directory, `${name}${extension}`);
+      try {
+        return existsSync(candidate) && statSync(candidate).isFile();
+      } catch {
+        return false;
+      }
+    }));
+}
+
+/**
+ * The version the command on PATH reports, or null when there is none or it will not say.
+ *
+ * Existence used to be the only question, and on 2026-08-11 that cost the operator every guard on
+ * the machine: an install from the clone wrote `codex-bridge hook <name>` while the command on
+ * PATH was the previous release, which has no `hook` subcommand. Every guard then failed before it
+ * could decide anything, and the host refused Bash, PowerShell, file edits and agent launches.
+ */
+export function reachableCommandVersion(name = 'codex-bridge', env = process.env) {
+  if (!commandReachable(name, env)) return null;
+  const result = spawnSync(name, ['--version'], {
+    encoding: 'utf8',
+    env,
+    // The launcher npm writes on Windows is a .cmd shim, which spawn cannot execute without a
+    // shell. The name is a constant of this module, never operator input.
+    shell: process.platform === 'win32',
+  });
+  if (result.error || result.status !== 0) return null;
+  return String(result.stdout || '').trim().split(/\r?\n/).pop()?.trim() || null;
+}
+
+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) {
+    return {
+      command: shortCommandFor(name),
+      form: 'short',
+      reason: `codex-bridge ${reachable} on PATH matches this package; the global command will execute`,
+    };
+  }
+  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 };
+}
+
+export function commandForm(command) {
+  return command.startsWith('codex-bridge hook ') ? 'short' : 'path';
+}
+
 function normalizeSpec(specOrPath) {
   if (typeof specOrPath === 'string') {
     return { ...LEGACY_SPEC, command: commandFor(specOrPath) };
@@ -26,6 +96,9 @@ function normalizeSpec(specOrPath) {
     event: specOrPath.event,
     matcher: specOrPath.matcher,
     command: specOrPath.command,
+    alternateCommands: Array.isArray(specOrPath.alternateCommands)
+      ? specOrPath.alternateCommands.filter((command) => typeof command === 'string')
+      : [],
   };
 }
 
@@ -55,8 +128,10 @@ function groupHooks(group) {
   return Array.isArray(group?.hooks) ? group.hooks : [];
 }
 
-const hasOwnCommand = (group, command) =>
-  groupHooks(group).some((hook) => hook?.type === 'command' && hook.command === command);
+const hasOwnCommand = (group, commands) => {
+  const expected = Array.isArray(commands) ? commands : [commands];
+  return groupHooks(group).some((hook) => hook?.type === 'command' && expected.includes(hook.command));
+};
 
 /**
  * Presence is decided by the command, not by the matcher it currently sits under.
@@ -71,9 +146,17 @@ const hasOwnCommand = (group, command) =>
 export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
   const spec = normalizeSpec(specOrPath);
-  const present = groups(state.settings, spec.event)
-    .some((group) => hasOwnCommand(group, spec.command));
-  return { ...state, ...spec, present };
+  const commands = [spec.command, ...spec.alternateCommands];
+  let matchedCommand;
+  for (const group of groups(state.settings, spec.event)) {
+    const hook = groupHooks(group).find((entry) =>
+      entry?.type === 'command' && commands.includes(entry.command));
+    if (hook) {
+      matchedCommand = hook.command;
+      break;
+    }
+  }
+  return { ...state, ...spec, present: Boolean(matchedCommand), matchedCommand };
 }
 
 function backupName(settingsPath) {
@@ -173,10 +256,11 @@ export async function removeHook(settingsPath, specOrPath, { createdGroup = fals
     // sits in another group.
     for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
       const group = eventGroups[index];
-      if (!hasOwnCommand(group, spec.command)) continue;
+      const commands = [spec.command, ...spec.alternateCommands];
+      if (!hasOwnCommand(group, commands)) continue;
       if (!Array.isArray(group?.hooks)) continue;
       group.hooks = group.hooks.filter((hook) =>
-        !(hook?.type === 'command' && hook.command === spec.command));
+        !(hook?.type === 'command' && commands.includes(hook.command)));
       if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
     }
     await atomicWrite(settingsPath, settings, state);