@lyupro/codex-bridge 0.5.0 → 0.5.2

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;
@@ -99,19 +99,41 @@ async function dropStaleLock(lockPath) {
   }
 }
 
+/**
+ * Windows answers a taken lock with three different codes, and only one of them is EEXIST. A file
+ * whose last handle closed while a delete was pending stays visible but refuses to be opened:
+ * `open(..., 'wx')` comes back EPERM, and a file another process still holds comes back EBUSY.
+ * Treating those as fatal is what made `tests/cli/rules-owners.test.mjs` fail twice on 2026-08-11
+ * with EPERM on the lock file — the suite went red over a lock that was simply busy for one more
+ * millisecond. All three mean the same thing to a caller waiting for a lock: not yours yet.
+ */
+const LOCK_TAKEN_CODES = new Set(['EEXIST', 'EPERM', 'EBUSY']);
+
+/** Exported so the retry contract is asserted directly; the race itself reproduces only by luck. */
+export function isLockTaken(err) {
+  return LOCK_TAKEN_CODES.has(err?.code);
+}
+
 async function acquireRegistryLock(host) {
   await fs.mkdir(host.codexRulesDir, { recursive: true });
   const lockPath = registryLockPath(host);
+  let lastTaken;
   for (let attempt = 0; attempt < REGISTRY_LOCK_RETRIES; attempt += 1) {
     try {
       const handle = await fs.open(lockPath, 'wx');
       return { handle, lockPath };
     } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
+      if (!isLockTaken(err)) throw err;
+      lastTaken = err;
       if (!(await dropStaleLock(lockPath))) await waitForRegistryLock();
     }
   }
-  throw new Error(`timed out waiting for rules ownership registry lock: ${lockPath}`);
+  // The code is part of the message: a timeout on EPERM points at a delete that never completed,
+  // a timeout on EEXIST at an owner that never released.
+  throw new Error(
+    `timed out waiting for rules ownership registry lock: ${lockPath} (last attempt: ${lastTaken.code})`,
+    { cause: lastTaken },
+  );
 }
 
 async function withRegistryLock(host, action) {

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();

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.0",
-  "description": "Claude Code-to-Codex delegation with 5 guards, 603 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.5.2",
+  "description": "Claude Code-to-Codex delegation with 5 guards, 604 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, '..');