@lyupro/codex-bridge 0.5.1 → 0.5.3

package/cli/frontmatter.mjs

@@ -0,0 +1,137 @@
+/**
+ * Reads and normalizes the flat frontmatter shipped by this package.
+ *
+ * The 2026-08-10 agent-registration incident showed that placeholder text can turn a previously
+ * plain YAML value into invalid syntax. Keeping this boundary deliberately flat makes host
+ * readability testable without adding a general YAML parser or changing markdown bodies.
+ */
+
+const PLAIN_START = /^(?:[-?:](?:[ \t]|$)|[,\[\]{}#&*!|>'"%@`])/;
+
+function locateFrontmatter(content) {
+  const firstBreak = content.indexOf('\n');
+  if (firstBreak === -1 || content.slice(0, firstBreak).replace(/\r$/, '') !== '---') return null;
+
+  const blockStart = firstBreak + 1;
+  let lineStart = blockStart;
+  while (lineStart <= content.length) {
+    const nextBreak = content.indexOf('\n', lineStart);
+    const lineEnd = nextBreak === -1 ? content.length : nextBreak;
+    if (content.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return { blockStart, blockEnd: lineStart };
+    }
+    if (nextBreak === -1) break;
+    lineStart = nextBreak + 1;
+  }
+  throw new Error('frontmatter closing delimiter is missing');
+}
+
+function blockLines(block) {
+  const lines = [];
+  let start = 0;
+  while (start < block.length) {
+    const nextBreak = block.indexOf('\n', start);
+    const end = nextBreak === -1 ? block.length : nextBreak;
+    const hasCarriageReturn = block[end - 1] === '\r';
+    lines.push({
+      text: block.slice(start, hasCarriageReturn ? end - 1 : end),
+      ending: nextBreak === -1 ? '' : hasCarriageReturn ? '\r\n' : '\n',
+    });
+    if (nextBreak === -1) break;
+    start = nextBreak + 1;
+  }
+  return lines;
+}
+
+function splitEntry(line) {
+  const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+  if (!match) throw new Error(`frontmatter line is not a flat key/value entry: ${line}`);
+  const remainder = match[2];
+  if (remainder && !/^[ \t]/.test(remainder)) {
+    throw new Error(`frontmatter value for ${match[1]} must follow YAML separator whitespace`);
+  }
+  return { key: match[1], rawValue: remainder ? remainder.slice(1) : '' };
+}
+
+function decodeDoubleQuoted(value) {
+  if (!value.endsWith('"')) return null;
+  let decoded = '';
+  for (let index = 1; index < value.length - 1; index += 1) {
+    const character = value[index];
+    if (character === '"') return null;
+    if (character !== '\\') {
+      decoded += character;
+      continue;
+    }
+    const escaped = value[index + 1];
+    if (escaped !== '\\' && escaped !== '"') return null;
+    decoded += escaped;
+    index += 1;
+  }
+  return decoded;
+}
+
+function decodeSingleQuoted(value) {
+  if (!value.endsWith("'")) return null;
+  const inner = value.slice(1, -1);
+  if (/(^|[^'])'(?:[^']|$)/.test(inner)) return null;
+  return inner.replaceAll("''", "'");
+}
+
+function quotedValue(value) {
+  if (value.startsWith('"')) return decodeDoubleQuoted(value);
+  if (value.startsWith("'")) return decodeSingleQuoted(value);
+  return undefined;
+}
+
+function plainScalarIsSafe(value) {
+  return value.length > 0
+    && value === value.trim()
+    && !PLAIN_START.test(value)
+    && !/:[ \t]/.test(value)
+    && !/[ \t]#/.test(value);
+}
+
+function parseValue(rawValue) {
+  const decoded = quotedValue(rawValue);
+  if (decoded !== undefined) {
+    if (decoded === null) throw new Error('frontmatter contains an invalid quoted value');
+    return decoded;
+  }
+  if (!plainScalarIsSafe(rawValue)) {
+    throw new Error(`frontmatter contains an invalid plain scalar: ${rawValue}`);
+  }
+  return rawValue;
+}
+
+function encodeValue(value) {
+  const decoded = quotedValue(value);
+  const intended = decoded === undefined || decoded === null ? value : decoded;
+  if (decoded === undefined && plainScalarIsSafe(value)) return value;
+  return `"${intended.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+export function parseFrontmatter(content) {
+  const bounds = locateFrontmatter(content);
+  if (!bounds) return null;
+  const values = {};
+  for (const { text } of blockLines(content.slice(bounds.blockStart, bounds.blockEnd))) {
+    const { key, rawValue } = splitEntry(text);
+    if (Object.hasOwn(values, key)) throw new Error(`frontmatter contains duplicate key: ${key}`);
+    values[key] = parseValue(rawValue);
+  }
+  return values;
+}
+
+export function normalizeFrontmatter(content) {
+  const bounds = locateFrontmatter(content);
+  if (!bounds) return content;
+  const keys = new Set();
+  const normalized = blockLines(content.slice(bounds.blockStart, bounds.blockEnd)).map(({ text, ending }) => {
+    const { key, rawValue } = splitEntry(text);
+    if (keys.has(key)) throw new Error(`frontmatter contains duplicate key: ${key}`);
+    keys.add(key);
+    return `${key}: ${encodeValue(rawValue)}${ending}`;
+  }).join('');
+  return `${content.slice(0, bounds.blockStart)}${normalized}${content.slice(bounds.blockEnd)}`;
+}

package/cli/hook.mjs

@@ -1,9 +1,9 @@
 /** 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';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 
-const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'hooks');
+const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'home', 'hooks');
 const VALID_NAMES = HOOK_DEFINITIONS.map(({ name }) => name);
 
 function validNames() {

package/cli/install-record.mjs

@@ -1,8 +1,8 @@
 /** 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';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 
 export const INSTALL_RECORD_NAME = '.installed.json';
 export const LEGACY_INSTALL_RECORD_NAME = '.codex-bridge-install.json';

package/cli/install.mjs

@@ -25,7 +25,8 @@ import {
   withSettingsRun,
 } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
-import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
+import { addPermissionRules } from './permissions.mjs';
+import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 
 const WARNING = '\u001b[33m';
 const RESET = '\u001b[0m';
@@ -158,6 +159,13 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   }
   const hookResults = [];
   for (const { spec } of targets) hookResults.push(await mergeHook(host.settingsPath, spec));
+  // Uninstall has always removed these rules, and install never granted them — so removal took
+  // away what installation never gave. Without the rule the host refuses the package command,
+  // and the 2026-08-15 `cartoons-r136-scout-lock-scope` order shows what a dispatcher does next:
+  // it goes looking for a way around, down to the absolute path to run-codex.mjs that Plan_41
+  // removed. The rule follows the scope of the install, because host.settingsPath already is the
+  // scope — a --scope project install must not reach into the operator's global config.
+  const permissionResult = dryRun ? { added: 0 } : await addPermissionRules(host.settingsPath);
   const fingerprints = {};
   for (const item of plan) {
     fingerprints[item.root] ??= {};
@@ -188,7 +196,11 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   });
   return {
     exitCode: 0,
-    output: retentionOutput(configuredRetentionLine, `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`),
+    output: retentionOutput(
+      configuredRetentionLine,
+      `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`
+        + `\nGranted ${permissionResult.added} permission rule(s) in ${host.settingsPath} so the host runs the package command without asking.`,
+    ),
   };
 }
 

package/cli/manifest.mjs

@@ -3,14 +3,15 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 import {
   renderRequiredInputSummary,
   renderRequiredInputs,
-} from '../src/required-inputs.mjs';
-import { renderNoSelfExecution } from '../src/no-self-execution.mjs';
-import { renderStopSummary } from '../src/stop-contract.mjs';
-import { readJsonFile } from '../src/json-file.mjs';
+} from '../src/home/lib/required-inputs.mjs';
+import { renderNoSelfExecution } from '../src/home/lib/no-self-execution.mjs';
+import { renderStopSummary } from '../src/home/lib/stop-contract.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
+import { normalizeFrontmatter } from './frontmatter.mjs';
 import {
   INSTALL_RECORD_NAME,
   RULES_NAME,
@@ -49,18 +50,19 @@ 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
+ * visible and editable, then never written, never compared, never removed: config.json
  * is where a host states which model each mode runs on, conventions.md is the rule set it hands
  * every run, and an installer that overwrites either would erase host decisions on the next
  * update — the same way overwriting a .env would.
  */
-export const SEEDED_SOURCES = Object.freeze(['src/run-config.json', 'src/conventions.md']);
+export const SEEDED_SOURCES = Object.freeze(['src/home/config.json', 'src/home/conventions.md']);
 
 export const INSTALL_TABLE = Object.freeze([
   { 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 source is the host image. Keeping one source root and one target root makes any future
+  // remapping visible as a test failure instead of another clone-only import success.
+  { source: 'src/home/**', root: 'brand', target: 'brandRoot', 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
@@ -72,12 +74,13 @@ const posix = (value) => value.split(path.sep).join('/');
 
 export function replacePlaceholders(content, installationRoot) {
   const agentType = content.match(/^name:\s*([^\r\n]+)$/m)?.[1].trim();
-  return content
+  const replaced = content
     .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_STOP_SUMMARY}}', renderStopSummary());
+  return normalizeFrontmatter(replaced);
 }
 
 export async function packageInfo(packageRoot = PACKAGE_ROOT) {
@@ -92,14 +95,13 @@ export function installedHookPath(host, definition) {
 /** 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) => {
-    const target = source.endsWith('run-config.json')
-      ? host.brandConfigPath
-      : host.brandConventionsPath;
+    const relativeToRoot = posix(path.relative('src/home', source));
+    const target = path.join(host.brandRoot, relativeToRoot);
     return {
       source: path.join(packageRoot, source),
       target,
       root: 'brand',
-      relativeToRoot: posix(path.relative(host.brandRoot, target)),
+      relativeToRoot,
       processing: 'copy',
     };
   });
@@ -115,13 +117,17 @@ export function rulesPlan(host, packageRoot = PACKAGE_ROOT) {
 
 export async function fileFingerprint(absolutePath) {
   try {
-    return createHash('sha256').update(await fs.readFile(absolutePath)).digest('hex');
+    return contentFingerprint(await fs.readFile(absolutePath));
   } catch (err) {
     if (err.code === 'ENOENT') return null;
     throw err;
   }
 }
 
+export function contentFingerprint(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
 function targetBase(host, mapping) {
   const base = host[mapping.target];
   if (!base) throw new Error(`host has no ${mapping.target} install target`);
@@ -136,17 +142,13 @@ function targetRelative(packageRoot, source, mapping) {
   if (mapping.processing === 'placeholders' || mapping.source === 'package.json') {
     return path.basename(source);
   }
-  const sourceRoot = mapping.source === 'src/hooks/**'
-    ? path.join(packageRoot, 'src', 'hooks')
-    : path.join(packageRoot, 'src');
-  return path.relative(sourceRoot, source);
+  return path.relative(path.join(packageRoot, 'src', 'home'), source);
 }
 
 export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {
   const files = [];
-  const claimedSources = [];
   for (const mapping of INSTALL_TABLE) {
-    for await (const relative of fs.glob(mapping.source, { cwd: packageRoot, exclude: claimedSources })) {
+    for await (const relative of fs.glob(mapping.source, { cwd: packageRoot })) {
       if (posix(relative) === RULES_SOURCE || SEEDED_SOURCES.includes(posix(relative))) continue;
       const source = path.join(packageRoot, relative);
       if (!(await fs.stat(source)).isFile()) continue;
@@ -165,7 +167,6 @@ export async function buildInstallPlan(host, packageRoot = PACKAGE_ROOT) {
           : rootFor(host, mapping),
       });
     }
-    claimedSources.push(mapping.source);
   }
   return files.sort((a, b) => recordFileKey(a).localeCompare(recordFileKey(b)));
 }

package/cli/permissions.mjs

@@ -1,8 +1,8 @@
 /** 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 { CLI_NAMES } from '../src/home/lib/cli-names.mjs';
+import { SHELL_TOOLS } from '../src/home/lib/hook-definitions.mjs';
 import { readSettings, updateSettings, withSettingsRun } from './settings-merge.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');

package/cli/projects.mjs

@@ -1,9 +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';
+import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/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

package/cli/prune-plan.mjs

@@ -3,8 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { listProjectRuns, listProjects, recursiveSize } from './runs-inventory.mjs';
 import { parseOlderThan } from './prune-args.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
-import { runIsOlderThan, TRANSPORT_FILES } from '../src/retention.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { runIsOlderThan, TRANSPORT_FILES } from '../src/home/lib/retention.mjs';
 
 export { runIsOlderThan, TRANSPORT_FILES };
 

package/cli/prune.mjs

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline/promises';
-import { normalizePath } from '../src/hooks/live-runs.mjs';
+import { normalizePath } from '../src/home/hooks/live-runs.mjs';
 import { parsePruneArgs } from './prune-args.mjs';
 import { prunePlan } from './prune-plan.mjs';
 import { recursiveSize } from './runs-inventory.mjs';

package/cli/read.mjs

@@ -1,6 +1,6 @@
 /** Renders a run's structured Codex transport as a readable event-by-event report. */
-import { readEvents } from '../src/meta/events.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
+import { readEvents } from '../src/home/lib/meta/events.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
 
 const result = (exitCode, output) => ({ exitCode, output });

package/cli/rules-owners.mjs

@@ -2,8 +2,8 @@
 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';
+import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
 export const RULES_REGISTRY_VERSION = 1;

package/cli/run-lookup.mjs

@@ -1,9 +1,9 @@
 /** Resolves a run argument and confirms that it names an existing run directory. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { git } from '../src/runner/git-state.mjs';
-import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
+import { git } from '../src/home/lib/runner/git-state.mjs';
+import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 
 function projectRoot(cwd) {
   const result = git(cwd, ['rev-parse', '--show-toplevel']);

package/cli/runs-inventory.mjs

@@ -1,9 +1,9 @@
 /** Reads run-store directories into inventory data. */
 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';
+import { liveRuns } from '../src/home/hooks/live-runs.mjs';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 

package/cli/settings-merge.mjs

@@ -5,7 +5,7 @@ import { existsSync, statSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { readJsonFileWithRaw } from '../src/json-file.mjs';
+import { readJsonFileWithRaw } from '../src/home/lib/json-file.mjs';
 
 const LEGACY_SPEC = { event: 'SubagentStop', matcher: '*' };
 const settingsRuns = new AsyncLocalStorage();
@@ -134,29 +134,41 @@ const hasOwnCommand = (group, commands) => {
 };
 
 /**
- * Presence is decided by the command, not by the matcher it currently sits under.
+ * Presence is decided by the command, not by the matcher it currently sits under; writing then
+ * places that command under the matcher the package declares. These are two halves of one rule.
  *
  * The matcher is generated from the tool list in hook-definitions.mjs, so it changes whenever a
  * host spelling is added — `Agent` became `Agent|Task` in one release, and the write-tool matcher
  * will grow the same way. A host installed under the old matcher would then be invisible to the
  * new lookup: update would register a duplicate and uninstall would leave a hook pointing at a
- * deleted file. The command is this package's own absolute path, so it identifies our entry
- * wherever the group ended up.
+ * deleted file. Conversely, the 2026-08-17 host proved that finding alone is insufficient: its
+ * worktree lock stayed under the pre-shell matcher, so Bash never reached the guard. The command
+ * is this package's own absolute path, so it identifies our entry wherever the group ended up,
+ * and merge can move it without creating a duplicate.
  */
 export async function inspectHook(settingsPath, specOrPath) {
   const state = await readSettings(settingsPath);
   const spec = normalizeSpec(specOrPath);
   const commands = [spec.command, ...spec.alternateCommands];
   let matchedCommand;
+  let matchedMatcher;
+  let requiresMove = false;
   for (const group of groups(state.settings, spec.event)) {
-    const hook = groupHooks(group).find((entry) =>
-      entry?.type === 'command' && commands.includes(entry.command));
-    if (hook) {
-      matchedCommand = hook.command;
-      break;
+    for (const hook of groupHooks(group)) {
+      if (hook?.type !== 'command' || !commands.includes(hook.command)) continue;
+      matchedCommand ??= hook.command;
+      matchedMatcher ??= group?.matcher;
+      if (group?.matcher !== spec.matcher) requiresMove = true;
     }
   }
-  return { ...state, ...spec, present: Boolean(matchedCommand), matchedCommand };
+  return {
+    ...state,
+    ...spec,
+    present: Boolean(matchedCommand),
+    matchedCommand,
+    matchedMatcher,
+    requiresMove,
+  };
 }
 
 function backupName(settingsPath) {
@@ -227,10 +239,43 @@ export async function mergeHook(settingsPath, specOrPath, inspected) {
   return withMutationRun(settingsPath, async () => {
     const spec = normalizeSpec(specOrPath);
     const state = inspected || await inspectHook(settingsPath, spec);
-    if (state.present) return { changed: false, createdGroup: false };
+    if (state.present && !state.requiresMove) return { changed: false, createdGroup: false };
     const settings = structuredClone(state.settings);
     settings.hooks ??= {};
     if (!Array.isArray(settings.hooks[spec.event])) settings.hooks[spec.event] = [];
+    if (state.present) {
+      const eventGroups = settings.hooks[spec.event];
+      const commands = [spec.command, ...spec.alternateCommands];
+      let hookToMove;
+      let keptDeclaredHook = false;
+      for (let index = eventGroups.length - 1; index >= 0; index -= 1) {
+        const group = eventGroups[index];
+        if (!Array.isArray(group?.hooks)) continue;
+        const hadOwnHook = hasOwnCommand(group, commands);
+        group.hooks = group.hooks.filter((hook) => {
+          if (hook?.type !== 'command' || !commands.includes(hook.command)) return true;
+          hookToMove ??= hook;
+          if (group.matcher === spec.matcher && !keptDeclaredHook) {
+            keptDeclaredHook = true;
+            return true;
+          }
+          return false;
+        });
+        if (hadOwnHook && group.hooks.length === 0) eventGroups.splice(index, 1);
+      }
+      let group = eventGroups.find((entry) => entry?.matcher === spec.matcher);
+      const createdGroup = !group;
+      if (!keptDeclaredHook) {
+        if (!group) {
+          group = { matcher: spec.matcher, hooks: [] };
+          eventGroups.push(group);
+        }
+        if (!Array.isArray(group.hooks)) group.hooks = [];
+        group.hooks.push(hookToMove);
+      }
+      await atomicWrite(settingsPath, settings, state);
+      return { changed: true, createdGroup, moved: true };
+    }
     let group = settings.hooks[spec.event].find((entry) => entry?.matcher === spec.matcher);
     const createdGroup = !group;
     if (!group) {

package/cli/stop.mjs

@@ -1,16 +1,16 @@
 /** Stops a live run and records the same abandoned FAIL artifacts as the normal unlock. */
 import path from 'node:path';
-import { stopCodex } from '../src/runner/codex-cmd.mjs';
-import { git, worktreeSnapshot } from '../src/runner/git-state.mjs';
+import { stopCodex } from '../src/home/lib/runner/codex-cmd.mjs';
+import { git, worktreeSnapshot } from '../src/home/lib/runner/git-state.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_FOREIGN,
   IDENTITY_UNVERIFIED,
   processAlive,
   processIdentity,
-} from '../src/process-identity.mjs';
-import { markAbandoned, readJson } from '../src/write-meta.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
+} from '../src/home/lib/process-identity.mjs';
+import { markAbandoned, readJson } from '../src/home/lib/write-meta.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 import { resolveRunFolder } from './run-lookup.mjs';
 
 const EXIT_POLL_MS = 25;

package/cli/unlock.mjs

@@ -2,17 +2,17 @@
 /** Closes dead-pid running records without deleting any run artifacts. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/heartbeat.mjs';
-import { markAbandoned } from '../src/meta/run-state.mjs';
+import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/home/lib/heartbeat.mjs';
+import { markAbandoned } from '../src/home/lib/meta/run-state.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_UNVERIFIED,
   processIdentity,
-} from '../src/process-identity.mjs';
-import { git } from '../src/runner/git-state.mjs';
-import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
-import { runsRoot } from '../src/runner/runs-root.mjs';
-import { readJson } from '../src/write-meta.mjs';
+} from '../src/home/lib/process-identity.mjs';
+import { git } from '../src/home/lib/runner/git-state.mjs';
+import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { readJson } from '../src/home/lib/write-meta.mjs';
 import { renderTable } from './table.mjs';
 
 const CLOSED_COLUMNS = [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.5.1",
-  "description": "Claude Code-to-Codex delegation with 5 guards, 604 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.5.3",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 757 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/scripts/check-file-size.mjs

@@ -21,7 +21,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readJsonFile } from '../src/json-file.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '..');

package/scripts/run-tests.mjs

@@ -16,21 +16,50 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { ISOLATED_ROOTS } from './isolated-roots.mjs';
+import { readmeText, suiteCountMismatch } from './suite-count.mjs';
 
 const created = ISOLATED_ROOTS.map((name) => [
   name,
   fs.mkdtempSync(path.join(os.tmpdir(), `codex-bridge-test-${name.toLowerCase()}-`)),
 ]);
 const pattern = process.argv[2] || 'tests/**/*.test.mjs';
+// Only a whole-suite run can judge the README's number; a single file legitimately reports two.
+const wholeSuite = !process.argv[2];
+const tapFile = wholeSuite
+  ? path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'codex-bridge-test-summary-')), 'summary.tap')
+  : null;
+const repositoryRoot = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+// The spec reporter is named explicitly because the second reporter would otherwise replace it,
+// and the operator would lose the live output this command exists to show.
+const reporters = tapFile
+  ? ['--test-reporter=spec', '--test-reporter-destination=stdout',
+    '--test-reporter=tap', `--test-reporter-destination=${tapFile}`]
+  : [];
 
 try {
-  const result = spawnSync(process.execPath, ['--test', pattern], {
+  const result = spawnSync(process.execPath, ['--test', ...reporters, pattern], {
     stdio: 'inherit',
     env: { ...process.env, ...Object.fromEntries(created) },
   });
   process.exitCode = result.status ?? 1;
+  if (tapFile && process.exitCode === 0) {
+    let tap = null;
+    try {
+      tap = fs.readFileSync(tapFile, 'utf8');
+    } catch {
+      tap = null;
+    }
+    const mismatch = suiteCountMismatch(readmeText(path.join(repositoryRoot, 'README.md')), tap);
+    if (mismatch) {
+      process.stderr.write(`\nsuite-count: ${mismatch}\n`);
+      process.exitCode = 1;
+    }
+  }
 } finally {
   for (const [, directory] of created) fs.rmSync(directory, { recursive: true, force: true });
+  if (tapFile) fs.rmSync(path.dirname(tapFile), { recursive: true, force: true });
 }