@lyupro/codex-bridge 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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).
 
+## [0.1.2] - 2026-08-04
+
+### Fixed
+
+- A damaged ownership registry no longer breaks the command that reads it. Every command parses the registry before its first write, `doctor` reports the damage as a failed check while still printing the other eight, and `uninstall` finishes removing the package but keeps the shared rules file, because ownership is unknown and disarming another installation is worse than leaving a file behind. Until this release an `uninstall` on a damaged registry stopped after the hook was gone, leaving the host with every package file and no reply guard.
+- Owner updates are written through a temporary file under a lock, so two installers running at once merge instead of overwriting each other. The lock expires: an interrupted run used to leave it behind, and every later install and uninstall then died on it until someone deleted the file by hand.
+- Installation claims its share of the rules file before writing anything. Claiming it last meant a failure at that step left a fully installed host missing from the registry, and the next uninstall elsewhere would delete the rules out from under it.
+
 ## [0.1.1] - 2026-08-04
 
 ### Fixed

package/cli/doctor.mjs

@@ -103,7 +103,13 @@ async function rulesCheck(host, record) {
   if (!record.rules) {
     return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
   }
-  const registry = await readRulesRegistry(host);
+  let registry;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
+    return check('rules', 'fail', err.message);
+  }
   const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
   const fingerprint = await fileFingerprint(record.rules.path);
   if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);

package/cli/install.mjs

@@ -13,7 +13,7 @@ import {
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
 import { inspectHook, mergeHook } from './settings-merge.mjs';
-import { addRulesOwner } from './rules-owners.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function targetExists(target) {
   try {
@@ -26,6 +26,8 @@ async function targetExists(target) {
 }
 
 export async function install({ 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 plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
@@ -82,6 +84,10 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     return { exitCode: 0, output: lines.join('\n') };
   }
 
+  // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
+  // failure at that step left a fully installed host absent from the registry, and the next
+  // uninstall elsewhere would then delete the rules out from under it.
+  await addRulesOwner(host);
   for (const { item } of changedFiles) await copyPlannedFile(item, host.agentsDir);
   if (changedRule) await copyPlannedFile(rule, host.agentsDir);
   // Seeded files are written once and then belong to the operator: an existing one is left
@@ -107,6 +113,5 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },
     hook: { event: 'SubagentStop', path: hookRelative, createdGroup: hookResult.createdGroup || record?.hook?.createdGroup || false },
   });
-  await addRulesOwner(host);
   return { exitCode: 0, output: `Installed ${plan.length + 1} files and registered the SubagentStop hook.` };
 }

package/cli/rules-owners.mjs

@@ -1,11 +1,16 @@
 /** Tracks which Claude Code hosts own the shared Codex bridge rules file. */
 import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { normalizeRepoPath } from '../src/runner/project-dir.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
 export const RULES_REGISTRY_VERSION = 1;
 
+const REGISTRY_LOCK_RETRIES = 200;
+const REGISTRY_LOCK_DELAY_MS = 5;
+const REGISTRY_LOCK_STALE_MS = 30_000;
+
 export function rulesRegistryPath(host) {
   return path.join(host.codexRulesDir, RULES_REGISTRY_NAME);
 }
@@ -59,8 +64,66 @@ function hasSameOwners(raw, registry) {
 }
 
 async function writeRulesRegistry(host, registry) {
+  const target = rulesRegistryPath(host);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(registry, null, 2)}\n`, { flag: 'wx' });
+    await fs.rename(temporary, target);
+  } catch (err) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+function registryLockPath(host) {
+  return `${rulesRegistryPath(host)}.lock`;
+}
+
+function waitForRegistryLock() {
+  return new Promise((resolve) => setTimeout(resolve, REGISTRY_LOCK_DELAY_MS));
+}
+
+/**
+ * A lock nobody released is worse than no lock: interrupting an install left the file behind and
+ * every later install and uninstall died on it until someone deleted it by hand (reproduced
+ * 2026-08-04). An owner update takes milliseconds, so a lock older than the staleness window
+ * belongs to a process that is gone.
+ */
+async function dropStaleLock(lockPath) {
+  try {
+    const { mtimeMs } = await fs.stat(lockPath);
+    if (Date.now() - mtimeMs < REGISTRY_LOCK_STALE_MS) return false;
+    await fs.rm(lockPath, { force: true });
+    return true;
+  } catch {
+    // Vanished or unreadable — let the next open() decide rather than guess here.
+    return false;
+  }
+}
+
+async function acquireRegistryLock(host) {
   await fs.mkdir(host.codexRulesDir, { recursive: true });
-  await fs.writeFile(rulesRegistryPath(host), `${JSON.stringify(registry, null, 2)}\n`);
+  const lockPath = registryLockPath(host);
+  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 (!(await dropStaleLock(lockPath))) await waitForRegistryLock();
+    }
+  }
+  throw new Error(`timed out waiting for rules ownership registry lock: ${lockPath}`);
+}
+
+async function withRegistryLock(host, action) {
+  const lock = await acquireRegistryLock(host);
+  try {
+    return await action();
+  } finally {
+    await lock.handle.close().catch(() => {});
+    await fs.rm(lock.lockPath, { force: true }).catch(() => {});
+  }
 }
 
 export async function readRulesRegistry(host) {
@@ -68,15 +131,19 @@ export async function readRulesRegistry(host) {
 }
 
 export async function addRulesOwner(host) {
-  const loaded = await loadRulesRegistry(host);
-  const owner = normalizedRulesOwner(host);
-  const current = loaded?.registry || { version: RULES_REGISTRY_VERSION, owners: [] };
-  const registry = {
-    version: RULES_REGISTRY_VERSION,
-    owners: normalizeOwners([...current.owners, owner]),
-  };
-  if (!loaded || !hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
-  return registry;
+  await loadRulesRegistry(host);
+  return withRegistryLock(host, async () => {
+    // Read after locking so a concurrent installer is merged instead of overwritten.
+    const loaded = await loadRulesRegistry(host);
+    const owner = normalizedRulesOwner(host);
+    const current = loaded?.registry || { version: RULES_REGISTRY_VERSION, owners: [] };
+    const registry = {
+      version: RULES_REGISTRY_VERSION,
+      owners: normalizeOwners([...current.owners, owner]),
+    };
+    if (!loaded || !hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
+    return registry;
+  });
 }
 
 export function remainingRulesOwners(registry, host) {
@@ -86,16 +153,20 @@ export function remainingRulesOwners(registry, host) {
 }
 
 export async function removeRulesOwner(host) {
-  const loaded = await loadRulesRegistry(host);
-  if (!loaded) return null;
-  const registry = {
-    version: RULES_REGISTRY_VERSION,
-    owners: remainingRulesOwners(loaded.registry, host),
-  };
-  if (registry.owners.length) {
-    if (!hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
-  } else {
-    await fs.rm(rulesRegistryPath(host), { force: true });
-  }
-  return registry;
+  const initial = await loadRulesRegistry(host);
+  if (!initial) return null;
+  return withRegistryLock(host, async () => {
+    const loaded = await loadRulesRegistry(host);
+    if (!loaded) return null;
+    const registry = {
+      version: RULES_REGISTRY_VERSION,
+      owners: remainingRulesOwners(loaded.registry, host),
+    };
+    if (registry.owners.length) {
+      if (!hasSameOwners(loaded.raw, registry)) await writeRulesRegistry(host, registry);
+    } else {
+      await fs.rm(rulesRegistryPath(host), { force: true });
+    }
+    return registry;
+  });
 }

package/cli/uninstall.mjs

@@ -26,6 +26,14 @@ function remainingOwnersText(count) {
 }
 
 export async function uninstall({ host, dryRun = false } = {}) {
+  // Preflight before removing the hook: package removal on a broken registry left the host without its watchdog.
+  let registry = null;
+  let registryError = null;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    registryError = err;
+  }
   const record = await readInstallRecord(host);
   const preservation = `Run artifacts in ${path.join(host.root, 'codex-runs')} and the run `
     + `configuration in ${path.join(host.agentsDir, 'run-config.json')} are preserved.`;
@@ -34,17 +42,23 @@ export async function uninstall({ host, dryRun = false } = {}) {
   if (dryRun) {
     const lines = record.files.map((file) => `Would remove ${file}`);
     if (record.rules) {
-      const registry = await readRulesRegistry(host);
-      const remainingOwners = remainingRulesOwners(registry, host);
-      const currentFingerprint = await fileFingerprint(record.rules.path);
-      if (remainingOwners?.length) {
-        lines.push(`Would leave ${record.rules.path} because ${remainingOwnersText(remainingOwners.length)}.`);
-      } else if (currentFingerprint === record.rules.fingerprint) {
-        lines.push(`Would remove ${record.rules.path}; no other owners remain and its fingerprint is unchanged.`);
-      } else if (currentFingerprint !== null) {
-        lines.push(`Would leave ${record.rules.path} because its contents changed after installation.`);
+      if (registryError) {
+        lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
       } else {
-        lines.push(`Would leave ${record.rules.path} because it is already absent.`);
+        const remainingOwners = remainingRulesOwners(registry, host);
+        const currentFingerprint = await fileFingerprint(record.rules.path);
+        if (remainingOwners?.length) {
+          lines.push(`Would leave ${record.rules.path} because ${remainingOwnersText(remainingOwners.length)}.`);
+        } else if (currentFingerprint === record.rules.fingerprint) {
+          lines.push(`Would remove ${record.rules.path}; no other owners remain and its fingerprint is unchanged.`);
+        } else if (currentFingerprint !== null) {
+          lines.push(`Would leave ${record.rules.path} because its contents changed after installation.`);
+        } else {
+          lines.push(`Would leave ${record.rules.path} because it is already absent.`);
+        }
+        if (!registry) {
+          lines.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
+        }
       }
     }
     lines.push('Would remove the SubagentStop hook and installation record.');
@@ -55,17 +69,31 @@ export async function uninstall({ host, dryRun = false } = {}) {
   await removeHook(host.settingsPath, path.join(host.root, record.hook.path), {
     createdGroup: record.hook.createdGroup === true,
   });
-  const ownership = await removeRulesOwner(host);
-  let rulesOutput;
+  let ownership = null;
+  if (!registryError) {
+    try {
+      ownership = await removeRulesOwner(host);
+    } catch (err) {
+      registryError = err;
+    }
+  }
+  const rulesOutput = [];
   if (record.rules) {
-    if (ownership?.owners.length) {
-      rulesOutput = `Left ${record.rules.path} because ${remainingOwnersText(ownership.owners.length)}.`;
+    if (registryError) {
+      rulesOutput.push(`Left ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
     } else {
-      const currentFingerprint = await fileFingerprint(record.rules.path);
-      if (currentFingerprint === record.rules.fingerprint) {
-        await fs.rm(record.rules.path, { force: true });
-      } else if (currentFingerprint !== null) {
-        rulesOutput = `Left ${record.rules.path} because its contents changed after installation.`;
+      if (ownership?.owners.length) {
+        rulesOutput.push(`Left ${record.rules.path} because ${remainingOwnersText(ownership.owners.length)}.`);
+      } else {
+        const currentFingerprint = await fileFingerprint(record.rules.path);
+        if (currentFingerprint === record.rules.fingerprint) {
+          await fs.rm(record.rules.path, { force: true });
+        } else if (currentFingerprint !== null) {
+          rulesOutput.push(`Left ${record.rules.path} because its contents changed after installation.`);
+        }
+      }
+      if (!registry) {
+        rulesOutput.push(`Warning: the rules ownership registry was missing; other installations may use ${record.rules.path}.`);
       }
     }
   }
@@ -80,6 +108,6 @@ export async function uninstall({ host, dryRun = false } = {}) {
   await removeEmpty(host.agentsDir);
   return {
     exitCode: 0,
-    output: [`Uninstalled codex-bridge.`, rulesOutput, preservation].filter(Boolean).join('\n'),
+    output: [`Uninstalled codex-bridge.`, ...rulesOutput, preservation].join('\n'),
   };
 }

package/cli/update.mjs

@@ -12,7 +12,7 @@ import {
 } from './manifest.mjs';
 import { targetMatches } from './copy.mjs';
 import { inspectHook } from './settings-merge.mjs';
-import { addRulesOwner } from './rules-owners.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function exists(target) {
   try {
@@ -81,6 +81,7 @@ function dryRunOutput(states, hookPresent, legacy) {
 }
 
 export async function update({ host, dryRun = false, force = false, packageRoot } = {}) {
+  await readRulesRegistry(host);
   const record = await readInstallRecord(host);
   if (!record) {
     return { exitCode: 1, output: 'codex-bridge is not installed. Run codex-bridge install first.' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Delegate implementation, reconnaissance and code review from Claude Code to the Codex CLI: dispatcher agents, a runner that survives a dropped call, and a verdict that checks the report against the worktree.",
   "keywords": [
     "claude-code",