@creatornader/agent-bridge 0.3.1 → 0.5.0

package/README.md

@@ -43,6 +43,71 @@ 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.
+
+The repository also maintains a provider-neutral Fly.io reference at
+[`deploy/fly.toml`](deploy/fly.toml). It deliberately omits an app name and release
+command. Check the local contract before creating or changing any Fly resource:
+
+```bash
+npm run preflight:fly -- --json
+```
+
+Before migrating an existing PostgreSQL database, run the read-only production
+preflight with schema-owner authority:
+
+```bash
+AGENT_BRIDGE_DATABASE_URL="..." npm run preflight:postgres:production -- --json --require-ssl
+```
+
+The command checks the PostgreSQL major, database and role authority, existing
+migration ledger, derived-role collisions, and the legacy `shared_context` import
+shape inside a read-only transaction. `authority.roles` reports migration capability:
+the schema owner may be a true superuser or a managed-provider administrator with
+`CREATEROLE`. `authority.native_dr` reports source-backup capability. The source normally
+connects as the schema owner, which must be a true superuser or hold `BYPASSRLS`, so
+`CREATEROLE` alone can run migrations but cannot create a native backup. A restore target
+uses its superuser session to validate a suspended restored schema-owner shell. The
+migration suite tests both authority forms on PostgreSQL 15 through
+18. The command does not print the connection URL or apply DDL. `--require-ssl` rejects
+an unencrypted public database connection. Passing the preflight does not replace a
+backup or authorize migration. When a session pooler terminates TLS, the check inspects
+the client socket instead of the pooler's separate database connection.
+
+After an operator supplies an existing app, `npm run preflight:fly -- --app <app>
+--json` adds read-only account, app, machine, config, and secret-name observations.
+The command does not deploy, migrate, scale, restart, or print environment-variable
+values. The [Fly production procedure](docs/deployment.md#flyio-reference-hosting)
+keeps database migration and runtime-role bootstrap outside the gateway process.
+
+The manual `gateway production proof` workflow tests an existing gateway after its
+deployment gate has passed. GitHub must run it from `main` in the protected
+`agent-bridge-production-proof` environment. Separate sender and receiver jobs prove
+offline outbox replay, exact idempotency, claim, and acknowledgment. The workflow then
+restarts the single Fly machine, requires a new runtime instance ID, and verifies the
+message and settled delivery with a fresh receiver instance and a new SQLite edge file.
+Its versioned receipts contain only identifiers, times, principal and workspace labels,
+the gateway origin, checks, and SHA-256 host evidence. They omit credentials, database
+URLs, message content, and SQLite files.
+
 ## What v2 provides
 
 - Immutable messages with UUIDv7 IDs and opaque server cursors.
@@ -67,6 +132,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 +216,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 +373,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.
 
@@ -339,10 +409,15 @@ PostgreSQL restore executes SQL from the dump, so use `--accept-source-sql-risk`
 for a bundle from a source you trust. The target must be a dedicated fresh database
 with the same database name and PostgreSQL major as the backup. Restore requires a
 superuser because it recreates object owners, role shells, memberships, and default
-privileges. It never enables login on restored external principals. If a restore fails
-after mutation begins, Agent Bridge disables new target connections and reports any
-residual roles or recovery paths. Inspect and clean those artifacts before retrying.
-Never run the source and restored target as active authorities at the same time.
+privileges. It never enables login on restored external principals. Runtime principals
+lose their runtime membership. Active control and archive registrations receive a new
+revocation event, and their principals lose those memberships. Re-enable a principal
+and register it again only after inspecting the restored target. A restore may reuse a
+preexisting role only when it is the source schema owner, the target session user, and
+a true superuser. Every other role collision fails. If a restore fails after mutation
+begins, Agent Bridge disables new target connections and reports any residual roles or
+recovery paths. Inspect and clean those artifacts before retrying. Never run the source
+and restored target as active authorities at the same time.
 
 Backup publication never replaces an existing output. Deterministic adjacent staging
 paths use the backup or request UUID. A retry with the same UUID reports retained
@@ -385,12 +460,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
@@ -572,9 +835,18 @@ followed by capability locks in operator-before-auditor order. Registration and
 revocation use the same order. A stale session that remains in a revoked role cannot
 continue operating. The schema owner is the only bootstrap holder of all three control
 roles and the only role with ordinary execution authority on the registration
-functions. PostgreSQL superusers remain inside this trusted database-administration
-boundary. Readiness checks the running PostgreSQL major on every call, so upgrading an
-already-migrated database to an uncertified major disables the runtime.
+functions. PostgreSQL 16 and newer may represent its effective admin, inherit, and set
+authority with a bootstrap administrator row plus a schema-owner row. A native DR
+restore may recreate the same authority as one combined bootstrap-superuser grant.
+Readiness validates either physical form and its effective authority. True superusers
+and managed-provider schema owners remain inside this trusted database-administration
+boundary. A separate `NOLOGIN` backup-reader role grants only table and sequence read
+access to the schema owner. Runtime, control, archive, and external principals cannot
+inherit it. Native backups require the schema owner to be a true superuser or hold
+`BYPASSRLS`. A target restore superuser can validate the intentionally suspended
+schema-owner shell. `CREATEROLE` alone remains sufficient for migrations. Readiness checks the
+running PostgreSQL major on every call, so upgrading an already-migrated database to an
+uncertified major disables the runtime.
 
 Direct credential inserts default to empty scopes rather than full access. Issued
 identity, scope, label, expiry, and lineage fields cannot be edited directly. Existing
@@ -631,6 +903,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
@@ -644,6 +917,7 @@ agent-bridge get --since 24h --unacked-by codex
 agent-bridge history --thread-id release-1
 agent-bridge acknowledge --ids <message-uuid>
 agent-bridge claim --lease-ms 30000
+agent-bridge claim --message-id <message-uuid> --lease-ms 30000
 agent-bridge send --target worker --delivery-policy '{"mode":"leased","maxAttempts":3,"retryBaseDelayMs":1000,"retryMaxDelayMs":60000,"retryJitterRatio":0.2}' "work"
 agent-bridge deliveries --state dead
 agent-bridge delivery-events --delivery-id <uuid>
@@ -658,12 +932,22 @@ 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.
 
 Publishers set `deliveryPolicy` on the message. Leased policy uses `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. Consumers cannot override those values. Consumer-side `maxAttempts` on claim and `retryPolicy` on nack remain validated but ignored for one compatibility release. New code should omit both fields.
 
+Claims normally select the next due delivery by priority. HTTP 2.1, MCP, and CLI
+callers may supply `messageId` or `--message-id` to atomically select only that due,
+recipient-visible delivery. The filter also scopes lease-expiry and exhaustion
+maintenance performed by that claim. Released HTTP 2.0 request shapes remain frozen
+and reject the field.
+
 The legacy Supabase adapter applies mailbox and receipt rules cooperatively. A holder of the legacy publishable key can bypass the adapter through PostgREST or its receipt RPC. Use the authenticated v2 gateway when the authorization boundary must be enforced.
 
 `agent-bridge pending` is a cheap shell gate for agent startup. It exits 0 when unread candidates or due delivery work are visible, 1 only for an authoritative empty result, and 2 when an empty remote state cannot be confirmed. Its JSON result separates unread context from executable delivery work and labels the state as `available`, `empty`, or `unknown`.
@@ -773,6 +1057,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 +1099,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 +1134,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,97 @@ 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.
+
+### 0.5.0 package contents
+
+- Read-only PostgreSQL and Fly production preflights. The database preflight reports
+  migration authority separately from native DR authority. The Fly preflight checks
+  the maintained deployment contract and existing app state without exposing secret
+  values.
+- A maintained Fly.io reference config. The repository contract keeps schema-owner
+  and operator authority out of the gateway, but creating an app, provisioning
+  PostgreSQL, setting secrets, migrating, and deploying still require an operator
+  gate.
+- A manual, approval-protected production proof harness for an existing Fly gateway.
+  It separates sender, receiver, machine restart, and fresh-edge verification,
+  and publishes versioned receipts that exclude credentials and message content.
+- Managed PostgreSQL schema-owner and native-backup compatibility across PostgreSQL 15
+  through 18. Migrations accept either a true superuser or a non-superuser with the
+  required role-administration authority. Native DR separately requires the schema
+  owner to be a true superuser or hold `BYPASSRLS`. A restore target superuser can
+  validate the intentionally suspended restored schema-owner shell. PostgreSQL 16 and
+  newer split grants are normalized to one effective membership for readiness and native DR. A
+  dedicated read-only role lets the schema owner back up protected tables without
+  granting that access to the gateway or control principals. Exact released migration
+  checksums remain accepted during upgrade, while unrelated checksum drift still fails
+  closed.
+- Optional exact-message delivery claims in HTTP 2.1, MCP, and the CLI. HTTP 2.0 keeps
+  the released claim-next contract.
+
 ### 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.
+- Run the manual Fly proof against an operator-owned app and retain its sender,
+  receiver, machine-cycle, and verifier receipts. The repository harness is ready,
+  but the external proof remains incomplete until an approved workflow run succeeds.
 - 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 +134,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