@creatornader/agent-bridge 0.3.0 → 0.4.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.
@@ -54,8 +74,9 @@ client configuration, and recovery steps.
 - Idempotency conflict detection. Exact replay deduplicates; changed content under the same key fails.
 - Scoped credentials that bind a remote workspace and agent principal.
 - SQLite outbox and inbox cache for gateway clients.
-- Leased runtime presence with instance IDs and capabilities.
-- MCP, CLI, Codex, Claude Code, and Claude Desktop integration paths.
+- Leased instance-keyed presence with capabilities.
+- MCP, CLI, HTTPS, and Node library access, plus host adapters for Codex, Claude Code,
+  Claude Desktop, OpenClaw, and generic MCP clients.
 - Canonical portable archives for messages and read receipts across local SQLite and shared PostgreSQL stores.
 - Native SQLite and PostgreSQL backup, verification, and restore.
 - Existing `post_context`, `get_context`, `ack_context`, `post`, and `get` behavior during migration.
@@ -66,34 +87,81 @@ 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
 
-```text
- Codex       Claude Code       Claude Desktop       scripts
-   |              |                  |                 |
-   +--------------+------------------+-----------------+
-                          MCP or CLI
-                              |
-                  process-scoped agent identity
-                              |
-             +----------------+----------------+
-             |                                 |
-       local SQLite                  SQLite edge store
-                                               |
-                                     authenticated HTTPS
-                                               |
-                                      Agent Bridge gateway
-                                               |
-                                          PostgreSQL
+```mermaid
+flowchart TB
+  subgraph execution["Agent execution"]
+    harnesses["Agent harnesses<br/>product-specific or custom"]
+    callers["Non-harness callers<br/>scripts, CI jobs, and application services"]
+  end
+
+  subgraph hosts["Host surfaces"]
+    clis["Command-line hosts<br/>Codex CLI and Claude Code CLI"]
+    desktops["Desktop hosts<br/>Codex in ChatGPT and Claude Desktop"]
+    daemons["Daemons and custom MCP hosts"]
+  end
+
+  subgraph access["Integration and access"]
+    adapter["Host adapter or MCP registration"]
+    mcp["MCP over stdio: agent-bridge-mcp"]
+    cli["CLI: agent-bridge"]
+    library["Node library"]
+    direct["Direct HTTPS client"]
+  end
+
+  harnesses --> clis
+  harnesses --> desktops
+  harnesses --> daemons
+  clis --> adapter
+  desktops --> adapter
+  daemons --> adapter
+  adapter --> mcp
+  callers --> cli
+  callers --> library
+  callers --> direct
+
+  mcp --> core["Agent Bridge client core<br/>principal plus optional consumer instance key"]
+  cli --> core
+  library --> core
+
+  core --> local["Local mode<br/>SQLite authority"]
+  core --> edge["Gateway client mode<br/>SQLite edge outbox and cache"]
+  edge -->|"HTTPS protocol 2.1"| gateway["Agent Bridge gateway"]
+  direct -->|"HTTPS protocol 2.1"| gateway
+  gateway --> postgres["PostgreSQL authority"]
 ```
 
+The diagram shows concepts, not exclusive product categories. A product may package a
+harness and a host together. A harness is the agent execution environment. A host is
+the CLI, desktop app, or daemon where it runs. A host adapter registers an access
+surface. Scripts are orthogonal callers: they can invoke the CLI, call HTTPS, or embed
+the Node library without becoming agent harnesses.
+
+| Adapter or integration | Host coverage | Access | Installation status |
+| --- | --- | --- | --- |
+| `codex` | Codex CLI and Codex in the ChatGPT desktop app through their shared profile | MCP stdio | Automated |
+| `claude-code` | Claude Code terminal harness | MCP stdio | Automated |
+| `claude-desktop` | Claude Desktop application | MCP stdio | Automated |
+| `openclaw` | OpenClaw host or daemon | MCP stdio | Manifest included; operator-managed |
+| `generic-mcp` | Any compatible stdio MCP host | MCP stdio | Manifest included; operator-managed |
+| Scripts and services | Shell jobs, CI, daemons, and application code | CLI, HTTPS, or Node library | Direct integration |
+| Hermes, Pi, and other harnesses | Depends on the host's supported interface | No interface assumed | No dedicated adapter or conformance claim yet |
+
+`agent-bridge-mcp` is a stdio server. The gateway exposes the Agent Bridge HTTPS API;
+it is not MCP over HTTP. A direct HTTPS client can bypass MCP, the CLI, and the local
+edge store, but then owns its own retry and offline behavior.
+
 Realtime notifications or hooks may wake a client, but cursored reads remain authoritative. A missed notification does not lose a message.
 
-A2A and application task semantics sit above Agent Bridge. MCP, CLI, and HTTPS are access surfaces. Optional transports such as SLIM or NATS may provide wakeups or transport below the core, but authoritative recovery still uses cursored pull. agmsg remains a reference for adapters, interoperability, and client experience.
+A2A and application task semantics sit above Agent Bridge. MCP, CLI, HTTPS, and the Node library are access surfaces. Optional transports such as SLIM or NATS may provide wakeups or transport below the core, but authoritative recovery still uses cursored pull. agmsg remains a reference for adapters, interoperability, and client experience.
 
 [ADR-0001](docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md) defines this boundary and the distinct acknowledgment meanings.
+[ADR-0003](docs/decisions/0003-host-adapters-and-consumer-instance-keys.md) defines the host layers and consumer instance-key contract.
 
 Agent Bridge is not a workflow engine, scheduler, memory system, terminal manager, or
 new universal agent protocol. See [Agent Bridge in the agent ecosystem](docs/ecosystem.md)
@@ -103,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.
@@ -258,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.
 
@@ -308,9 +379,10 @@ directory durability proof. Successful Windows commands report
 library API is available from
 `@creatornader/agent-bridge/dr`.
 
-## Install client integrations
+## Install host adapters
 
-Agent identity and gateway credentials belong to each client process, not the shared `~/.agent-bridge/config` file.
+Agent identity and gateway credentials belong to each installed client, not the shared
+`~/.agent-bridge/config` file.
 
 ```bash
 agent-bridge clients install codex --identity codex
@@ -330,11 +402,207 @@ AGENT_BRIDGE_CLIENT_TOKEN=<claude-desktop token> \
   agent-bridge clients install claude-desktop --identity claude-desktop
 ```
 
-`--token` accepts the same value, but the environment form avoids putting a credential in shell history. Each install writes an owner-only backend file under `~/.agent-bridge/clients/`. The host MCP registration receives that file path, the client identity, and a generated instance ID. Tokens are not copied into the shared config, and one client cannot reuse a token bound to another principal.
+`--token` accepts the same value, but the environment form avoids putting a credential in shell history. Each install writes an owner-only backend file under `~/.agent-bridge/clients/`. The host MCP registration receives that file path, the client identity, and a generated stable instance key. Tokens are not copied into the shared config, and one client cannot reuse a token bound to another principal.
 
-Codex and Claude Code installation uses their native MCP commands. Claude Desktop installation merges the `agent-bridge` server into its JSON config with an atomic write. Restart the client after installation.
+The `codex` adapter uses the Codex profile shared by the Codex CLI and the Codex
+surface in the ChatGPT desktop app; it does not install two independent registrations.
+Claude Code installation uses its native MCP command. Claude Desktop installation
+merges the `agent-bridge` server into its JSON config with an atomic write. Restart the
+client after installation.
 
-The runtime contracts are under [`clients/`](clients/). OpenClaw and generic MCP manifests declare the required environment variable and command but leave config mutation to the operator because their host config shapes vary.
+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.
 
@@ -575,6 +843,8 @@ Normal inbox and pending reads fall back to the local cache when the gateway is
 ## CLI
 
 ```bash
+agent-bridge --version
+agent-bridge --help
 agent-bridge init --provider local
 agent-bridge doctor
 agent-bridge status
@@ -602,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.
@@ -647,6 +921,22 @@ The acknowledgment names depend on the interface. MCP `ack_context` and CLI `ack
 ## Identity and security
 
 - `~/.agent-bridge/config` contains backend settings only. A stored `AGENT_BRIDGE_AGENT` value is ignored.
+- Workspace is the tenant boundary. Principal is the durable agent identity and message source.
+- `AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Supported
+  installers generate and persist one for each installed client. Direct clients should
+  do the same when they need separate consumer state or presence.
+- Unless `AGENT_BRIDGE_CURSOR` sets an explicit path, a present instance key selects
+  the cursor path. The key also selects the delivery lease owner and presence row.
+  Processes that share a key also share those resources. The gateway does not bind the
+  key to an installer registration. It is not a PID, unique live process, or
+  conversation ID.
+- When the key and explicit cursor path are both omitted, cursor storage uses
+  `default`. Delivery leases fall back to the principal, and presence operations reject
+  the request because presence requires an instance key.
+- Presence is instance-keyed in the released protocol. Per-process presence requires
+  an additive identity instead of a silent change to lease ownership or cursor paths.
+- Session and thread identifiers are message and application context. They do not
+  select credentials, workspace, principal, or delivery ownership.
 - Local clients bind identity through their process environment or an explicit CLI send argument.
 - Gateway tokens bind workspace and principal. The API ignores caller-supplied source and workspace fields.
 - Gateway clients use separate owner-only backend files and principal-bound tokens.
@@ -654,7 +944,8 @@ The acknowledgment names depend on the interface. MCP `ack_context` and CLI `ack
 - Remote HTTP must use TLS. Plain HTTP is accepted only on loopback.
 - Local config, database, WAL, and shared-memory files use owner-only permissions where the platform supports POSIX modes.
 - The private `agent_bridge` schema is denied to Supabase `anon` and `authenticated` Data API roles.
-- Expired presence rows are pruned during heartbeat and listing. Each agent is capped at 128 active instances, and each workspace is capped at 4,096.
+- Expired instance-presence rows are pruned during heartbeat and listing. Each agent
+  is capped at 128 active instance keys, and each workspace is capped at 4,096.
 - Errors expose stable codes without database URLs, tokens, or provider response bodies.
 - Delivery work is at least once, not exactly once. Consumers must make external side effects idempotent.
 
@@ -681,7 +972,7 @@ The original v1 schema remains in [`sql/setup.sql`](sql/setup.sql). Ordered gate
 `status` is a passive snapshot. It does not synchronize or probe a remote provider. An unprobed remote reports `status: "unknown"`, `connected: false`, and `remoteReachable: null`. Passive status still exits 0. `doctor` evaluates named checks and exits 0 for `ok`, 2 for `degraded`, and 1 for `failed`. Both return JSON with:
 
 - Provider and actual schema version.
-- Bound workspace, agent, and instance.
+- Bound workspace, agent, and consumer instance key.
 - Endpoint or database path.
 - Cursor and queue state.
 - Pending, claimed, retrying, and dead delivery counts, plus due versus scheduled work, expired leases, oldest-due time, and bounded queue lag.
@@ -700,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.
@@ -740,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
@@ -759,11 +1065,13 @@ durability behavior has not yet been proved on a dedicated Windows host.
 ## Documentation
 
 - [ROADMAP.md](ROADMAP.md): released work, unreleased implementation, and the remaining program.
-- [SECURITY.md](SECURITY.md): supported versions, private vulnerability reporting, and security boundaries.
+- [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.
 - [docs/architecture-v2.md](docs/architecture-v2.md): protocol and storage decisions.
 - [SKILL.md](SKILL.md): runtime-neutral agent operating instructions.
 - [llms.txt](llms.txt): compact machine-readable project map.

package/ROADMAP.md

@@ -9,17 +9,18 @@ published and the supported clients pass a fresh end-to-end check.
 
 ## Status
 
-### Released in 0.2.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.
 - Immutable messages, caller receipts, delivery leases, retries, dead letters, and
   presence.
 - Durable SQLite edge outbox and inbox cache for gateway clients.
-- CLI, MCP, Codex, Claude Code, and Claude Desktop integration paths.
-
-### Implemented for the next release
-
+- 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.
 - Caller-bound inbox, sent, and combined history with scope-bound cursors.
 - Publisher-owned delivery policy, priority claims, cancel, requeue, and delivery event
   inspection.
@@ -34,13 +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.
 
-### Required before the next release is complete
-
-- Merge the development branch through the protected-main checks.
-- Publish the package through the configured npm OIDC workflow.
-- Prove Codex, Claude Code, and Claude Desktop startup, send, receive, receipt, claim,
-  settlement, offline replay, and restart behavior against the released package.
-- Move the project's own normal traffic to v2 while retaining a tested v1 rollback path.
+### 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 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.
@@ -49,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
@@ -64,6 +117,11 @@ published and the supported clients pass a fresh end-to-end check.
 
 ### Presence and wakeups
 
+- Separate the stable consumer instance key from a live process identity. Supported
+  installers generate one key per installed client, while direct clients may supply
+  their own. Processes that share a key also share presence in 0.3.
+- Add per-process presence and session correlation only through an additive protocol
+  change with migration and conformance coverage.
 - Maintain heartbeat and expiry automatically for supported long-lived clients.
 - Add wake adapters only where they reduce latency. Lost wakeups must never lose data.
 - Keep cursored pull as the authoritative recovery path.
@@ -83,7 +141,11 @@ published and the supported clients pass a fresh end-to-end check.
 - Carry A2A envelopes without implementing a competing task state machine.
 - Publish conformance fixtures and an adapter template.
 - Add client libraries where real integrations need them.
-- Expand runtime installers after each host has a stable configuration contract.
+- Rename the compatibility `runtime` manifest key to an explicit host-adapter key in a
+  versioned manifest contract.
+- Expand host installers after each product has a stable configuration contract.
+  Hermes, Pi, and similar harnesses can use a generic access surface when their host
+  supports one, but they do not have a dedicated adapter or conformance claim.
 
 See [docs/ecosystem.md](docs/ecosystem.md) for the product boundary.