@creatornader/agent-bridge 0.3.0 → 0.4.0

package/docs/decisions/0003-host-adapters-and-consumer-instance-keys.md

@@ -0,0 +1,88 @@
+# ADR-0003: Separate host adapters from consumer instance keys
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-15
+
+## Context
+
+Agent products often combine an agent harness with a host application. Codex runs in
+the Codex CLI and in the Codex surface of the ChatGPT desktop app. Claude Code and
+Claude Desktop are separate hosts. OpenClaw, Hermes, Pi, scripts, CI jobs, and services
+have different host and access options.
+
+The released protocol also uses `AGENT_BRIDGE_INSTANCE` in several places. Supported
+installers generate one value for each installed client, but the gateway accepts the
+value from the caller. Calling it a registered process identity would promise an
+authority check that the server does not perform.
+
+## Decision
+
+The integration model separates these concepts:
+
+- A harness runs an agent loop.
+- A host is a CLI, desktop application, daemon, job, or service that contains a
+  harness or calls Agent Bridge.
+- A host adapter configures a host to use Agent Bridge.
+- MCP over stdio, the CLI, the HTTPS API, and the Node library are access surfaces.
+- Scripts, CI jobs, and services may use an access surface directly without becoming
+  agent harnesses.
+
+The `codex` adapter configures the profile shared by the Codex CLI and the Codex
+surface in the ChatGPT desktop app. Claude Code and Claude Desktop have separate
+adapters. Their supported installation flows create separate host registrations and
+instance keys. OpenClaw and generic MCP manifests are operator-managed. Hermes, Pi,
+and other harnesses have no dedicated compatibility or conformance claim until an
+adapter is tested.
+
+`AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Supported
+installers generate and persist one for each installed client. Direct clients should
+generate and persist a value when they need separate consumer state or presence. The
+gateway does not bind the value to an installer registration.
+
+Unless `AGENT_BRIDGE_CURSOR` sets an explicit path, a present instance key selects
+cursor storage. The key also selects delivery lease ownership and presence. Processes
+that share one key also share those resources. When the key and explicit cursor path
+are both absent, cursor storage uses the `default` path component. Delivery ownership
+falls back to the principal, and presence is unavailable. The key is not a PID,
+live-process identity, session, or conversation. Per-process presence requires a
+separate additive identity.
+
+The v1 client manifest key named `runtime` remains a compatibility field for the host
+installation target. A future manifest version may rename it without changing the
+meaning of `AGENT_BRIDGE_INSTANCE`.
+
+## Consequences
+
+The architecture diagram and compatibility matrix can list desktop apps, CLIs,
+daemons, and direct callers without presenting them as one category.
+
+Installer-generated keys work without a new protocol field. Direct client authors who
+use a key are responsible for stable storage and uniqueness within a principal. Reusing
+a key intentionally creates one shared delivery consumer and presence identity.
+
+The current gateway does not prevent two callers from choosing the same key. Clients
+must not treat an instance value as proof of process identity or server registration.
+
+## Alternatives considered
+
+### Treat the adapter name as the harness identity
+
+Rejected because one adapter may configure more than one host surface. The `codex`
+adapter is the current example.
+
+### Treat every live process as an instance
+
+Rejected because the released instance key already selects cursor paths, lease
+ownership, and presence. Changing it on every process start would alter consumer
+ownership and strand existing state.
+
+### Bind instance keys to server-side registrations now
+
+Deferred. Binding could prevent accidental key collisions, but it needs a migration,
+credential rules, and direct-client enrollment semantics. The current gateway accepts
+the caller-supplied key and must be documented honestly.

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/ecosystem.md

@@ -9,16 +9,48 @@ full agent stack.
 
 | Layer | Examples | Relationship to Agent Bridge |
 | --- | --- | --- |
-| Tool and context access | MCP | Agent Bridge exposes MCP tools. MCP does not define Agent Bridge's stored message or delivery protocol. |
+| Tool and context access | MCP, CLI, HTTPS, Node library | These surfaces expose Agent Bridge operations. They do not define its stored message or delivery protocol. |
 | Agent task semantics | A2A and application protocols | These systems own tasks, artifacts, status, and domain completion. Agent Bridge can carry their identifiers and payloads. |
 | Durable mailbox | Agent Bridge | Agent Bridge owns cursored history, receipts, work claims, leases, retry state, and offline replay. |
 | Live transport and brokers | SLIM, NATS, RabbitMQ, Kafka | A future adapter may use one of these systems for transport or wakeups. Cursored pull remains the recovery path. |
-| Agent execution | LangGraph, AutoGen, agent-loop, hosted agent platforms | These systems decide what runs and how workflows advance. Agent Bridge carries messages between them. |
+| Agent execution | Codex, Claude Code, OpenClaw, Hermes, Pi, LangGraph, AutoGen, agent-loop | These harnesses decide what runs and how workflows advance. Agent Bridge can carry messages when their host implements a supported access surface. |
 | Local operator experience | agmsg and similar tools | These tools may provide terminal placement, agent spawning, roles, and local coordination. They can use Agent Bridge when they need its durable cross-machine state. |
 
 [ADR-0001](decisions/0001-protocol-layers-and-acknowledgment-semantics.md)
 defines the protocol boundary and the separate meanings of read receipts, delivery
 settlement, and external task completion.
+[ADR-0003](decisions/0003-host-adapters-and-consumer-instance-keys.md) defines
+the host layers and consumer instance-key contract.
+
+## Harnesses, hosts, adapters, and access
+
+Agent Bridge keeps four integration concepts separate:
+
+- A harness runs an agent loop, such as Codex, Claude Code, OpenClaw, Hermes, or Pi.
+- A host is the CLI, desktop application, daemon, CI job, or service that contains the
+  harness or invokes Agent Bridge.
+- A host adapter configures that host to use Agent Bridge.
+- An access surface is MCP over stdio, the CLI, the HTTPS API, or the Node library.
+
+This distinction matters when one profile serves more than one host surface. The
+`codex` adapter configures the profile shared by the Codex CLI and the Codex surface
+in the ChatGPT desktop app. It does not create two independent Agent Bridge
+registrations. Claude Code and Claude Desktop have separate adapters and registrations.
+
+| Adapter or integration | Host coverage | Access | Support level |
+| --- | --- | --- | --- |
+| `codex` | Codex CLI and Codex in the ChatGPT desktop app | MCP stdio | Automated install |
+| `claude-code` | Claude Code CLI | MCP stdio | Automated install |
+| `claude-desktop` | Claude Desktop | MCP stdio | Automated install |
+| `openclaw` | OpenClaw daemon or host | MCP stdio | Manifest included; operator-managed |
+| `generic-mcp` | Any compatible MCP host | MCP stdio | Manifest included; operator-managed |
+| Direct integration | Scripts, CI, daemons, and services | CLI, HTTPS, or Node library | No host adapter required |
+| Generic harness integration | Hermes, Pi, and other harnesses | Any access surface their host supports | No dedicated adapter or conformance claim yet |
+
+Scripts are orthogonal to harnesses. A script may start a harness, invoke the CLI,
+call the HTTPS API, or embed the Node library. It is not a separate agent category.
+The MCP server currently uses stdio. The gateway exposes the Agent Bridge HTTPS
+protocol, not MCP over HTTP.
 
 ## Relationship to agmsg
 
@@ -49,6 +81,6 @@ vendors without forcing every participant into the same runtime or deployment st
 ## Interoperability direction
 
 The next interoperability work is tracked in [ROADMAP.md](../ROADMAP.md). Planned
-surfaces include an agmsg adapter, a thin A2A envelope mapping, runtime conformance
+surfaces include an agmsg adapter, a thin A2A envelope mapping, host-adapter conformance
 fixtures, and client libraries. Each integration must retain caller-bound identity,
 idempotent publication, cursored replay, and at-least-once delivery semantics.

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`