@lyupro/codex-bridge 0.3.1 → 0.5.0

package/cli/runs-inventory.mjs

@@ -2,13 +2,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { liveRuns } from '../src/hooks/live-runs.mjs';
+import { readJsonFileSync } from '../src/json-file.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
 function readRecord(file) {
   try {
-    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const value = readJsonFileSync(file);
     return record(value) ? value : null;
   } catch {
     return null;

package/cli/settings-merge.mjs

@@ -1,14 +1,87 @@
 /** 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';
+import { readJsonFileWithRaw } from '../src/json-file.mjs';
 
 const LEGACY_SPEC = { event: 'SubagentStop', matcher: '*' };
+const settingsRuns = new AsyncLocalStorage();
 
 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) };
@@ -23,21 +96,19 @@ function normalizeSpec(specOrPath) {
     event: specOrPath.event,
     matcher: specOrPath.matcher,
     command: specOrPath.command,
+    alternateCommands: Array.isArray(specOrPath.alternateCommands)
+      ? specOrPath.alternateCommands.filter((command) => typeof command === 'string')
+      : [],
   };
 }
 
-async function readSettings(settingsPath) {
+export async function readSettings(settingsPath) {
   try {
-    const raw = await fs.readFile(settingsPath, 'utf8');
-    try {
-      const parsed = JSON.parse(raw);
-      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('top level must be an object');
-      }
-      return { exists: true, raw, settings: parsed };
-    } catch (err) {
-      throw new Error(`cannot parse ${settingsPath}: ${err.message}`);
+    const { raw, value: settings } = await readJsonFileWithRaw(settingsPath);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+      throw new Error(`cannot parse ${settingsPath}: top level must be an object`);
     }
+    return { exists: true, raw, settings };
   } catch (err) {
     if (err.code === 'ENOENT') return { exists: false, raw: null, settings: {} };
     throw err;
@@ -57,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.
@@ -73,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) {
@@ -83,9 +164,38 @@ function backupName(settingsPath) {
   return `${settingsPath}.codex-bridge-backup-${stamp}-${randomUUID()}`;
 }
 
+function runKey(settingsPath) {
+  return path.resolve(settingsPath);
+}
+
+/**
+ * A command gets one in-memory backup scope. AsyncLocalStorage keeps concurrent commands separate
+ * in one process, while nested install calls reuse their caller's scope (Plan_24).
+ */
+export async function withSettingsRun(settingsPath, action) {
+  if (typeof action !== 'function') throw new TypeError('settings run action must be a function');
+  const key = runKey(settingsPath);
+  const active = settingsRuns.getStore();
+  if (active?.key === key) return action();
+  return settingsRuns.run({ key, backupTaken: false }, action);
+}
+
+function withMutationRun(settingsPath, action) {
+  const active = settingsRuns.getStore();
+  return active?.key === runKey(settingsPath)
+    ? action()
+    : withSettingsRun(settingsPath, action);
+}
+
 async function atomicWrite(settingsPath, settings, previous) {
   await fs.mkdir(path.dirname(settingsPath), { recursive: true });
-  if (previous.exists) await fs.writeFile(backupName(settingsPath), previous.raw, { flag: 'wx' });
+  const active = settingsRuns.getStore();
+  const ownsScope = active?.key === runKey(settingsPath);
+  const shouldBackup = !ownsScope || !active.backupTaken;
+  if (ownsScope) active.backupTaken = true;
+  if (shouldBackup && previous.exists) {
+    await fs.writeFile(backupName(settingsPath), previous.raw, { flag: 'wx' });
+  }
   const temporary = `${settingsPath}.${randomUUID()}.tmp`;
   try {
     await fs.writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, { flag: 'wx' });
@@ -96,42 +206,64 @@ async function atomicWrite(settingsPath, settings, previous) {
   }
 }
 
+/**
+ * Runs a settings mutation through the hook writer's backup and atomic-write boundary.
+ * Plan_22 requires permissions to preserve the same recovery guarantee after the settings merge
+ * incident: a second writer must not grow its own backup or serialization path.
+ */
+export async function updateSettings(settingsPath, edit) {
+  if (typeof edit !== 'function') throw new TypeError('settings edit must be a function');
+  return withMutationRun(settingsPath, async () => {
+    const previous = await readSettings(settingsPath);
+    const settings = structuredClone(previous.settings);
+    const result = await edit(settings);
+    if (!result?.changed) return result || { changed: false };
+    await atomicWrite(settingsPath, settings, previous);
+    return result;
+  });
+}
+
 export async function mergeHook(settingsPath, specOrPath, inspected) {
-  const spec = normalizeSpec(specOrPath);
-  const state = inspected || await inspectHook(settingsPath, spec);
-  if (state.present) return { changed: false, createdGroup: false };
-  const settings = structuredClone(state.settings);
-  settings.hooks ??= {};
-  if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
-  let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
-  const createdGroup = !group;
-  if (!group) {
-    group = { matcher: spec.matcher, hooks: [] };
-    settings.hooks[spec.event].push(group);
-  }
-  if (!Array.isArray(group.hooks)) group.hooks = [];
-  group.hooks.push(ownHook(spec.command));
-  await atomicWrite(settingsPath, settings, state);
-  return { changed: true, createdGroup };
+  return withMutationRun(settingsPath, async () => {
+    const spec = normalizeSpec(specOrPath);
+    const state = inspected || await inspectHook(settingsPath, spec);
+    if (state.present) return { changed: false, createdGroup: false };
+    const settings = structuredClone(state.settings);
+    settings.hooks ??= {};
+    if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
+    let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
+    const createdGroup = !group;
+    if (!group) {
+      group = { matcher: spec.matcher, hooks: [] };
+      settings.hooks[spec.event].push(group);
+    }
+    if (!Array.isArray(group.hooks)) group.hooks = [];
+    group.hooks.push(ownHook(spec.command));
+    await atomicWrite(settingsPath, settings, state);
+    return { changed: true, createdGroup };
+  });
 }
 
 export async function removeHook(settingsPath, specOrPath, { createdGroup = false } = {}) {
-  const spec = normalizeSpec(specOrPath);
-  const state = await inspectHook(settingsPath, spec);
-  if (!state.present) return { changed: false };
-  const settings = structuredClone(state.settings);
-  const eventGroups = groups(settings, spec.event);
-  // Removal follows the same rule as the lookup above: our command, whatever matcher it is
-  // filed under. A foreign hook is left alone because its command is not ours, not because it
-  // sits in another group.
-  for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
-    const group = eventGroups[index];
-    if (!hasOwnCommand(group, spec.command)) continue;
-    if (!Array.isArray(group?.hooks)) continue;
-    group.hooks = group.hooks.filter((hook) =>
-      !(hook?.type === 'command' && hook.command === spec.command));
-    if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
-  }
-  await atomicWrite(settingsPath, settings, state);
-  return { changed: true };
+  return withMutationRun(settingsPath, async () => {
+    const spec = normalizeSpec(specOrPath);
+    const state = await inspectHook(settingsPath, spec);
+    if (!state.present) return { changed: false };
+    const settings = structuredClone(state.settings);
+    const eventGroups = groups(settings, spec.event);
+    // Removal follows the same rule as the lookup above: our command, whatever matcher it is
+    // filed under. A foreign hook is left alone because its command is not ours, not because it
+    // sits in another group.
+    for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
+      const group = eventGroups[index];
+      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' && commands.includes(hook.command)));
+      if (createdGroup && group.hooks.length === 0) eventGroups.splice(index, 1);
+    }
+    await atomicWrite(settingsPath, settings, state);
+    return { changed: true };
+  });
 }

package/cli/stop.mjs

@@ -1,7 +1,14 @@
-/** Stops a live run and records the same abandoned FAIL artifacts as the normal sweep. */
+/** Stops a live run and records the same abandoned FAIL artifacts as the normal unlock. */
 import path from 'node:path';
 import { stopCodex } from '../src/runner/codex-cmd.mjs';
 import { git, worktreeSnapshot } from '../src/runner/git-state.mjs';
+import {
+  IDENTITY_ALIVE,
+  IDENTITY_FOREIGN,
+  IDENTITY_UNVERIFIED,
+  processAlive,
+  processIdentity,
+} from '../src/process-identity.mjs';
 import { markAbandoned, readJson } from '../src/write-meta.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
@@ -32,27 +39,22 @@ function processHandle(pid) {
   };
 }
 
-function alive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
-}
-
 async function waitForExit(pid) {
   const deadline = Date.now() + EXIT_WAIT_MS;
-  while (alive(pid) && Date.now() < deadline) await sleep(EXIT_POLL_MS);
-  return !alive(pid);
+  while (processAlive(pid) && Date.now() < deadline) await sleep(EXIT_POLL_MS);
+  return !processAlive(pid);
 }
 
 function result(exitCode, output) {
   return { exitCode, output };
 }
 
-export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
+export async function stop({
+  run,
+  cwd = process.cwd(),
+  runsRootPath = runsRoot(),
+  commandRunner,
+} = {}) {
   const lookup = resolveRunFolder({ command: 'stop', run, cwd, runsRootPath });
   if (lookup.error) return result(1, lookup.error);
   const { runDir } = lookup;
@@ -70,13 +72,24 @@ export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot()
     return result(1, `Run ${runDir} has no valid recorded pid; it was not changed.`);
   }
 
-  try {
-    stopCodex(processHandle(status.pid));
-    if (!(await waitForExit(status.pid))) {
-      return result(1, `Run ${runDir} did not stop within ${EXIT_WAIT_MS}ms; it was not closed.`);
+  const identity = processIdentity({ runDir, status, commandRunner });
+  if (identity === IDENTITY_UNVERIFIED || identity === IDENTITY_FOREIGN) {
+    return result(
+      1,
+      `Process identity could not be confirmed for run ${runDir} (${identity}); no signal was sent. ` +
+        '"codex-bridge unlock" closes the record without killing a process.',
+    );
+  }
+
+  if (identity === IDENTITY_ALIVE) {
+    try {
+      stopCodex(processHandle(status.pid));
+      if (!(await waitForExit(status.pid))) {
+        return result(1, `Run ${runDir} did not stop within ${EXIT_WAIT_MS}ms; it was not closed.`);
+      }
+    } catch (err) {
+      return result(1, `Could not stop run ${runDir}: ${err.message}; it was not closed.`);
     }
-  } catch (err) {
-    return result(1, `Could not stop run ${runDir}: ${err.message}; it was not closed.`);
   }
 
   // The snapshot is what turns the verdict from a bare label into a list of what the stopped run

package/cli/uninstall.mjs

@@ -1,40 +1,56 @@
-/** Uninstalls only recorded codex-bridge files while preserving host data and foreign files. */
+/** Uninstalls only recorded files from both roots while preserving host data and foreign files. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
+  definitionForRecordedHook,
   fileFingerprint,
-  HOOK_DEFINITIONS,
   installRecordPath,
+  legacyInstallRecordPath,
   readInstallRecord,
+  recordTarget,
 } from './manifest.mjs';
-import { commandFor, removeHook } from './settings-merge.mjs';
+import { removePermissionRules } from './permissions.mjs';
+import {
+  commandFor,
+  removeHook,
+  withSettingsRun,
+} from './settings-merge.mjs';
 import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
+import {
+  claudeBoundary,
+  removeEmpty,
+  removeEmptyLayout,
+  removeEmptyParents,
+} from './remove-layout.mjs';
 
-async function removeEmpty(directory) {
-  try {
-    if ((await fs.readdir(directory)).length === 0) await fs.rmdir(directory);
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-  }
+function remainingOwnersText(count) {
+  return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
 }
 
-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);
-  }
+function permissionOutput(host, removed, dryRun) {
+  const verb = dryRun ? 'Would remove' : 'Removed';
+  const plural = removed === 1 ? 'string' : 'strings';
+  return `${verb} ${removed} permission rule ${plural} from ${host.settingsPath}.`;
 }
 
-function remainingOwnersText(count) {
-  return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
+function displayFile(file) {
+  return `${file.root}/${file.path}`;
 }
 
-function hookDefinition(event) {
-  return HOOK_DEFINITIONS.find((definition) => definition.event === event);
+function hookRemovalSpec(host, hook) {
+  const definition = definitionForRecordedHook(hook);
+  const target = recordTarget(host, hook);
+  const full = commandFor(target);
+  const short = `codex-bridge hook ${definition.name}`;
+  return {
+    event: hook.event,
+    matcher: definition.matcher,
+    command: hook.command || full,
+    alternateCommands: [full, short],
+  };
 }
 
-export async function uninstall({ host, dryRun = false } = {}) {
+async function uninstallInRun({ host, dryRun = false } = {}) {
   // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
   let registry = null;
   let registryError = null;
@@ -43,13 +59,17 @@ export async function uninstall({ host, dryRun = false } = {}) {
   } catch (err) {
     registryError = err;
   }
+  const permissionResult = await removePermissionRules(host.settingsPath, { dryRun });
+  const permissionLine = permissionOutput(host, permissionResult.removed, dryRun);
   const record = await readInstallRecord(host);
   const preservation = `Run artifacts in ${path.join(host.root, 'codex-runs')} and the run `
-    + `configuration in ${path.join(host.agentsDir, 'run-config.json')} are preserved.`;
-  if (!record) return { exitCode: 1, output: `codex-bridge is not installed.\n${preservation}` };
+    + `configuration in ${host.brandConfigPath} are preserved.`;
+  if (!record) {
+    return { exitCode: 1, output: `${permissionLine}\ncodex-bridge is not installed.\n${preservation}` };
+  }
 
   if (dryRun) {
-    const lines = record.files.map((file) => `Would remove ${file}`);
+    const lines = [permissionLine, ...record.files.map((file) => `Would remove ${displayFile(file)}`)];
     if (record.rules) {
       if (registryError) {
         lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
@@ -71,22 +91,18 @@ export async function uninstall({ host, dryRun = false } = {}) {
       }
     }
     for (const hook of record.hooks) {
-      const definition = hookDefinition(hook.event);
+      const definition = definitionForRecordedHook(hook);
       lines.push(`Would remove the ${hook.event} hook for matcher ${definition.matcher}.`);
     }
-    lines.push('Would remove the installation record.');
+    lines.push('Would remove the installation record from the brand root.');
     lines.push(preservation);
     return { exitCode: 0, output: lines.join('\n') };
   }
 
   for (const hook of record.hooks) {
-    const definition = hookDefinition(hook.event);
-    const target = path.join(host.root, hook.path);
-    await removeHook(host.settingsPath, {
-      event: hook.event,
-      matcher: definition.matcher,
-      command: commandFor(target),
-    }, { createdGroup: hook.createdGroup === true });
+    await removeHook(host.settingsPath, hookRemovalSpec(host, hook), {
+      createdGroup: hook.createdGroup === true,
+    });
   }
   let ownership = null;
   if (!registryError) {
@@ -116,17 +132,29 @@ export async function uninstall({ host, dryRun = false } = {}) {
       }
     }
   }
-  for (const relative of record.files) {
-    const target = path.join(host.root, relative);
+  for (const file of record.files) {
+    const target = recordTarget(host, file);
     await fs.rm(target, { force: true });
-    const boundary = target.startsWith(`${host.commandsDir}${path.sep}`) ? host.commandsDir : host.agentsDir;
+    const boundary = file.root === 'brand'
+      ? host.brandRoot
+      : claudeBoundary(host, target);
     await removeEmptyParents(target, boundary);
   }
   await removeEmpty(host.commandsDir);
   await fs.rm(installRecordPath(host), { force: true });
+  await fs.rm(legacyInstallRecordPath(host), { force: true });
   await removeEmpty(host.agentsDir);
+  await removeEmptyLayout(host.legacyAgentsDir);
+  await removeEmptyLayout(host.legacyCommandsDir);
+  await removeEmpty(host.brandRoot);
   return {
     exitCode: 0,
-    output: [`Uninstalled codex-bridge.`, ...rulesOutput, preservation].join('\n'),
+    output: ['Uninstalled codex-bridge.', permissionLine, ...rulesOutput, preservation].join('\n'),
   };
 }
+
+export async function uninstall(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return uninstallInRun(options);
+  return withSettingsRun(host.settingsPath, () => uninstallInRun(options));
+}