@lyupro/codex-bridge 0.3.1 → 0.5.0

package/cli/hook.mjs

@@ -0,0 +1,34 @@
+/** Dispatches a named host hook without changing the guard's stdin or process lifecycle. */
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+
+const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'hooks');
+const VALID_NAMES = HOOK_DEFINITIONS.map(({ name }) => name);
+
+function validNames() {
+  return VALID_NAMES.join(', ');
+}
+
+function usageError(io, message) {
+  io.error(`codex-bridge hook ${message} Valid hook names: ${validNames()}.`);
+  return 2;
+}
+
+export async function hook(args = [], io = console) {
+  if (!Array.isArray(args) || args.length !== 1) {
+    const detail = Array.isArray(args) && args.length
+      ? `accepts exactly one hook name; received ${args.length}.`
+      : 'requires exactly one hook name.';
+    return usageError(io, detail);
+  }
+
+  const definition = HOOK_DEFINITIONS.find(({ name }) => name === args[0]);
+  if (!definition) return usageError(io, `unknown hook name "${args[0]}".`);
+
+  // Plan_25 replaces absolute paths in foreign settings.json with this command. Importing the
+  // proven top-level script keeps its stdin reader and process.exit() contract intact; exporting
+  // guard functions would be a second implementation of the live hook boundary.
+  await import(pathToFileURL(path.join(HOOKS_DIR, definition.file)).href);
+  return typeof process.exitCode === 'number' ? process.exitCode : 0;
+}

package/cli/hosts.mjs

@@ -13,24 +13,48 @@ function repositoryRoot(start) {
   }
 }
 
+function claudePaths(root) {
+  return {
+    agentsDir: path.join(root, 'agents', 'codex-bridge'),
+    commandsDir: path.join(root, 'commands', 'codex-bridge'),
+    legacyAgentsDir: path.join(root, 'agents', 'codex'),
+    legacyCommandsDir: path.join(root, 'commands', 'codex'),
+  };
+}
+
 export function resolveHost({
   scope = 'user',
   host,
   cwd = process.cwd(),
   homedir = os.homedir(),
   codexHome,
+  brandRoot,
 } = {}) {
   const resolvedCodexHome = codexHome || process.env.CODEX_HOME || path.join(homedir, '.codex');
   const codexRulesDir = path.join(resolvedCodexHome, 'rules');
+  // Plan_25 moves package-owned runtime files out of foreign Claude settings, whose absolute
+  // hook paths caused the package-file-layout incident. Keep the brand root overrideable so tests
+  // and later installation steps never need to know the operator's home directory.
+  const resolvedBrandRoot = path.resolve(
+    brandRoot || process.env.CODEX_BRIDGE_HOME || path.join(homedir, '.lyupro', '.codex-bridge'),
+  );
+  const brandPaths = {
+    brandRoot: resolvedBrandRoot,
+    brandHooksDir: path.join(resolvedBrandRoot, 'hooks'),
+    brandRunnerDir: path.join(resolvedBrandRoot, 'lib'),
+    brandConfigPath: path.join(resolvedBrandRoot, 'config.json'),
+    brandConventionsPath: path.join(resolvedBrandRoot, 'conventions.md'),
+    brandInstallRecordPath: path.join(resolvedBrandRoot, '.installed.json'),
+  };
   if (host) {
     const root = path.resolve(host);
     return {
       root,
-      agentsDir: path.join(root, 'agents', 'codex'),
-      commandsDir: path.join(root, 'commands', 'codex'),
+      ...claudePaths(root),
       codexRulesDir,
       settingsPath: path.join(root, 'settings.json'),
       scope: 'host',
+      ...brandPaths,
     };
   }
   if (scope !== 'user' && scope !== 'project') {
@@ -41,10 +65,10 @@ export function resolveHost({
   );
   return {
     root,
-    agentsDir: path.join(root, 'agents', 'codex'),
-    commandsDir: path.join(root, 'commands', 'codex'),
+    ...claudePaths(root),
     codexRulesDir,
     settingsPath: path.join(root, 'settings.json'),
     scope,
+    ...brandPaths,
   };
 }

package/cli/install-record.mjs

@@ -0,0 +1,287 @@
+/** Reads, validates, and writes the installation record shared by installer commands. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readJsonFile } from '../src/json-file.mjs';
+import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+
+export const INSTALL_RECORD_NAME = '.installed.json';
+export const LEGACY_INSTALL_RECORD_NAME = '.codex-bridge-install.json';
+export const RULES_NAME = 'codex-bridge.rules';
+
+const ROOTS = new Set(['claude', 'brand']);
+
+const posix = (value) => value.split(path.sep).join('/');
+
+export function fileEntry(file) {
+  if (typeof file === 'string') return { root: 'claude', path: file };
+  // Plan items carry the same root but call the relative field relativeToRoot; normalizing that
+  // shape here keeps matching, fingerprint lookup, and display on one record-key contract.
+  if (file?.path === undefined && file?.relativeToRoot !== undefined) {
+    return { root: file.root, path: file.relativeToRoot };
+  }
+  return file;
+}
+
+export function recordFileKey(file) {
+  const entry = fileEntry(file);
+  return `${entry.root}:${entry.path}`;
+}
+
+export function recordTarget(host, file) {
+  const entry = fileEntry(file);
+  const root = entry.root === 'brand' ? host.brandRoot : host.root;
+  if (!root) throw new Error(`host has no ${entry.root} installation root`);
+  return path.join(root, entry.path);
+}
+
+export function recordRelativeToHost(host, file) {
+  return posix(path.relative(host.root, recordTarget(host, file)));
+}
+
+export function definitionForRecordedHook(hook) {
+  return HOOK_DEFINITIONS.find((definition) => definition.event === hook?.event
+    && path.basename(String(hook?.path ?? '')) === definition.file);
+}
+
+function validPath(value, label) {
+  if (typeof value !== 'string' || !value) throw new Error(`${label} must be a non-empty string`);
+  if (path.isAbsolute(value) || value.split(/[\\/]/).some((part) => part === '..' || part === '.')) {
+    throw new Error(`${label} must stay relative to its installation root`);
+  }
+  return value;
+}
+
+function normalizedFiles(record) {
+  if (!Array.isArray(record.files) || !record.files.length) {
+    throw new Error('installation record files must be a non-empty list');
+  }
+  const files = record.files.map((file) => {
+    const entry = fileEntry(file);
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error('installation record files must contain root and path entries');
+    }
+    if (!ROOTS.has(entry.root)) throw new Error('installation record file root must be claude or brand');
+    validPath(entry.path, 'installation record file path');
+    // 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 (entry.path === 'codex-runs' || entry.path.split(/[\\/]/)[0] === 'codex-runs') {
+      throw new Error('installation record files must not name run artifacts under codex-runs');
+    }
+    return { root: entry.root, path: entry.path };
+  });
+  if (new Set(files.map(recordFileKey)).size !== files.length) {
+    throw new Error('installation record files must not contain duplicates');
+  }
+  return files;
+}
+
+function fingerprintPairs(files, fingerprints) {
+  if (!fingerprints || typeof fingerprints !== 'object' || Array.isArray(fingerprints)) {
+    throw new Error('installation record fingerprints must be an object');
+  }
+  const fingerprintKeys = Object.keys(fingerprints);
+  const nested = fingerprintKeys.some((key) => ROOTS.has(key));
+  const pairs = files.map((file) => [file, nested
+    ? fingerprints[file.root]?.[file.path]
+    : file.root === 'claude' ? fingerprints[file.path] : undefined]);
+  if (!nested) {
+    if (files.some((file) => file.root !== 'claude')
+      || fingerprintKeys.length !== files.length
+      || files.some((file) => !Object.hasOwn(fingerprints, file.path))) {
+      throw new Error('installation record fingerprints keys must exactly match files');
+    }
+  } else {
+    const expectedRoots = new Set(files.map((file) => file.root));
+    const actualRoots = new Set(fingerprintKeys);
+    if (fingerprintKeys.some((root) => !ROOTS.has(root))
+      || actualRoots.size !== expectedRoots.size
+      || [...actualRoots].some((root) => !expectedRoots.has(root))
+      || [...expectedRoots].some((root) => {
+        const expected = files.filter((file) => file.root === root).map((file) => file.path);
+        const actual = Object.keys(fingerprints[root] ?? {});
+        return actual.length !== expected.length || expected.some((file) => !actual.includes(file));
+      })) {
+      throw new Error('installation record fingerprints keys must exactly match files');
+    }
+  }
+  if (pairs.some(([, fingerprint]) => fingerprint === undefined)) {
+    throw new Error('installation record fingerprints keys must exactly match files');
+  }
+  if (pairs.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');
+  }
+  return pairs;
+}
+
+function validateHooks(record, files) {
+  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);
+    const entry = fileEntry(hook.root ? hook : { root: 'claude', path: hook.path });
+    if (!definitions.length || typeof entry.path !== 'string' || !entry.path) {
+      throw new Error('installation record hook must identify a supported event and its path');
+    }
+    if (!ROOTS.has(entry.root)) throw new Error('installation record hook root must be claude or brand');
+    validPath(entry.path, 'installation record hook path');
+    const definition = definitions.find((candidate) => path.basename(entry.path) === candidate.file);
+    if (!definition || !files.some((file) => recordFileKey(file) === recordFileKey(entry))) {
+      const names = definitions.map((candidate) => candidate.file).join(' or ');
+      throw new Error(`installation record hook path must name the installed ${names}`);
+    }
+  }
+}
+
+export function validateInstallRecord(record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new Error('installation record must be an object');
+  }
+  for (const key of ['name', 'version', 'installedAt', 'mode']) {
+    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');
+  const files = normalizedFiles(record);
+  if (record.fingerprints !== undefined) fingerprintPairs(files, record.fingerprints);
+  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');
+    }
+  }
+  validateHooks(record, files);
+  return record;
+}
+
+function normalizedHook(hook) {
+  return hook.root ? { ...hook, root: hook.root, path: hook.path }
+    : { ...hook, root: 'claude', path: hook.path };
+}
+
+function normalizedFingerprints(files, fingerprints) {
+  if (fingerprints === undefined) return undefined;
+  const pairs = fingerprintPairs(files, fingerprints);
+  const result = {};
+  for (const [file, fingerprint] of pairs) {
+    result[file.root] ??= {};
+    result[file.root][file.path] = fingerprint;
+  }
+  return result;
+}
+
+export function normalizeInstallRecord(record) {
+  validateInstallRecord(record);
+  const files = normalizedFiles(record);
+  const hooks = record.hooks !== undefined ? record.hooks : [record.hook];
+  const { hook: _legacyHook, ...withoutLegacyHook } = record;
+  const normalized = {
+    ...withoutLegacyHook,
+    files,
+    hooks: hooks.map(normalizedHook),
+  };
+  const fingerprints = normalizedFingerprints(files, record.fingerprints);
+  if (fingerprints !== undefined) normalized.fingerprints = fingerprints;
+  return normalized;
+}
+
+function legacySeedEntries(host) {
+  const agentDirs = [host.agentsDir, host.legacyAgentsDir].filter(Boolean);
+  return new Set(agentDirs.flatMap((agentsDir) => [
+    { root: 'claude', path: posix(path.relative(host.root, path.join(agentsDir, 'run-config.json'))) },
+    { root: 'claude', path: posix(path.relative(host.root, path.join(agentsDir, 'conventions.md'))) },
+  ]).map(recordFileKey));
+}
+
+function newSeedEntries() {
+  return new Set(['brand:config.json', 'brand:conventions.md']);
+}
+
+function withoutSeededFiles(host, record) {
+  const seeded = new Set([...legacySeedEntries(host), ...newSeedEntries()]);
+  record.files = record.files.filter((file) => !seeded.has(recordFileKey(file)));
+  if (record.fingerprints) {
+    const fingerprints = {};
+    for (const file of record.files) {
+      const value = record.fingerprints[file.root]?.[file.path];
+      if (value !== undefined) {
+        fingerprints[file.root] ??= {};
+        fingerprints[file.root][file.path] = value;
+      }
+    }
+    record.fingerprints = fingerprints;
+  }
+  return record;
+}
+
+async function readAt(recordPath) {
+  try {
+    return await readJsonFile(recordPath);
+  } 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;
+  }
+}
+
+export function installRecordPath(host) {
+  return host.brandInstallRecordPath || path.join(host.brandRoot, INSTALL_RECORD_NAME);
+}
+
+export function legacyInstallRecordPath(host) {
+  return path.join(host.legacyAgentsDir, LEGACY_INSTALL_RECORD_NAME);
+}
+
+export async function readInstallRecord(host) {
+  const parsed = await readAt(installRecordPath(host));
+  const legacy = parsed === null ? await readAt(legacyInstallRecordPath(host)) : null;
+  if (parsed === null && legacy === null) return null;
+  return withoutSeededFiles(host, normalizeInstallRecord(parsed ?? legacy));
+}
+
+export async function writeInstallRecord(host, record) {
+  const normalized = normalizeInstallRecord(record);
+  const target = installRecordPath(host);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(normalized, null, 2)}\n`);
+}
+
+export function fingerprintFor(record, file) {
+  const entry = fileEntry(file);
+  if (!record?.fingerprints) return undefined;
+  if (record.fingerprints[entry.root]?.[entry.path] !== undefined) {
+    return record.fingerprints[entry.root][entry.path];
+  }
+  return entry.root === 'claude' ? record.fingerprints[entry.path] : undefined;
+}
+
+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) => recordFileKey(file) === recordFileKey(plan[index]))
+    && Boolean(record.fingerprints)
+    && plan.every((item) => fingerprintFor(record, item) === fingerprints.get(recordFileKey(item)))
+    && (!ruleState || (record.rules?.path === ruleState.path
+      && record.rules.fingerprint === ruleState.fingerprint));
+}

package/cli/install.mjs

@@ -1,4 +1,4 @@
-/** Installs codex-bridge files and its host hook with conflict-safe idempotency. */
+/** Installs codex-bridge files into the Claude and brand roots with conflict-safe idempotency. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
@@ -7,6 +7,7 @@ import {
   HOOK_DEFINITIONS,
   installedHookPath,
   packageInfo,
+  recordFileKey,
   readInstallRecord,
   recordMatchesPackage,
   rulesPlan,
@@ -14,7 +15,15 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
+import { hookTargets } from './hook-targets.mjs';
+import { fingerprintFor } from './install-record.mjs';
+import {
+  commandFor,
+  hookRegistration,
+  inspectHook,
+  mergeHook,
+  withSettingsRun,
+} from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
 
@@ -31,26 +40,14 @@ async function targetExists(target) {
   }
 }
 
-function hookTargets(host) {
-  return HOOK_DEFINITIONS.map((definition) => {
-    const target = installedHookPath(host, definition);
-    return {
-      definition,
-      target,
-      relative: path.relative(host.root, target).split(path.sep).join('/'),
-      spec: { event: definition.event, matcher: definition.matcher, command: commandFor(target) },
-    };
-  });
-}
-
 function recordHasHooks(record, targets) {
   return Boolean(record)
     && targets.every(({ definition, relative }) => record.hooks?.some((hook) =>
-      hook.event === definition.event && hook.path === relative));
+      hook.event === definition.event && hook.root === 'brand' && hook.path === relative));
 }
 
 function retentionLine(host) {
-  const notice = retentionNotice(readRunConfig(path.join(host.agentsDir, 'run-config.json')));
+  const notice = retentionNotice(readRunConfig(host.brandConfigPath));
   return notice.enabled ? `${WARNING}${notice.text}${RESET}` : notice.text;
 }
 
@@ -58,7 +55,24 @@ function retentionOutput(line, output) {
   return `${output}\n${line}`;
 }
 
-export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
+async function migrateLegacySeed(host, seed) {
+  if (await targetExists(seed.target)) return;
+  const legacyName = path.basename(seed.target) === 'config.json' ? 'run-config.json' : path.basename(seed.target);
+  const legacy = path.join(host.legacyAgentsDir, legacyName);
+  if (legacy === seed.target || !(await targetExists(legacy))) return;
+  // Existing seeded files hold operator decisions, so Plan_25 moves them rather than reading a
+  // fresh default: copy first, compare the bytes, and only then drop the old path. Leaving the old
+  // copy behind — the first version of this migration did — keeps agents/codex non-empty forever,
+  // so the previous layout is never taken down and the operator goes on editing a file nothing
+  // reads. If the comparison fails the old file stays: a half-copied config is the one case where
+  // having two is better than having none.
+  await fs.mkdir(path.dirname(seed.target), { recursive: true });
+  await fs.copyFile(legacy, seed.target);
+  if (await fileFingerprint(legacy) !== await fileFingerprint(seed.target)) return;
+  await fs.rm(legacy, { force: true });
+}
+
+async function installInRun({ host, dryRun = false, force = false, packageRoot, env = process.env } = {}) {
   // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
   await readRulesRegistry(host);
   const configuredRetentionLine = retentionLine(host);
@@ -66,9 +80,9 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
   const record = await readInstallRecord(host);
-  const targets = hookTargets(host);
+  const targets = hookTargets(host, env, currentPackage.version);
   for (const target of targets) {
-    if (!plan.some((item) => item.relativeToHost === target.relative)) {
+    if (!plan.some((item) => item.root === 'brand' && item.relativeToRoot === target.relative)) {
       throw new Error(`install plan does not contain hooks/${target.definition.file}`);
     }
   }
@@ -77,24 +91,24 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   const states = await Promise.all(plan.map(async (item) => ({
     item,
     exists: await targetExists(item.target),
-    matches: await targetMatches(item, host.agentsDir),
+    matches: await targetMatches(item, host.brandRoot),
     fingerprint: await fileFingerprint(item.target),
   })));
   const ruleState = {
     item: rule,
     exists: await targetExists(rule.target),
-    matches: await targetMatches(rule, host.agentsDir),
+    matches: await targetMatches(rule, host.brandRoot),
     fingerprint: await fileFingerprint(rule.target),
   };
   const conflicts = [
     ...states.filter((state) => state.exists && !state.matches
       && (!record || (record.fingerprints
-        && record.fingerprints[state.item.relativeToHost] !== state.fingerprint))),
+        && fingerprintFor(record, state.item) !== 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');
+    const files = conflicts.map(({ item }) => `  ${item.relativeToRoot || item.name}`).join('\n');
     return {
       exitCode: 1,
       output: retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`),
@@ -104,7 +118,7 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   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])),
+    new Map(states.map((state) => [recordFileKey(state.item), state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
   if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
     && recordHasHooks(record, targets) && sameRecord) {
@@ -114,17 +128,17 @@ export async function install({ host, dryRun = false, force = false, packageRoot
 
   if (dryRun) {
     const lines = changedFiles.map(({ item, exists }) =>
-      `${exists ? 'Would overwrite' : 'Would create'} ${item.relativeToHost}`);
+      `${exists ? 'Would overwrite' : 'Would create'} ${item.root}/${item.relativeToRoot}`);
     if (changedRule) {
       lines.push(`${ruleState.exists ? 'Would overwrite' : 'Would create'} ${rule.target}`);
     }
     inspectedHooks.forEach((state, index) => {
-      const { definition } = targets[index];
+      const { definition, registration } = targets[index];
       lines.push(state.present
-        ? `${definition.event} hook is already registered.`
-        : `Would register ${definition.event} hook for matcher ${definition.matcher}.`);
+        ? `${definition.event} hook is already registered (${registration.form} command).`
+        : `Would register ${definition.event} hook for matcher ${definition.matcher} with ${registration.form} command.`);
     });
-    lines.push('Would write installation record.');
+    lines.push('Would write installation record in the brand root.');
     return { exitCode: 0, output: retentionOutput(configuredRetentionLine, lines.join('\n')) };
   }
 
@@ -132,28 +146,42 @@ export async function install({ host, dryRun = false, force = false, packageRoot
   // failure at that step left a fully installed host absent from the registry, and the next
   // uninstall elsewhere would then delete the rules out from under it.
   await addRulesOwner(host);
-  for (const { item } of changedFiles) await copyPlannedFile(item, host.agentsDir);
-  if (changedRule) await copyPlannedFile(rule, host.agentsDir);
+  for (const { item } of changedFiles) await copyPlannedFile(item, host.brandRoot);
+  if (changedRule) await copyPlannedFile(rule, host.brandRoot);
   // 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);
+    if (!(await targetExists(seed.target))) {
+      await migrateLegacySeed(host, seed);
+      if (!(await targetExists(seed.target))) await copyPlannedFile(seed, host.brandRoot);
+    }
   }
   const hookResults = [];
   for (const { spec } of targets) hookResults.push(await mergeHook(host.settingsPath, spec));
-  const fingerprints = Object.fromEntries(await Promise.all(plan.map(async (item) =>
-    [item.relativeToHost, await fileFingerprint(item.target)])));
-  const hooks = targets.map(({ definition, relative }, index) => {
-    const prior = record?.hooks?.find((hook) => hook.event === definition.event);
+  const fingerprints = {};
+  for (const item of plan) {
+    fingerprints[item.root] ??= {};
+    fingerprints[item.root][item.relativeToRoot] = await fileFingerprint(item.target);
+  }
+  const hooks = targets.map(({ definition, relative, registration }, index) => {
+    const prior = record?.hooks?.find((hook) => hook.event === definition.event
+      && hook.root === 'brand' && hook.path === relative);
     const createdGroup = hookResults[index].createdGroup || prior?.createdGroup === true;
-    return createdGroup ? { event: definition.event, path: relative, createdGroup: true }
-      : { event: definition.event, path: relative };
+    const command = inspectedHooks[index].matchedCommand || registration.command;
+    return {
+      event: definition.event,
+      root: 'brand',
+      path: relative,
+      command,
+      form: command.startsWith('codex-bridge hook ') ? 'short' : 'path',
+      ...(createdGroup ? { createdGroup: true } : {}),
+    };
   });
   await writeInstallRecord(host, {
     ...currentPackage,
     installedAt: new Date().toISOString(),
     mode: 'copy',
-    files: plan.map((item) => item.relativeToHost),
+    files: plan.map((item) => ({ root: item.root, path: item.relativeToRoot })),
     fingerprints,
     rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
     hooks,
@@ -163,3 +191,9 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     output: retentionOutput(configuredRetentionLine, `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`),
   };
 }
+
+export async function install(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return installInRun(options);
+  return withSettingsRun(host.settingsPath, () => installInRun(options));
+}

package/cli/invoked-directly.mjs

@@ -0,0 +1,37 @@
+/** Decides whether this process was started as the CLI or merely imported by another module. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolves a path through symlinks, falling back to plain resolution when that is impossible.
+ *
+ * This is the one place in the package where symlinks are deliberately resolved. Everywhere else
+ * they are not — realpath returns `\\?\` and UNC spellings, and host paths are compared as written.
+ * Here the question is not which path a file has but whether two paths name the same file, and
+ * both sides go through the same function, so the exotic spellings match each other.
+ */
+function sameFileKey(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+/**
+ * True when argv[1] names this very module.
+ *
+ * Comparing the two paths as written looked equivalent until `npm i -g .` linked the global
+ * package at the clone: argv[1] then held the path inside the global node_modules while
+ * import.meta.url held the clone, because Node resolves the module's own URL through the link and
+ * argv[1] keeps the spelling used to start it. The comparison failed, main() never ran, and the
+ * CLI exited 0 having printed nothing. That silence was the dangerous part — every guard is a hook
+ * that must print a refusal to refuse anything, so five guards went on reporting `[ok]` in doctor
+ * while permitting everything the operator installed them to stop (2026-08-11).
+ */
+export function isInvokedDirectly(argv1, moduleUrl) {
+  if (!argv1 || !moduleUrl) return false;
+  const modulePath = moduleUrl.startsWith('file:') ? fileURLToPath(moduleUrl) : moduleUrl;
+  return sameFileKey(argv1) === sameFileKey(modulePath);
+}