@creatornader/agent-bridge 0.3.1 → 0.5.0

package/docs/architecture-v2.md

@@ -1,6 +1,6 @@
 # Agent Bridge v2 architecture
 
-Status: living architecture. Version 0.3.0 was released on July 15, 2026.
+Status: living architecture for the 0.4.x package line.
 
 ## Product boundary
 
@@ -31,6 +31,42 @@ A standalone Agent Bridge API sits between remote clients and PostgreSQL. Client
 
 Supabase can still host the database. Existing direct PostgREST deployments remain available through an explicitly named legacy adapter while they migrate.
 
+### Deployment separates schema and request authority
+
+The schema-owner connection runs migrations as an explicit one-shot operation. A
+separate bootstrap step creates or updates a restricted runtime login and grants only
+the database-derived runtime role. The gateway starts only after both steps succeed and
+receives no schema-owner authority. Its readiness check fails on an incomplete
+migration plan, unsupported PostgreSQL major, row-isolation drift, protected catalog
+drift, or an invalid owner-control membership graph.
+
+Runtime bootstrap runs in one transaction. Before it changes an existing login, it
+rejects every database-derived Agent Bridge authority name, unexpected role edge, and
+object owner. PostgreSQL 16 and newer may add one managed-provider administrator edge
+when the schema owner creates the login. The bootstrap validates that edge exactly. It
+does not adopt a `NOLOGIN` shell restored by native DR.
+
+The schema owner can be a true superuser or a managed-provider administrator with
+`CREATEROLE`. That authority is sufficient for migrations. Native backup requires the
+schema owner to be a true superuser or hold `BYPASSRLS`. A restore target validates the
+intentionally suspended restored schema-owner shell through its superuser session. PostgreSQL 16 and newer may
+split its authority over an internal role between a bootstrap administrator row and a
+schema-owner inherit-and-set row. Native DR may restore the same effective authority as
+one combined bootstrap-superuser row. Security checks aggregate the effective options
+but also validate each allowed physical grant shape. Registered operator and archive
+memberships remain single, schema-owner-granted edges without the admin option.
+
+The repository Compose stack publishes the gateway and PostgreSQL on loopback for
+development. Production deployments put PostgreSQL on a private network, terminate TLS
+before every non-loopback gateway, and source credentials from the platform's secret
+manager. A persistent volume is runtime storage, not a backup.
+
+Upgrade order is database backup, migration, runtime bootstrap, readiness, then client
+or gateway rollout. Because an older image may reject the newer migration plan, schema
+rollback cannot rely on starting the previous container image. Operators apply a
+forward fix or restore a verified native DR bundle into a fresh target before switching
+authority. [The deployment guide](deployment.md) records the operational procedure.
+
 ### SQLite is local storage
 
 SQLite WAL provides local-only operation, a durable outbox, an inbox cache, cursor state, and a cheap pending-work check. Outbox writes use `synchronous=FULL`. It is not the canonical multi-machine database.
@@ -39,7 +75,17 @@ The gateway outbox queues immutable message publication. Receipt and lease mutat
 
 Long-lived gateway MCP clients own a cancellable transport loop that replays publications and refreshes the inbox cache with bounded exponential backoff. It is transport maintenance, not agent monitoring. Manual MCP and CLI sync use the same replay path. A publication timeout after the gateway may have committed remains queued under its stable idempotency key. A retry resolves to the original immutable message instead of publishing a duplicate.
 
-Local initialization must be idempotent. Every connection uses a bounded busy timeout. The minimum supported SQLite build must include the WAL-reset corruption fix. Node 22.23.1 on the current development machine embeds SQLite 3.51.3, which includes that fix.
+Local initialization must be idempotent. Concurrent initialization and schema upgrade
+use a 15-second minimum busy-retry window. Normal database operations retain the
+configured timeout. The minimum supported SQLite build must include the WAL-reset
+corruption fix. Node 22.23.1 on the current development machine embeds SQLite 3.51.3,
+which includes that fix.
+
+On Windows, an opening store verifies the private parent and main database before it
+connects. It applies and verifies explicit ACLs on live WAL and shared-memory sidecars
+after the connection establishes WAL and completes the serialized schema transaction.
+This avoids first-open sidecar churn between concurrent processes. A sidecar that is
+replaced during one ACL validation still fails closed.
 
 ### Portable archives cross storage engines without copying runtime state
 
@@ -123,19 +169,39 @@ PostgreSQL backup takes a repeatable-read exported snapshot while holding the na
 advisory fence. `pg_dump` captures only the `agent_bridge` schema. A separate canonical
 role inventory records the bounded role shells, membership options, and global or
 schema-scoped default ACLs that a schema-only dump omits. The dump excludes data for
-agent instances, rate-limit buckets, request authorities, and archive transaction
-authorizations. The manifest binds migration inventory, table counts, claimed-delivery
-count, tool major, role inventory, and the security, row-isolation, owner-control, and
-portable-archive readiness definitions.
+agent instances, rate-limit buckets, request authorities, endpoint-migration challenge
+rows, and archive transaction authorizations. The manifest binds migration
+inventory, table counts, claimed-delivery count, tool major, role inventory, and the
+security, row-isolation, owner-control, and portable-archive readiness definitions.
+
+The immutable gateway authority UUID is ordinary PostgreSQL data, so native backup and
+restore preserve it. The UUID proves that a restored target represents the same logical
+authority. It does not fence a live clone. Operators must still keep the source and
+restored target from serving traffic at the same time.
 
 PostgreSQL restore requires a dedicated fresh database, the same database name and
 server major, an exact-major `pg_restore`, and superuser authority. It restores role
 shells as `NOLOGIN`, then schema objects, memberships, and default privileges. Claimed
 deliveries become retrying deliveries with cleared leases. The restore checks migrations,
 counts, role inventory, and every readiness attestation before success. External
-principals remain `NOLOGIN`. A failure after target mutation begins disables new target
-connections. If that offlining step fails, the command reports the target as unsafe and
-lists residual role shells.
+principals remain `NOLOGIN`. Runtime memberships are omitted. Active control and archive
+memberships are omitted and receive explicit revocation events after their prior history.
+A matching schema-owner role may be reused only when it is the target session user and
+a true superuser. Every other role collision fails. A failure after target mutation
+begins disables new target connections. If that offlining step fails, the command
+reports the target as unsafe and lists residual role shells.
+
+Managed schema owners need read access to protected ledgers and sequences before
+`pg_dump` can produce a complete native backup. A database-derived `NOLOGIN`
+backup-reader role receives only that access and is granted only to the schema owner.
+Native backup requires that schema owner to be a true superuser or hold `BYPASSRLS`.
+During restore, the target superuser may validate the intentionally suspended restored
+schema-owner shell. A restricted runtime login cannot substitute for that authority.
+`CREATEROLE` alone can apply migrations but cannot produce a complete native backup.
+Native-backup readiness attests the role, authority, membership, and object ACLs. The
+gateway and external operator roles cannot inherit the reader. This backup gate is
+separate from gateway runtime readiness, so drift in an owner-only backup object cannot
+take a healthy gateway out of service.
 
 PostgreSQL source and target URLs come only from
 `AGENT_BRIDGE_DR_SOURCE_DATABASE_URL` and
@@ -173,7 +239,7 @@ A receipt records that a principal read a message.
 
 A publisher stores an immutable `deliveryPolicy` with each message. Untargeted messages default to mailbox mode. Targeted messages default to leased mode with `maxAttempts: 5`, `retryBaseDelayMs: 1000`, `retryMaxDelayMs: 60000`, and `retryJitterRatio: 0.2`. Leased policy may also set `notBefore`. Mailbox messages create no deliveries, and legacy mode rejects leased policy.
 
-A leased delivery records executable work for a recipient. Its state is one of `pending`, `claimed`, `acked`, `retrying`, `dead`, or `cancelled`. `attempt` is lifetime-monotonic, while `cycleAttempt` resets on publisher requeue and `requeueCount` increments. Stored policy owns retry and exhaustion. Claims order due work by urgent, high, then info priority, followed by availability, message creation time, and the stable delivery ID tie-break.
+A leased delivery records executable work for a recipient. Its state is one of `pending`, `claimed`, `acked`, `retrying`, `dead`, or `cancelled`. `attempt` is lifetime-monotonic, while `cycleAttempt` resets on publisher requeue and `requeueCount` increments. Stored policy owns retry and exhaustion. Claims order due work by urgent, high, then info priority, followed by availability, message creation time, and the stable delivery ID tie-break. HTTP 2.1, MCP, and CLI may optionally identify one message. That form atomically selects only the eligible delivery for the authenticated recipient and scopes claim-time expiry and exhaustion maintenance to the same message. Omitting the filter preserves claim-next behavior. The frozen HTTP 2.0 request rejects the additive field.
 
 Consumer-side `maxAttempts` on claim and `retryPolicy` on nack are compatibility inputs for one release. The service validates them and ignores them. This keeps older clients working without letting a consumer change immutable publisher intent.
 
@@ -250,6 +316,189 @@ Protocol logic depends on a `BridgeStore` interface, not a provider SDK. The ini
 
 Host and wakeup adapters are independent from storage. A client manifest declares identity injection, supported wake modes, config locations, health checks, and install actions for Codex, Claude Code, Claude Desktop, OpenClaw, or a generic MCP client. The v1 manifest key named `runtime` identifies an installation target for compatibility. It does not identify a unique running process. The `codex` adapter configures the profile shared by the Codex CLI and the Codex surface in the ChatGPT desktop app. Scripts, CI jobs, daemons, and application services may instead call the CLI or HTTPS API or embed the Node library without pretending to be a harness adapter.
 
+Client lifecycle ownership is separate from registration existence. Local inspection
+classifies a requested Codex, Claude Code, or Claude Desktop contract as absent,
+unmanaged, managed, or drifted by comparing the exact identity, stable instance key,
+backend path, scope, launch contract, and nonsecret registration locator. Desktop
+locators name the normalized host config, Codex locators name the active profile
+config, and Claude Code local or project locators include the invocation directory
+because the native CLI exposes no stronger target. Adoption is plan-first and writes
+only owner-private, credential-free metadata when `--apply` is explicit and the
+unmanaged registration is exact. Backend files and their immediate parents must pass
+the owner-only no-link policy. Codex JSON comparisons ignore diagnostic/status fields
+and property order but require exactly the three Agent Bridge environment keys;
+Claude Code connectivity status is not registration state. Claude Desktop inspection
+shares the installer's validated absolute launch resolver. Applied adoption
+re-inspects its postcondition. It does not read backend values or mutate the
+registration.
+Enrollment-based first-time provisioning retains strict registration and backend-file
+collision refusal. See
+[ADR 0004](decisions/0004-client-lifecycle-and-endpoint-migration.md).
+
+Managed-client repair, update, and uninstall use a local crash-safe substrate. Strict
+owner-private metadata is the mutation authority. Runtime plus stable instance locate
+the metadata, and identity must match both the record and the immutable repair or
+update request. Uninstall also binds the identity. Repair restores its launch contract. Update validates a new launch
+before it creates the journal and stores only the identity, normalized command,
+arguments, scope, and fixed Agent Bridge environment key names.
+Caller backend, scope, and host-config flags are rejected. Owner-private revisioned
+manifests live under
+`~/.agent-bridge/operations/<uuid>` with private snapshots and an exclusive lock keyed
+by runtime plus stable instance. Manifest publication fsyncs files, atomically renames,
+verifies private paths, and fsyncs directories where supported. Snapshot publication
+uses atomic no-replace links, so residue from an interrupted manifest update cannot be
+overwritten. Sensitive file access pins its immediate directory. Operation-root and
+target identities remain pinned throughout creation and destructive cleanup. The root
+and locks identities remain pinned throughout stale recovery, and the artifact-directory
+identity remains pinned across enumeration and every read. A typed credential-agnostic
+request and immutable plan record non-sensitive locators, unique no-replace before and
+after artifacts, and expected digests. Backend artifacts contain only a role, file
+identity, and private or repairable policy state. They never contain backend bytes,
+credentials, URLs, or workspace values. Begin is lock-covered and refuses another
+unfinished operation; any blocked journal fences new mutation, including resume. Resume
+is same-host only. The journal advances through 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 and reverse
+rollback journals use v4. A v4 update request and terminal completion retain a bounded
+credential-free inverse contract: prior managed metadata, prior exact registration
+contract, and forward metadata and registration digests. Version 2 manifests retain
+their released request interpretation and remain inspectable. A non-terminal version 2
+record is blocked because it cannot prove the identity-bound request needed for these
+public mutations.
+
+Before a mutation, repair, update, and uninstall compare the full strict metadata record after
+acquiring the lock. Each non-metadata step repeats that authority check. Registration
+proofs include a bounded observation of the Agent Bridge entry and its full target
+contract. Unknown environment keys, malformed values, unsafe arguments, an unexpected
+scope, or an opaque registration shape stop before a journal is created.
+
+Native repair and update remove the managed entry, prove absence, add the exact target,
+and change metadata last when the launch changes. A native update command is one
+executable contract. Bare commands cannot contain argument separators, while absolute
+paths must resolve to executable files before an update is journaled. Codex runs get,
+remove, and add with the recorded profile home over the supplied environment. Claude
+Code uses its recorded scope, working directory, and supplied environment. Claude
+Desktop reads its recorded config without following links or link ancestors, replaces
+only `mcpServers.agent-bridge`, writes through an operation-scoped private temporary
+file, and verifies the published entry. Node cannot make that update atomic with an
+uncooperative same-user Desktop writer. The code pins and rechecks the file and parent
+identities immediately before rename, but this is an advisory race boundary, not an OS
+transaction guarantee. Windows accepts an already owner-private backend path and
+refuses a non-private backend instead of claiming a safe permission tightening.
+
+Uninstall removes a managed registration, proves its absence, deletes the private
+backend file, then deletes the management metadata. It does not tighten an unsafe
+backend before deletion. A backend that is not already private stops the plan before
+it removes the registration. Uninstall never rolls a completed step back. Desktop
+deletes only `mcpServers.agent-bridge` and preserves unrelated JSON. Before a backend
+or metadata unlink, the code checks the private parent and file identities. POSIX
+syncs that parent after deletion. Windows reports verified deletion with unavailable
+directory durability. Node pathname deletion cannot make this atomic against an
+uncooperative same-user writer, so that race remains advisory.
+
+Rollback is an explicit update-only operation. `clients rollback` locates authority
+only from a committed same-host v4 update record and requires the recorded identity as
+an assertion. It rejects a changed forward registration or metadata state before it
+creates a new reverse journal. Native rollback removes the forward registration,
+proves absence, adds the prior registration, proves it, and writes prior metadata last.
+Desktop replaces only `mcpServers.agent-bridge` and writes prior metadata last. The
+reverse journal retains its source operation UUID and inverse contract so generic
+resume needs no caller-provided backend, scope, command, runtime, or instance. A
+failed forward update is never compensated automatically. Repair has no rollback, and
+uninstall recovery requires re-enrollment.
+
+Native Windows ACL checks start uncached for each acquired or resumed mutation lock.
+While that lock remains held, later directory checks may reuse the result only for the
+same directory path, device, and inode. File checks always use the native policy.
+Passive inspection starts without a cache, and POSIX mode checks run on every access.
+A same-user process can still change an ACL on an unchanged directory or replace it
+with a directory that reuses the same filesystem identity. Local mode already treats
+that OS user as trusted. Agent Bridge does not delete a cached directory during a
+successful managed-client mutation.
+
+Cleanup durably records per-artifact intent, verifies and unlinks the pinned artifact,
+then records POSIX directory sync or explicit Windows unavailability. An absent file
+is resumable only when intent predates the cleanup attempt. Inspection also recognizes
+one verified after artifact left by an interrupted manifest publication. Other missing
+or extra files block. Committed means verified writes and removed artifacts. Its
+manifest drops requests, steps, locators, digests, and artifact metadata. A v4 update
+completion retains only its inverse contract. A v5 stage and a v6 migration phase
+retain bounded credential-free contracts. Other terminal completions retain the
+operation kind, step count, completion time, and cleanup durability for audit. Uninstall
+adds no rolled-back state. Physical erasure remains outside the filesystem contract.
+
+`clients resume <operation-id>` accepts stored v3 repair, update, and uninstall
+operations, supported v4 update and rollback operations, a committed v5 migration
+stage, and v6 endpoint-migration operations, with optional same-host stale-lock
+recovery. It derives authority from the immutable request. It rejects v2 records and
+cannot take replacement caller authority. Generic resume finishes an uninstall
+interrupted after metadata deletion and a reverse rollback interrupted after any
+recorded boundary.
+
+### Gateway client migration staging prepares a later cutover
+
+`clients migrate stage <runtime>` creates a private successor backend and a
+credential-free stage record. It leaves the managed registration, active backend, and
+source edge gate state unchanged after initializing the gate schema. It requires a
+rotation enrollment that keeps the predecessor valid through a future grace cutoff.
+The stage record binds the managed
+identity, source and target endpoint digests, both credential IDs, the source edge
+database path and scope key, and the grace cutoff. It does not store either token or a
+raw gateway URL.
+
+The source backend must bind an absolute, normalized edge database file. Relative and
+in-memory paths cannot identify the same durable outbox across harness working
+directories, so staging rejects them.
+
+An applied stage probes the active and staged bearer credentials, records the
+enrollment credential IDs, initializes the recorded source edge database, and requires
+its migration gate to be active. SQLite rejects a new outbox insert as soon as that
+gate begins draining, including inserts from a client that had already opened the
+database. These checks prepare a later drain and cutover. They do not authorize either
+action.
+
+The stage does not prove that source and target reach the same database authority. A
+later endpoint cutover may use alternate URLs only after it dynamically attests one
+logical authority. The authority identifier must survive clone and restore. Moving to
+an independent database requires a separate owner-mediated fence and is outside this
+staging command. A copied authority identifier does not prove that a live clone is
+fenced.
+
+### Endpoint cutover uses a separate v6 journal
+
+`clients migrate cutover <stage-operation-id> --exclusive-edge --apply` accepts only a
+committed v5 stage with its retained contract. It checks both live gateway status
+responses under HTTP 2.1. Each response must bind the recorded workspace, principal,
+and credential ID, and both must return the recorded immutable authority ID. The
+successor must grant `status:read` and `messages:write`. The source issues a direct
+predecessor-to-successor route challenge that the target consumes before the command
+changes an edge gate or host registration.
+
+The forward journal records full credential-free source and target metadata and
+registration proofs, source and target edge paths, a normalized credential-free source
+gateway URL, the v5 stage contract, and digest bindings for each proof. Once that
+journal exists, every mutation uses a fresh same-successor route proof issued from the
+retained source URL and consumed by the target. The source edge replays through the
+target gateway with the successor credential. It creates a durable source drain lease.
+The edge rejects new outbox inserts while draining. The lease worker must publish all
+work and prove a zero outbox before a native remove or add, a Desktop replacement, or
+the metadata-last switch. The command renews and reasserts the lease immediately before
+each host write. It rechecks the live target authority before every mutation. Source
+and target edge files must be distinct private regular files. The command rejects a
+managed cohort that shares the source edge, including a hardlink alias.
+`--exclusive-edge` covers unmanaged publishers that cannot be enumerated.
+
+Finalization requires a fresh assertion after the grace cutoff. It verifies the
+successor's live status binding and retires the retained source edge. Returning to a
+former endpoint requires a new owner credential rotation and a separate forward
+cutover. Cutover and finalization use exact durable before and after proofs for restart
+classification. A replacement worker can resume a draining edge only after the prior
+lease expires. Dry runs use read-only edge inspection. They do not initialize SQLite,
+create sidecars, or contact gateways. A dry run refuses an edge with live WAL sidecars
+because an immutable read could miss uncheckpointed outbox state.
+
 ### v1 compatibility is additive
 
 The MCP tools `post_context`, `get_context`, and `ack_context` remain available. Existing CLI verbs and flags remain accepted. Text responses remain present while v2 adds structured result data.
@@ -294,7 +543,7 @@ must already satisfy that final policy. Node identity and file-type checks run b
 and after the native policy check. Native reparse attributes
 reject symlinks, junctions, and other reparse objects before and after DACL work.
 
-The schema owner is the trusted offline role administrator. It holds all three control roles with the admin option and registers eligible login roles through `register_control_member`; `revoke_control_member` removes them. Those functions are not available through HTTP or MCP. Each call is idempotent by request UUID and appends the database session actor to the membership ledger. Runtime readiness compares the active registry with the full `pg_has_role` closure and the direct `pg_auth_members` edges. It rejects unregistered operator or auditor holders, every external owner holder, missing registered grants, unsafe login attributes, extra roles inherited by a registered member, and roles that inherit a registered member. Direct edges must retain their expected grantor, admin, inherit, and set options. Only the schema owner is exempt from the broad closure check because a PostgreSQL superuser reports membership across roles. A direct `GRANT` is never a valid deployment shortcut.
+The schema owner is the trusted offline role administrator. It holds all three control roles with effective admin, inherit, and set authority and registers eligible login roles through `register_control_member`; `revoke_control_member` removes them. Those functions are not available through HTTP or MCP. Each call is idempotent by request UUID and appends the database session actor to the membership ledger. Runtime readiness compares the active registry with the full `pg_has_role` closure and normalized direct `pg_auth_members` edges. It also checks the raw grant origins and option shapes. It rejects unregistered operator or auditor holders, every external owner holder, missing registered grants, unsafe login attributes, extra roles inherited by a registered member, and roles that inherit a registered member. Only the schema owner is exempt from the broad closure check because a PostgreSQL superuser reports membership across roles. A direct `GRANT` is never a valid deployment shortcut.
 
 Every protected operation first locks a member-global key for `session_user`, followed by capability keys in operator-before-auditor order. It then checks the active registry, direct membership edge, safe login attributes, and complete upstream and downstream role closure. Inventory accepts either registered capability. Registration and revocation use the same global-first lock hierarchy. Opposite operator and auditor changes for one member therefore cannot deadlock. A revocation waits for an operation that already passed authorization, while every operation begun after revocation observes the new state. A session that remains in a revoked role through `SET ROLE` cannot use that stale authorization.
 
@@ -314,6 +563,33 @@ The stored definition is scoped to the control plane and its dependencies. It in
 
 Migration 012 removes direct runtime reads of credential digest material and establishes transaction-bound request authority. Node computes the credential hash, so PostgreSQL never receives the raw bearer credential. Request authority, security accounting, and domain work use one checked-out PostgreSQL client and one explicit transaction. A security-definer opener matches the credential ID and hash against current revocation, expiry, successor-grace, agent, and workspace state in one locked statement, then records the database-derived credential, workspace, principal, and scopes for that backend and transaction. Instance remains validated same-principal attribution and never establishes authority. Claim, cancel, and requeue reuse the outer transaction without nested `BEGIN`.
 
+Migration 017 adds an immutable singleton authority UUID and a separate bound opener.
+The released opener retains its original result shape. The bound opener returns the
+same credential, workspace, principal, and scopes with the authority UUID in the same
+request transaction. Runtime readiness checks the singleton row, mutation trigger,
+function catalog, and direct table and column privileges. The UUID is returned only by
+authenticated gateway status. It is not a capability field, log field, or readiness
+field.
+
+Migration 018 adds issue and consume operations for a gateway-only HTTP 2.1
+endpoint-migration challenge. The issuer provides a lowercase 64-character hexadecimal
+challenge, expected authority UUID, and direct active successor credential. The
+successor consumes the same commitment with its active transaction-bound authority.
+PostgreSQL hashes the challenge with a domain separator before persistence and retains
+no raw challenge in records, events, or replies. Challenges expire within 60 seconds,
+can be consumed once, and do not permit endpoint cutover. The migration 018
+predecessor-to-successor relation alone does not prove that two distinct URLs share
+live database state. The migration extends the credential-security catalog and records
+endpoint and owner-control v5 attestations before readiness succeeds.
+
+Migration 019 keeps the direct predecessor-to-successor challenge for initial
+preflight and also permits one active successor credential to issue and consume a
+challenge across the retained source and target URLs. It preserves the migration 018
+challenge data, events, security boundaries, and native DR treatment. Endpoint v2 and
+owner-control v6 attestations seal the updated catalog. Authenticated HTTP 2.1
+capabilities report the credential's granted scopes so cutover can reject a successor
+that lacks `status:read` or `messages:write` before it begins a journal.
+
 The domain savepoint separates expected rejected domain work from security effects: expected scope and rate accounting can commit while failed domain mutations are rolled back. An abort before commit rolls the whole request back. Once commit dispatch begins, the gateway never retries and reports `mutation_outcome_unknown` if the outcome is ambiguous. A failed rollback discards the pooled connection.
 
 Migration 013 enables and forces RLS on the five domain tables: messages, receipts, deliveries, delivery events, and agent instances. A database-specific no-login role owns those tables. Two more no-login roles isolate request-context reads and delivery-event writes. The gateway login inherits only the runtime role, which has `NOBYPASSRLS` and cannot inherit any of the owner roles. Zero-argument stable context functions read the workspace and principal from the authority row bound to the current backend, transaction ID, and session user. Policies call those functions through scalar subqueries so PostgreSQL evaluates them as InitPlans rather than once per row.
@@ -330,7 +606,7 @@ Limits apply to content bytes, payload bytes, metadata depth, target count, batc
 
 The CLI provides `init`, `doctor`, `status`, `demo`, `send`, `inbox`, `history`, `claim`, `ack`, `nack`, `watch`, `sync`, portable archive, and migration commands. Existing `post` and `get` aliases remain available.
 
-`/readyz` reports storage and schema readiness. Authenticated HTTP status reports the bound principal, provider schema, delivery counts, and the oldest due delivery. CLI `doctor` and `status` use a separate client-status contract that also reports local edge state and remote gateway reachability.
+`/readyz` reports storage and schema readiness. Authenticated HTTP status reports the bound principal, provider schema, delivery counts, and the oldest due delivery. When production request authority is active, it also returns additive `gatewayAuthorityId` and `credentialId` fields. They are optional in HTTP 2.1. CLI `doctor` and `status` use a separate client-status contract that also reports local edge state and remote gateway reachability.
 
 Gateway responses carry a request ID, including stable error envelopes. Scope failures return required scopes under `error.details`. Rate failures return a rounded retry delay in both the HTTP header and error details. Authenticated Prometheus output counts requests, errors, timeouts, and authentication failures. Responses, metrics, and append-only security events exclude bearer tokens, hashes, database URLs, payload bodies, arbitrary metadata, and credential material.
 
@@ -346,10 +622,11 @@ source, a tag-to-version check, and npm provenance. The npm environment does not
 currently require a human reviewer, so the release process must not claim a manual
 approval gate.
 
-GitHub immutable releases are enabled, and GitHub reports release `v0.3.0` as
+GitHub immutable releases are enabled, and GitHub reports release `v0.3.1` as
 immutable. A tag ruleset also blocks update and deletion of `v*` tags with no bypass
-actor. Future recovery dispatches must run the workflow at the release tag ref so the
-provenance workflow identity and checked-out source commit do not diverge.
+actor. Recovery dispatches must run the workflow at the release tag ref so the
+provenance workflow identity and checked-out source commit do not diverge. Release
+packaging also waits for the exact commit to pass the full `test.yml` matrix on `main`.
 
 ## Acceptance checks
 

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.