@lyupro/codex-bridge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-04
+
+### Added
+
+- Three dispatcher agents for reconnaissance (`codex-scout`), scoped implementation (`codex-build`), and independent review (`codex-review`), each with a structured response contract.
+- A delegating runner that separates the launcher from a detached worker, preserves run artifacts after a dropped call, and supports configurable artifact roots.
+- A zero-dependency `codex-bridge` CLI with `install`, `uninstall`, `update`, and `doctor`, including user/project scopes, dry runs, force handling, idempotent installs, hook merging with backups, and manifest-based ownership tracking.
+- A reply guard hook that blocks dispatcher replies that do not match the recorded run state or required response shape.
+- Run-chain and busy-tree lock protections: repeated work is linked across runs, an unfinished chain requires explicit `--continue`, and concurrent writing runs for one repository are refused before Codex starts.
+- Scope and coverage validation: implementation changes must stay within the declared scope, report/worktree mismatches fail the run, and reconnaissance reports must account for all requested subquestions.
+- Package-managed Codex execution rules that forbid history-, branch-, index-, and worktree-destructive operations, writes inside `.git`, and other unsafe repository mutations while leaving the operator's existing rules untouched.
+- A 400-line source-file size gate with explicit rationale required for exclusions.
+- Asynchronous run start: the launcher reports the run folder and returns instead of holding the caller for the length of the run, and repeating the same order attaches to the run already in flight rather than paying for a second one.
+- Per-mode time budgets that end a run and its whole process tree at a deadline, plus a `stop` subcommand for closing a run that wedged anyway.
+- Explicit reconnaissance subquestions through a mandatory, repeatable `--question` flag, so coverage is counted against what was ordered rather than against prose the dispatcher rewrote.
+- An `answerLanguage` configuration key that fixes the language of a run's answer instead of leaving it to the model.
+
+### Changed
+
+- Run identity now includes an orchestrator-issued mandatory `--order-id`, stored with run state and used alongside the task identity to detect repeats even when a run is renamed.
+- A repeat of an order is now continued at most once, and only behind a run that already carries a verdict, so a dispatcher can no longer restart itself into a chain of paid runs.
+- A run left behind by a dropped call is now closed with a `FAIL` verdict that names what it left in the worktree, instead of staying open with no account of its work.
+- Runs now snapshot both branch and `HEAD` before and after execution; branch changes, detached `HEAD`, and commit drift are treated as failures, with preflight refusal for a subsequent run when an abandoned run left repository state out of sync.
+- English-language prompts and runner/command output are shipped for the three dispatchers and their supporting commands.
+- Installation updates track installed file contents so outdated package files can be refreshed without overwriting hand edits unless `--force` is requested.
+
+### Fixed
+
+- Prevented environment and service writes from being misreported as delegated work while keeping them visible in run results.
+- Prevented different repositories with the same directory name from sharing run history.
+- Prevented malformed state files, including files with a byte-order mark, from silently bypassing abandoned-run detection, busy-tree locking, and chain lookup.
+- Fixed diagnostics to report the run folder actually used by the runner and to continue reporting remaining checks when a project marker is unreadable.
+- Fixed reported file paths to keep the spelling on disk instead of the case-folded form used for matching, so a reply names a path that exists on case-sensitive filesystems.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lyupro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# codex-bridge
+
+Delegate implementation, reconnaissance and code review from Claude Code to the
+[Codex CLI](https://developers.openai.com/codex/cli), so the work runs on a Codex
+subscription instead of the Claude one.
+
+## Install
+
+```bash
+npx @lyupro/codex-bridge install        # into ~/.claude
+node bin/codex-bridge.mjs install       # from a clone, same thing
+node bin/codex-bridge.mjs install --scope project   # into <repo>/.claude
+node bin/codex-bridge.mjs update        # bring an installation up to the current version
+node bin/codex-bridge.mjs doctor        # what is installed, where it points, is codex alive
+node bin/codex-bridge.mjs uninstall     # removes exactly what was installed
+node bin/codex-bridge.mjs stop <run>    # close a hanging run by hand, without hunting for a pid
+```
+
+`install` copies the package into the host's `agents/codex/`, its slash commands into
+`commands/codex/`, and registers the stop hook in `settings.json` — **merged**, so hooks that
+are already there survive, and the file is backed up before every write. Run it twice and the
+second run does nothing. `--dry-run` prints the plan and touches nothing.
+
+`update` moves an existing installation to the current version. It knows the sha256 of every file
+as it was installed, so it can tell a file you edited on the host from one left over by an older
+version: outdated files are refreshed silently, files you changed by hand stop the run and are
+named, and `--force` is what overwrites them. A file the package no longer ships is removed only
+if you never touched it.
+
+`uninstall` removes only what the install recorded: a file you put in `agents/codex/` yourself
+stays, and `codex-runs/` is never touched — those are your run artifacts, not the package.
+
+`stop` takes a run folder — a full path or a bare name from the current project's runs directory —
+kills that run's whole process tree and closes the folder the way an abandoned run is closed: a
+`FAIL` verdict naming what the run left in the worktree. A run that already has a verdict is left
+alone. Runs end on their own time budget now, so this is for the case where something wedged
+anyway.
+
+Run artifacts live in `codex-runs/<project>/`, one folder per repository, marked with a
+`.project.json` holding that repository's path. Two checkouts that share a directory name — two
+different `api` — therefore get `api` and `api-2` instead of one mixed history. `doctor` prints
+which folder the current repository writes to.
+
+## What it gives you
+
+- **Three dispatcher agents** for Claude Code — reconnaissance (read-only), implementation
+  (write access limited to a declared scope), and an independent review by a second model.
+- **A runner that survives a dropped call.** The launcher hands the run to a detached
+  worker, so a killed dispatcher no longer leaves the work unexplainable: the run folder is
+  closed with artifacts either way.
+- **A verdict that checks the report against the worktree.** The agent's own account of what
+  it changed is compared with what git says actually changed, and a mismatch is a failed run
+  rather than a nicer-sounding summary.
+- **A stop hook** that refuses a dispatcher reply which does not match the recorded state of
+  the run.
+
+## Requirements
+
+- Node.js >= 24 (the file-size gate uses `fs.glob`, the test runner uses directory globs)
+- The `codex` CLI, authenticated (`codex --version`, `codex login`)
+- Claude Code, for the agents and the hook to be registered in
+
+No runtime dependencies: everything here is plain `.mjs` on the Node standard library, and
+that is deliberate — installing from a clone stays one command, with no build step.
+
+## Development
+
+```bash
+git clone https://github.com/lyupro/codex-bridge.git
+cd codex-bridge
+git config core.hooksPath .githooks   # pre-commit file-size gate, 400 lines per source file
+npm test                              # node --test, no dependencies to install
+```
+
+## License
+
+MIT

package/bin/codex-bridge.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/** Dispatches codex-bridge CLI arguments to focused command modules. */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { diagnose, renderDoctor } from '../cli/doctor.mjs';
+import { resolveHost } from '../cli/hosts.mjs';
+import { install } from '../cli/install.mjs';
+import { packageInfo } from '../cli/manifest.mjs';
+import { stop } from '../cli/stop.mjs';
+import { uninstall } from '../cli/uninstall.mjs';
+import { update } from '../cli/update.mjs';
+
+export const HELP = `codex-bridge — Claude Code dispatchers for Codex
+
+Usage:
+  codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
+  codex-bridge doctor [--scope user|project] [--host <path>]
+  codex-bridge stop <run>
+  codex-bridge --help
+  codex-bridge --version
+
+Commands:
+  install   Install codex-bridge into the selected Claude Code host
+  update    Update a recorded codex-bridge installation
+  uninstall Remove installed files while preserving run artifacts
+  doctor    Diagnose the selected Claude Code host
+  stop      Stop a running Codex run and record FAIL`;
+
+function commandOptions(command, argv) {
+  const options = {};
+  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
+    : command === 'uninstall' ? new Set(['--dry-run']) : new Set();
+  const flagNames = new Map([
+    ['--dry-run', 'dryRun'],
+    ['--force', 'force'],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (booleanFlags.has(arg)) {
+      options[flagNames.get(arg)] = true;
+      continue;
+    }
+    if (arg !== '--scope' && arg !== '--host') throw new Error(`unknown ${command} option "${arg}"`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+    options[arg === '--scope' ? 'scope' : 'host'] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export async function main(argv, io = console) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h') {
+    io.log(HELP);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    io.log((await packageInfo()).version);
+    return 0;
+  }
+  if (command === 'doctor') {
+    const host = resolveHost(commandOptions(command, rest));
+    const result = await diagnose({ host });
+    io.log(renderDoctor(result));
+    return result.exitCode;
+  }
+  if (command === 'stop') {
+    if (rest.length !== 1) {
+      io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
+      return 2;
+    }
+    const result = await stop({ run: rest[0] });
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'install' || command === 'update' || command === 'uninstall') {
+    const options = commandOptions(command, rest);
+    const host = resolveHost(options);
+    const handlers = {
+      install: () => install({ host, dryRun: options.dryRun, force: options.force }),
+      update: () => update({ host, dryRun: options.dryRun, force: options.force }),
+      uninstall: () => uninstall({ host, dryRun: options.dryRun }),
+    };
+    const result = await handlers[command]();
+    io.log(result.output);
+    return result.exitCode;
+  }
+  io.error(`codex-bridge: unknown command "${command}"\nRun codex-bridge --help for usage.`);
+  return 2;
+}
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
+  main(process.argv.slice(2))
+    .then((exitCode) => { process.exitCode = exitCode; })
+    .catch((err) => {
+      console.error(`codex-bridge: ${err.message}`);
+      process.exitCode = 2;
+    });
+}

package/cli/copy.mjs

@@ -0,0 +1,38 @@
+/** Copies planned install files atomically and compares their rendered contents. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replacePlaceholders } from './manifest.mjs';
+
+export async function plannedContent(item, agentsDir) {
+  const source = await fs.readFile(item.source);
+  if (item.processing === 'copy') return source;
+  if (item.processing === 'placeholders') {
+    return Buffer.from(replacePlaceholders(source.toString('utf8'), agentsDir));
+  }
+  throw new Error(`unknown install processing "${item.processing}"`);
+}
+
+export async function targetMatches(item, agentsDir) {
+  const expected = await plannedContent(item, agentsDir);
+  try {
+    const actual = await fs.readFile(item.target);
+    return actual.equals(expected);
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'EISDIR') return false;
+    throw err;
+  }
+}
+
+export async function copyPlannedFile(item, agentsDir) {
+  const content = await plannedContent(item, agentsDir);
+  await fs.mkdir(path.dirname(item.target), { recursive: true });
+  const temporary = path.join(path.dirname(item.target), `.${path.basename(item.target)}.${randomUUID()}.tmp`);
+  try {
+    await fs.writeFile(temporary, content, { flag: 'wx' });
+    await fs.rename(temporary, item.target);
+  } catch (err) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw err;
+  }
+}

package/cli/doctor.mjs

@@ -0,0 +1,170 @@
+/** Diagnoses a Claude Code host without modifying it. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileFingerprint, readInstallRecord, packageInfo } from './manifest.mjs';
+import { runsRoot } from '../src/runner/runs-root.mjs';
+import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(target) {
+  try {
+    return (await fs.stat(target)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function check(key, status, value) {
+  return { key, status, value };
+}
+
+/**
+ * The runner asks git for the repository root before it picks a runs folder, so doctor has to
+ * ask the same question: run from `src/runner`, a plain cwd would name the folder `runner` and
+ * report a location no run will ever use.
+ */
+function repoRoot(cwd) {
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : cwd;
+}
+
+/**
+ * A marker that cannot be read is exactly what doctor exists to report, so it is caught here.
+ * Left to propagate it would kill the whole diagnosis and hide the seven checks around it.
+ */
+function projectRunsCheck() {
+  let resolved;
+  try {
+    resolved = resolveProjectRunsDir(runsRoot(), repoRoot(process.cwd()), { create: false });
+  } catch (err) {
+    return check('projectRuns', 'fail', err.message);
+  }
+  const note = resolved.reason === 'created' ? 'not created yet' : resolved.reason;
+  return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
+}
+
+function hookCommands(value) {
+  if (Array.isArray(value)) return value.flatMap(hookCommands);
+  if (value && typeof value === 'object') {
+    const own = value.type === 'command' && typeof value.command === 'string' ? [value.command] : [];
+    return [...own, ...Object.values(value).filter((child) => child !== value.command).flatMap(hookCommands)];
+  }
+  return [];
+}
+
+function commandReferences(command, expected) {
+  const normalizedExpected = path.resolve(expected).split(path.sep).join('/');
+  const tokens = [...command.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)]
+    .map((match) => match[1] ?? match[2] ?? match[3]);
+  return tokens.some((token) => path.resolve(token).split(path.sep).join('/') === normalizedExpected);
+}
+
+export function probeCodex() {
+  const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
+  const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'];
+  const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) {
+    return { available: false, value: (result.stderr || result.error?.message || 'not found').trim() };
+  }
+  return { available: true, value: (result.stdout || result.stderr).trim() };
+}
+
+async function hookCheck(host, record) {
+  if (!record) return check('hook', 'warn', 'cannot check before installation');
+  let settings;
+  try {
+    settings = JSON.parse(await fs.readFile(host.settingsPath, 'utf8'));
+  } catch (err) {
+    const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
+    return check('hook', 'warn', value);
+  }
+  const registration = settings?.hooks?.SubagentStop;
+  if (!registration) return check('hook', 'warn', 'SubagentStop is not registered');
+  const expected = path.resolve(host.root, record.hook.path);
+  const commands = hookCommands(registration);
+  const pointsToGuard = commands.some((command) => commandReferences(command, expected));
+  return pointsToGuard
+    ? check('hook', 'ok', `SubagentStop -> ${expected}`)
+    : check('hook', 'warn', 'SubagentStop does not point to the installed reply-guard.mjs');
+}
+
+async function rulesCheck(record) {
+  if (!record) return check('rules', 'warn', 'cannot check before installation');
+  if (!record.rules) {
+    return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
+  }
+  const fingerprint = await fileFingerprint(record.rules.path);
+  if (!fingerprint) return check('rules', 'fail', record.rules.path);
+  return fingerprint === record.rules.fingerprint
+    ? check('rules', 'ok', `${record.rules.path} (matches record)`)
+    : check('rules', 'warn', `${record.rules.path} (modified after installation)`);
+}
+
+export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
+  const checks = [];
+  const hostExists = await exists(host.root);
+  checks.push(check('host', hostExists ? 'ok' : 'warn', `${host.root} (${host.scope}, ${hostExists ? 'exists' : 'absent'})`));
+
+  const ownPackage = currentPackage || await packageInfo();
+  let record = null;
+  let recordBroken = false;
+  try {
+    record = await readInstallRecord(host);
+    if (!record) checks.push(check('installation', 'fail', 'not installed'));
+    else {
+      const matches = record.name === ownPackage.name && record.version === ownPackage.version;
+      checks.push(check(
+        'installation',
+        matches ? 'ok' : 'warn',
+        `${record.name}@${record.version} (${matches ? 'matches package' : `package is ${ownPackage.name}@${ownPackage.version}`})`,
+      ));
+    }
+  } catch (err) {
+    recordBroken = true;
+    checks.push(check('installation', 'fail', `broken record: ${err.message}`));
+  }
+
+  const missingFiles = [];
+  if (record) {
+    for (const relative of record.files) {
+      if (!(await isFile(path.join(host.root, relative)))) missingFiles.push(relative);
+    }
+  }
+  checks.push(check(
+    'files',
+    !record ? 'warn' : missingFiles.length ? 'fail' : 'ok',
+    !record ? 'not checked' : missingFiles.length ? `missing: ${missingFiles.join(', ')}` : `${record.files.length} installed file(s) present`,
+  ));
+  const rules = await rulesCheck(record);
+  checks.push(rules);
+  checks.push(await hookCheck(host, record));
+
+  const codex = codexProbe();
+  checks.push(check('codex', codex.available ? 'ok' : 'warn', codex.value || 'available'));
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
+  checks.push(check('node', nodeMajor >= 24 ? 'ok' : 'fail', `${process.versions.node} (requires >=24)`));
+  checks.push(check('runsRoot', 'ok', path.resolve(runsRoot())));
+  const projectRuns = projectRunsCheck();
+  checks.push(projectRuns);
+
+  return {
+    exitCode: !record || recordBroken || missingFiles.length || rules.status === 'fail'
+      || projectRuns.status === 'fail' ? 1 : 0,
+    checks,
+    record,
+    missingFiles,
+  };
+}
+
+export function renderDoctor(result) {
+  return result.checks.map(({ key, status, value }) => `[${status}] ${key}: ${value}`).join('\n');
+}

package/cli/hosts.mjs

@@ -0,0 +1,50 @@
+/** Resolves Claude Code host paths without touching the filesystem. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function repositoryRoot(start) {
+  let current = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(start);
+    current = parent;
+  }
+}
+
+export function resolveHost({
+  scope = 'user',
+  host,
+  cwd = process.cwd(),
+  homedir = os.homedir(),
+  codexHome,
+} = {}) {
+  const resolvedCodexHome = codexHome || process.env.CODEX_HOME || path.join(homedir, '.codex');
+  const codexRulesDir = path.join(resolvedCodexHome, 'rules');
+  if (host) {
+    const root = path.resolve(host);
+    return {
+      root,
+      agentsDir: path.join(root, 'agents', 'codex'),
+      commandsDir: path.join(root, 'commands', 'codex'),
+      codexRulesDir,
+      settingsPath: path.join(root, 'settings.json'),
+      scope: 'host',
+    };
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    throw new Error(`unknown scope "${scope}": expected user or project`);
+  }
+  const root = path.resolve(
+    scope === 'project' ? path.join(repositoryRoot(cwd), '.claude') : path.join(homedir, '.claude'),
+  );
+  return {
+    root,
+    agentsDir: path.join(root, 'agents', 'codex'),
+    commandsDir: path.join(root, 'commands', 'codex'),
+    codexRulesDir,
+    settingsPath: path.join(root, 'settings.json'),
+    scope,
+  };
+}

package/cli/install.mjs

@@ -0,0 +1,109 @@
+/** Installs codex-bridge files and its host hook with conflict-safe idempotency. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  buildInstallPlan,
+  fileFingerprint,
+  packageInfo,
+  readInstallRecord,
+  recordMatchesPackage,
+  rulesPlan,
+  seedPlan,
+  writeInstallRecord,
+} from './manifest.mjs';
+import { copyPlannedFile, targetMatches } from './copy.mjs';
+import { inspectHook, mergeHook } from './settings-merge.mjs';
+
+async function targetExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
+  const plan = await buildInstallPlan(host, packageRoot);
+  const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
+  const currentPackage = await packageInfo(packageRoot);
+  const record = await readInstallRecord(host);
+  const inspectedHook = await inspectHook(
+    host.settingsPath,
+    path.join(host.agentsDir, 'hooks', 'reply-guard.mjs'),
+  );
+  const states = await Promise.all(plan.map(async (item) => ({
+    item,
+    exists: await targetExists(item.target),
+    matches: await targetMatches(item, host.agentsDir),
+    fingerprint: await fileFingerprint(item.target),
+  })));
+  const ruleState = {
+    item: rule,
+    exists: await targetExists(rule.target),
+    matches: await targetMatches(rule, host.agentsDir),
+    fingerprint: await fileFingerprint(rule.target),
+  };
+  const conflicts = [
+    ...states.filter((state) => state.exists && !state.matches
+      && (!record || (record.fingerprints
+        && record.fingerprints[state.item.relativeToHost] !== state.fingerprint))),
+    ...(ruleState.exists && !ruleState.matches
+      && (!record?.rules || record.rules.fingerprint !== ruleState.fingerprint) ? [ruleState] : []),
+  ];
+  if (conflicts.length && !force) {
+    const files = conflicts.map(({ item }) => `  ${item.relativeToHost || item.name}`).join('\n');
+    return {
+      exitCode: 1,
+      output: `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`,
+    };
+  }
+
+  const changedFiles = states.filter((state) => !state.matches);
+  const changedRule = !ruleState.matches;
+  const sameRecord = recordMatchesPackage(record, plan, currentPackage,
+    new Map(states.map((state) => [state.item.relativeToHost, state.fingerprint])),
+    { path: rule.target, fingerprint: ruleState.fingerprint });
+  if (!changedFiles.length && !changedRule && inspectedHook.present && sameRecord) {
+    return { exitCode: 0, output: 'codex-bridge is already installed; nothing to do.' };
+  }
+
+  if (dryRun) {
+    const lines = changedFiles.map(({ item, exists }) =>
+      `${exists ? 'Would overwrite' : 'Would create'} ${item.relativeToHost}`);
+    if (changedRule) {
+      lines.push(`${ruleState.exists ? 'Would overwrite' : 'Would create'} ${rule.target}`);
+    }
+    lines.push(inspectedHook.present ? 'Hook is already registered.' : 'Would register SubagentStop hook.');
+    lines.push('Would write installation record.');
+    return { exitCode: 0, output: lines.join('\n') };
+  }
+
+  for (const { item } of changedFiles) await copyPlannedFile(item, host.agentsDir);
+  if (changedRule) await copyPlannedFile(rule, host.agentsDir);
+  // Seeded files are written once and then belong to the operator: an existing one is left
+  // exactly as it is, including under --force, because --force is about our files, not theirs.
+  for (const seed of seedPlan(host, packageRoot)) {
+    if (!(await targetExists(seed.target))) await copyPlannedFile(seed, host.agentsDir);
+  }
+  const hookResult = await mergeHook(
+    host.settingsPath,
+    path.join(host.agentsDir, 'hooks', 'reply-guard.mjs'),
+    inspectedHook,
+  );
+  const hookRelative = plan.find((item) => path.basename(item.target) === 'reply-guard.mjs')?.relativeToHost;
+  if (!hookRelative) throw new Error('install plan does not contain hooks/reply-guard.mjs');
+  const fingerprints = Object.fromEntries(await Promise.all(plan.map(async (item) =>
+    [item.relativeToHost, await fileFingerprint(item.target)])));
+  await writeInstallRecord(host, {
+    ...currentPackage,
+    installedAt: new Date().toISOString(),
+    mode: 'copy',
+    files: plan.map((item) => item.relativeToHost),
+    fingerprints,
+    rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
+    hook: { event: 'SubagentStop', path: hookRelative, createdGroup: hookResult.createdGroup || record?.hook?.createdGroup || false },
+  });
+  return { exitCode: 0, output: `Installed ${plan.length + 1} files and registered the SubagentStop hook.` };
+}