@lyupro/codex-bridge 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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
+
+- Two runners starting at the same moment in equally named repositories no longer fail on the exclusive writes that assign a runs directory: the runner that loses either race now reads the marker the winner wrote and takes the next candidate, which is the collision the marker was introduced to survive.
+- A repeated order is answered from its newest run instead of the pass before it: while a continuation was in flight, repeating the command returned the previous run's verdict as if it described the current one.
+- Uninstalling one installation no longer takes the Codex rules file away from every other installation on the machine. The file lives in `CODEX_HOME`, which is shared by every host, while ownership was recorded per host and two installations of the same version share a fingerprint — so removing a project-scope or throwaway host silently left the remaining ones running Codex without the execpolicy that forbids destructive repository work. Ownership is now tracked next to the file itself, and the last owner to leave is the one that removes it.
+
 ## [0.1.0] - 2026-08-04
 
 ### Added

package/cli/doctor.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileFingerprint, readInstallRecord, packageInfo } from './manifest.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
 
@@ -97,16 +98,24 @@ async function hookCheck(host, record) {
     : check('hook', 'warn', 'SubagentStop does not point to the installed reply-guard.mjs');
 }
 
-async function rulesCheck(record) {
+async function rulesCheck(host, record) {
   if (!record) return check('rules', 'warn', 'cannot check before installation');
   if (!record.rules) {
     return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
   }
+  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);
+  if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
   return fingerprint === record.rules.fingerprint
-    ? check('rules', 'ok', `${record.rules.path} (matches record)`)
-    : check('rules', 'warn', `${record.rules.path} (modified after installation)`);
+    ? check('rules', 'ok', `${record.rules.path} (matches record${ownerNote})`)
+    : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
 }
 
 export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
@@ -144,7 +153,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
     !record ? 'warn' : missingFiles.length ? 'fail' : 'ok',
     !record ? 'not checked' : missingFiles.length ? `missing: ${missingFiles.join(', ')}` : `${record.files.length} installed file(s) present`,
   ));
-  const rules = await rulesCheck(record);
+  const rules = await rulesCheck(host, record);
   checks.push(rules);
   checks.push(await hookCheck(host, record));
 

package/cli/install.mjs

@@ -13,6 +13,7 @@ import {
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
 import { inspectHook, mergeHook } from './settings-merge.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function targetExists(target) {
   try {
@@ -25,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);
@@ -66,6 +69,7 @@ export async function install({ host, dryRun = false, force = false, packageRoot
     new Map(states.map((state) => [state.item.relativeToHost, state.fingerprint])),
     { path: rule.target, fingerprint: ruleState.fingerprint });
   if (!changedFiles.length && !changedRule && inspectedHook.present && sameRecord) {
+    if (!dryRun) await addRulesOwner(host);
     return { exitCode: 0, output: 'codex-bridge is already installed; nothing to do.' };
   }
 
@@ -80,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

package/cli/rules-owners.mjs

@@ -0,0 +1,172 @@
+/** 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);
+}
+
+export function normalizedRulesOwner(host) {
+  return normalizeRepoPath(host.root);
+}
+
+function normalizeOwners(owners) {
+  return [...new Set(owners.map((owner) => normalizeRepoPath(owner)))];
+}
+
+function validateRegistry(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('rules ownership registry must be an object');
+  }
+  if (parsed.version !== RULES_REGISTRY_VERSION) {
+    throw new Error(`rules ownership registry version must be ${RULES_REGISTRY_VERSION}`);
+  }
+  if (!Array.isArray(parsed.owners) || parsed.owners.some((owner) => typeof owner !== 'string' || !owner)) {
+    throw new Error('rules ownership registry owners must be a list of non-empty strings');
+  }
+  return {
+    version: RULES_REGISTRY_VERSION,
+    owners: normalizeOwners(parsed.owners),
+  };
+}
+
+async function loadRulesRegistry(host) {
+  let raw;
+  try {
+    raw = await fs.readFile(rulesRegistryPath(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 rules ownership registry JSON: ${err.message}`);
+  }
+  return { raw: parsed, registry: validateRegistry(parsed) };
+}
+
+function hasSameOwners(raw, registry) {
+  return raw?.version === registry.version
+    && Array.isArray(raw.owners)
+    && raw.owners.length === registry.owners.length
+    && raw.owners.every((owner, index) => owner === registry.owners[index]);
+}
+
+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 });
+  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) {
+  return (await loadRulesRegistry(host))?.registry ?? null;
+}
+
+export async function addRulesOwner(host) {
+  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) {
+  if (!registry) return null;
+  const owner = normalizedRulesOwner(host);
+  return registry.owners.filter((candidate) => candidate !== owner);
+}
+
+export async function removeRulesOwner(host) {
+  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

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileFingerprint, installRecordPath, readInstallRecord } from './manifest.mjs';
 import { removeHook } from './settings-merge.mjs';
+import { readRulesRegistry, removeRulesOwner, remainingRulesOwners } from './rules-owners.mjs';
 
 async function removeEmpty(directory) {
   try {
@@ -20,7 +21,19 @@ async function removeEmptyParents(target, boundary) {
   }
 }
 
+function remainingOwnersText(count) {
+  return `${count} other owner${count === 1 ? '' : 's'} ${count === 1 ? 'remains' : 'remain'}`;
+}
+
 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.`;
@@ -28,7 +41,26 @@ export async function uninstall({ host, dryRun = false } = {}) {
 
   if (dryRun) {
     const lines = record.files.map((file) => `Would remove ${file}`);
-    if (record.rules) lines.push(`Would remove ${record.rules.path} if its fingerprint is unchanged.`);
+    if (record.rules) {
+      if (registryError) {
+        lines.push(`Would leave ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
+      } else {
+        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.');
     lines.push(preservation);
     return { exitCode: 0, output: lines.join('\n') };
@@ -37,13 +69,32 @@ export async function uninstall({ host, dryRun = false } = {}) {
   await removeHook(host.settingsPath, path.join(host.root, record.hook.path), {
     createdGroup: record.hook.createdGroup === true,
   });
-  let rulesOutput;
+  let ownership = null;
+  if (!registryError) {
+    try {
+      ownership = await removeRulesOwner(host);
+    } catch (err) {
+      registryError = err;
+    }
+  }
+  const rulesOutput = [];
   if (record.rules) {
-    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 (registryError) {
+      rulesOutput.push(`Left ${record.rules.path} because the rules ownership registry is invalid; ownership is unknown.`);
+    } else {
+      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}.`);
+      }
     }
   }
   for (const relative of record.files) {
@@ -57,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,6 +12,7 @@ import {
 } from './manifest.mjs';
 import { targetMatches } from './copy.mjs';
 import { inspectHook } from './settings-merge.mjs';
+import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 
 async function exists(target) {
   try {
@@ -80,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.' };
@@ -141,6 +143,7 @@ export async function update({ host, dryRun = false, force = false, packageRoot
     { path: rule.target, fingerprint: ruleState.fingerprint });
   const changed = states.some((state) => state.status !== 'up-to-date');
   if (!changed && inspectedHook.present && recordCurrent) {
+    if (!dryRun) await addRulesOwner(host);
     return { exitCode: 0, output: 'codex-bridge is up to date' };
   }
   if (dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.1.0",
+  "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",

package/src/runner/attach.mjs

@@ -71,15 +71,24 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
     .map((run) => ({ run, status: readJsonFile(path.join(runsRoot, run, 'status.json')) }))
     .filter(({ status }) => status && String(status.order_id ?? '') === String(orderId ?? ''));
 
-  const answered = sameOrder.find(({ run }) => fs.existsSync(path.join(runsRoot, run, 'reply.txt')));
-  if (answered) {
-    const runDir = path.join(runsRoot, answered.run);
-    console.log(`ATTACH=${runDir} started=${answered.status.started_at}`);
-    console.log(fs.readFileSync(path.join(runDir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
-    return exitCodeFor(readJsonFile(path.join(runDir, 'meta.json'))?.status);
+  // The run an order is currently about is its newest one, and the chain arrives oldest first.
+  // Reading it from the end is the whole point: `--continue` adds a second run under the same
+  // order, and while it was in flight a repeat used to be answered by the first run's reply.txt —
+  // a stale verdict presented as this pass's answer. Found by the Plan_11-2 checklist, 2026-08-04.
+  let candidate = null;
+  for (let i = sameOrder.length - 1; i >= 0; i -= 1) {
+    const entry = sameOrder[i];
+    const dir = path.join(runsRoot, entry.run);
+    if (fs.existsSync(path.join(dir, 'reply.txt'))) {
+      console.log(`ATTACH=${dir} started=${entry.status.started_at}`);
+      console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
+      return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
+    }
+    if (alive(entry.status.pid)) {
+      candidate = entry;
+      break;
+    }
   }
-
-  const candidate = sameOrder.find(({ status }) => alive(status.pid));
   if (!candidate) return null;
 
   const runDir = path.join(runsRoot, candidate.run);

package/src/runner/project-dir.mjs

@@ -28,9 +28,35 @@ function readMarker(dir) {
   return marker;
 }
 
-function writeMarker(dir, repo) {
+/**
+ * Takes ownership of a candidate directory, or reports that someone else got it.
+ *
+ * Two runners starting at the same moment in equally named repositories pick the
+ * same free candidate, and exactly one of them wins each of the two exclusive
+ * writes below. Until 2026-08-04 the loser died on `EEXIST` instead of reading
+ * the marker the winner had just written — the very collision stage 9 of Plan_9
+ * existed to solve.
+ */
+function claimMarker(dir, repo, wantedRepo) {
   const marker = { repo, created: new Date().toISOString() };
-  fs.writeFileSync(path.join(dir, PROJECT_MARKER), `${JSON.stringify(marker, null, 2)}\n`, { flag: 'wx' });
+  try {
+    fs.writeFileSync(path.join(dir, PROJECT_MARKER), `${JSON.stringify(marker, null, 2)}\n`, { flag: 'wx' });
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    const existing = readMarker(dir);
+    return Boolean(existing) && normalizeRepoPath(existing.repo) === wantedRepo;
+  }
+}
+
+function createDir(dir) {
+  try {
+    fs.mkdirSync(dir);
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    return false;
+  }
 }
 
 function legacyOwner(dir) {
@@ -60,11 +86,12 @@ export function resolveProjectRunsDir(runsRootPath, repoRoot, { create = true }
     const name = candidateName(base, index);
     const dir = path.join(runsRootPath, name);
     if (!fs.existsSync(dir)) {
-      if (create) {
-        fs.mkdirSync(dir);
-        writeMarker(dir, repoRoot);
+      if (!create) return { dir, name, reason: 'created' };
+      if (createDir(dir)) {
+        if (claimMarker(dir, repoRoot, wantedRepo)) return { dir, name, reason: 'created' };
+        continue;
       }
-      return { dir, name, reason: 'created' };
+      // The name was free a moment ago and is not any more: judge it like any other.
     }
     if (!fs.statSync(dir).isDirectory()) {
       throw new Error(`Project runs candidate is not a directory: ${dir}`);
@@ -78,11 +105,12 @@ export function resolveProjectRunsDir(runsRootPath, repoRoot, { create = true }
 
     const owner = legacyOwner(dir);
     if (!owner || normalizeRepoPath(owner) === wantedRepo) {
-      if (create) writeMarker(dir, repoRoot);
-      return { dir, name, reason: 'adopted' };
+      if (!create) return { dir, name, reason: 'adopted' };
+      if (claimMarker(dir, repoRoot, wantedRepo)) return { dir, name, reason: 'adopted' };
+      continue;
     }
     // Recording the discovered owner prevents later runs from reinterpreting mixed history.
-    if (create) writeMarker(dir, owner);
+    if (create) claimMarker(dir, owner, normalizeRepoPath(owner));
   }
 
   throw new Error(