@lyupro/codex-bridge 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-08-09
+
+### Added
+
+- Scope patterns are checked before Codex starts. A pattern that cannot match anything — an
+  absolute or drive-qualified path, backslash separators, a `..` segment, or a spelling no
+  repository file answers to — is refused with no run folder and no quota spent, for all three
+  dispatchers. The file list comes from `git ls-files --cached --others --exclude-standard`, so
+  ignored output does not count as repository content. A file the run is meant to create is
+  declared with `--scope-new`, accepted only by `codex-build` and recorded in `worker.json`.
+- `codex-bridge permissions` reports, adds, and removes the optional shell permission rules for
+  both CLI names and the clone entry point. The exact allow and deny strings merge into
+  `settings.json`, preserve foreign rules, and are also removed by `uninstall`; `doctor` reports
+  an absent or partial set as an optional warning.
+
+### Changed
+
+- `codex-bridge sweep` is now `codex-bridge unlock`. The default scope is the current repository;
+  a bare project name remains addressable, and `--all` is now required for the whole store. The
+  report shows age, silence, and `alive` / `dead` / `foreign` / `unverified` identity verdicts;
+  confirmed-alive records are refused with `codex-bridge stop <run>` instead of being closed.
+
+### Fixed
+
+- Run records now verify that a pid still belongs to the process that started the run, using the
+  process start time and a fresh heartbeat before falling back to an OS probe. A reused or
+  unverified pid is never signalled by `stop`; `codex-bridge unlock` remains the non-killing way to
+  close a record whose process identity cannot be confirmed.
+- JSON files written by PowerShell with a UTF-8 BOM are now read consistently by the CLI and
+  installed hooks, and one command run creates at most one settings backup without deleting older
+  backups.
+- A run a guard refused before Codex ever started no longer costs the next attempt a round trip. Such a folder now closes as `aborted_pre_start` instead of the same `failed` a twenty-minute paid run gets, and the chain gate, the continuation limit and the tree baseline all skip it: the same order id starts as a first run, silently, with no `continue:` grant. Reported from a parallel `codex-build` launch — the second run was correctly refused with "two writing runs in one tree are prohibited", and its one-millisecond folder then made the retry demand a grant for work that never happened. Folders written before this release are recognised by what `meta.json` records — `exit`, `session_id`, `events_bytes`, `stderr_bytes`, `tokens_reported` — rather than by whether `events.jsonl` is still on disk, because retention deletes that file from paid runs too. The folder itself is kept: it is the audit trail of who was refused and why.
+- `chainBaseline()` takes the first run of the chain that actually started, so a pre-start folder sorting first no longer leaves the next pass without the `state-before.txt` its work is measured against.
+- `uninstall --dry-run` names each hook by its own matcher. Three of the four hooks are PreToolUse,
+  and a lookup by event alone reported `Agent|Task` for the worktree lock and the prune guard too —
+  in the one line an operator reads to see what a removal is about to touch. The removal itself was
+  never affected: hooks are found by command, not by matcher.
+- The order gate's refusal now shows the line it found. A caller who wrote
+  `scope (you may create/modify ONLY these):` was told scope was missing, re-read their own prompt,
+  saw it written there, and had nothing to act on; an autonomous run rewrites the same text forever.
+  The refusal names the candidate line under the input it belongs to and says why it was not
+  accepted — a qualifier between the label and the colon, a value that is still a placeholder, or no
+  separator at all — and stays silent when no candidate exists, because then "the input is missing"
+  is the truth. The parser accepts exactly what it accepted before: deriving scope from prose would
+  give away the only guarantee that a run cannot touch files nobody listed.
+
 ## [0.3.1] - 2026-08-07
 
 ### Added

package/README.md

@@ -14,13 +14,16 @@ codexb install                          # short name, same command
 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 permissions   # show optional shell permission rules
+node bin/codex-bridge.mjs permissions add # add the complete allow/deny rule set
+node bin/codex-bridge.mjs permissions remove # remove only codex-bridge's rule strings
 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
 node bin/codex-bridge.mjs read <run>   # read a run: its events rendered as text, on demand
 node bin/codex-bridge.mjs projects     # what the run store holds: projects, runs, weight, tokens
 node bin/codex-bridge.mjs prune <project>   # reclaim disk space, transport only unless told otherwise
-node bin/codex-bridge.mjs sweep [<project>] # close running records whose runner is gone
+node bin/codex-bridge.mjs unlock [<project>|--all] # close records whose runner is gone
 ```
 
 When a global install and a clone coexist, there are two copies of the package. `codex-bridge update`
@@ -38,6 +41,13 @@ version: outdated files are refreshed silently, files you changed by hand stop t
 named, and `--force` is what overwrites them. A file the package no longer ships is removed only
 if you never touched it.
 
+`permissions` manages the optional shell rules in the selected host's `settings.json`. `add`
+merges the exact allow and deny strings for both CLI names, the clone entry point, Bash and
+PowerShell; it preserves foreign rules and is safe to repeat. `remove` takes back those exact
+strings from `allow`, `deny`, or `ask`, so an operator-authored lookalike is left alone. With no
+action it reports whether the rule set is installed, partial, or absent. The command accepts the
+same `--scope` and `--host` selectors as `install`, and `uninstall` removes the same strings too.
+
 `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.
 
@@ -62,11 +72,14 @@ accounting, reports and worktree snapshots alone; `--purge` is what takes a fold
 The same transport is dropped automatically from runs older than 30 days when a new run starts,
 which the reply says out loud; `retention` in `run-config.json` changes the age or turns it off.
 
-`sweep` is housekeeping for records left by a dead runner. With no project it scans the whole
-store; with one project it limits the scan to that folder. It uses the same dead-pid decision as
-start-of-run cleanup, never closes a live pid even when its heartbeat is stale, and never deletes
-run artifacts. A stale live-pid record is named with the exact `codex-bridge stop <run>` command
-needed to close it.
+`unlock` is housekeeping for records left by a dead runner. With no argument it acts on the current
+repository; a bare project name limits the scan to that folder, and `--all` explicitly scans the
+whole store. It uses the same process-identity decision as start-of-run cleanup, closes only
+`dead` or `foreign` records, and reports each record's age, silence duration, and identity verdict.
+A confirmed `alive` record is refused rather than closed and is named with the exact
+`codex-bridge stop <run>` command needed to end it; `unverified` records stay untouched with the
+reason visible. The command never deletes run artifacts. The old spelling `sweep` is recognized and
+refused with the rename to `unlock`, rather than treated as an unknown command.
 
 ## What it gives you
 

package/bin/codex-bridge.mjs

@@ -8,9 +8,10 @@ import { install } from '../cli/install.mjs';
 import { projects } from '../cli/projects.mjs';
 import { read } from '../cli/read.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
+import { permissions } from '../cli/permissions.mjs';
 import { prune } from '../cli/prune.mjs';
 import { stop } from '../cli/stop.mjs';
-import { sweep } from '../cli/sweep.mjs';
+import { unlock } from '../cli/unlock.mjs';
 import { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
 
@@ -19,12 +20,13 @@ 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 permissions [add|remove] [--scope user|project] [--host <path>]
   codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
   codex-bridge doctor [--scope user|project] [--host <path>]
   codex-bridge projects [<name>] [--json]
   codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
   codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
-  codex-bridge sweep [<project>]
+  codex-bridge unlock [<project>|--all]
   codex-bridge read <run>
   codex-bridge stop <run>
   codexb <same command forms as codex-bridge>
@@ -34,11 +36,12 @@ Usage:
 Commands:
   install   Install codex-bridge into the selected Claude Code host
   update    Update a recorded codex-bridge installation
+  permissions Show, add, or remove optional shell permission rules
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host
   projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
-  sweep     Close running records whose runner is gone
+  unlock    Close running records whose runner is gone
   read      Render a run's structured event stream
   stop      Stop a running Codex run and record FAIL`;
 
@@ -110,7 +113,27 @@ export async function main(argv, io = console) {
     return result.exitCode;
   }
   if (command === 'sweep') {
-    const result = sweep(rest);
+    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+    return 2;
+  }
+  if (command === 'unlock') {
+    const result = unlock(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'permissions') {
+    let action;
+    let optionArgs = rest;
+    if (rest[0] && !rest[0].startsWith('-')) {
+      action = rest[0];
+      optionArgs = rest.slice(1);
+    }
+    if (action && !['add', 'remove'].includes(action)) {
+      throw new Error(`unknown permissions action "${action}"`);
+    }
+    const options = commandOptions(command, optionArgs);
+    const host = resolveHost(options);
+    const result = await permissions({ host, action });
     io.log(result.output);
     return result.exitCode;
   }

package/cli/doctor.mjs

@@ -9,6 +9,7 @@ import {
   readInstallRecord,
   packageInfo,
 } from './manifest.mjs';
+import { inspectPermissions } from './permissions.mjs';
 import { commandFor, inspectHook } from './settings-merge.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
@@ -162,6 +163,21 @@ async function rulesCheck(host, record) {
     : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
 }
 
+async function permissionsCheck(host) {
+  try {
+    const status = await inspectPermissions(host.settingsPath);
+    // Permission rules are an optional operator action; Plan_22 keeps their absence a warning so
+    // doctor does not turn a healthy installation red merely because hardening was not requested.
+    // The ask count is part of the line because a full set shadowed by `ask` reads as working and
+    // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
+    const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
+    return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
+      `${status.state} (${status.present}/${status.total} own strings in allow/deny${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}
+
 export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
@@ -199,6 +215,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   ));
   const rules = await rulesCheck(host, record);
   checks.push(rules);
+  checks.push(await permissionsCheck(host));
   checks.push(...await hookChecks(host, record));
   const retention = retentionCheck(host);
   checks.push(retention);
@@ -225,7 +242,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 export function renderDoctor(result) {
   return result.checks.map(({ key, status, value }) => {
     const rendered = `[${status}] ${key}: ${value}`;
-    return ['retention', 'conventions'].includes(key) && status === 'warn'
+    return ['retention', 'conventions', 'permissions'].includes(key) && status === 'warn'
       ? `${WARNING}${rendered}${RESET}`
       : rendered;
   }).join('\n');

package/cli/install.mjs

@@ -14,7 +14,7 @@ import {
   writeInstallRecord,
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
-import { commandFor, inspectHook, mergeHook } from './settings-merge.mjs';
+import { commandFor, inspectHook, mergeHook, withSettingsRun } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
 
@@ -58,7 +58,7 @@ function retentionOutput(line, output) {
   return `${output}\n${line}`;
 }
 
-export async function install({ host, dryRun = false, force = false, packageRoot } = {}) {
+async function installInRun({ host, dryRun = false, force = false, packageRoot } = {}) {
   // 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);
@@ -163,3 +163,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/manifest.mjs

@@ -11,9 +11,23 @@ import {
   renderRequiredInputs,
 } from '../src/required-inputs.mjs';
 import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
+import { readJsonFile } from '../src/json-file.mjs';
 
 export { HOOK_DEFINITIONS };
 
+/**
+ * Finds the definition a recorded hook belongs to. The event alone does not identify one: three of
+ * the four hooks are PreToolUse, so `find(d => d.event === hook.event)` returns the order gate for
+ * all three. `doctor` was fixed for exactly this and kept its own inline matching; `uninstall` was
+ * not, and its dry-run announced matcher `Agent|Task` for the worktree lock and the prune guard —
+ * the operator's only view of what a removal is about to touch. One function, so a third caller
+ * cannot repeat it.
+ */
+export function definitionForRecordedHook(hook) {
+  return HOOK_DEFINITIONS.find((definition) => definition.event === hook?.event
+    && path.basename(String(hook?.path ?? '')) === definition.file);
+}
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(HERE, '..');
 export const INSTALL_RECORD_NAME = '.codex-bridge-install.json';
@@ -49,7 +63,7 @@ export function replacePlaceholders(content, agentsDir) {
 }
 
 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 };
 }
 
@@ -191,19 +205,16 @@ export function normalizeInstallRecord(record) {
 }
 
 export async function readInstallRecord(host) {
-  let raw;
+  let parsed;
   try {
-    raw = await fs.readFile(installRecordPath(host), 'utf8');
+    parsed = await readJsonFile(installRecordPath(host));
   } 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;
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`invalid installation record JSON: ${err.message}`);
-  }
   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

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/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/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) };
 }
 

package/cli/runs-inventory.mjs

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