@lyupro/codex-bridge 0.5.1 → 0.5.3

package/README.md

@@ -1,6 +1,6 @@
 # codex-bridge
 
-**Delegate implementation, reconnaissance and review from Claude Code to Codex — five host guards, zero runtime dependencies, zero build steps.**
+**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
 
 [![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
 [![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
@@ -22,6 +22,10 @@ codexb install                  # the short name, same command
 
 Two other entry points reach the same command: `npx @lyupro/codex-bridge install` for a one-off run without a global install, and `node bin/codex-bridge.mjs install` from a clone. Every command below works through all three.
 
+Shipped agents invoke delegated runs through `codex-bridge run`. This is a permission contract,
+not a style choice: the stable package command lets host permission rules match the invocation
+without exposing an installation-specific absolute path and prompting on every delegation.
+
 Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
 
 Installation has two roots:
@@ -29,6 +33,10 @@ Installation has two roots:
 - `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
 - The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
 
+The repository's `src/home/` directory is the literal image copied into the branded root: its
+`hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
+Only npm's `package.json` is copied into that root from outside the image.
+
 Before every `settings.json` write, the existing file is backed up. Existing settings and foreign hooks are preserved. `--dry-run` prints the plan without writing.
 
 If a global install and a clone coexist, you have two package copies. `codex-bridge update`, `codexb update`, and the clone entry point copy files from whichever copy launched the command; using the wrong one can replace a newer host installation with older files.
@@ -47,12 +55,12 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **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.
+- **6 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway.
 - **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**.
+The current suite contains **757 automated tests: 756 passing and 1 skipped**.
 
 ## Verify
 
@@ -81,7 +89,15 @@ Output on a healthy host (trimmed):
 [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.
+`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. The `agents` line is a read, not a file count: each installed definition is parsed and its `name` checked against the dispatcher it claims to be, because a definition the host cannot read is a dispatcher that does not exist while every other line still says `[ok]`. Content that drifts from the packaged definition is a failure, not a warning: `doctor` exits 1 and names `codex-bridge update --force`, because a host running someone else's agent files may be calling the runner in a form no permission rule matches.
+
+If a session answers `Agent type 'codex-build' not found`, a run can still be started without the dispatcher — the agent is a wrapper that types one command:
+
+```bash
+codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
+```
+
+The trade-off is explicit: `order-gate` and `reply-guard` sit on the dispatcher call, so a direct run is unguarded and its result is judged by the worktree and the suite.
 
 ## Update
 
@@ -111,6 +127,7 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
 | `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
 | `doctor [--scope user\|project] [--host <path>]` | Diagnose the selected host and Codex connection. |
+| `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
 | `projects [<name>] [--json]` | List projects or runs in the run store. |
 | `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup. |
 | `unlock [<project>\|--all]` | Close records whose runner is gone. |

package/bin/codex-bridge.mjs

@@ -7,6 +7,7 @@ import { resolveHost } from '../cli/hosts.mjs';
 import { install } from '../cli/install.mjs';
 import { projects } from '../cli/projects.mjs';
 import { read } from '../cli/read.mjs';
+import { runCodexCommand } from '../src/home/lib/run-codex.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
 import { permissions } from '../cli/permissions.mjs';
 import { prune } from '../cli/prune.mjs';
@@ -23,6 +24,7 @@ Usage:
   codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
   codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
   codex-bridge doctor [--scope user|project] [--host <path>]
+  codex-bridge run <runner options> --task-file <path>
   codex-bridge projects [<name>] [--json]
   codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
   codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
@@ -40,6 +42,7 @@ Commands:
   permissions Show, add, or remove optional shell permission rules
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host
+  run       Start or attach to a delegated Codex run
   projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
   unlock    Close running records whose runner is gone
@@ -84,6 +87,7 @@ export async function main(argv, io = console) {
     io.log((await packageInfo()).version);
     return 0;
   }
+  if (command === 'run') return runCodexCommand(rest);
   if (command === 'doctor') {
     const host = resolveHost(commandOptions(command, rest));
     const result = await diagnose({ host });