@lyupro/codex-bridge 0.6.8 → 0.6.10

package/CHANGELOG.md

@@ -4,6 +4,166 @@ 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.10] - 2026-10-04
+
+### Added
+
+- `UNAVAILABLE` is a status of its own, with exit code `5`. Before any quota is spent, a bounded
+  `codex --version` and `codex login status` tell a missing or signed-out Codex from an unclear answer.
+  Only a missing or signed-out Codex refuses as `UNAVAILABLE`, without a run folder. After the start,
+  only a measured sample (a final `401 Unauthorized` turn failure) ends a run `UNAVAILABLE`. Any other
+  error stays `FAIL` with its raw text, so a lost subscription is never mistaken for a failed task.
+- A failed pass can be repeated once: `retry: <failed run> — <reason>` in the task header, with `--continue`.
+  The retry is accepted only for the last run of the chain, with a finished non-`OK` verdict and a worker
+  proven dead. It keeps the order id, agent, phase and continuation base, and does not spend another
+  continuation of the order. The reply says `Attempt: N of this pass`. Refusals met at a failed last run
+  print a ready `retry:` line.
+- One order id admits one paid worker. A launcher takes a kernel-held claim on the project's run store and
+  the exact order id (named pipe on Windows, abstract socket on Linux). It holds the claim until its worker is
+  registered, and the worker admits itself under the same claim before Codex starts. A second launch of the
+  same order attaches to the first run instead of paying again. A claim that stays busy for 60 seconds is a
+  free refusal, never a second start. On 2026-09-24 two launchers of one order started 2.8 s apart and
+  both paid.
+- A scout question can be marked `[context-only]` by its orderer. Such questions are about startup
+  context and pass without commands. An answer must cite `startup:<source>`, and a repository `path:line`
+  read by no command fails as an unread address. `questions.json` records `{id, text, kind}`.
+- The build reply adds a `Flags coverage: incomplete` line when the start content of a file could not be
+  judged. The status stays as it is.
+
+### Changed
+
+- Every runner exit code comes from one table, and a guard ties it to the docs and the prompts:
+  `0` OK, `1` FAIL, `2` usage error, `3` LIMIT, `4` still running or no run (`--no-wait`), `5` UNAVAILABLE.
+- Service lines of a task file live only in its header: consecutive `advice:`, `continue:` and `retry:`
+  lines from the first line. One parser serves the runner, the task hash and the `order-gate` hook. The task
+  hash covers the body only, and new runs record `task_hash_scheme: 2`. A label line below the header that
+  looks like metadata is refused for free, with its line number and the repair. **Orchestrators that write
+  `advice:` further down a build task must move it to the top.**
+- TODO, FIXME, skip and only flags judge only the lines a build run added. Before the run, the start content
+  of every dirty and untracked file is recorded, and only that run's additions are compared. Before this
+  change, a run was accused of markers it found in the tree.
+- A scope refusal names the flag the pattern came from (`--scope` or `--scope-new`). When git cannot list
+  the folder the run started in, the refusal says so instead of claiming a tracked file does not exist.
+
+### Fixed
+
+- A grant line no longer changes the task hash, so a run named in `continue:` is found again under a new
+  order id (it used to answer "the current last run is none").
+- An order owned by a run from before the task header is refused truthfully, not as a different task.
+- `codex-bridge read` on a run refused before Codex started now names that refusal. It no longer says
+  the run predates the event stream.
+- A reply no longer repeats its verdict (`OK — OK —`) when the model began its own summary with one.
+- An unparsable scope pattern is named in its refusal instead of printing `undefined`.
+
+## [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

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 **1667 automated tests: 1666 passing and 1 skipped**.
+The current suite contains **2848 automated tests: 2847 passing and 1 skipped**.
 
 ## Verify
 
@@ -129,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. |
+| `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,89 +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';
-import { resolveProbeTarget } from '../cli/probe-target.mjs';
-import { brandStateDir } from '../src/home/lib/brand-home.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] [--probe-executable <path>]
-  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' && !(command === 'doctor' && arg === '--probe-executable')) 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' : arg === '--host' ? 'host' : 'probeExecutable'] = 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;
@@ -95,103 +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);
-    if (options.probeExecutable && !options.probeContract) throw new Error('--probe-executable requires --probe-contract');
-    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) {
-      const target = resolveProbeTarget({ stateDir: brandStateDir(host.brandRoot), executable: options.probeExecutable });
-      if (!target.error) io.log(`probe: target ${target.version} at ${target.executable} (${target.source})`);
-      probe = await probeContract({ host, target });
-      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');
+}