@lyupro/codex-bridge 0.3.1 → 0.5.0

package/cli/manifest.mjs

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

package/cli/permissions.mjs

@@ -0,0 +1,179 @@
+/** Manages the optional shell permission rules for every codex-bridge command spelling. */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CLI_NAMES } from '../src/cli-names.mjs';
+import { SHELL_TOOLS } from '../src/hook-definitions.mjs';
+import { readSettings, updateSettings, withSettingsRun } from './settings-merge.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const entryPoint = fileURLToPath(new URL('../bin/codex-bridge.mjs', import.meta.url));
+const nodeCommand = `node ${path.relative(packageRoot, entryPoint).split(path.sep).join('/')}`;
+const commandNames = Object.freeze([...CLI_NAMES, nodeCommand]);
+const formsFor = (command) => [command, `${command}:*`];
+
+function buildRules(commandTransform) {
+  return Object.freeze(SHELL_TOOLS.flatMap((tool) => commandNames.flatMap((command) =>
+    formsFor(commandTransform(command)).map((form) => `${tool}(${form})`))));
+}
+
+/**
+ * The executable names stay owned by cli-names.mjs; only the clone entry point is derived here.
+ * Plan_22 records the incident because repeating the node spelling in CLI_NAMES would make the
+ * source list answer two different questions and let a future alias bypass one of them.
+ *
+ * The deny half subtracts `prune` from the allow half rather than guarding it: `Bash(codex-bridge:*)`
+ * would otherwise hand out the deletion this package refuses to give an agent. Its refusal is never
+ * seen in a live session — a PreToolUse hook answers before permissions are consulted, and
+ * prune-guard is installed always while these rules are optional. The 2026-08-09 run held that
+ * observation open as a checklist item until it turned out to be the answer, not the obstacle.
+ */
+export const PERMISSION_RULES = Object.freeze({
+  allow: buildRules((command) => command),
+  deny: buildRules((command) => `${command} prune`),
+});
+
+const allRules = new Set([...PERMISSION_RULES.allow, ...PERMISSION_RULES.deny]);
+const ruleLists = Object.freeze(['allow', 'deny', 'ask']);
+const activeLists = Object.freeze(['allow', 'deny']);
+const totalRules = PERMISSION_RULES.allow.length + PERMISSION_RULES.deny.length;
+
+function listValue(settings, name) {
+  const list = settings?.permissions?.[name];
+  return Array.isArray(list) ? list : [];
+}
+
+function matchingRules(list, rules) {
+  return rules.filter((rule) => list.includes(rule)).length;
+}
+
+/**
+ * A count of strings in allow and deny is not the state of the set, because `ask` outranks `allow`:
+ * a copy sitting there keeps asking the question the rule was added to end. The live run of
+ * Plan_22-1 caught doctor reporting `installed (24/24)` over exactly that arrangement — the number
+ * was true and the conclusion drawn from it was false. Every consumer reads the state, so the
+ * shadow has to live in the state rather than in one command's wording.
+ */
+function permissionStatus(settings) {
+  const counts = Object.fromEntries(activeLists.map((name) => [
+    name,
+    matchingRules(listValue(settings, name), PERMISSION_RULES[name]),
+  ]));
+  const askCount = matchingRules(listValue(settings, 'ask'), [...allRules]);
+  const present = counts.allow + counts.deny;
+  const complete = present === totalRules;
+  const state = askCount
+    ? (complete ? 'shadowed by ask' : 'partially installed, shadowed by ask')
+    : complete ? 'installed' : present === 0 ? 'absent' : 'partially installed';
+  return {
+    state,
+    complete,
+    counts,
+    askCount,
+    present,
+    total: totalRules,
+  };
+}
+
+function ensureList(settings, name) {
+  if (settings.permissions === undefined) settings.permissions = {};
+  if (!settings.permissions || typeof settings.permissions !== 'object'
+    || Array.isArray(settings.permissions)) {
+    throw new TypeError('settings.permissions must be an object');
+  }
+  if (settings.permissions[name] === undefined) settings.permissions[name] = [];
+  if (!Array.isArray(settings.permissions[name])) {
+    throw new TypeError(`settings.permissions.${name} must be an array`);
+  }
+  return settings.permissions[name];
+}
+
+function countRemovable(settings) {
+  return ruleLists.reduce((total, name) => total + listValue(settings, name)
+    .filter((entry) => allRules.has(entry)).length, 0);
+}
+
+export async function inspectPermissions(settingsPath) {
+  const state = await readSettings(settingsPath);
+  return { ...state, ...permissionStatus(state.settings) };
+}
+
+export async function addPermissionRules(settingsPath) {
+  return updateSettings(settingsPath, (settings) => {
+    let added = 0;
+    for (const name of activeLists) {
+      const list = ensureList(settings, name);
+      for (const rule of PERMISSION_RULES[name]) {
+        if (list.includes(rule)) continue;
+        list.push(rule);
+        added += 1;
+      }
+    }
+    return { changed: added > 0, added };
+  });
+}
+
+export async function removePermissionRules(settingsPath, { dryRun = false } = {}) {
+  if (dryRun) {
+    const state = await readSettings(settingsPath);
+    return { changed: false, removed: countRemovable(state.settings) };
+  }
+  return updateSettings(settingsPath, (settings) => {
+    let removed = 0;
+    for (const name of ruleLists) {
+      const list = settings?.permissions?.[name];
+      if (!Array.isArray(list)) continue;
+      settings.permissions[name] = list.filter((entry) => {
+        if (!allRules.has(entry)) return true;
+        removed += 1;
+        return false;
+      });
+    }
+    return { changed: removed > 0, removed };
+  });
+}
+
+function statusOutput(status) {
+  const moved = status.askCount
+    ? `; ${status.askCount} own string(s) in ask, which outranks allow`
+    : '';
+  return `Permissions: ${status.state} (${status.present}/${status.total} own strings in allow/deny${moved}).`;
+}
+
+async function permissionsInRun({ host, action } = {}) {
+  if (!host?.settingsPath) throw new TypeError('permissions requires a resolved host');
+  if (!action) {
+    const status = await inspectPermissions(host.settingsPath);
+    return { exitCode: 0, output: statusOutput(status), ...status };
+  }
+  if (action === 'add') {
+    const result = await addPermissionRules(host.settingsPath);
+    // A string the operator moved into `ask` outranks the copy `add` just put into `allow`, so the
+    // command would report a complete set while the questions it was run to end keep appearing.
+    // `ask` stays untouched — it is a hand-made decision — but silence about it is a false success.
+    const status = await inspectPermissions(host.settingsPath);
+    const conflict = status.askCount
+      ? ` ${status.askCount} own string(s) also sit in ask, which outranks allow; they were left there.`
+      : '';
+    return {
+      exitCode: 0,
+      output: `Added ${result.added} permission rule string${result.added === 1 ? '' : 's'}.${conflict}`,
+      ...result,
+      askCount: status.askCount,
+    };
+  }
+  if (action === 'remove') {
+    const result = await removePermissionRules(host.settingsPath);
+    return {
+      exitCode: 0,
+      output: `Removed ${result.removed} permission rule string${result.removed === 1 ? '' : 's'}.`,
+      ...result,
+    };
+  }
+  throw new Error(`unknown permissions action "${action}"`);
+}
+
+export async function permissions(options = {}) {
+  const host = options?.host;
+  if (!host?.settingsPath) return permissionsInRun(options);
+  return withSettingsRun(host.settingsPath, () => permissionsInRun(options));
+}

package/cli/projects.mjs

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

package/cli/prune-args.mjs

@@ -112,7 +112,7 @@ export function parsePruneArgs(argv = []) {
     if (invalid) return invalid;
   }
 
-  // The 30-day default belongs to the gentle sweep, which searches history for weight to shed.
+  // The 30-day default belongs to the gentle cleanup, which searches history for weight to shed.
   // A purge is never implicitly aged: `prune sbx2 --purge` means that folder, now. Defaulting it
   // made the plan's own fourth scenario unreachable — a young project answered "nothing to
   // remove", which reads as a broken command, not as a refusal.

package/cli/remove-layout.mjs

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

package/cli/rules-owners.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { normalizeRepoPath } from '../src/runner/project-dir.mjs';
+import { readJsonFile } from '../src/json-file.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
 export const RULES_REGISTRY_VERSION = 1;
@@ -40,19 +41,16 @@ function validateRegistry(parsed) {
 }
 
 async function loadRulesRegistry(host) {
-  let raw;
+  let parsed;
   try {
-    raw = await fs.readFile(rulesRegistryPath(host), 'utf8');
+    parsed = await readJsonFile(rulesRegistryPath(host));
   } catch (err) {
     if (err.code === 'ENOENT') return null;
+    if (err.cause) {
+      throw new Error(`invalid rules ownership registry JSON: ${err.cause.message}`, { cause: err.cause });
+    }
     throw err;
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`invalid rules ownership registry JSON: ${err.message}`);
-  }
   return { raw: parsed, registry: validateRegistry(parsed) };
 }