@creatornader/agent-bridge 0.3.1 → 0.4.0

package/docs/decisions/0004-client-lifecycle-and-endpoint-migration.md

@@ -0,0 +1,204 @@
+# ADR 0004: Client lifecycle ownership and endpoint migration
+
+Status: accepted
+
+Date: 2026-07-18
+
+## Context
+
+Agent Bridge can install Codex, Claude Code, and Claude Desktop registrations, but an
+existing registration may have been created by an older package or by an operator.
+Repair, update, uninstall, and endpoint migration must not silently take ownership of
+such state. In particular, host configuration and per-client backend files may contain
+credential-bearing references and queued gateway edge state.
+
+Lifecycle unit 1 needs a safe ownership boundary before later mutating operations are
+added. It must distinguish missing state, exact but unowned state, owned state, and
+drift without probing a gateway or exposing backend configuration values.
+
+## Decision
+
+The CLI provides two local lifecycle operations for the three automated adapters:
+
+- `clients inspect` is read-only. The operator supplies the expected runtime,
+  identity, stable instance key, backend file path, launch command, and Claude Code
+  scope when applicable. Inspection reads only the host registration, backend path
+  existence, and managed metadata. It does not read backend values, contact the
+  gateway, interpret connectivity health, rewrite a host config, or create metadata.
+- `clients adopt` uses the same exact contract. Without `--apply` it returns a plan.
+  With `--apply` it may create managed metadata only when inspection reports an exact
+  unmanaged registration. Adoption never rewrites the registration or backend file.
+
+Inspection returns one of four states:
+
+- `absent`: the requested registration, backend file, and managed metadata are all absent.
+- `unmanaged`: the host registration, identity, instance, backend path, scope, and
+  launch contract are exact, the backend path and its immediate parent pass the
+  no-link owner-only private-path policy, and metadata is absent.
+- `managed`: the exact registration and backend file are accompanied by exact managed
+  metadata.
+- `drifted`: any other combination, including malformed or inexact registration,
+  missing, insecure, or linked backend residue without a registration, stale metadata,
+  or metadata that structurally differs from the requested contract.
+
+Managed metadata uses schema `agent-bridge.client-management`, version 1, under the
+owner-only `~/.agent-bridge/clients/` directory. It records only runtime, identity,
+instance, absolute backend path, launch command and arguments, scope, and a nonsecret
+registration locator. Claude Desktop records the normalized configuration path.
+Codex records the active profile configuration path. Claude Code records scope and,
+for local or project scope, the normalized invocation directory. Its native CLI does
+not expose a stronger configuration locator. User scope has no directory context. A
+later inspection from a different locator reports drift instead of guessing which
+registration to mutate. Metadata never copies a token, backend setting, credential
+identifier, URL, workspace, or backend file contents. Publication uses a private
+same-directory temporary file, file fsync, atomic rename, private-path verification,
+and directory fsync where supported.
+
+Codex inspection compares the semantic registration fields in its real JSON MCP
+description and ignores status, timeout, and transport diagnostic fields. JSON object
+property order is not significant, while the environment must contain exactly the
+three Agent Bridge keys. Claude Code inspection uses its native MCP description and
+exact scope/removal contract but excludes connectivity status from registration
+exactness. Claude Desktop inspection reads only the `agent-bridge` entry in its JSON
+configuration and uses the installer's canonical resolver: an explicit executable is
+validated, while the default is absolute Node plus the absolute server entry.
+
+Identity, instance, backend, and command inputs are normalized before comparison and
+metadata publication. Desktop configuration and Codex profile paths are normalized
+before they become locators. Claude Code local and project adoption must run from the
+directory that later lifecycle operations should use. After publication, adoption
+re-inspects the live registration and fails if it changed. Inspection and plan-only
+adoption preserve backend bytes, inode, and modification time. Applied adoption
+writes only the management metadata described above; registration state and client
+health remain separate authorities.
+
+First-time `clients install` and enrollment behavior remains unchanged. A provision
+enrollment still refuses an existing backend file or MCP registration, so adoption
+cannot weaken first-install collision protection.
+
+`clients repair`, `clients update`, and `clients uninstall` operate only on a strict
+managed metadata record.
+The runtime and stable instance locate that record. `--identity` must match the record
+and the immutable request, but never locates it. These commands reject
+backend path, scope, and config-path flags.
+They plan without writing by default. A no-op exact registration creates no operation.
+
+Repair restores the recorded launch. Update resolves a replacement launch before it
+creates a journal. The update request records the identity, command, arguments, scope,
+and fixed three Agent Bridge environment key names. It does not record their values.
+Native launch arguments are empty. A native command is one executable contract. Bare
+commands reject argument separators and URL-like surfaces. Absolute paths must resolve
+to executable files before an update is journaled. Claude Desktop uses the installer's
+absolute launch resolver. An action-specific resume uses that recorded request and
+rejects another action, runtime, instance, identity, or replacement command.
+
+Before a mutation starts, metadata load verifies the private management root, clients
+directory, and metadata file. It rejects links, replacement, oversized files, unknown
+keys, incorrect schema versions, malformed locators, and non-absolute backend paths.
+The file is opened without following links and checked against its path identity before
+the loader accepts it. The full record is loaded again after the client lock is acquired
+and before every non-metadata mutation. Any difference blocks the operation.
+
+Repair can tighten backend privacy only when that change removes access. Its journal
+proofs contain the role, file identity, and private or repairable policy state. They
+never contain backend bytes, credentials, URLs, workspace, or configuration values.
+Links, disappearance, owner changes, replacement, and a permission change that would
+grant new owner access fail closed. Windows accepts an already private backend path and
+refuses a non-private one because the repair path cannot prove a monotonic ACL change.
+
+Registration proofing records a bounded Agent Bridge observation and its full target
+contract. Unknown environment keys, malformed values, unexpected scope, opaque fields,
+or arguments outside the stored current or target launch stop before journal creation.
+For Codex, get, remove, and add run with the recorded `CODEX_HOME` over the supplied
+environment. Claude Code uses the recorded scope, invocation directory, and supplied
+environment. Native changes remove, verify absence, add, verify the target, and write
+changed metadata last. Claude Desktop reads the recorded JSON config without following
+links or link ancestors, changes only `mcpServers.agent-bridge`, and publishes through
+a private operation-scoped temporary file. It pins and rechecks the original file and
+parent identities before rename, then verifies the final entry. Claude Desktop has no
+cooperative transaction protocol. Node cannot guarantee a transaction against an
+independent same-user writer.
+
+The operation substrate remains internal with read-only inspection. Revisioned
+manifests contain typed credential-agnostic requests, non-sensitive locators, and
+unique no-replace before/after artifacts. Begin holds the runtime-plus-instance lock
+while refusing another unfinished operation; a blocked journal fences new mutations and
+resume. Resume is same-host only. Journal states
+are prepared, snapshotted, in-progress, applied, cleaning, and committed. Inspection
+separately reports resumable, classification-required, blocked, or complete.
+
+Repair and uninstall journals use operation format version 3. New update journals use
+v4 and carry a bounded credential-free inverse contract. Gateway migration staging
+uses v5 and binds a managed identity, source and target endpoint digests, enrollment
+credential IDs, a source edge database path and scope key, and a predecessor grace
+cutoff. It contains no raw gateway URL or token. A version 2 journal keeps its released
+request shape and remains inspectable. A non-terminal version 2 journal cannot resume
+because it lacks an identity-bound request.
+
+Endpoint cutover uses v6. Its journal retains the normalized source gateway URL without
+a token so post-journal recovery can reconstruct the source edge route from the target
+successor backend. Initial preflight uses the predecessor and direct successor. Every
+later proof and source-edge replay uses the successor credential at both URLs. There is
+no endpoint reverse operation. Returning to a prior endpoint requires a fresh owner
+rotation and a new forward cutover.
+
+Creation pins the operation root before it publishes state. Cleanup pins that root,
+the operation directory, and the snapshots directory before it records intent or
+unlinks anything. Cleanup records durable intent per artifact, verifies and unlinks the pinned file, and
+records POSIX directory sync or explicit Windows unavailability. An absent artifact is
+safe only when intent predates the cleanup attempt. Inspection recognizes a verified
+after artifact for the current intent-recorded step, but rejects other missing or extra
+files. Committed means verified writes and removed artifacts. It drops requests, steps,
+locators, digests, and artifact metadata while retaining a bounded credential-free
+completion record for audit. Public repair, update, and uninstall use this substrate.
+
+Uninstall is forward-only. It removes the managed registration and proves absence,
+deletes the already private backend file, then deletes metadata. It refuses a backend
+that still needs privacy repair, so it cannot loosen that policy as a side effect of
+deletion. A later failure does not restore a registration, backend, or metadata file.
+The uninstall plan never stores backend bytes. File deletion confirms the file and
+private parent identities before unlink. POSIX syncs the parent directory after a
+verified absence. Windows records unavailable directory durability. Node's pathname
+unlink cannot provide a transaction against a same-user writer, so this is an advisory
+race boundary. Desktop removes only `mcpServers.agent-bridge`.
+
+`clients rollback <source-operation-id> --identity <name>` is plan-first and accepts
+only a committed same-host v4 update source. `--apply` creates a new v4 `rollback`
+operation. It verifies the asserted identity, prior nonsecret metadata and exact
+registration contract, and the current forward metadata and registration digests.
+Native rollback removes the forward registration, proves absence, adds the prior
+registration, proves it, then writes prior metadata. Desktop replaces only
+`mcpServers.agent-bridge` and writes prior metadata last. The source journal remains
+unchanged. Reverse resume derives authority from its recorded source UUID and inverse
+contract. A changed current state, v2 or v3 source, repair, uninstall, unsafe inverse
+fields, or a different host fails closed. A failed forward update never rolls back
+automatically. Repair remains monotonic. Uninstall recovery is re-enrollment.
+
+`clients migrate stage <runtime> --identity <name> --instance <key>
+--enrollment-file <path>` is plan-first. With `--apply`, it creates a private staged
+successor backend and a credential-free v5 record without changing the managed
+registration or active backend. It initializes the source edge gate and leaves its
+state active. It probes active and staged bearer credentials and requires a
+non-immediate predecessor grace cutoff. It neither drains the outbox nor authorizes a
+cutover. It requires an absolute, normalized source edge database path and rejects
+in-memory edge state. The stage does not prove that source and target URLs reach the
+same database authority.
+
+`clients resume <operation-id> [--recover-lock]` resumes v3 repair, update, and
+uninstall requests, supported v4 update and rollback requests, and v5 migration-stage
+requests. It derives action, runtime, instance, identity, launch, and reverse source
+from the record and accepts no replacement client authority. It cannot resume a version
+2 operation. It also completes an uninstall interrupted after metadata deletion and a
+rollback interrupted after any ordered step. A later endpoint cutover is limited to
+alternate URLs and must dynamically attest one logical database authority. Physical
+erasure is outside the contract.
+
+## Consequences
+
+Managed repair, update, and uninstall have a narrow authority boundary and can fail
+closed on drift, metadata corruption, ambiguous crash state, and unsafe backend policy
+changes. Existing exact registrations still require intentional, reviewable adoption.
+Migration staging preserves active state while it prepares later work. Endpoint
+cutover uses a separate v6 journal to drain the gateway edge outbox, attest shared live
+route state, change the host registration, and retain enough credential-free authority
+for crash recovery and post-grace source retirement.

package/docs/deployment.md

@@ -0,0 +1,205 @@
+# Deploy Agent Bridge
+
+The repository includes a Compose stack for local development and a production image
+definition. The Compose file is intentionally bound to loopback. It is useful for
+evaluation, integration work, and the repository acceptance test. It is not a public
+TLS deployment.
+
+## Development stack
+
+Requirements:
+
+- Docker Engine or Docker Desktop with Compose v2.
+- Node.js 22.23.1 or newer to generate private development secrets and run operator
+  commands from the source checkout.
+- Free loopback ports 8787 and 54329, or explicit replacement values.
+
+Create two independent passwords. Keep the files out of version control.
+
+```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/*
+```
+
+Build and start the stack:
+
+```bash
+docker compose build --pull gateway
+docker compose up --wait gateway
+curl --fail http://127.0.0.1:8787/readyz
+```
+
+The services start in this order:
+
+1. PostgreSQL becomes healthy.
+2. `migrate` applies the ordered schema with the schema-owner login and exits.
+3. `bootstrap-runtime` creates or updates `agent_bridge_gateway`, grants the
+   database-derived runtime role, and exits.
+4. `gateway` starts with the restricted login and must pass `/readyz`.
+
+The stack stores PostgreSQL data in the `postgres_data` named volume. `docker compose
+down` removes containers and keeps the volume. `docker compose down --volumes` deletes
+the development database. Inspect the project name and volume before using the second
+command.
+
+The default bindings are `127.0.0.1:8787` for the gateway and `127.0.0.1:54329` for
+PostgreSQL. Override them without editing the file:
+
+```bash
+AGENT_BRIDGE_PORT=18787 \
+AGENT_BRIDGE_POSTGRES_PORT=15432 \
+docker compose up --wait gateway
+```
+
+Use the [owner enrollment workflow](../README.md#gateway-setup) to
+create principal-bound credentials. Do not put a gateway token in the shared backend
+config. Each installed client receives its own private backend file.
+
+Run the same disposable proof as CI after building the TypeScript artifacts:
+
+```bash
+npm ci
+npm run build
+./scripts/compose-smoke.sh
+```
+
+The script creates a unique Compose project name that callers cannot override. It also
+creates temporary database passwords, a temporary operator, and two principal
+credentials. It proves source and workspace binding, targeted delivery, lease
+settlement, short-password rejection, denied runtime access to credential hashes, and
+message persistence through a full stack restart with a fresh edge cache. Its exit trap
+removes the project volume, image tag, credentials, and temporary files.
+
+## Production requirements
+
+Use the image stages and service boundaries as inputs to the deployment platform. Do
+not expose the checked-in Compose stack unchanged.
+
+### Network and TLS
+
+- Keep PostgreSQL on a private network. Do not publish port 5432 to the internet.
+- Put every non-loopback gateway behind a TLS terminator. Forward only from the trusted
+  proxy or ingress layer to the gateway's HTTP port.
+- Restrict administrative database access to migration, owner-control, archive,
+  backup, and restore jobs. Clients use the HTTPS gateway, not PostgreSQL.
+- Apply request size, connection, and upstream timeouts at the proxy without retrying
+  ambiguous mutations. Agent Bridge uses idempotency keys for safe publication replay.
+
+### Images and process policy
+
+- Build from the pinned Node base image and deploy an immutable image digest.
+- Run the gateway with a read-only root filesystem, a small writable temporary
+  filesystem, and `no-new-privileges`. The final gateway process must run as the
+  non-root image user with no effective Linux capabilities.
+- Compose file secrets retain host ownership on native Linux. The migration and gateway
+  services therefore start a small Node entrypoint as root with `DAC_OVERRIDE`,
+  `SETUID`, and `SETGID`. It reads the one granted secret, drops supplementary groups
+  and UID/GID to 1000, then imports the requested module. The final process has no
+  effective capabilities. The one-shot runtime bootstrap keeps `DAC_OVERRIDE`,
+  `SETUID`, and `SETGID` while it reads the two secret files, then `gosu` runs its fixed
+  SQL script as the PostgreSQL account. A production
+  secret injector may mount the secret directly for the runtime UID and omit this
+  handoff.
+- Allow at least 30 seconds for graceful shutdown. Stop accepting traffic before
+  terminating the process.
+- Gate traffic on `/readyz`. Liveness alone does not prove migration, row-isolation,
+  role, or protected-catalog readiness.
+
+### Secrets and database roles
+
+Keep these authorities separate:
+
+| Authority | Purpose | Long-lived gateway access |
+| --- | --- | --- |
+| Schema owner | Ordered migrations and trusted role registration | Never |
+| Runtime login | Gateway requests and readiness | Required |
+| Control operator | Credential provision, inventory, rotation, and revocation | Never |
+| Archive operator | Portable PostgreSQL archive operations | Never |
+| Backup and restore | Native DR backup or restore | Never |
+
+Use the platform's secret manager or private mounted secret files. Do not put raw
+passwords, tokens, or complete database URLs in image layers, source control, command
+arguments, deployment logs, or shared client config. Rotate each authority on its own
+schedule and after any suspected exposure.
+
+The runtime database password must contain at least 32 characters. The bootstrap job
+fails before role creation or alteration when the mounted value is shorter.
+
+### Persistent data and backup
+
+A database volume or managed PostgreSQL disk keeps runtime state. It does not protect
+against operator error, catalog drift, account loss, or regional failure.
+
+- Schedule native PostgreSQL DR backups with the exact PostgreSQL major tools.
+- Store verified bundles on a separate failure domain.
+- Record retention and deletion policy separately from message immutability.
+- Run restore drills into a fresh database with the same name and PostgreSQL major.
+- Never activate the source and restored target as authorities at the same time.
+
+Portable archives complement native DR when an operator needs one workspace's messages
+and eligible read receipts. They do not contain credentials, delivery state,
+owner-control state, or security events.
+
+## Upgrade procedure
+
+1. Confirm the target image supports the deployed PostgreSQL major and current protocol
+   clients.
+2. Drain or preserve each gateway client's SQLite outbox. Do not discard an edge store
+   with queued publications.
+3. Drain old gateway instances or remove them from traffic before migration 017, then
+   keep them out of traffic before migration 018. An old process can serve ordinary
+   requests until it exits even though its `/readyz` probe
+   fails after the newer migration is applied.
+4. Create and verify a native DR backup.
+5. Stop schema-changing jobs other than the selected migration job.
+6. Run the new image's migration command once with schema-owner authority.
+7. Run the runtime bootstrap with separate runtime-login credentials.
+8. Start the new gateway and require `/readyz`, an authenticated capability probe, and
+   an authenticated status probe.
+9. Send, read, claim, and settle a disposable targeted delivery.
+10. Roll clients forward only after the gateway proof passes.
+11. Keep the previous authority available but inactive until the observation window
+    closes.
+
+Run one migration job at a time. The migration ledger makes ordered application
+idempotent, but it does not make concurrent deployment orchestration desirable.
+
+## Rollback boundaries
+
+| Failure point | Safe response |
+| --- | --- |
+| Before schema migration | Stop the new gateway and return to the prior image and configuration. |
+| After migration, before client rollout | Keep clients on the old authority. Apply a forward fix, or restore the verified backup into a fresh target. |
+| After clients have published through the new gateway | Stop further cutover. Preserve every edge database and credential until queued outboxes are zero. Reconcile authoritative messages before switching back. |
+| Database corruption or unrecoverable catalog drift | Restore native DR into a fresh target, verify readiness, then switch authority once. |
+
+An older gateway may refuse a database with a newer migration plan. Starting the old
+image is therefore not a general schema rollback. A volume snapshot is also not enough
+unless its consistency and restore procedure have been proved for the database setup.
+Migration 017 makes this readiness failure explicit for an old compiled migration
+plan. It does not terminate an already-running old gateway. Drain it before applying
+the migration.
+
+## Operational checks
+
+- `/healthz` proves the HTTP process is alive.
+- `/readyz` proves the gateway can use the restricted database and that required
+  security attestations still match.
+- `agent-bridge doctor --json` probes a configured client's remote path.
+- `agent-bridge status` is passive and reports remote reachability as unknown until a
+  probe occurs.
+- Gateway metrics require a credential with `gateway:metrics`.
+
+Alert on readiness failure, repeated authorization denial, rate-limit pressure,
+database connection exhaustion, due or blocked outbox rows, dead-letter growth, backup
+failure, and restore-test failure. Keep tokens, database URLs, message content, and DR
+bundle paths out of telemetry.
+
+Related references:
+
+- [Architecture](architecture-v2.md)
+- [Security policy](../SECURITY.md)
+- [Troubleshooting](troubleshooting.md)
+- [Portable archives and native DR](../README.md#portable-archives)

package/docs/troubleshooting.md

@@ -81,6 +81,29 @@ Queued sends retain their idempotency keys. Long-lived MCP clients retry them, a
 `agent-bridge sync` triggers the same bounded replay manually. Claims, lease changes,
 delivery settlement, presence, and read-receipt writes still require the gateway.
 
+## Migration gate reported by status or doctor
+
+`clients migrate stage` does not begin a drain. `clients migrate cutover
+<stage-operation-id> --exclusive-edge --apply` changes the source edge to `draining`
+after it verifies both live gateways and their route challenge. In that state, normal
+publication is blocked while the recorded lease worker completes existing outbox work.
+`doctor` reports `draining` as degraded. A `retired` scope rejects new publication and
+`doctor` reports it as failed.
+
+Do not delete the edge database, alter the gate tables, or reopen a retired scope by
+hand. Inspect the operation ID reported by status. Resume the matching v6 operation
+with `clients resume <operation-id> [--recover-lock]`. A new worker cannot take an
+unexpired drain lease. It must wait for the lease to expire. Reverse before the
+predecessor grace cutoff is not supported. To return to the earlier endpoint, first
+rotate a new owner credential for that endpoint, then run an ordinary forward cutover
+with it as the successor. Finalization after grace retires the source. If no matching
+operation exists, preserve the database and stop rather than changing the gate
+manually.
+
+A dry migration plan refuses an edge with live `-wal` or `-shm` sidecars. Stop the
+writer and let SQLite checkpoint its state, then retry the plan. The plan never opens
+the edge in write mode to inspect it.
+
 ## Report a defect
 
 Include the client name, operating system, package version, sanitized `doctor --json`

package/llms.txt

@@ -11,6 +11,10 @@ History uses mailbox `inbox` (default), `sent`, or `all`. Receipt state is `any`
 - `npm install --global @creatornader/agent-bridge`
 - `agent-bridge init --provider local`
 - `agent-bridge demo`
+- Development gateway: create `.secrets/postgres_password` and
+  `.secrets/runtime_password`, then run `docker compose up --build --wait gateway`.
+  Both checked-in port bindings are loopback-only. See `docs/deployment.md` before a
+  non-loopback deployment.
 
 If an MCP client cannot attach, run `agent-bridge doctor --json` and see
 `docs/troubleshooting.md`. Normal client installation resolves the MCP launch command;
@@ -30,6 +34,7 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 ## Commands
 
 - `agent-bridge --version` or `agent-bridge -V`: print the installed package version without loading backend configuration.
+- `agent-bridge --help`, `agent-bridge -h`, or a command followed by either help flag: print help without loading backend configuration or dispatching the command.
 - `agent-bridge capabilities`: print the canonical v2 operation and protocol capability document.
 
 - agent-bridge init --provider local
@@ -41,11 +46,49 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 - agent-bridge claim, extend, ack, nack, deliveries, delivery-events, cancel, requeue
 - agent-bridge sync, watch, join, presence
 - agent-bridge clients install <runtime> --identity <principal>
+- agent-bridge clients inspect <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path>
+- agent-bridge clients adopt <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path> [--apply]
+- agent-bridge clients repair <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients update <runtime> --identity <principal> --instance <stable-key> [--command <command>] [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients uninstall <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients rollback <update-operation-id> --identity <principal> [--apply] [--recover-lock]
+- agent-bridge clients migrate stage <runtime> --identity <principal> --instance <stable-key> --enrollment-file <private-path> [--apply] [--recover-lock]
+- agent-bridge clients migrate cutover <stage-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients migrate finalize <cutover-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients resume <operation-id> [--recover-lock]  # resumes recorded v3, supported v4, v5 stage, or v6 migration authority
+- agent-bridge clients operations [<operation-id>]  # read-only resumable/classification-required/blocked/complete summaries
 - agent-bridge owner provision|inventory|rotate|revoke
 - agent-bridge clients install <runtime> --enrollment-file <private path>
 - agent-bridge archive export|verify|import
 - agent-bridge dr backup|verify|restore
 
+Client inspection is local, read-only, secret-free, and reports absent, unmanaged,
+managed, or drifted. Adoption is a plan unless `--apply` is explicit. It writes only
+owner-private credential-free management metadata after the identity, stable instance,
+backend path, scope, and launch contract match exactly; it never rewrites the host
+registration or backend file. Enrollment-based first-time provisioning continues to
+refuse registration and backend-file collisions. Metadata binds Desktop to its
+normalized config path and Codex to its active profile config. Claude Code local and
+project scope bind to the invocation directory because its native CLI exposes no
+stronger registration target.
+The backend and its immediate parent must pass the owner-only no-link policy. Codex
+registration comparison ignores diagnostic fields and JSON property order but requires
+exactly AGENT_BRIDGE_AGENT, AGENT_BRIDGE_INSTANCE, and AGENT_BRIDGE_CONFIG. Claude Code
+connectivity status is not registration state. Desktop inspection uses the installer's
+validated absolute launch resolver, and applied adoption re-inspects its postcondition.
+Only Claude Code accepts `--scope`; only Claude Desktop accepts `--config-path` for
+inspect and adopt. Repair, update, and uninstall derive those locators from strict managed metadata.
+They reject backend, scope, and config-path authority flags. `--identity` binds the
+metadata record and immutable request. Repair restores the recorded launch contract.
+Update records a normalized credential-free launch request, including only fixed Agent
+Bridge environment key names. Native commands are one executable contract and reject
+arguments, URL-like selectors, and credential surfaces. Plan-only calls create no lock
+or operation. Native changes prove remove then add. Desktop replaces only the Agent
+Bridge config entry through a private operation-scoped temporary file. Its same-user
+writer race is advisory because Node cannot provide an OS transaction. Resume requires
+the same action and managed identity. Lock recovery requires
+same-host process-death proof.
+
 Archive export moves one workspace's immutable messages and read receipts between
 canonical local SQLite and PostgreSQL stores. Import defaults to a rollback-backed dry
 run and requires `--apply` to commit. PostgreSQL archive authority comes only from
@@ -75,11 +118,16 @@ excludes transient request, rate-limit, instance, and archive-authorization rows
 normalizes claimed deliveries on restore. Never run source and restored target at the
 same time. The package API is @creatornader/agent-bridge/dr. Bundle hashes detect
 changed bytes but do not encrypt or authenticate the source.
+The immutable PostgreSQL gateway authority UUID is preserved by native DR. It identifies
+one logical authority across restore but does not fence a live clone.
 
 ## MCP tools
 
 - `capabilities`: return operations, required scopes, provider-specific enforcement, and supported protocol versions. Gateway access needs an active credential but no named scope for this operation.
 - Production gateway capabilities report `requestAuthority: true` and `rowIsolation: true` only after the migration and live catalog, role, policy, privilege, and function checks pass. PostgreSQL forces RLS on messages, receipts, deliveries, delivery events, and presence. Lease transitions and target-to-delivery membership remain service-enforced.
+- Authenticated gateway `/v2/status` returns optional `gatewayAuthorityId` and
+  `credentialId` fields when PostgreSQL request authority is active. They are additive
+  in HTTP 2.1 and do not appear in capabilities.
 
 Compatibility: post_context, get_context, ack_context.
 Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
@@ -122,6 +170,24 @@ workspace, and live MCP registration matches. Consumed-file deletion and lock re
 report retained, missing, durable, and durability-unknown outcomes without claiming that
 an unlinked path was retained.
 
+`clients migrate stage` is a plan-first gateway migration preparation command. An
+applied stage creates an owner-private successor backend and credential-free operation
+record. It leaves the active registration, active backend, and source edge scope
+active after initializing its gate. Staging requires an absolute, normalized source
+edge database path and rejects `:memory:`.
+
+`clients migrate cutover` requires a committed v5 stage and `--exclusive-edge`. Initial
+preflight checks exact HTTP 2.1 status bindings at both gateways, one immutable
+authority ID, the successor's `status:read` and `messages:write` grants, and a direct
+predecessor-to-successor route challenge. Once it creates the journal, it uses a
+retained normalized source URL and the successor credential for every route proof and
+source outbox replay through the target gateway. `finalize` requires a fresh assertion
+after grace expires and retires the source. To return to a former endpoint, rotate a
+new owner credential and run an ordinary forward cutover to that endpoint. Dry runs
+read private edge state without SQLite writes or gateway requests. They refuse live WAL
+sidecars rather than read uncheckpointed outbox state. Resume uses only the retained v6
+request and waits for an unexpired drain lease instead of taking it over.
+
 Project is an optional immutable message label, not a tenant or identity selector. Omitted project reads include labeled and unlabeled messages. Exact project filters are supported by CLI, MCP, HTTP, and stores. Gateway workspace assertions must match the bound credential before network access.
 Local CLI calls may override workspace for one invocation. The legacy Supabase schema is global and always reports workspace `*`; use project labels for legacy filtering.
 
@@ -132,6 +198,7 @@ Local CLI calls may override workspace for one invocation. The legacy Supabase s
 - SECURITY.md: reporting process and security boundaries
 - docs/ecosystem.md: relationship to adjacent protocols, brokers, and runtimes
 - docs/troubleshooting.md: MCP startup and client recovery
+- docs/deployment.md: Compose development stack and production deployment constraints
 - docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md: protocol layers and acknowledgment semantics
 - docs/decisions/0002-canonical-operation-contract-registry.md: generated contracts and version negotiation
 - docs/decisions/0003-host-adapters-and-consumer-instance-keys.md: host layers and instance-key semantics