@lyupro/codex-bridge 0.1.0

package/cli/manifest.mjs

@@ -0,0 +1,210 @@
+/** Defines install mappings and validates the persisted installation record. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+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
+ * is where a host states which model each mode runs on, and an installer that overwrites it
+ * would erase that on the next update — the same way overwriting a .env would.
+ */
+export const SEEDED_SOURCES = Object.freeze(['src/run-config.json']);
+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' },
+]);
+
+const posix = (value) => value.split(path.sep).join('/');
+
+export function replacePlaceholders(content, agentsDir) {
+  return content.replaceAll('{{CODEX_BRIDGE_DIR}}', posix(path.resolve(agentsDir)));
+}
+
+export async function packageInfo(packageRoot = PACKAGE_ROOT) {
+  const parsed = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+  return { name: parsed.name, version: parsed.version };
+}
+
+export function installRecordPath(host) {
+  return path.join(host.agentsDir, INSTALL_RECORD_NAME);
+}
+
+/** 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',
+  }));
+}
+
+export function rulesPlan(host, packageRoot = PACKAGE_ROOT) {
+  return {
+    source: path.join(packageRoot, RULES_SOURCE),
+    target: path.join(host.codexRulesDir, RULES_NAME),
+    name: RULES_NAME,
+  };
+}
+
+export async function fileFingerprint(absolutePath) {
+  try {
+    return createHash('sha256').update(await fs.readFile(absolutePath)).digest('hex');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * 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.hook || typeof record.hook !== 'object' || Array.isArray(record.hook)) {
+    throw new Error('installation record hook must be an object');
+  }
+  if (record.hook.event !== 'SubagentStop' || typeof record.hook.path !== 'string' || !record.hook.path) {
+    throw new Error('installation record hook must identify SubagentStop and its path');
+  }
+  if (path.isAbsolute(record.hook.path) || record.hook.path.split(/[\\/]/).includes('..')) {
+    throw new Error('installation record hook path must stay relative to the host root');
+  }
+  if (path.basename(record.hook.path) !== 'reply-guard.mjs' || !record.files.includes(record.hook.path)) {
+    throw new Error('installation record hook path must name the installed reply-guard.mjs');
+  }
+  return record;
+}
+
+export async function readInstallRecord(host) {
+  let raw;
+  try {
+    raw = await fs.readFile(installRecordPath(host), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`invalid installation record JSON: ${err.message}`);
+  }
+  const record = validateInstallRecord(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) {
+  validateInstallRecord(record);
+  await fs.writeFile(installRecordPath(host), `${JSON.stringify(record, null, 2)}\n`);
+}
+
+export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {
+  const files = [];
+  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;
+      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);
+      files.push({
+        source,
+        target,
+        relativeToHost: posix(path.relative(host.root, target)),
+        processing: mapping.processing,
+      });
+    }
+    claimedSources.push(mapping.source);
+  }
+  return files.sort((a, b) => a.relativeToHost.localeCompare(b.relativeToHost));
+}

package/cli/settings-merge.mjs

@@ -0,0 +1,101 @@
+/** Merges and removes the codex-bridge SubagentStop hook without disturbing host settings. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const EVENT = 'SubagentStop';
+
+function commandFor(guardPath) {
+  return `node "${path.resolve(guardPath)}"`;
+}
+
+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}`);
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') return { exists: false, raw: null, settings: {} };
+    throw err;
+  }
+}
+
+function groups(settings) {
+  const value = settings?.hooks?.[EVENT];
+  return Array.isArray(value) ? value : [];
+}
+
+function ownHook(command) {
+  return { type: 'command', command, timeout: 10 };
+}
+
+function groupHooks(group) {
+  return Array.isArray(group?.hooks) ? group.hooks : [];
+}
+
+export async function inspectHook(settingsPath, guardPath) {
+  const state = await readSettings(settingsPath);
+  const command = commandFor(guardPath);
+  const present = groups(state.settings).some((group) =>
+    groupHooks(group).some((hook) => hook?.type === 'command' && hook.command === command));
+  return { ...state, command, present };
+}
+
+function backupName(settingsPath) {
+  const stamp = new Date().toISOString().replaceAll(':', '-');
+  return `${settingsPath}.codex-bridge-backup-${stamp}-${randomUUID()}`;
+}
+
+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 temporary = `${settingsPath}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, { flag: 'wx' });
+    await fs.rename(temporary, settingsPath);
+  } catch (err) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+export async function mergeHook(settingsPath, guardPath, inspected) {
+  const state = inspected || await inspectHook(settingsPath, guardPath);
+  if (state.present) return { changed: false, createdGroup: false };
+  const settings = structuredClone(state.settings);
+  settings.hooks ??= {};
+  if (!Array.isArray(settings.hooks[EVENT])) settings.hooks[EVENT] = [];
+  let group = settings.hooks[EVENT].find((entry) => entry?.matcher === '*');
+  const createdGroup = !group;
+  if (!group) {
+    group = { matcher: '*', hooks: [] };
+    settings.hooks[EVENT].push(group);
+  }
+  if (!Array.isArray(group.hooks)) group.hooks = [];
+  group.hooks.push(ownHook(state.command));
+  await atomicWrite(settingsPath, settings, state);
+  return { changed: true, createdGroup };
+}
+
+export async function removeHook(settingsPath, guardPath, { createdGroup = false } = {}) {
+  const state = await inspectHook(settingsPath, guardPath);
+  if (!state.present) return { changed: false };
+  const settings = structuredClone(state.settings);
+  const eventGroups = groups(settings);
+  for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
+    const group = eventGroups[index];
+    if (!Array.isArray(group?.hooks)) continue;
+    group.hooks = group.hooks.filter((hook) =>
+      !(hook?.type === 'command' && hook.command === state.command));
+    if (createdGroup && group.matcher === '*' && group.hooks.length === 0) eventGroups.splice(index, 1);
+  }
+  await atomicWrite(settingsPath, settings, state);
+  return { changed: true };
+}

package/cli/stop.mjs

@@ -0,0 +1,125 @@
+/** Stops a live run and records the same abandoned FAIL artifacts as the normal sweep. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stopCodex } from '../src/runner/codex-cmd.mjs';
+import { git, worktreeSnapshot } from '../src/runner/git-state.mjs';
+import { markAbandoned, readJson } from '../src/write-meta.mjs';
+import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+
+const EXIT_POLL_MS = 25;
+const EXIT_WAIT_MS = 2000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function projectRoot(cwd) {
+  const result = git(cwd, ['rev-parse', '--show-toplevel']);
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : cwd;
+}
+
+function resolveRunFolder(run, cwd, runsRootPath) {
+  const value = String(run ?? '').trim();
+  if (!value || value === '.' || value === '..') {
+    throw new Error('stop requires a run folder (full path or bare folder name)');
+  }
+  if (path.isAbsolute(value)) return path.resolve(value);
+  if (path.dirname(value) !== '.') {
+    throw new Error('a bare run folder name or a full path is required');
+  }
+  const projectRuns = resolveProjectRunsDir(runsRootPath, projectRoot(cwd), { create: false });
+  return path.join(projectRuns.dir, value);
+}
+
+/** The stopped run's worktree as it stands now, or undefined when the repo is not a git one. */
+function treeOf(repo) {
+  const root = String(repo ?? '').trim();
+  if (!root) return undefined;
+  if (git(root, ['rev-parse', '--show-toplevel']).status !== 0) return undefined;
+  return worktreeSnapshot(root);
+}
+
+function processHandle(pid) {
+  return {
+    pid,
+    kill(signal) {
+      try {
+        process.kill(pid, signal);
+      } catch (err) {
+        if (err.code !== 'ESRCH') throw err;
+      }
+    },
+  };
+}
+
+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);
+}
+
+function result(exitCode, output) {
+  return { exitCode, output };
+}
+
+export async function stop({ run, cwd = process.cwd(), runsRootPath = runsRoot() } = {}) {
+  let runDir;
+  try {
+    runDir = resolveRunFolder(run, cwd, runsRootPath);
+  } catch (err) {
+    return result(1, `codex-bridge stop: ${err.message}`);
+  }
+
+  let isDirectory = false;
+  try {
+    isDirectory = fs.statSync(runDir).isDirectory();
+  } catch {}
+  if (!isDirectory) {
+    return result(
+      1,
+      `Run folder not found: ${runDir}. Pass a full path or a bare run folder name from the current project's runs directory.`,
+    );
+  }
+
+  const status = readJson(path.join(runDir, 'status.json'));
+  const meta = readJson(path.join(runDir, 'meta.json'));
+  if (meta && typeof meta.status === 'string') {
+    return result(0, `Run ${runDir} already has a verdict (${meta.status}); no changes made.`);
+  }
+  if (!status) return result(1, `Run ${runDir} has no readable status.json; it was not changed.`);
+  if (status.state !== 'running') {
+    return result(0, `Run ${runDir} is not marked running (state: ${status.state || 'unknown'}); no changes made.`);
+  }
+  if (!Number.isInteger(status.pid) || status.pid <= 0) {
+    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.`);
+    }
+  } 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
+  // left in the worktree. Omitting it would close the folder with "no file list is available" —
+  // the operator stopping a run by hand is exactly who needs to know what it managed to write.
+  markAbandoned(path.dirname(runDir), treeOf(status.repo));
+  const closedMeta = readJson(path.join(runDir, 'meta.json'));
+  const closedStatus = readJson(path.join(runDir, 'status.json'));
+  if (closedMeta?.status === 'FAIL' && closedStatus?.status === 'FAIL' && closedStatus.state !== 'running') {
+    return result(0, `Stopped run ${runDir}; recorded FAIL verdict.`);
+  }
+  return result(1, `Run ${runDir} stopped but could not be closed with consistent FAIL artifacts.`);
+}

package/cli/uninstall.mjs

@@ -0,0 +1,62 @@
+/** Uninstalls only recorded codex-bridge files while preserving host data and foreign files. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileFingerprint, installRecordPath, readInstallRecord } from './manifest.mjs';
+import { removeHook } from './settings-merge.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;
+  }
+}
+
+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);
+  }
+}
+
+export async function uninstall({ host, dryRun = false } = {}) {
+  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}` };
+
+  if (dryRun) {
+    const lines = record.files.map((file) => `Would remove ${file}`);
+    if (record.rules) lines.push(`Would remove ${record.rules.path} if its fingerprint is unchanged.`);
+    lines.push('Would remove the SubagentStop hook and installation record.');
+    lines.push(preservation);
+    return { exitCode: 0, output: lines.join('\n') };
+  }
+
+  await removeHook(host.settingsPath, path.join(host.root, record.hook.path), {
+    createdGroup: record.hook.createdGroup === true,
+  });
+  let rulesOutput;
+  if (record.rules) {
+    const currentFingerprint = await fileFingerprint(record.rules.path);
+    if (currentFingerprint === record.rules.fingerprint) {
+      await fs.rm(record.rules.path, { force: true });
+    } else if (currentFingerprint !== null) {
+      rulesOutput = `Left ${record.rules.path} because its contents changed after installation.`;
+    }
+  }
+  for (const relative of record.files) {
+    const target = path.join(host.root, relative);
+    await fs.rm(target, { force: true });
+    const boundary = target.startsWith(`${host.commandsDir}${path.sep}`) ? host.commandsDir : host.agentsDir;
+    await removeEmptyParents(target, boundary);
+  }
+  await removeEmpty(host.commandsDir);
+  await fs.rm(installRecordPath(host), { force: true });
+  await removeEmpty(host.agentsDir);
+  return {
+    exitCode: 0,
+    output: [`Uninstalled codex-bridge.`, rulesOutput, preservation].filter(Boolean).join('\n'),
+  };
+}

package/cli/update.mjs

@@ -0,0 +1,156 @@
+/** Updates a recorded codex-bridge installation without overwriting unapproved host changes. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { install } from './install.mjs';
+import {
+  buildInstallPlan,
+  fileFingerprint,
+  packageInfo,
+  readInstallRecord,
+  recordMatchesPackage,
+  rulesPlan,
+} from './manifest.mjs';
+import { targetMatches } from './copy.mjs';
+import { inspectHook } from './settings-merge.mjs';
+
+async function exists(target) {
+  try {
+    return (await fs.stat(target)).isFile();
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+    throw err;
+  }
+}
+
+function classifyPlanned(state, record) {
+  if (!state.recorded) return 'new';
+  if (!state.exists) return 'missing';
+  if (state.matchesPackage) return 'up-to-date';
+  if (state.recordedFingerprint === state.fingerprint) return 'outdated';
+  return 'modified';
+}
+
+function classifyOrphan(state, record) {
+  if (!state.exists) return 'orphaned';
+  if (record.fingerprints?.[state.relative] === state.fingerprint) return 'orphaned';
+  return 'modified';
+}
+
+/**
+ * What the run actually did, counted by outcome. `Updated codex-bridge.` alone told the operator
+ * nothing about the files that were rewritten or removed on their behalf.
+ */
+function appliedOutput(states) {
+  const count = (status) => states.filter((state) => state.status === status).length;
+  const parts = [
+    [count('outdated'), 'updated'],
+    [count('new'), 'added'],
+    [count('missing'), 'restored'],
+    // A modified orphan is preserved rather than rewritten, so it is not counted here.
+    [states.filter((state) => state.status === 'modified' && state.item).length, 'overwritten'],
+    [states.filter((state) => state.status === 'orphaned' && state.exists).length, 'removed'],
+  ].filter(([total]) => total > 0).map(([total, label]) => `${total} ${label}`);
+  return parts.length ? `Updated codex-bridge: ${parts.join(', ')}.` : 'Updated codex-bridge.';
+}
+
+function conflictOutput(conflicts, legacy, dryRun) {
+  const heading = dryRun ? 'Update would stop for these paths:' : 'Update stopped for these paths:';
+  const lines = conflicts.map((state) => `  ${state.relative} (${state.status})`);
+  if (legacy) lines.push('Installation record has no fingerprints; differing files are treated as modified.');
+  lines.push('Run update again with --force to overwrite modified files and restore missing files.');
+  return [heading, ...lines].join('\n');
+}
+
+function dryRunOutput(states, hookPresent, legacy) {
+  const lines = [];
+  for (const state of states) {
+    if (state.status === 'outdated') lines.push(`Would update ${state.relative}.`);
+    if (state.status === 'new') lines.push(`Would create ${state.relative}.`);
+    if (state.status === 'modified' && state.item) lines.push(`Would overwrite ${state.relative}.`);
+    if (state.status === 'missing') lines.push(`Would restore ${state.relative}.`);
+    if (state.status === 'orphaned' && state.exists) lines.push(`Would remove ${state.relative}.`);
+    if (state.status === 'modified' && !state.item) lines.push(`Would preserve modified orphan ${state.relative}.`);
+  }
+  if (!hookPresent) lines.push('Would register SubagentStop hook.');
+  lines.push('Would write installation record with new fingerprints.');
+  if (legacy && states.some((state) => state.status === 'modified')) {
+    lines.push('Installation record has no fingerprints; differing files are treated as modified.');
+  }
+  return lines.join('\n');
+}
+
+export async function update({ host, dryRun = false, force = false, packageRoot } = {}) {
+  const record = await readInstallRecord(host);
+  if (!record) {
+    return { exitCode: 1, output: 'codex-bridge is not installed. Run codex-bridge install first.' };
+  }
+
+  const plan = await buildInstallPlan(host, packageRoot);
+  const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
+  const planned = new Map(plan.map((item) => [item.relativeToHost, item]));
+  const plannedStates = await Promise.all(plan.map(async (item) => {
+    const relative = item.relativeToHost;
+    const targetExists = await exists(item.target);
+    const state = {
+      relative,
+      item,
+      recorded: record.files.includes(relative),
+      recordedFingerprint: record.fingerprints?.[relative],
+      exists: targetExists,
+      matchesPackage: targetExists && await targetMatches(item, host.agentsDir),
+      fingerprint: targetExists ? await fileFingerprint(item.target) : null,
+    };
+    return { ...state, status: classifyPlanned(state, record) };
+  }));
+  const ruleExists = await exists(rule.target);
+  const ruleState = {
+    relative: rule.target,
+    item: rule,
+    recorded: Boolean(record.rules),
+    recordedFingerprint: record.rules?.fingerprint,
+    exists: ruleExists,
+    matchesPackage: ruleExists && await targetMatches(rule, host.agentsDir),
+    fingerprint: ruleExists ? await fileFingerprint(rule.target) : null,
+  };
+  ruleState.status = classifyPlanned(ruleState, record);
+  const orphanStates = await Promise.all(record.files
+    .filter((relative) => !planned.has(relative))
+    .map(async (relative) => {
+      const target = path.join(host.root, relative);
+      const targetExists = await exists(target);
+      const state = {
+        relative,
+        item: null,
+        exists: targetExists,
+        fingerprint: targetExists ? await fileFingerprint(target) : null,
+      };
+      return { ...state, status: classifyOrphan(state, record) };
+    }));
+  const states = [...plannedStates, ruleState, ...orphanStates];
+  const conflicts = states.filter((state) => state.status === 'modified' || state.status === 'missing');
+  const legacy = !record.fingerprints;
+  if (conflicts.length && !force) {
+    return { exitCode: 1, output: conflictOutput(conflicts, legacy, dryRun) };
+  }
+
+  const guardPath = path.join(host.agentsDir, 'hooks', 'reply-guard.mjs');
+  const inspectedHook = await inspectHook(host.settingsPath, guardPath);
+  const currentPackage = await packageInfo(packageRoot);
+  const recordCurrent = recordMatchesPackage(record, plan, currentPackage,
+    new Map(plannedStates.map((state) => [state.relative, state.fingerprint])),
+    { path: rule.target, fingerprint: ruleState.fingerprint });
+  const changed = states.some((state) => state.status !== 'up-to-date');
+  if (!changed && inspectedHook.present && recordCurrent) {
+    return { exitCode: 0, output: 'codex-bridge is up to date' };
+  }
+  if (dryRun) {
+    return { exitCode: 0, output: dryRunOutput(states, inspectedHook.present, legacy) };
+  }
+
+  for (const state of orphanStates) {
+    if (state.status === 'orphaned' && state.exists) await fs.rm(path.join(host.root, state.relative));
+  }
+  const installed = await install({ host, force: true, packageRoot });
+  if (installed.exitCode !== 0) return installed;
+  return { exitCode: 0, output: appliedOutput(states) };
+}