@creatornader/agent-bridge 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,154 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-19
+
+### Added
+
+- Add v6 managed-client endpoint cutover and finalization commands. A
+  committed v5 stage authorizes a credential-free v6 journal only after both live
+  gateways negotiate HTTP 2.1, bind the recorded principal and credential IDs, report
+  one immutable authority ID, and complete a route challenge. Cutover drains the
+  source edge under an exclusive lease before changing a host registration. The initial
+  proof uses the predecessor and successor. Once a journal exists, every proof and
+  replay uses the successor credential at both URLs, then drains the source edge
+  through the target gateway. Finalization retires the source only after the
+  predecessor grace cutoff. Dry runs inspect edge state without opening SQLite for
+  write access or contacting a gateway. Resume classifies durable before and after
+  proofs and cannot take over a live lease.
+
+- Add migration 019 for successor-only endpoint-migration challenges. A challenge now
+  accepts either a direct predecessor-to-successor pair or the same active successor
+  credential on both endpoints. The migration preserves the migration 018 challenge
+  records and readiness controls, adds v2 endpoint and v6 owner attestations, and does
+  not grant cutover authority. Authenticated HTTP 2.1 capabilities now return the
+  credential's `grantedScopes`.
+
+- Add migration 017 with an immutable PostgreSQL gateway authority UUID. Production
+  request authority now uses a bound opener without changing the released opener's
+  return shape. Authenticated gateway status adds optional `gatewayAuthorityId` and
+  `credentialId` fields under HTTP 2.1. Native DR preserves the UUID as logical
+  authority continuity, not live-clone fencing. Deployments must drain old gateway
+  instances before the migration.
+
+- Add `clients migrate stage <runtime>` for inert gateway-client migration
+  preparation. The command probes the active and successor bearer credentials, records
+  enrollment credential IDs and credential-free source and target bindings, and
+  prepares a private successor backend without changing the active registration or
+  backend. It does not authorize cutover. The source SQLite edge gate prevents new
+  outbox inserts once a later drain starts, including from a client that opened the
+  database before the gate changed. Staging requires an absolute, normalized source
+  edge database path and rejects in-memory edge state.
+
+- Add explicit, plan-first `clients rollback <update-operation-id> --identity <name>`
+  for committed same-host v4 updates. `--apply` creates a separate reverse journal.
+  It verifies the source inverse contract and current forward metadata and
+  registration before it removes the forward native entry, restores the prior entry,
+  and writes prior metadata last. Claude Desktop replaces only its Agent Bridge entry.
+  Generic `clients resume` also resumes a reverse journal. The v4 source completion
+  keeps only a bounded credential-free inverse contract. Repair remains monotonic and
+  uninstall stays forward-only. Managed operation summaries preserve the durable
+  manifest version and include the `rollback` kind.
+
+- Add forward-only `clients uninstall` for metadata-owned Codex, Claude Code, and
+  Claude Desktop registrations. Uninstall proves and removes the managed
+  registration, deletes an already private backend file, then deletes management
+  metadata. It never snapshots backend bytes or reverses a completed step. POSIX
+  deletion syncs the private parent directory. Windows verifies deletion and records
+  unavailable directory durability. Native and Desktop writes retain their documented
+  same-user advisory race boundaries.
+  Add `clients resume <operation-id> [--recover-lock]`, which derives repair and
+  uninstall authority from recorded v3 requests, and update or rollback authority
+  from recorded v4 requests. It also accepts pre-v4 update journals. It accepts no
+  replacement identity, runtime, instance, launch, or file locator. Version 2
+  journals remain inspectable only. Generic resume also completes an uninstall
+  interrupted after its final metadata deletion.
+
+- Add plan-first `clients repair` and `clients update` for metadata-owned Codex,
+  Claude Code, and Claude Desktop registrations. Runtime and stable instance locate
+  strict owner-private metadata. Identity binds the record and immutable repair or
+  update request. Repair restores the stored launch contract, while update journals a
+  normalized credential-free launch request.
+  Applied native changes prove remove, absence, add, and exact target before a
+  metadata-last launch update. Desktop replaces only the Agent Bridge entry and
+  preserves unrelated JSON values. Backend privacy repair records only policy proofs
+  and tightens permissions without reading or snapshotting backend content. Full
+  metadata and bounded registration proofs prevent drifted state from advancing a
+  prior journal. Unknown environment keys and unsafe registration fields stop before
+  journal creation. Native update commands reject argument, credential, and URL-like
+  surfaces. Desktop publication uses a private operation-scoped temporary file and
+  detects the checked races that Node can observe, but it cannot provide an OS
+  transaction with Claude Desktop. Same-action same-host resume and stale-lock recovery
+  use the existing operation substrate.
+  New journals use operation format version 3. Version 2 journals remain inspectable,
+  but incomplete records cannot resume without an identity-bound request.
+
+- Give local and edge SQLite initialization a 15-second minimum busy-retry window
+  for concurrent first-start schema work. Normal database operations retain their
+  configured timeout. Concurrency tests also terminate hung child processes before
+  temporary-directory cleanup.
+
+- Add the crash-safe managed-client operation substrate and read-only `clients
+  operations [<operation-id>]` inspection. Owner-private revisioned manifests,
+  immutable ordered step plans, snapshot artifacts, pinned directory identities,
+  per-client locks, and same-host stale-lock proof keep private contents out of JSON
+  and errors. Restart classification distinguishes exact before-state retries,
+  verified after-state advancement, and blocked ambiguity. Snapshot publication never
+  replaces residue, every step requires a verified before-state snapshot, and bounded
+  manifests reject contradictory state. Typed credential-agnostic requests,
+  no-replace before/after artifacts, lock-covered begin, and same-host resume now feed
+  distinct resumable, classification-required, blocked, and complete inspection.
+  Crash-restartable per-artifact cleanup advances `applied` through `cleaning` to a
+  `committed` manifest after verified unlink and POSIX directory sync, or an explicit
+  Windows unavailable-durability result. Exact after-publication and post-intent unlink
+  residue can resume; every other missing or extra artifact blocks. Terminal manifests
+  retain a bounded credential-free completion record. Windows mutations reuse native
+  ACL results only within one held lock and for the same verified directory path
+  identity. File checks, new or resumed locks, and passive inspection recheck the
+  policy. POSIX checks remain per-access. Repair, update, and uninstall use this substrate.
+
+- Add read-only `clients inspect` and plan-first `clients adopt` for Codex, Claude
+  Code, and Claude Desktop. Exact unmanaged registrations can be adopted only with
+  `--apply`, which writes owner-only credential-free management metadata. Inspection
+  reports absent, unmanaged, managed, or drifted state without reading backend values
+  or contacting a gateway. Registration comparison is structural and health-neutral,
+  backend paths enforce the owner-only no-link policy, Desktop inspection shares the
+  installer launch resolver, and apply re-inspects its postcondition. Enrollment-based
+  provision collision behavior is unchanged. Managed metadata also binds Desktop to
+  its normalized config path, Codex to its active profile config, and Claude Code
+  local or project scope to its invocation directory so later operations cannot guess
+  at a registration target.
+
+- Add a pinned, non-root gateway image and a loopback-only Compose development stack.
+  The stack runs migrations separately, creates a restricted runtime login, reads
+  database passwords from private secret files, and retains PostgreSQL data in a named
+  volume.
+- Add a Linux Compose acceptance test for credential-bound identity, targeted delivery,
+  lease settlement, denied runtime access to credential hashes, and PostgreSQL
+  persistence across a full stack restart.
+- Add a deployment guide for production TLS, network isolation, secret handling,
+  backup, upgrade order, and rollback.
+
+### Fixed
+
+- Defer Windows SQLite sidecar ACL application until the opened connection establishes
+  WAL and completes its serialized schema transaction. Concurrent first-open processes
+  no longer race a transient sidecar before their own connection holds it. Replacement
+  during one ACL validation still fails.
+- Treat a Windows SQLite sidecar that disappears during ACL validation as an expected
+  race only when the path remains absent. A replacement or reparse object still fails
+  validation.
+- Handle `-h` and `--help` before command parsing and dispatch so help never opens a
+  backend or performs a command side effect.
+
+### Changed
+
+- Require the exact release commit to pass the full `test.yml` matrix on `main` before
+  release packaging begins. Pin GitHub Actions and reusable workflows to verified
+  commit SHAs.
+- Keep Dependabot's grouped npm updates to patch and minor versions. Major updates now
+  require separate review.
+
 ## [0.3.1] - 2026-07-15
 
 ### Added
@@ -136,7 +284,8 @@ First tagged release. Marks the point where agent-bridge has shipped its initial
 - Narrative-leak detection in CI + on commit via `creatornader/textleaks@v0.2.0` (renamed from leakguard).
 
 [0.1.0]: https://github.com/creatornader/agent-bridge/releases/tag/v0.1.0
-[Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/creatornader/agent-bridge/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/creatornader/agent-bridge/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/creatornader/agent-bridge/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/creatornader/agent-bridge/compare/v0.1.0...v0.2.0

package/README.md

@@ -43,6 +43,26 @@ Restart the client, then run `agent-bridge doctor --json` if the MCP server does
 attach. The [troubleshooting guide](docs/troubleshooting.md) covers executable paths,
 client configuration, and recovery steps.
 
+## Run the gateway with Compose
+
+The repository includes a loopback-only Compose stack for development and evaluation.
+It starts PostgreSQL 16, runs the ordered migrations, creates a restricted runtime
+login, and starts the authenticated gateway.
+
+```bash
+mkdir -m 700 .secrets
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/postgres_password
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/runtime_password
+chmod 600 .secrets/*
+docker compose up --build --wait gateway
+curl --fail http://127.0.0.1:8787/readyz
+```
+
+The checked-in stack publishes the gateway and PostgreSQL only on loopback. It is not
+a production TLS deployment. Read [the deployment guide](docs/deployment.md) before
+exposing a gateway, changing network bindings, upgrading the schema, or relying on the
+named volume for persistent data.
+
 ## What v2 provides
 
 - Immutable messages with UUIDv7 IDs and opaque server cursors.
@@ -67,6 +87,8 @@ The canonical v2 operation registry generates [JSON Schema](schemas/agent-bridge
 
 Protocol 2.1 uses a gateway-first rollout. An upgraded gateway continues to serve released 2.0 clients, including headerless requests and their direct or null delivery results. A 2.1 client probes before mutation and proceeds only when complete, consistent response headers select 2.1 and advertise 2.1 support. It rejects mutation against a headerless or 2.0 gateway instead of downgrading. Upgrade the gateway before installing or starting 2.1 clients.
 
+Two gateway-only HTTP 2.1 operations establish a short-lived endpoint-migration challenge. Initial preflight uses a direct predecessor and successor. After a cutover journal exists, the same active successor credential can issue at the retained source URL and consume at the target URL. Both calls require active transaction-bound authority and use the canonical credential and operation rate buckets. PostgreSQL stores only a domain-separated SHA-256 commitment. A challenge expires within 60 seconds and does not authorize endpoint cutover. Authenticated HTTP 2.1 capabilities include the credential's `grantedScopes`.
+
 The OpenAPI paths describe protocol 2.1. The embedded `x-agent-bridge-protocol-2.0` and `x-agent-bridge-schemas-2.0` vendor extensions contain frozen compatibility schema metadata for released 2.0 clients. They are not a second OpenAPI description. Gateway credentials enforce the operation scopes declared by the canonical registry. Local mode uses process identity, and legacy mode uses its configured key. Provider-neutral artifacts report this difference instead of claiming one authorization model for every backend.
 
 ## Architecture
@@ -149,6 +171,8 @@ for its relationship to MCP, A2A, agmsg, brokers, and agent runtimes.
 
 - Node.js 22.23.1 or newer.
 - SQLite 3.51.3 or newer for local and edge storage. The supported Node version includes it.
+- Concurrent local and edge initialization may wait up to 15 seconds for schema work;
+  normal database operations retain their configured busy timeout.
 - PostgreSQL 15, 16, 17, or 18 for gateway mode. New PostgreSQL majors fail the
   migration prerequisite and live readiness checks until their catalog digest is
   certified.
@@ -304,7 +328,8 @@ agent-bridge dr restore \
 PostgreSQL backup takes a repeatable-read snapshot while holding the native DR fence.
 It stores the `agent_bridge` schema dump plus a canonical inventory of required roles,
 memberships, and default privileges. The backup excludes transient data from agent
-instances, rate-limit buckets, request authority, and archive transaction authority.
+instances, rate-limit buckets, request authority, endpoint-migration challenge rows, and
+archive transaction authority.
 Restore turns claimed deliveries into immediately retryable work because a database
 restore cannot preserve a live lease.
 
@@ -385,12 +410,200 @@ Claude Code installation uses its native MCP command. Claude Desktop installatio
 merges the `agent-bridge` server into its JSON config with an atomic write. Restart the
 client after installation.
 
+Inspect an existing registration before making Agent Bridge its lifecycle owner:
+
+```bash
+agent-bridge clients inspect codex --identity codex --instance <stable-key> \
+  --backend-config <absolute-client-backend-path>
+agent-bridge clients adopt codex --identity codex --instance <stable-key> \
+  --backend-config <absolute-client-backend-path>
+agent-bridge clients adopt codex --identity codex --instance <stable-key> \
+  --backend-config <absolute-client-backend-path> --apply
+```
+
+`inspect` is local, read-only, and does not return backend values or credentials. It
+classifies the requested registration as `absent`, `unmanaged`, `managed`, or
+`drifted`. `adopt` is plan-only unless `--apply` is explicit, and application writes
+only owner-private, credential-free management metadata after the identity, instance,
+backend path, scope, launch contract, and registration locator match exactly. Adoption
+never rewrites the host registration or backend file. Enrollment-based first-time
+provisioning still refuses registration and backend-file collisions.
+Claude Code inspection accepts the installed `--scope`; Claude Desktop accepts an
+explicit validated `--command` and, when needed, `--config-path`; its default contract
+is absolute Node plus the absolute server entry. Other adapters reject these
+runtime-specific options. Managed metadata binds Desktop to that normalized config
+path and Codex to its active profile config. Claude Code local and project adoption
+bind to the current directory because the native CLI exposes no stronger locator, so
+run those operations from the project context that later lifecycle commands should
+use. Backend files and their immediate parents must satisfy the owner-only no-link
+policy. Registration state is independent of connectivity health, and applied
+adoption re-inspects before reporting success.
+
+Once adopted, repair, update, and uninstall locate the registration from owner-private managed
+metadata. The runtime and stable instance select that record. `--identity` must match
+the recorded identity and the immutable request. These commands reject backend-path, scope, and host
+config locator flags, so a caller cannot redirect a managed mutation.
+
+```bash
+agent-bridge clients repair codex --identity codex --instance <stable-key>
+agent-bridge clients repair codex --identity codex --instance <stable-key> --apply
+agent-bridge clients update codex --identity codex --instance <stable-key> \
+  --command agent-bridge-mcp --apply
+agent-bridge clients repair codex --identity codex --instance <stable-key> \
+  --apply --resume <operation-uuid>
+agent-bridge clients uninstall codex --identity codex --instance <stable-key> --apply
+agent-bridge clients rollback <update-operation-uuid> --identity codex
+agent-bridge clients rollback <update-operation-uuid> --identity codex --apply
+agent-bridge clients resume <operation-uuid>
+agent-bridge clients migrate stage codex --identity codex --instance <stable-key> \\
+  --enrollment-file <private-path>
+agent-bridge clients migrate cutover <stage-operation-uuid> --exclusive-edge
+agent-bridge clients migrate cutover <stage-operation-uuid> --exclusive-edge --apply
+agent-bridge clients migrate finalize <cutover-operation-uuid> --exclusive-edge --apply
+```
+
+These commands return a plan by default. A managed registration that is already exact
+and has a private backend file produces no operation. Repair restores the recorded
+launch contract. Update validates and records a new credential-free launch contract
+before it creates a journal. A native `--command` is one executable contract. Bare
+commands cannot contain arguments or URL-like selectors. Absolute paths must resolve
+to executable files. Native adapters remove, verify absence, add, and verify
+the target registration. Claude Desktop replaces only `mcpServers.agent-bridge`,
+preserves unrelated JSON values in memory, publishes through a private operation-scoped
+temporary file, and verifies the new entry. Node cannot provide an OS transaction with
+an uncooperative same-user Desktop writer. The pre-rename identity checks make this an
+advisory race boundary rather than a guarantee.
+
+Uninstall is forward-only. It removes the managed registration and verifies its
+absence, deletes the private backend file, then deletes the management metadata. It
+does not repair an unsafe backend before deletion. If the backend is not already
+private, uninstall stops without changing the registration. It does not restore a
+registration, backend, or metadata file after a later step fails. Desktop removes only
+`mcpServers.agent-bridge` and preserves other JSON values. Backend and metadata removal
+check the file and private parent identities before unlink. POSIX then syncs the parent
+directory. Windows verifies the result but records unavailable directory durability.
+Node cannot make pathname-based deletion atomic against an uncooperative same-user
+writer, so that boundary remains advisory.
+
+Rollback is explicit and update-only. A committed v4 update retains a bounded
+credential-free inverse contract: its prior managed metadata, prior exact
+registration contract, and digests for the forward metadata and registration state.
+`clients rollback` uses only the source operation UUID and matching identity. It first
+returns a plan. With `--apply`, it creates a separate reverse journal after it proves
+the source is same-host, the source is a committed v4 update, and the current state
+still matches the recorded forward state. Native reversal removes the forward entry,
+adds the prior entry, then writes prior metadata. Claude Desktop replaces only its
+Agent Bridge entry and writes prior metadata last. A reverse journal can resume with
+`clients resume`; a second rollback fails because the forward state is no longer
+present. Repair remains monotonic. Uninstall recovery requires re-enrollment.
+
+`--resume` must name an unfinished operation for the same action, runtime, instance,
+and identity. It uses the recorded request instead of new flags. `--recover-lock`
+requires `--apply` and only removes an old same-host lock after the process-death
+proof succeeds. Never delete a lock manually.
+
+`clients resume <operation-uuid>` takes only recorded v3, supported v4, v5
+migration-stage, or v6 endpoint-migration operation authority and an optional
+`--recover-lock`. It does not accept a replacement action, runtime,
+instance, identity, command, backend path, scope, or config locator. Use it for every
+generic resume. It is also required when an uninstall has already deleted its final
+metadata file, because the action-specific command has no metadata record left to
+assert.
+
+Repair and uninstall create v3 journals. New update and reverse rollback journals use
+v4. Existing v2 journals remain inspectable. A non-terminal v2 journal lacks the
+required identity-bound request, so it is blocked rather than resumed by these commands.
+
+Managed-client operations now have a crash-safe local substrate under the owner-only
+`~/.agent-bridge/operations/` directory. `agent-bridge clients operations` lists safe
+operation summaries, and appending an operation UUID inspects one manifest. Output
+never includes artifact contents or backend values. Update requests retain only a
+normalized launch command, arguments, scope, and the fixed Agent Bridge environment
+key names. Each immutable ordered plan names
+registration, backend, and management-metadata targets with non-sensitive locators,
+no-replace before and after artifacts, and expected digests. Registration artifacts
+contain only bounded Agent Bridge fields and the full nonsecret target contract. An
+unknown environment key, malformed field, unsafe argument, or wrong scope stops before
+the journal is created. Begin holds the
+runtime-plus-instance lock and refuses another unfinished operation. Any corrupt or
+blocked journal fences new mutations and resume until an operator resolves it. Resume is
+same-host only. Intent is durable before an
+external write; observed-applied is durable only after the after-state is verified.
+On restart, the exact pending step is retryable only at its before-state, advances only
+at its after-state, and otherwise blocks as ambiguous. Sensitive file access checks and
+pins its immediate directory. Stale-lock recovery separately pins the operation root
+and locks directory for the full recovery sequence. Creation and destructive cleanup
+also keep the operation root and target directories pinned through their writes. The
+full metadata record is rechecked after the lock and before every non-metadata step.
+
+On Windows, a held mutation lock can reuse a native ACL result only for the same
+directory path identity. File checks, every new or resumed lock, and each passive
+inspection check the ACL again. POSIX mode checks remain per-access. This cache does
+not change local mode's trust in the current OS user.
+
+The journal states are `prepared`, `snapshotted`, `in-progress`, `applied`, `cleaning`,
+and `committed`; inspection separately reports `resumable`,
+`classification-required`, `blocked`, or `complete`. `committed` means every write was
+verified and every artifact was removed. Cleanup records durable intent per artifact,
+pins and verifies it, unlinks it, and syncs the directory on POSIX; Windows explicitly
+records unavailable directory durability. A missing artifact is safe to resume only
+when cleanup intent predated the attempt. Inspection accepts only two exact crash
+residues: that authorized absence, or the verified after artifact for the current
+intent-recorded step. A terminal manifest removes request, step, digest, locator, and
+artifact metadata. A v4 update retains only its explicit credential-free inverse
+contract. A committed v5 stage retains its credential-free stage contract. A committed
+v6 phase retains its credential-free cutover contract. Completed records remain
+readable across hosts. Repair, update, rollback, uninstall, and endpoint migration use
+this journal. Agent Bridge cannot promise physical erasure
+on SSDs or journaled filesystems, so future commands must minimize credential-bearing
+snapshots and rotate credentials when retained copies contained them. Inspection
+changes no registration, backend, metadata, or snapshot file.
+
 The v1 host-adapter manifests are under [`clients/`](clients/). Their compatibility
 field is named `runtime`, but its value identifies the installation target, not a
 unique process. OpenClaw and generic MCP manifests declare the required environment
 variables and command but leave config mutation to the operator because their host
 config shapes vary.
 
+The lifecycle ownership boundary and deferred endpoint-migration constraints are
+recorded in [ADR 0004](docs/decisions/0004-client-lifecycle-and-endpoint-migration.md).
+
+`clients migrate stage <runtime> --identity <name> --instance <key>
+--enrollment-file <path> --apply` prepares a private gateway successor from a rotation
+enrollment. It does not change the active registration or backend. Staging records
+endpoint digests, credential IDs, the source edge path and scope key, and the
+predecessor grace cutoff without recording tokens or raw gateway URLs.
+
+`clients migrate cutover <stage-operation-uuid> --exclusive-edge --apply` consumes a
+committed v5 stage. Before it creates a journal, it verifies both live gateways under
+HTTP 2.1, including the recorded workspace, principal, credential ID, immutable gateway
+authority ID, and the successor credential's `status:read` and `messages:write` grants.
+The endpoints then exchange a direct predecessor-to-successor route challenge. The
+durable journal retains the normalized source gateway URL without a token. Every later
+route challenge uses the successor credential at both URLs, and it drains the source
+edge through the target gateway. The source edge changes to `draining`, receives an
+exclusive lease, and must reach an exact zero-work outbox before any host registration
+changes. The command removes and adds native registrations, or replaces the Claude
+Desktop entry, then changes managed metadata last. It rechecks the authority and lease
+before every host write.
+
+Every cutover phase requires `--exclusive-edge`. Agent Bridge can enumerate managed
+registrations that share an edge file, including hardlink aliases, but it cannot see
+unmanaged publishers. The flag records the operator's assertion for that remaining
+cohort. The forward phase also requires an active source edge and an active, empty
+target edge.
+
+`clients migrate finalize <cutover-operation-uuid> --exclusive-edge --apply` works
+only after the predecessor grace cutoff and retires the retained source edge. To return
+to an earlier endpoint, first rotate a new owner credential for that endpoint, then run
+an ordinary forward cutover with it as the successor. Use `clients resume
+<operation-uuid>` after a crash. Resume waits for a live drain lease to expire before
+another worker can take it. Dry inspection refuses an edge with live WAL sidecars rather
+than opening it in a mode that could miss uncheckpointed outbox state.
+Moving to an independent database needs a separate owner-mediated process.
+The source backend must name an absolute, normalized edge database file. Relative and
+in-memory edge paths cannot identify one durable outbox and are rejected.
+
 [`SKILL.md`](SKILL.md) provides concise runtime-neutral operating instructions for agents. [`llms.txt`](llms.txt) gives tools and model crawlers a compact map of the package, modes, commands, and identity rules.
 
 ## Gateway setup
@@ -631,6 +844,7 @@ Normal inbox and pending reads fall back to the local cache when the gateway is
 
 ```bash
 agent-bridge --version
+agent-bridge --help
 agent-bridge init --provider local
 agent-bridge doctor
 agent-bridge status
@@ -658,6 +872,10 @@ agent-bridge sync
 agent-bridge watch
 ```
 
+`-h` and `--help` print help before Agent Bridge loads backend configuration or
+dispatches a command. They are safe to use after a command name, including `archive`
+and `dr` commands.
+
 `--project` adds an optional immutable label to a message. It never selects a workspace or changes the active identity. Omit it on reads to include every project and unlabeled messages in the credential-bound workspace. Pass it to `get`, `inbox`, `history`, `pending`, or `watch` for an exact label match. Gateway callers may use `--workspace` only as an assertion. The CLI rejects a mismatch before sending a request. Local mode permits a per-command workspace override. The global legacy Supabase schema has no tenant workspace, so legacy mode fixes workspace to `*` and rejects other `--workspace` values.
 
 History defaults to mailbox `inbox`: broadcasts plus messages targeted to the configured principal, exactly as prior releases did. `sent` selects messages whose source is that principal, and `all` is the union. `--receipt-state any|unread|read` is caller-relative and valid only with `inbox`. The deprecated `--unacked-by` option remains an identity assertion. The CLI rejects a mismatch before opening storage or contacting a gateway. Server surfaces reject it before querying message storage. Cursors bind workspace, principal, mailbox, and normalized filters. Version 1 cursors are temporarily accepted, while all new cursors are version 2.
@@ -773,6 +991,8 @@ Each gateway operation checks the scopes in the canonical registry. `capabilitie
 
 Migration 012 makes PostgreSQL the authority for each production gateway request that passes credential preflight. Node hashes the bearer credential before PostgreSQL receives it. The gateway checks out one connection, opens one explicit transaction, matches the credential ID and hash inside a narrow security-definer function, and derives the workspace, principal, and scopes from current database state. Security accounting and domain work share that transaction and backend. Delivery claim, cancel, and requeue reuse it without nested `BEGIN`. Runtime logins cannot read credential hashes, agent records, workspace records, or request-authority records.
 
+Migration 017 adds one immutable PostgreSQL authority UUID. The released request-authority opener keeps its return shape. Production gateway requests use a bound opener that returns the authority UUID with the database-derived credential. Authenticated gateway `/v2/status` replies include `gatewayAuthorityId` and `credentialId` when transaction-bound request authority is active. Authenticated HTTP 2.1 capabilities return `grantedScopes` for that credential. Migration 018 uses the same bound authority to issue and consume an expiring challenge for a direct credential successor. Migration 019 also permits the same active successor credential at both endpoints after a cutover journal begins. Neither challenge proves a database migration or authorizes endpoint cutover.
+
 Migration 013 enables and forces row-level security on messages, receipts, deliveries, delivery events, and presence. Policies read workspace and principal from the transaction-bound request authority. The runtime role cannot set that authority through session variables, inherit a table-owner role, or bypass RLS. Separate no-login roles own domain tables, read request context, and write delivery audit events. Delivery identity and publisher bindings are immutable. A trigger lets recipients perform recipient lifecycle actions and reserves cancel and requeue for publishers.
 
 The migration records a catalog attestation after it creates the policies, constraints, triggers, and security functions. `/readyz` fails if the current catalog no longer matches that owner-created baseline. Gateway capabilities report `rowIsolation: true` only when request authority is enabled and the migration, catalog attestation, ownership, policy, privilege, and function checks all pass. An owner-approved schema change must update the attestation in its migration.
@@ -813,14 +1033,27 @@ The runtime role owns no schema objects. PostgreSQL keeps roles after a database
 ```bash
 npm run typecheck
 npm test
+npm run test:postgres:preflight
 npm run build
 npm pack
 ```
 
-Set `AGENT_BRIDGE_TEST_DATABASE_URL` to run the live PostgreSQL contract and migration
-tests. CI runs Node 22 and 24 on Linux, macOS, and Windows. PostgreSQL 15 through 18 each
-pack and install the npm tarball, register a least-privilege operator, and exercise
-owner provision, inventory, rotation, and revocation. Before applying a Windows DACL,
+The PostgreSQL preflight starts a fresh Docker container for each supported major,
+assigns a free loopback port, and runs the live contract. Normal completion removes
+each container. A later run removes labeled preflight containers older than two hours,
+which bounds residue after a process or machine stops before cleanup can run. Use
+`npm run test:postgres:preflight -- --major 16` for one major, or
+`npm run test:postgres:preflight:full` for the full suite on every major. The command
+requires a running Docker engine and never reuses a database from an earlier run.
+
+Set `AGENT_BRIDGE_TEST_DATABASE_URL` when an existing disposable PostgreSQL database is
+more convenient. CI runs one PostgreSQL 16 contract before starting the 15 through 18
+jobs. Each version then runs the live contract and matching native DR proof. The package
+job builds and installs the npm tarball separately.
+
+CI runs Node 22 and 24 on Linux, macOS, and Windows. One native Windows contract checks
+private paths, managed uninstall path identity, and recovery before the two Windows jobs
+start. Before applying a Windows DACL,
 private paths must be owned by the current account SID or the active token's default
 owner SID. The final owner and sole protected FullControl rule must use the account SID.
 Verification-only paths must already satisfy that final policy. Node file identity
@@ -835,6 +1068,7 @@ durability behavior has not yet been proved on a dedicated Windows host.
 - [SECURITY.md](SECURITY.md): supported versions, release integrity, private vulnerability reporting, and security boundaries.
 - [docs/ecosystem.md](docs/ecosystem.md): product boundary, adjacent systems, and interoperability direction.
 - [docs/troubleshooting.md](docs/troubleshooting.md): MCP startup, identity, backend, and client recovery.
+- [docs/deployment.md](docs/deployment.md): Compose development setup, production constraints, upgrades, backup, and rollback.
 - [ADR-0001](docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md): protocol layers and acknowledgment semantics.
 - [ADR-0002](docs/decisions/0002-canonical-operation-contract-registry.md): canonical contracts, generated artifacts, discovery, and version negotiation.
 - [ADR-0003](docs/decisions/0003-host-adapters-and-consumer-instance-keys.md): host layers and consumer instance-key semantics.

package/ROADMAP.md

@@ -9,7 +9,7 @@ published and the supported clients pass a fresh end-to-end check.
 
 ## Status
 
-### Released by 0.3.0
+### Released by 0.3.1
 
 - Local SQLite and shared PostgreSQL storage behind provider-neutral interfaces.
 - An authenticated HTTPS gateway and a named legacy Supabase adapter.
@@ -17,6 +17,7 @@ published and the supported clients pass a fresh end-to-end check.
   presence.
 - Durable SQLite edge outbox and inbox cache for gateway clients.
 - CLI, MCP, HTTPS, and Node library access surfaces.
+- Installed-package version reporting through `agent-bridge --version` and `-V`.
 - Automated host adapters for Codex, Claude Code, and Claude Desktop. The Codex
   adapter configures the profile shared by the Codex CLI and the Codex surface in the
   ChatGPT desktop app.
@@ -34,14 +35,68 @@ published and the supported clients pass a fresh end-to-end check.
 - Portable workspace archives across canonical SQLite and PostgreSQL stores.
 - Native SQLite and PostgreSQL backup, verification, and restore.
 
+### 0.4.0 package contents
+
+The published npm version is the authority for whether this package line has shipped.
+
+- Read-only lifecycle inspection and explicit, plan-first adoption for the Codex,
+  Claude Code, and Claude Desktop adapters, backed by owner-only credential-free
+  managed metadata, private backend-path verification, health-neutral exact
+  registration comparison, immutable nonsecret host locators, and a re-inspected
+  adoption postcondition.
+
+- Plan-first managed-client repair, update, and forward-only uninstall for Codex, Claude Code, and Claude
+  Desktop. Mutation authority comes only from strict private metadata selected by
+  runtime and instance, then bound to the exact managed identity. Applied work uses
+  the crash-safe journal, fixed-key credential-free update requests, full metadata and
+  bounded registration proofs, exact restart classification, monotonic POSIX backend
+  privacy repair, and metadata-last launch updates. Windows accepts only an already
+  private backend path. Uninstall removes the registration, backend, and metadata in
+  that order without rollback. It refuses a backend that still needs privacy repair.
+  Desktop publication and deletion have a documented same-user advisory race.
+  New updates use v4 journals and retain a bounded credential-free inverse contract.
+  `clients rollback <update-operation-id> --identity <name>` is plan-first and, with
+  `--apply`, creates a separate reverse journal after it proves the recorded forward
+  state. Generic `clients resume` derives authority from recorded v3, supported v4,
+  v5 migration-stage, and v6 endpoint-migration requests. Repair remains monotonic
+  and uninstall recovery is re-enrollment.
+
+- Gateway-client migration staging, cutover, and finalization for managed
+  clients. A v5 stage creates a private successor backend without changing the active
+  host registration. A v6 cutover verifies one live gateway authority and a route
+  challenge, drains the source SQLite edge under a lease, changes the host registration
+  and metadata, and preserves credential-free contracts for restart classification.
+  After journal creation, cutover proves both routes with the successor credential and
+  drains the source edge through the target gateway. Finalize retires the retained
+  source after the predecessor grace cutoff. Return to an earlier endpoint requires a
+  new owner rotation and a new forward cutover. Each phase requires a fresh
+  `--exclusive-edge` assertion because unmanaged publishers cannot be enumerated.
+
+- Gateway-only HTTP 2.1 endpoint-migration challenge operations. An active issuer and
+  direct active successor use a 64-character challenge bound to the immutable gateway
+  authority UUID. PostgreSQL stores only a domain-separated commitment for at most 60
+  seconds. A consumed cross-route challenge proves that both live routes share its
+  short-lived database state. It does not authorize endpoint cutover or prove a
+  historical database move.
+
+- A pinned, non-root gateway image and a Compose development stack with ordered
+  migration, restricted runtime-role bootstrap, health checks, private secret files,
+  and a persistent PostgreSQL volume.
+- A Linux Compose acceptance test that provisions two temporary principals and proves
+  authority binding, delivery settlement, denied runtime access to credential hashes,
+  idempotent restart, and PostgreSQL volume persistence.
+- A production deployment guide covering TLS, network exposure, secret separation,
+  backups, upgrade order, and schema rollback limits.
+
 ### Post-release validation and adoption
 
 - Move the project's own normal traffic to the authenticated gateway while retaining a
   tested legacy rollback path.
 - Prove cross-machine claim, settlement, offline replay, and restart behavior against
-  the published package and a deployed v2 gateway. The 0.3.0 live release check covered
-  startup, private mailbox sends, caller-scoped history, receipts, and client restart
-  through the legacy compatibility backend; it could not prove gateway-only behavior.
+  the published package and a deployed v2 gateway. The historical 0.3.0 live release
+  check covered startup, private mailbox sends, caller-scoped history, receipts, and
+  client restart through the legacy compatibility backend. It did not prove
+  gateway-only behavior.
 - Replace remaining direct legacy table pollers with the v2 cursor protocol.
 - Confirm the README, npm metadata, GitHub metadata, release notes, and package contents
   match the released artifact.
@@ -50,9 +105,6 @@ published and the supported clients pass a fresh end-to-end check.
 
 ### Installation and operations
 
-- Add client repair, update, uninstall, and registration diagnostics.
-- Provide a Compose-based development deployment and a production deployment guide.
-- Add endpoint migration tooling that does not strand an existing SQLite outbox.
 - Publish a maintained client compatibility matrix.
 
 ### Storage lifecycle and observability