@lyupro/codex-bridge 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-08-12
+
+### Fixed
+
+- Installing or uninstalling no longer fails over a rules-registry lock that is busy for one more
+  millisecond. Windows answers a taken lock with three codes, and only one of them is `EEXIST`: a
+  lock file whose delete is still pending comes back `EPERM`, and a file another process still
+  holds comes back `EBUSY` — the acquisition loop treated both as fatal instead of waiting. All
+  three now mean "not yours yet", and the decision lives in one exported check, `isLockTaken()`.
+
+### Changed
+
+- The README's first screen names the problem the package solves, keeps the install command inside
+  the first 30 lines, adds a second badge row, and shows `doctor` output from a healthy host in
+  place of a screenshot.
+- The reference documentation under `docs/` is English-only now (`overview.ru.md` became
+  `overview.md`), and the working folders — plans, checklists and audits — left the repository and
+  its history: a fresh clone contains the five reference documents and nothing else.
+
 ## [0.5.0] - 2026-08-11
 
 ### Added

package/README.md

@@ -6,29 +6,14 @@
 [![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## What it gives you
-
-- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
-- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
-- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
-- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
-- **5 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping.
-- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
-- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
-- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
+[![npm downloads](https://img.shields.io/npm/dm/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![npm unpacked size](https://img.shields.io/npm/unpacked-size/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
 
-The current suite contains **603 automated tests: 602 passing and 1 skipped**.
-
-## Requirements
-
-- Node.js >= 24
-- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
-- Claude Code, which hosts the agents, commands, and guards
+Agentic coding spends one model subscription on everything, and implementation is the expensive part. codex-bridge moves that work to a separate [Codex CLI](https://developers.openai.com/codex/cli) subscription: Claude Code plans, dispatches and accepts, Codex executes — and every delegated run is guarded, verified and audited on disk.
 
 ## Install
 
-For a one-off user installation, global access, or a clone entry point:
-
 ```bash
 npm i -g @lyupro/codex-bridge   # puts both command names on PATH
 codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
@@ -50,12 +35,52 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 
 `codex-runs/` contains operator data. Uninstall never removes it.
 
+## Requirements
+
+- Node.js >= 24
+- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
+- Claude Code, which hosts the agents, commands, and guards
+
+## What it gives you
+
+- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
+- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
+- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
+- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
+- **5 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping.
+- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
+- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
+- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
+
+The current suite contains **604 automated tests: 603 passing and 1 skipped**.
+
 ## Verify
 
 ```bash
 codex-bridge doctor
 ```
 
+Output on a healthy host (trimmed):
+
+```text
+[ok] host: ~/.claude (user, exists)
+[ok] installation: @lyupro/codex-bridge@0.5.1 (matches package)
+[ok] files: 53 installed file(s) present
+[ok] rules: ~/.codex/rules/codex-bridge.rules (matches record)
+[ok] permissions: installed (24/24 own strings in allow/deny)
+[ok] hook:SubagentStop: matcher * -> ~/.lyupro/.codex-bridge/hooks/reply-guard.mjs
+[ok] hook:PreToolUse: matcher Agent|Task -> ~/.lyupro/.codex-bridge/hooks/order-gate.mjs
+[ok] hook:PreToolUse: matcher Write|Edit|MultiEdit|NotebookEdit -> ~/.lyupro/.codex-bridge/hooks/worktree-lock.mjs
+[ok] hook:PreToolUse: matcher Bash|PowerShell -> ~/.lyupro/.codex-bridge/hooks/prune-guard.mjs
+[ok] hook:PreToolUse: matcher TaskStop -> ~/.lyupro/.codex-bridge/hooks/stop-guard.mjs
+[warn] retention: Automatic cleanup is ON — run transport older than 30 days is removed to reclaim disk space.
+[ok] conventions: ~/.lyupro/.codex-bridge/conventions.md (found)
+[ok] codex: codex-cli 0.146.1
+[ok] node: 24.18.0 (requires >=24)
+[ok] runsRoot: ~/.claude/codex-runs
+[ok] liveRuns: 0 runs working right now
+```
+
 `doctor` reports the selected host, package source, installed files and guards, Codex availability, retention policy, permissions, live runs, and the current repository's run folder.
 
 ## Update

package/cli/rules-owners.mjs

@@ -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/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.1",
+  "description": "Claude Code-to-Codex delegation with 5 guards, 604 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",