@creatornader/agent-bridge 0.2.0 → 0.3.0

package/docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md

@@ -0,0 +1,85 @@
+# ADR-0001: Define protocol layers and acknowledgment semantics
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-14
+
+## Context
+
+Agent Bridge overlaps with agent protocols, client interfaces, message transports, and task systems. Without a firm boundary, an access adapter can become the protocol, transport state can be mistaken for task state, and different acknowledgments can acquire conflicting meanings.
+
+Agent Bridge needs to serve agents across clients, sessions, processes, and machines without owning every protocol above or transport below it.
+
+## Decision
+
+Agent Bridge is the durable, pull-first mailbox and work-delivery control plane for intermittently connected agent runtimes.
+
+Its protocol owns:
+
+- Immutable messages and cursored history.
+- Read receipts.
+- Targeted work deliveries.
+- Claims, leases, retries, settlement, and dead-letter state.
+- Principal-bound identity and workspace isolation.
+- Durable replay after disconnection.
+
+The surrounding layers have separate responsibilities:
+
+- A2A and application protocols sit above Agent Bridge. They own task, conversation, artifact, and domain lifecycle semantics.
+- MCP, CLI, and HTTPS are client access surfaces. They expose Agent Bridge operations without defining its stored protocol.
+- Optional transports such as SLIM or NATS may sit below the core as wakeup or transport adapters. They must not replace authoritative cursor replay or durable delivery state.
+- agmsg is a reference for adapters, interoperability, and client experience. Its patterns may inform clients, but it does not define Agent Bridge identity, persistence, or delivery semantics.
+
+A2A task IDs or application status may travel through Agent Bridge fields and payloads. Agent Bridge does not infer a task lifecycle from message or delivery state.
+
+## Acknowledgment semantics
+
+| Operation | Meaning | State changed | It does not mean |
+| --- | --- | --- | --- |
+| Read receipt | A principal records that it has read or handled a message. | Receipt record | Work ownership, delivery settlement, or task completion |
+| Delivery claim | One principal and instance own a delivery until its lease expires. | Delivery state and lease | The message was read or the work succeeded |
+| Lease extension | The active owner renews its claim. | Lease expiry | Progress, success, or task completion |
+| Delivery acknowledgment | The worker finished processing the delivery and Agent Bridge may stop redelivery. | Delivery becomes `acked` | A read receipt or an external task status |
+| Delivery negative acknowledgment | The worker releases the delivery for retry or marks it dead. | Delivery becomes `retrying` or `dead` | An A2A task failure, cancellation, or rejection |
+| External task completion | An application or A2A task reaches a domain-defined terminal state. | State owned above Agent Bridge | Any automatic receipt or delivery transition |
+
+The interfaces use overlapping names, so documentation must identify the surface:
+
+- MCP `ack_context` and CLI `acknowledge` write read receipts.
+- MCP `acknowledge` and CLI `ack` settle claimed deliveries.
+- MCP `negative_acknowledge` and CLI `nack` negatively settle claimed deliveries.
+- MCP `extend` and CLI `extend` renew a lease.
+
+Read receipts and delivery settlement remain independent in both directions. Recording a receipt does not consume or settle work. Settling a delivery does not create a receipt.
+
+## Consequences
+
+Agent Bridge can carry A2A messages without implementing the A2A task state machine. A client that needs both task completion and delivery settlement must record both operations explicitly.
+
+MCP remains replaceable by another access adapter. A transport integration must preserve cursors, idempotency, identity binding, and delivery leases.
+
+Push notifications and future brokers can reduce wakeup latency. Pull and replay remain the recovery path.
+
+Adapters inspired by agmsg must map into Agent Bridge semantics rather than creating a second receipt, identity, or delivery model.
+
+## Alternatives considered
+
+### Make MCP the Agent Bridge protocol
+
+Rejected because MCP is one client interface. CLI, HTTPS, and future clients need the same stored semantics.
+
+### Own the full task lifecycle
+
+Rejected because A2A and applications define richer task and artifact state. Duplicating that state would create conflicting authorities.
+
+### Require a broker as the shared authority
+
+Rejected for the current architecture. PostgreSQL already provides durable shared state, while cursored pull supports intermittent clients without another required service.
+
+### Adopt agmsg semantics as the core
+
+Rejected because Agent Bridge must persist messages across machines, bind principals to credentials, replay from cursors, and manage leased deliveries. agmsg remains useful as an adapter and interface reference.

package/docs/decisions/0002-canonical-operation-contract-registry.md

@@ -0,0 +1,46 @@
+# ADR-0002: Canonical operation contract registry
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-14
+
+## Context
+
+Agent Bridge v2 exposed the same operations through MCP, HTTPS, and the CLI, but schemas and surface metadata were maintained separately. That allowed request shapes, capability descriptions, and generated documentation to drift. Package, MCP implementation, protocol, and database migration versions also have different compatibility lifecycles.
+
+## Decision
+
+`src/contracts/registry.ts` is the canonical v2 operation registry. Each operation owns its request and response schemas, reserved authorization scope metadata, provider availability, and surface metadata. The generator writes checked-in JSON Schema 2020-12, OpenAPI 3.1.2, MCP manifest, and capability documents from that registry.
+
+External requests pass closed structural schema validation before domain validation. Responses require their known fields and accept additive unknown properties. MCP and HTTP 2.1 claim responses use `{ delivery, leaseToken? }`, and delivery controls use `{ delivery }`. HTTP 2.0 and the unversioned CLI retain direct or null delivery results. Public send requests may supply an immutable message `id`, but never a workspace. An optional `source` is an identity assertion and must match the active principal.
+
+Authenticated HTTP operations negotiate with `X-Agent-Bridge-Protocol-Version`. Version 2.1 is current. A missing request header selects 2.0, and the gateway accepts exactly 2.0 and 2.1. Other versions return 426 with `unsupported_protocol_version`. An upgraded gateway returns the selected version in `X-Agent-Bridge-Protocol-Version` and its supported versions in `X-Agent-Bridge-Supported-Protocol-Versions`. Gateway errors use one envelope with a stable code and request ID.
+
+The HTTP 2.1 client performs and caches a read-only status probe before its first mutation. Negotiation succeeds only when `X-Agent-Bridge-Protocol-Version` equals `2.1` and `X-Agent-Bridge-Supported-Protocol-Versions` includes `2.1`. A headerless response is classified as a released d8184fe 2.0 gateway. A selected 2.0 response, either missing response header, or contradictory values cause the client to reject mutation with a gateway-upgrade error. The client does not downgrade to the 2.0 wire contract.
+
+Compatibility runs in the other direction. An upgraded gateway continues to serve released headerless and explicit 2.0 clients with their original message, delivery, and direct or null response shapes. This makes gateway-first deployment mandatory: deploy the upgraded gateway, verify 2.0 clients, and only then install or start 2.1 clients. Capability output reports current, selected, and supported versions separately.
+
+The OpenAPI paths require protocol 2.1. The `x-agent-bridge-protocol-2.0` and `x-agent-bridge-schemas-2.0` vendor extensions provide limited metadata and frozen schemas for the released compatibility contract. They do not define a second set of paths or a separate OpenAPI description.
+
+Capability documents are filtered by surface and provider. HTTP capability discovery requires a valid credential but has no named scope. The exact scope names are reserved metadata until a later security migration. Gateway credentials grant access as a whole, local mode uses process identity, and legacy mode uses its configured key. Capability documents and OpenAPI set `scopeEnforcement` to false.
+
+Package version, MCP implementation version, Agent Bridge protocol version, and migration version remain independent. The MCP server reports the explicit `MCP_IMPLEMENTATION_VERSION` constant instead of the npm package version.
+
+## Consequences
+
+- `npm run contracts:generate` updates artifacts and `npm run contracts:check` rejects drift.
+- The npm package includes the generated schema and OpenAPI directories.
+- New v2 operations must be added to the registry before surface wiring.
+- Legacy `post_context`, `get_context`, and `ack_context` remain separate frozen compatibility contracts.
+- Protocol 2.1 deployments upgrade and verify the gateway before upgrading clients.
+- This decision adds no task semantics and requires no database migration.
+
+## Related
+
+- [ADR-0001](0001-protocol-layers-and-acknowledgment-semantics.md) defines the protocol layers and acknowledgment meanings.
+- [Architecture v2](../architecture-v2.md) describes the system that follows these decisions.
+- The [README](../../README.md) documents public setup and upgrade behavior.

package/docs/ecosystem.md

@@ -0,0 +1,54 @@
+# Agent Bridge in the agent ecosystem
+
+Agent Bridge is a durable mailbox and work-delivery control plane for agent runtimes
+that may disconnect, restart, or move between machines. It stores immutable messages,
+read receipts, delivery claims, leases, retries, and replay state. It does not own the
+full agent stack.
+
+## System boundaries
+
+| 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. |
+| 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. |
+| 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.
+
+## Relationship to agmsg
+
+Agent Bridge does not claim to replace agmsg's operator interface, process management,
+terminal integration, or community. It treats agmsg as a useful client and adapter
+reference.
+
+The two projects meet at the storage and delivery boundary. An agmsg adapter could map
+send, inbox, history, claim, and settlement operations onto Agent Bridge while keeping
+agmsg's local interaction model. Agent Bridge would then provide durable history,
+principal-bound identity, and cross-machine replay. The adapter must preserve Agent
+Bridge receipt and lease semantics instead of creating a second state model.
+
+## What Agent Bridge does not do
+
+Agent Bridge is not:
+
+- A workflow engine or scheduler.
+- A memory or retrieval system.
+- A terminal multiplexer or agent process manager.
+- A replacement for A2A task semantics.
+- An encrypted global network.
+- A general-purpose event streaming platform.
+
+These boundaries keep the protocol small enough to support clients from different
+vendors without forcing every participant into the same runtime or deployment stack.
+
+## 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
+fixtures, and client libraries. Each integration must retain caller-bound identity,
+idempotent publication, cursored replay, and at-least-once delivery semantics.

package/docs/postmortems/2026-07-08-wrapper-source-drift.md

@@ -0,0 +1,82 @@
+# 2026-07-08 Agent Bridge Wrapper Source Drift
+
+## Status
+
+Resolved for basic Codex, Claude Code, and Claude Desktop availability.
+
+Codex, Claude Code, and Claude Desktop now launch the source repo MCP server
+directly from its built `dist/index.js` entrypoint with a pinned Node binary.
+The direct server reads credentials from `~/.agent-bridge/config`, so client
+configs no longer need to duplicate the Supabase URL or anon key.
+
+The broken Codex, Claude Code, and Claude Desktop signed-wrapper launchd jobs
+were removed after their labels stayed loaded while `/mcp/health` refused
+connections. The wrapper code still exists as an optional signed attribution
+layer.
+
+## Impact
+
+Codex, Claude Code, and Claude Desktop could not use Agent Bridge through MCP
+while their client configs pointed at signed HTTP wrapper ports:
+
+- Codex: `http://127.0.0.1:8794/mcp`
+- Claude Code: `http://127.0.0.1:8793/mcp`
+- Claude Desktop: `http://127.0.0.1:8791/mcp`
+
+The source repo CLI and Supabase connection stayed healthy. The outage was in
+the local wrapper path and client wiring, not in the shared context database.
+
+## Root Cause
+
+The live client configs made the wrapper the only MCP path. That turned an
+optional signing layer into the availability boundary for Agent Bridge.
+
+The wrapper launchd jobs also treated process supervision as enough. A label
+could be loaded while the HTTP health route was unavailable. Nothing moved the
+clients back to the source MCP server when `/mcp/health` failed.
+
+The source MCP server made the fallback harder than it should have been because
+it required `AGENT_BRIDGE_URL` and `AGENT_BRIDGE_KEY` in process env. The CLI
+already read `~/.agent-bridge/config`, so the two source-repo entrypoints had
+drifted.
+
+During recovery, the wrapper installer also selected `node` from ambient
+`PATH`. That allowed restarts to drift to a local Node shim instead of the
+Homebrew Node binary that had previously run the service.
+
+## Fixes
+
+- `src/server.ts` now reads `~/.agent-bridge/config` when env credentials are
+  absent. Env values still take precedence.
+- `test/server_factory.test.ts` covers config-file fallback, env precedence,
+  quoted config values, explicit config paths, and missing credentials.
+- Local Codex, Claude Code, and Claude Desktop configs now launch the source
+  MCP server directly with `/opt/homebrew/bin/node` and only set
+  `AGENT_BRIDGE_AGENT`.
+- The dead Codex, Claude Code, and Claude Desktop wrapper launchd jobs were
+  uninstalled.
+- The internal wrapper installer now prefers `/opt/homebrew/bin/node` by default
+  while still honoring `NODE_BIN`.
+
+## Wrapper Policy
+
+Keep the signed wrapper for attribution receipts and local-substrate metadata.
+Do not make it the only Agent Bridge path for Codex, Claude Code, or Claude
+Desktop.
+
+Only reinstall those wrapper jobs as active client targets after the wrapper has
+health-based supervision. A loaded launchd label is not proof that Agent Bridge
+MCP is available. The proof is a successful `/mcp/health` probe and a real MCP
+tool call.
+
+## Verification
+
+- `npm test`: 24 tests passed.
+- `npm run build`: passed.
+- Direct stdio MCP smoke: listed `post_context`, `get_context`, and
+  `ack_context`, then read live context.
+- CLI status: returned `{"status":"ok","message":"Agent Bridge is connected to Supabase"}`.
+- Claude Desktop launch proof: fresh Desktop log showed `initialize` and
+  `tools/list` succeeding against the direct source MCP entrypoint.
+- Wrapper cleanup: Codex, Claude Code, and Claude Desktop wrapper labels are
+  absent, and their launchd plist files are absent.

package/docs/troubleshooting.md

@@ -0,0 +1,89 @@
+# Troubleshooting Agent Bridge
+
+Start with the command line even when the failure appears inside an MCP client:
+
+```bash
+agent-bridge doctor --json
+```
+
+`doctor` checks the configured backend and reports named failures. It exits 0 when the
+client is ready, 2 when it is degraded, and 1 when a required check fails. `status` is
+passive and does not test remote reachability.
+
+## MCP server disconnected or could not attach
+
+An MCP client must be able to start the server in its own process environment. Desktop
+applications do not always inherit the `PATH` from an interactive shell, so the normal
+Claude Desktop installer records an absolute Node executable and an absolute server
+entry point.
+
+1. Reinstall the Claude Desktop registration:
+
+   ```bash
+   agent-bridge clients install claude-desktop --identity claude-desktop
+   ```
+
+2. Restart Claude Desktop completely. Closing only its window may leave the old process
+   running.
+
+3. Run `agent-bridge doctor --json` again from a shell.
+
+Use `--command` only when an operator intentionally maintains a separate executable.
+Pass an absolute path:
+
+```bash
+agent-bridge clients install claude-desktop \
+  --identity claude-desktop \
+  --command "$(command -v agent-bridge-mcp)"
+```
+
+Claude Desktop stores its Agent Bridge registration under `mcpServers.agent-bridge` in:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+The registered environment must contain distinct `AGENT_BRIDGE_AGENT`,
+`AGENT_BRIDGE_INSTANCE`, and `AGENT_BRIDGE_CONFIG` values for that client. Do not copy
+another client's identity or backend file into the entry.
+
+## The executable is missing
+
+Install the published package globally, then repeat the normal client installation:
+
+```bash
+npm install --global @creatornader/agent-bridge
+agent-bridge clients install claude-desktop --identity claude-desktop
+```
+
+The normal Claude Desktop registration does not depend on the application's inherited
+`PATH`. If an explicit `--command` override is necessary, locate that executable and
+pass its absolute path.
+
+## Identity mismatch
+
+The active runtime owns its identity. Shared backend config must not contain
+`AGENT_BRIDGE_AGENT`, and one client must not claim another client's source label.
+
+Check the client registration and its private backend file. Reinstall that client with
+its intended principal if the values differ. Do not work around the error by adding a
+literal `--source` for normal MCP traffic.
+
+## Gateway failures
+
+Use the doctor output to distinguish local edge health from remote reachability.
+
+- `unknown` means no active probe established remote state.
+- `degraded` can mean cached inbox data or queued outbox messages remain usable while
+  the gateway is unavailable.
+- `failed` means a required local or remote check did not pass.
+
+Queued sends retain their idempotency keys. Long-lived MCP clients retry them, and
+`agent-bridge sync` triggers the same bounded replay manually. Claims, lease changes,
+delivery settlement, presence, and read-receipt writes still require the gateway.
+
+## Report a defect
+
+Include the client name, operating system, package version, sanitized `doctor --json`
+output, and whether the executable path is absolute. Remove tokens, database URLs,
+message content, and private backend contents before posting an issue. Report possible
+security defects through the private process in [SECURITY.md](../SECURITY.md).

package/llms.txt

@@ -3,7 +3,18 @@
 Repository: https://github.com/creatornader/agent-bridge
 Package: @creatornader/agent-bridge
 
-Agent Bridge carries durable context and executable work between AI agents in different clients, processes, sessions, and machines.
+Agent Bridge is a durable, pull-first mailbox and work-delivery control plane for AI agents in different clients, processes, sessions, and machines.
+History uses mailbox `inbox` (default), `sent`, or `all`. Receipt state is `any` (default), `unread`, or `read`; it is caller-relative and inbox-only. CLI: `inbox`, `sent`, and `history --mailbox/--receipt-state`. Deprecated unacked-principal arguments must equal the configured identity.
+
+## Install
+
+- `npm install --global @creatornader/agent-bridge`
+- `agent-bridge init --provider local`
+- `agent-bridge demo`
+
+If an MCP client cannot attach, run `agent-bridge doctor --json` and see
+`docs/troubleshooting.md`. Normal client installation resolves the MCP launch command;
+do not copy another runtime's identity or backend file.
 
 ## Modes
 
@@ -13,27 +24,108 @@ Agent Bridge carries durable context and executable work between AI agents in di
 
 ## Commands
 
+- `agent-bridge capabilities`: print the canonical v2 operation and protocol capability document.
+
 - agent-bridge init --provider local
 - agent-bridge demo
-- agent-bridge doctor
+- `agent-bridge status`: passive JSON snapshot; never probes or synchronizes. Unprobed remote reachability returns unknown with `connected: false`.
+- `agent-bridge doctor`: active named checks; exits 0 ok, 2 degraded, 1 failed. Blocked outbox rows cannot be healthy.
 - agent-bridge pending
 - agent-bridge send, inbox, history, acknowledge
-- agent-bridge claim, extend, ack, nack
+- 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 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
+
+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
+`AGENT_BRIDGE_ARCHIVE_DATABASE_URL`. The digest detects changed bytes; it is neither
+encryption nor authentication. Archives exclude delivery, event, presence, credential,
+control, and security state. Import uses one private file descriptor for format,
+message, and receipt passes with a 4 MiB batch budget. Export completes its audit only
+after durable publication. `--dry-run` and `--apply` are exclusive. Library import:
+`@creatornader/agent-bridge/archive`.
+Portable v1 requires current-domain records, lowercase UUIDs, and six-digit UTC
+timestamps. It does not trim, deduplicate, default, or rewrite message content.
+Legacy or direct rows that fail validation require native database recovery.
+Export accepts a request ID, stores it as header `exportRequestId`, and returns it.
+Verify and import return the same provenance; an import request ID is independent.
+Same-ID export retries verify completed files or reconcile matching started files
+without streaming again. Deterministic adjacent recovery files are derived from the
+export ID. Force replacement keeps a private backup until the new file is durable and
+reports recovery paths plus backup, durability, and audit uncertainty.
+
+Native DR preserves a complete local SQLite authority or shared PostgreSQL authority;
+it does not translate between providers. Local DR rejects gateway edge stores.
+PostgreSQL source and target URLs come only from AGENT_BRIDGE_DR_SOURCE_DATABASE_URL
+and AGENT_BRIDGE_DR_TARGET_DATABASE_URL. Restore requires a dedicated fresh database
+with the same name and PostgreSQL major, superuser authority, an explicit request ID,
+and --accept-source-sql-risk. The backup includes role membership and default ACL state,
+excludes transient request, rate-limit, instance, and archive-authorization rows, and
+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.
 
 ## 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.
+
 Compatibility: post_context, get_context, ack_context.
-Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence.
+Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
+Publisher delivery intent: `deliveryPolicy` mode `mailbox|leased` with `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. MCP delivery controls: `list_deliveries`, `list_delivery_events`, `cancel_delivery`, `requeue_delivery`. Consumer `maxAttempts` and `retryPolicy` are validated but ignored for one compatibility release.
+
+Gateway MCP clients sync automatically and expose manual sync for bounded outbox replay and inbox cache refresh. Offline unacknowledged results are degraded candidates with unknown acknowledgement state, not proof that messages are unread or that no remote work exists.
+
+## Protocol boundary
+
+A2A and application task semantics sit above Agent Bridge.
+MCP, CLI, and HTTPS are client access surfaces.
+Optional transports such as SLIM or NATS may sit below the core.
+agmsg is a reference for adapters, interoperability, and client experience.
+HTTP protocol 2.1 is current. Upgraded gateways continue to serve released headerless and explicit 2.0 clients. New 2.1 clients probe before mutation and proceed only after complete, consistent negotiation selects and advertises 2.1. They reject headerless or selected 2.0 gateways instead of downgrading. Upgrade the gateway before 2.1 clients. Capabilities distinguish current, selected, and supported versions.
+MCP and HTTP 2.1 use delivery response envelopes. The unversioned CLI and HTTP 2.0 retain direct or null delivery results.
+OpenAPI paths describe 2.1. Embedded 2.0 vendor extensions provide limited compatibility schema metadata, not a second OpenAPI description.
+
+## Acknowledgment rules
+
+MCP ack_context and CLI acknowledge write read receipts.
+MCP acknowledge and CLI ack settle claimed deliveries.
+A receipt does not settle work. Delivery settlement does not create a receipt.
+Lease extension does not report progress or external task completion.
 
 ## Identity rule
 
 The active runtime supplies AGENT_BRIDGE_AGENT and AGENT_BRIDGE_INSTANCE. Do not hardcode another client name and do not store agent identity in the shared backend config. Gateway installations use a separate principal-bound token and owner-only backend file for each client.
 
+Owner commands are offline and use only AGENT_BRIDGE_OPERATOR_DATABASE_URL. They are
+not MCP, HTTP, or public gateway operations. Provision and rotation write private
+versioned enrollment files before calling PostgreSQL. The installer consumes the raw
+token from that file without command arguments. Rotation updates the exact existing
+client backend and does not repeat host registration. Enrollment operations hold an
+exclusive per-file lock and use revisioned compare-and-swap transitions. Use explicit
+`--recover-lock` only after a crash; recovery checks lock age, host, owner, and process
+liveness. Rotation requires predecessor credential, principal, instance, gateway,
+workspace, and live MCP registration matches. Consumed-file deletion and lock release
+report retained, missing, durable, and durability-unknown outcomes without claiming that
+an unlinked path was retained.
+
+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.
+
 ## References
 
 - README.md: setup, commands, security, and provider behavior
+- ROADMAP.md: released, implemented, and remaining work
+- 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/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/architecture-v2.md: protocol, storage, identity, delivery, and acceptance decisions
 - clients/*.json: runtime adapter manifests
 - SKILL.md: concise agent operating instructions