@lyupro/codex-bridge 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -4,6 +4,154 @@ 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.6.9] - 2026-10-02
+
+### Added
+
+- `uninstall --purge` can remove operator data and the home folder after one preflight under the lifecycle lock:
+  no live runs, a readable installation record and no other recorded owners, before permissions, hooks or files change.
+  A live run is named with its stop command; an unreadable run folder refuses because it cannot be proven idle.
+- Purge asks separately whether the host inventory is complete and whether it may remove the listed operator data,
+  because a record cannot prove that nobody else uses the home and inventory consent is not deletion consent.
+  Without a terminal both answers are no; a refusal or cancellation changes nothing.
+- `uninstall --purge --dry-run` reports every refusal together and lists removals under
+  `If you confirm both questions:`, so an inspection never implies consent. It takes no lock and asks no questions;
+  refusals and unsafe entries exit 1, while the two pending confirmations alone do not.
+- The "Uninstall and purge" section in `docs/overview.md` explains removal and its limits, because a run can start
+  during purge and Node cannot prevent an ancestor being swapped between its check and removal.
+- The installation record keeps one owner per host sharing the home, because installing a second host used to erase
+  the first host's record. A new home starts with a complete inventory; an old record cannot prove all its owners.
+- Interactive install and update ask once whether this host is the home's only owner when migrating an old record
+  or recording a pre-existing image, because those transitions leave other users unknown. Uninstall asks again when
+  the last known owner of an incomplete inventory leaves; no keeps the image, and Ctrl+C cancels before changes.
+- `doctor` prints `host files` and `home owners` lines showing package files and hooks, files uninstall would keep,
+  recorded hosts and inventory completeness, because "not installed" had hidden files in an unrecorded host.
+- The `doctor` line `owners in sync` names hosts verified against an older shared image and gives their update commands,
+  because a warning printed only during install was easily lost. It reports recorded verification, not a fresh
+  inspection of those hosts, and an incomplete inventory never reads as all in sync.
+- Install, update and uninstall take the home's lifecycle lock before their first read, because concurrent hosts
+  could interleave image copies and record writes. Windows uses a named pipe and Linux an abstract socket released
+  by the kernel when the holder dies; macOS uses a lock file requiring explicit recovery. Dry runs take no lock.
+- `codex-bridge unlock --lifecycle` shows whether the home is free, held or unverified, with the holder's command,
+  host and pid when available, because a busy-home refusal previously pointed to a command that did not exist.
+- `codex-bridge unlock --lifecycle --clear` removes only a proven-dead holder's macOS lock file, because automatic
+  takeover could remove a live or replacement holder's lock. Windows and Linux have no lock file to clear.
+- Every command and its actions answer `-h` and `--help` from one command registry, because separate usage text had
+  omitted model actions and subcommands refused help. A flag that needs a value still refuses `--host --help`.
+- The model table ends with `codex-bridge model set <role> <model> [effort]` and `codex-bridge model list`, because
+  the profiles alone did not tell the operator how to change one.
+
+### Changed
+
+- Install and update bring other recorded hosts' package files and hooks along with the shared image, even when the
+  initiating host is already current, because those hosts had kept old agents without the guards the new image needs.
+  A host left behind is named with its update command and makes the command exit 1.
+- Other hosts' edited, missing or linked files remain conflicts that the initiating host's `--force` cannot override,
+  because replacing the shared image must not erase another host's edits. Synchronization leaves permissions, seeds
+  and Codex rules ownership alone; unreachable host roots are named rather than created.
+- `uninstall` removes only the departing host's owner entry while other hosts still use the home, because removing
+  the whole record and image had broken their installations. The shared image goes only after the last owner's
+  hooks are gone and the inventory is complete or the operator confirms nobody else uses it.
+- The installer and uninstall touch only declared files in the package home, because undeclared writes and copied
+  removal lists had left files that removal could not account for.
+- Ordinary `uninstall` and its dry run use one home removal plan, and the real summary counts actual outcomes and
+  distinguishes an owner removed from a record removed, because planned removals were reported as completed even
+  when files stayed. Folders are removed only when empty, never recursively.
+- Ordinary `uninstall` names each operator file it keeps for `--purge`, such as `config.json` and `conventions.md`,
+  because a hand-written preservation sentence missed files. Runs in `codex-runs` remain outside both uninstall
+  and purge.
+- Advisor default budgets are now 10 minutes for `scope` and 25 minutes for `advise`, because measured advise runs
+  approached or exceeded the previous 15-minute deadline.
+- Worktree snapshots use format v2 with exact file names, because quoted and trimmed legacy names could change the
+  verdict. A legacy clean snapshot still reads as clean; missing, damaged or incompatible snapshot pairs fail the
+  verdict rather than count as a clean tree, including a run started before and judged after this format update.
+
+### Fixed
+
+- `uninstall` recognizes host files and hooks by the package's marks and deletes files only when content matches
+  that host's recorded fingerprint or the current package, because edited agents were lost and unrecorded hosts
+  could not be cleaned safely. Edited, unknown and seed files, links and unreadable entries are kept and named.
+- Host hooks are removed before host files, and a host whose hooks cannot be detached keeps its files, rules
+  ownership, record entry and shared image, because a broken `settings.json` had left hooks pointing at removed files.
+- Edited image files stay and are named by uninstall and purge unless their content proves they are package files,
+  because recorded paths alone had authorized deletion. Links are never crossed or removed; unreadable entries are
+  kept, and a link, inspection error or removal failure exits 1 instead of claiming complete removal.
+- Purge re-checks the home after removal, names files that appeared with `Appeared during purge:` and exits 1,
+  because a run started during purge can recreate a file after it was removed.
+- Repeating `uninstall` for a home with no recorded owners asks whether anyone still uses it, because declining
+  removal once had left a home that the next uninstall incorrectly called "not installed".
+- A migrated old record is no longer treated as every unrecorded host's own installation, because update and
+  uninstall had operated on another host's files. Install or update can record an unrecorded host from its
+  package marks.
+- Install and update refresh the host's stale image verification even when its files are current, because the
+  "up to date" exit had left the `doctor` warning in place after the prescribed update.
+- Command usage refusals point to the command's `-h`, including inside the JSON error from `prune --json`,
+  because malformed arguments had failed without showing where to find the correct syntax.
+- `model speed` refuses dash arguments before reading config or fetching the catalogue and points to
+  `model speed -h`, because `model speed build --fast` had treated the flag as a tier identifier.
+- Advisor prose containing clock times, ratios or host:port no longer fails as a file citation, because `00:05`
+  had been read as a file and line number. Invented paths and citations outside the allowed files still fail.
+- Advisor recommendations can contain full text and paragraphs, because hidden length and line-break limits had
+  cut answers mid-citation or caused broken text during decoding. Remaining array bounds are stated in the prompt.
+- Broken advisor text now fails with a named contract error, and reply previews preserve whole characters,
+  because a NUL-containing answer had passed and UTF-16 shortening could split an emoji.
+- An advisor `scope` with `--continue` is refused before starting and asks for a new order id, because continuing
+  scope spent the order's only continuation and made its advise phase unreachable.
+- Scope checks, snapshots and verdicts read Git file names byte-exact, so Cyrillic and other non-ASCII names work,
+  because Git's quoted output had refused valid scopes and judged in-scope edits outside them. Invalid UTF-8 names
+  fail instead of being silently replaced, and scope patterns with line breaks are refused before starting.
+- An untracked file edit that keeps the same size now appears in the snapshot comparison, because recording size
+  alone had made such edits invisible; files that disappear or cannot be read are recorded as missing or unreadable.
+- An unreadable `config.json` fails with its path and reason in the runner and `doctor`, because permission errors
+  or a directory in its place had silently selected default models and budgets. Only a missing file uses defaults.
+- `prune` checks links from the trusted root down and keeps the target on any inspection error, because checking
+  from the leaf up had crossed links first and treated unreadable ancestors as permission to delete.
+
+After `npm i -g @lyupro/codex-bridge@0.6.9`, run `codex-bridge update` once to migrate the installation record.
+An interactive update asks once whether this host is the home's only owner; answer it, because it decides whether a
+later uninstall may remove the shared image. Every host sharing the home should run 0.6.9: older CLI copies do not take
+the lifecycle lock. `codex-bridge doctor` from 0.6.8 cannot read a record written by 0.6.9 and reports
+`[fail] installation: broken record`; installing 0.6.9 clears that report.
+
+## [0.6.8] - 2026-09-25
+
+### Added
+
+- Every session records the version of the host that runs its hooks, read from the `version` the
+  host writes into its own transcript, in `state/host-observations.json`. `doctor` prints a
+  `sessionHost` line and one `otherHost:<version>` line for each other host seen in the last 30
+  days. Sessions ran in the VS Code extension 2.1.282 while `claude` on PATH was 2.1.281, and the
+  extension's `CLAUDE_CODE_EXECPATH` and `CLAUDE_AGENT_SDK_VERSION` are inherited by every `claude`
+  it starts, so neither PATH nor the environment names the host.
+- A subagent stop that carries an `agent_id` but no `agent_type` records a witness alarm and tells
+  the session that the dispatcher gate cannot recognise dispatchers. That was the one host change the
+  gate would otherwise have passed silently.
+
+### Changed
+
+- `.host-contract.json` and `state/dispatcher-contract.json` keep one verdict per host version, so a
+  CLI session and an extension session on different versions no longer overwrite each other's
+  measurement. Existing single-version files are read as the record of their own version.
+- `doctor --probe-contract` measures the executable of the newest observed host. `claude` on PATH
+  and `CLAUDE_CODE_EXECPATH` are used only when their own `--version` matches it;
+  `--probe-executable <path>` names one explicitly. A host that completes the probe but writes
+  another version into its transcript records nothing.
+
+### Fixed
+
+- `doctor` and `install` judge the hosts sessions actually ran on instead of `claude` on PATH. A
+  machine whose sessions run in an editor extension had its contracts reported as verified for a
+  different program, and a permanent `handbackWitness` warning asked for a dispatcher run that could
+  never clear it. With no session observed yet, `doctor` says so rather than falling back to PATH.
+- The handback witness records the host version from the transcript and compares it exactly. It had
+  matched an SDK version to a CLI version by patch number, which accepted unrelated versions sharing
+  a patch. An older SDK-based witness file reads as "not seen yet" and keeps its alarms.
+- `uninstall` names the host observations among the files it leaves in the package home.
+
+After installing 0.6.8, run `codex-bridge update` once so the home receives the observation code,
+then run any shell command in a session. If `doctor` reports the session host as probed on another
+version, run `codex-bridge doctor --probe-contract` once (about two minutes of Claude quota).
+
 ## [0.6.7] - 2026-09-25
 
 ### Added

package/README.md

@@ -62,7 +62,7 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **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 **1636 automated tests: 1635 passing and 1 skipped**.
+The current suite contains **2570 automated tests: 2569 passing and 1 skipped**.
 
 ## Verify
 
@@ -91,7 +91,9 @@ 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. It also reports `handbackWitness` and the four dispatcher contract lines (`dispatcherContract:agentIdentity`, `dispatcherContract:shellStdout`, `dispatcherContract:shellFailure`, and `dispatcherContract:agentTranscript`): verified contracts are `ok`, unknown, unprobed, or stale contracts are `warn`, and a measured change is `fail` with exit 1. 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.
+`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. It judges contracts against the newest host version observed in a session transcript, not `claude` on `PATH`: on 2026-09-25 the VS Code extension ran sessions on 2.1.282 while `PATH` resolved to 2.1.281, and the extension's `CLAUDE_CODE_EXECPATH` and `CLAUDE_AGENT_SDK_VERSION` were inherited by every descendant `claude`. The transcript entry's `version` identifies the host. The dispatcher gate records it once per session in `state/host-observations.json` (sessions kept 7 days, hosts 30); `doctor` and `install` judge the newest observed host. `doctor` prints `sessionHost` and one `otherHost:<version>` line for each other observed version, with `ok`, `warn` and a probe command, or `fail` with exit 1. If no session has been observed, they say so instead of using `PATH`. Refusal and dispatcher contract records keep one verdict per host version, so a measurement of version V applies to every host of version V; older single-version records count only for their recorded version.
+
+`doctor` also reports `handbackWitness` and the four dispatcher contract lines (`dispatcherContract:agentIdentity`, `dispatcherContract:shellStdout`, `dispatcherContract:shellFailure`, and `dispatcherContract:agentTranscript`): verified contracts are `ok`, unknown, unprobed, or stale contracts are `warn`, and a measured change is `fail` with exit 1. Handback sightings and alarms carry the transcript version, and sightings match only that exact version; an older SDK-based record counts as no sighting while preserving its alarms. If a subagent stop has an `agent_id` but no `agent_type`, the reply guard records an alarm and tells the session that the dispatcher gate cannot recognise dispatchers. 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:
 
@@ -127,17 +129,19 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `install [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Install into a Claude Code host. |
 | `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
 | `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>] [--probe-contract]` | Diagnose the selected host and Codex connection, including the handback witness and four dispatcher contract lines. `--probe-contract` measures refusal and dispatcher contracts in one live host run and records them when the host completes it. |
+| `uninstall [--scope user\|project] [--host <path>] [--dry-run] [--purge]` | Remove recorded package files while preserving run artifacts; `--purge` also deletes your data and the home after one preflight and two consents (see [Uninstall and purge](docs/overview.md#uninstall-and-purge)). |
+| `doctor [--scope user\|project] [--host <path>] [--probe-contract] [--probe-executable <path>]` | Diagnose the selected host and Codex connection, including the handback witness and four dispatcher contract lines. `--probe-contract` targets the newest observed host, accepting `CLAUDE_CODE_EXECPATH` or `claude` on `PATH` only when each reports that version with `--version`; use `--probe-executable <path>` to name an executable (`--host` selects the Claude Code configuration). The probe prints its target and records nothing if the completed host run reports another transcript version. |
 | `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. |
 | `model [list\|set\|unset\|speed]` | Show the model, effort, pinned speed tier and provenance of each role, with the config path; `model list` prints the live catalogue from Codex, hidden models included and marked; `model set <role> <model> [effort]` checks the pair and any retained speed tier against that model's catalogue entry, and `model unset <role>` removes the profile. `model speed <role> <tier>` previews a live accelerated tier and its quoted cost description; repeat with trailing `confirm` to pin it. `model speed <role> unset` removes only speed, without confirmation. The profile is machine-wide, shared by every project on this machine. |
 | `projects [<name>] [--json]` | List projects or runs in the run store. |
 | `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
-| `unlock [<project>\|--all]` | Close records whose runner is gone. |
+| `unlock [<project>\|--all]`<br>`unlock --lifecycle [--clear]` | Close records whose runner is gone, or show who holds the lock that serializes install, update and uninstall of this home; `--clear` removes that lock only when it is a file left by a holder proven dead (macOS; Windows and Linux locks are released by the kernel). |
 | `read <run>` | Render a run's structured event stream. |
 | `stop <run>` | Stop a run and record a `FAIL` verdict. |
 
-Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms.
+Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms, or `-h` after
+any command or action for its own usage (`codex-bridge model -h`, `codex-bridge model set -h`); a refusal of an unknown
+option or an extra argument ends with that pointer.
 
 ### Development
 

package/bin/codex-bridge.mjs

@@ -1,87 +1,33 @@
 #!/usr/bin/env node
-/** Dispatches codex-bridge CLI arguments to focused command modules. */
-import { diagnose, renderDoctor } from '../cli/doctor.mjs';
-import { probeContract } from '../cli/probe-contract.mjs';
+/** Dispatches codex-bridge CLI arguments through the command registry (Plan_71 D1). */
 import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
-import { hook } from '../cli/hook.mjs';
-import { resolveHost } from '../cli/hosts.mjs';
-import { install } from '../cli/install.mjs';
-import { model } from '../cli/model.mjs';
-import { projects } from '../cli/projects.mjs';
-import { read } from '../cli/read.mjs';
-import { runCodex } from '../cli/run-launcher.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
-import { permissions } from '../cli/permissions.mjs';
-import { prune } from '../cli/prune.mjs';
-import { stop } from '../cli/stop.mjs';
-import { unlock } from '../cli/unlock.mjs';
-import { uninstall } from '../cli/uninstall.mjs';
-import { update } from '../cli/update.mjs';
-
-export const HELP = `codex-bridge — Claude Code dispatchers for Codex
-
-Usage:
-  codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
-  codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
-  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>] [--probe-contract]
-  codex-bridge run <runner options> --task-file <path>
-  codex-bridge model [list]
-  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]
-  codex-bridge unlock [<project>|--all]
-  codex-bridge read <run>
-  codex-bridge stop <run>
-  codex-bridge hook <name>
-  codexb <same command forms as codex-bridge>
-  codex-bridge --help
-  codex-bridge --version
-
-Commands:
-  install   Install codex-bridge into the selected Claude Code host
-  update    Update a recorded codex-bridge installation
-  permissions Show, add, or remove optional shell permission rules
-  uninstall Remove installed files while preserving run artifacts
-  doctor    Diagnose the selected Claude Code host (--probe-contract measures on a live host)
-  run       Start or attach to a delegated Codex run
-  model     Show machine-wide model profiles or list the live catalogue
-  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
-  read      Render a run's structured event stream
-  stop      Stop a running Codex run and record FAIL
-
-Hook dispatch:
-  codex-bridge hook <name>  Dispatch a registered guard with stdin unchanged`;
-
-const HOOK_COMMAND = 'hook';
-
-export function commandOptions(command, argv) {
-  const options = {};
-  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
-    : command === 'uninstall' ? new Set(['--dry-run'])
-      : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
-  const flagNames = new Map([
-    ['--dry-run', 'dryRun'],
-    ['--force', 'force'],
-    ['--probe-contract', 'probeContract'],
-  ]);
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (booleanFlags.has(arg)) {
-      options[flagNames.get(arg)] = true;
-      continue;
-    }
-    if (arg !== '--scope' && arg !== '--host') throw new Error(`unknown ${command} option "${arg}"`);
-    const value = argv[index + 1];
-    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
-    options[arg === '--scope' ? 'scope' : 'host'] = value;
-    index += 1;
-  }
-  return options;
-}
+import { COMMANDS } from '../cli/command-registry.mjs';
+import { helpRequest, renderCommandHelp } from '../cli/command-help.mjs';
+
+export { commandOptions } from '../cli/command-registry.mjs';
+
+const publicCommands = COMMANDS.filter((entry) => entry.section === 'public');
+const commandWidth = Math.max(...publicCommands.map((entry) => entry.name.length));
+export const HELP = [
+  'codex-bridge — Claude Code dispatchers for Codex',
+  '',
+  'Usage:',
+  ...publicCommands.flatMap((entry) => [entry, ...Object.values(entry.actions ?? {})]
+    .flatMap((section) => section.usage.map((line) => `  ${line}`))),
+  '  codexb <same command forms as codex-bridge>',
+  '  codex-bridge --help',
+  '  codex-bridge --version',
+  '',
+  'Commands:',
+  ...publicCommands.map((entry) => `  ${entry.name.padEnd(commandWidth)}  ${entry.summary}`),
+  '',
+  'Hook dispatch:',
+  ...COMMANDS.filter((entry) => entry.section === 'machine')
+    .flatMap((entry) => entry.usage.map((line) => `  ${line}  ${entry.summary}`)),
+  '',
+  'Run codex-bridge <command> -h for one command.',
+].join('\n');
 
 export async function main(argv, io = console) {
   const [command, ...rest] = argv;
@@ -93,100 +39,17 @@ export async function main(argv, io = console) {
     io.log((await packageInfo()).version);
     return 0;
   }
-  if (command === 'run') return runCodex(rest);
-  if (command === 'doctor') {
-    const options = commandOptions(command, rest);
-    const host = resolveHost(options);
-    // The probe runs BEFORE the diagnosis so the `hostContract` line below carries the verdict just
-    // measured. Printing the diagnosis first and the measurement after would answer one question
-    // twice in one output, with the older answer on top (Plan_52 D25).
-    let probe = null;
-    if (options.probeContract) {
-      probe = await probeContract({ host });
-      io.log(`probe: ${probe.message}`);
-      for (const [name, verdict] of Object.entries(probe.dispatcher ?? {})) {
-        io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);
-      }
-    }
-    const result = await diagnose({ host });
-    io.log(renderDoctor(result));
-    // An inconclusive probe wrote nothing and measured nothing; exiting 0 would let a failed
-    // measurement pass silently in a script (Plan_52 D26).
-    return probe && probe.state === 'inconclusive' ? 2 : result.exitCode;
-  }
-  if (command === 'stop') {
-    if (rest.length !== 1) {
-      io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
-      return 2;
-    }
-    const result = await stop({ run: rest[0] });
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === HOOK_COMMAND) return hook(rest, io);
-  if (command === 'read') {
-    if (rest.length !== 1) {
-      io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
-      return 2;
-    }
-    const result = read({ run: rest[0] });
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'projects') {
-    const result = projects(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'model') {
-    const result = await model(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'prune') {
-    const result = await prune(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'sweep') {
-    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+  const entry = COMMANDS.find((candidate) => candidate.name === command);
+  if (!entry) {
+    io.error(`codex-bridge: unknown command "${command}"\nRun codex-bridge --help for usage.`);
     return 2;
   }
-  if (command === 'unlock') {
-    const result = unlock(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'permissions') {
-    let action;
-    let optionArgs = rest;
-    if (rest[0] && !rest[0].startsWith('-')) {
-      action = rest[0];
-      optionArgs = rest.slice(1);
-    }
-    if (action && !['add', 'remove'].includes(action)) {
-      throw new Error(`unknown permissions action "${action}"`);
-    }
-    const options = commandOptions(command, optionArgs);
-    const host = resolveHost(options);
-    const result = await permissions({ host, action });
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'install' || command === 'update' || command === 'uninstall') {
-    const options = commandOptions(command, rest);
-    const host = resolveHost(options);
-    const handlers = {
-      install: () => install({ host, dryRun: options.dryRun, force: options.force }),
-      update: () => update({ host, dryRun: options.dryRun, force: options.force }),
-      uninstall: () => uninstall({ host, dryRun: options.dryRun }),
-    };
-    const result = await handlers[command]();
-    io.log(result.output);
-    return result.exitCode;
+  const asked = helpRequest(rest, Object.keys(entry.actions ?? {}));
+  if (asked && entry.section !== 'renamed') {
+    io.log(renderCommandHelp(entry, asked.action));
+    return 0;
   }
-  io.error(`codex-bridge: unknown command "${command}"\nRun codex-bridge --help for usage.`);
-  return 2;
+  return entry.handler(rest, io);
 }
 
 if (isInvokedDirectly(process.argv[1], import.meta.url)) {

package/cli/command-help.mjs

@@ -0,0 +1,49 @@
+/**
+ * Decides what a help request is and how one command's help reads (Plan_71 D1).
+ * `codex-bridge model -h` answered "unexpected argument" and no subcommand answered -h at all
+ * (2026-09-29), so the operator could not learn how to set a model. Only exact argv shapes count
+ * (advice A1): a scan for --help would turn `--host --help` — today a "requires a value" refusal —
+ * into a help answer and hide the parser's error.
+ */
+
+export function helpRequest(argv, actions = []) {
+  const isHelp = (value) => value === '-h' || value === '--help';
+  if (argv.length === 1 && isHelp(argv[0])) return { action: null };
+  if (argv.length === 2 && actions.includes(argv[0]) && isHelp(argv[1])) {
+    return { action: argv[0] };
+  }
+  return null;
+}
+
+export function withCommandHelp(command, message) {
+  const hint = `Run codex-bridge ${command} -h for usage.`;
+  if (message === hint || message.endsWith(`\n${hint}`)) return message;
+  return `${message}\n${hint}`;
+}
+
+export function renderCommandHelp(entry, action = null) {
+  const prefix = `codex-bridge ${entry.name}`;
+  const actions = Object.entries(entry.actions ?? {});
+  // Registry typos must fail even when the malformed action is not the requested one.
+  for (const section of [entry, ...actions.map(([, details]) => details)]) {
+    for (const line of section.usage) {
+      if (line !== prefix && !line.startsWith(`${prefix} `)) {
+        throw new Error(`Help usage must start with "${prefix}": ${line}`);
+      }
+    }
+  }
+
+  let section = entry;
+  if (action !== null) {
+    const match = actions.find(([name]) => name === action);
+    if (!match) throw new Error(`Unknown help action for ${entry.name}: ${action}`);
+    section = match[1];
+  }
+  const lines = ['Usage:', ...section.usage.map((line) => `  ${line}`), '', section.summary];
+  if (action === null && entry.actions) {
+    const width = Math.max(...actions.map(([name]) => name.length));
+    lines.push('', 'Actions:', ...actions.map(([name, details]) => `  ${name.padEnd(width)}  ${details.summary}`));
+    lines.push(`Run codex-bridge ${entry.name} <action> -h for one action.`);
+  }
+  return lines.join('\n');
+}