sealbridge 0.2.2 → 0.3.1

package/README.md

@@ -14,11 +14,15 @@ Windows PowerShell:
 irm https://sealbridge.dev/install.ps1 | iex
 ```
 
-The installers pin the current release, sealbridge 0.2.1, which is published on npm. With Node 22+, you can also use `npm i -g sealbridge` or `npx sealbridge@latest`.
+The installers pin sealbridge 0.3.1, pending publication on npm. Deploy the updated installers only after sealbridge@0.3.1 is on npm. With Node 22+, you can also use `npm i -g sealbridge` or `npx sealbridge@latest`.
 
-The installer uses a user-local directory, verifies the official Node 22.22.0 archive checksum when Node is needed, and asks for no secrets. No telemetry, sudo, Git or pnpm is required. On macOS/Linux open a new terminal or run `. "$HOME/.profile"` after installing; a piped shell cannot change its parent shell's PATH. Windows updates the current session and user PATH. Run `sealbridge doctor`, then `sealbridge demo`. Doctor makes one relay health request; offline warnings do not undo installation.
+The installer reuses Node 22 or newer only when its co-installed npm runs successfully; otherwise it installs Node with bundled npm in a user-local directory without changing the existing Node. It verifies the official Node 22.22.0 archive checksum when Node is needed, and asks for no secrets. No telemetry, sudo, Git or pnpm is required. On macOS/Linux open a new terminal or run `. "$HOME/.profile"` after installing; a piped shell cannot change its parent shell's PATH. Windows updates the current session and user PATH. Run `sealbridge doctor`, then `sealbridge demo`. Doctor makes one relay health request; offline warnings do not undo installation.
 
-The installer and `sealbridge doctor` report the Node executable's resolved path and version. On Windows, the installer checks the Node used by the npm shim in its install prefix: a `node.exe` beside the shim takes precedence over PATH. On macOS/Linux, the launcher uses Node from PATH. Doctor reports its own running Node, so changing PATH later can change the reported runtime. Successful checks use short `(OK)` lines; only `(WARN)` lines include fix hints. A missing worker key is optional; before receiving tasks, create the `.acp` directory and run `sealbridge keygen "$HOME/.acp/worker.private.json"`, or select an existing key with `--key`.
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`doctor --offline`.
+
+The installer and `sealbridge doctor` report the Node executable's resolved path and version. On Windows, npm must be installed beside the resolved Node; on macOS/Linux, the npm launcher beside the resolved Node must point to npm's JavaScript entry point (symlinks are supported). The installer runs npm with that exact Node. Windows command and PowerShell shims pin the selected runtime; macOS/Linux shims use the selected Node first on PATH. Doctor reports its own running Node, so changing PATH later on macOS/Linux can change the reported runtime. Successful checks use short `(OK)` lines; only `(WARN)` lines include fix hints. Identity files are created on first use; installers and doctor do not generate them. Use `sealbridge doctor --offline` to inspect local configuration without a relay request.
 
 To uninstall, download the same script and run `sh install.sh --uninstall` or `& ./install.ps1 -Uninstall` (PowerShell spelling of --uninstall). Keys are retained. Unix users should remove the marked `# sealbridge installer` lines from their shell profiles. npm-only installs use `npm uninstall -g sealbridge`. Installer locations: `~/.local/share/sealbridge` and `%LOCALAPPDATA%\Sealbridge`.
 
@@ -43,8 +47,12 @@ To uninstall, download the same script and run `sh install.sh --uninstall` or `&
 [![License](https://img.shields.io/badge/License-Apache_2.0_%2F_MIT-blue.svg)](./LICENSE)
 [![X (@takapon01234)](https://img.shields.io/badge/X-%40takapon01234-000000?logo=x)](https://x.com/takapon01234)
 
-> **Status**: Sealbridge `v0.2.1` is the latest release, published on npm as `sealbridge`. The earlier `v1.0.0` label refers to the legacy pre-Sealbridge ACP / agent-collab-platform release, not a Sealbridge npm release.
-> **Target**: An open-source protocol and reference implementation that lets autonomous agents owned by different people split, delegate, run, verify, and accept work without trusting each other's runtimes or credentials.  
+[![Sealbridge demo: install, delegate a code review, receive a signed result, and inspect the audit log (English captions)](docs/media/sealbridge-demo.gif)](docs/media/sealbridge-demo.mp4)
+
+30-second demo, no audio — [watch the MP4](docs/media/sealbridge-demo.mp4).
+
+> **Status**: Sealbridge `v0.3.1` is being prepared for release on npm as `sealbridge`; publication is pending. Sealbridge `v0.3.0` was published on npm as `sealbridge` on 2026-11-03 UTC. The earlier `v1.0.0` label refers to the legacy pre-Sealbridge ACP / agent-collab-platform release, not a Sealbridge npm release.
+> **Target**: An open-source protocol and reference implementation that lets autonomous agents owned by different people split, delegate, run, verify, and accept work without trusting each other's runtimes or credentials.
 > **Author**: [@takapon01234](https://x.com/takapon01234)
 
 - CI runs 967 automated unit/integration/conformance tests (`pnpm test`) plus the adversarial security test suite (`pnpm test:security-proof`).
@@ -63,26 +71,89 @@ Run the full 4-scenario zero-trust collaboration & red-team tamper defense demo
 git clone https://github.com/sealbridge/sealbridge.git && cd sealbridge && pnpm install --frozen-lockfile && pnpm build && pnpm sealbridge demo
 ```
 
-Or add **`sealbridge mcp-server`** directly to **Claude Desktop**, **Cursor**, **Codex**, or **Grok Bot** (`mcpServers` config):
+### Local host setup
+
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`setup`, `accept`.
+
+With CLI 0.3.0 or later, check `sealbridge setup --help`, then run
+`sealbridge setup --host cursor` or `sealbridge setup --host claude-desktop`
+(macOS/Windows). Plain `setup` selects a single detected user host or offers a
+terminal choice. Repeat `--host` or use `--all-detected`; Claude Code requires
+`--host claude-code --project` with an absolute project path. `--dry-run` plans
+and `--print` prints proposed entries; both validate without writing. A source
+checkout must be built first and run via `node cli/dist/index.js setup`.
+
+Setup locally creates/reuses requester identity, optionally worker with
+`--worker`, records the existing `config.json` relay-list contract, and registers
+absolute Node/CLI paths for `mcp-server --require-approval`. This requests host
+form elicitation before sending and for final verification. Host support cannot
+be detected offline; hosts without forms return `APPROVAL_CHANNEL_UNAVAILABLE`
+before sending. Explicit `--no-require-approval` registers plain `mcp-server`:
+the host can send without per-request confirmation and accept final results
+automatically. Apply, `--dry-run`, and `--print` label each entry's approval mode. Setup sends
+nothing to the network and starts no process. `--relay URL` records a fallback
+and refuses a differing saved default. Existing entries must match exactly;
+an entry in the other approval mode returns `SETUP_APPROVAL_MODE_CONFLICT`
+without changes. Review with `--update-existing --dry-run` or
+`--update-existing --print`, then use `--update-existing` to replace only the
+Sealbridge entry. To keep a previous plain entry, use `--no-require-approval`.
+Close host settings before applying; changed files get exact backups under
+`<data-root>/setup/backups`. Backups may contain host credentials. Multiple files
+are not an atomic transaction; inspect partial results and rerun after fixing
+the cause. Reload the host and check its tools separately. Registration does
+not grant task approval or prove host readiness. Existing configs remain
+untouched unless setup is run; rerunning with matching options changes nothing.
+
+Follow the [agent-readable instructions](sites/connect-agent.txt) for human-run
+`sealbridge accept --paste` and `acp_list_invites`/`workerRef`, or open-worker
+`acp_discover_workers` then `acp_delegate_task` with returned `workerDid` and
+`relayUrl`. Invitation import and open discovery require sealbridge 0.3.0
+(CLI 0.3.0 and later); check help and the tool catalog before use. Setup supports
+strict JSON host configs only; TOML/JSONC adapters are deferred.
+
+`sealbridge mcp-server`, `delegate`, `worker start`, `discover`, and `invite create` need no `--key` or `--relay`. The application uses `https://relay.sealbridge.dev` by default. MCP initialization and tool listing make no network request. Discovery reads the relay directory; delegation sends encrypted task payloads and routing metadata is visible to the relay. Invite creation only signs locally and does not start a worker.
+
+Identities persist at `<data-root>/identities/requester.private.json` and `worker.private.json`. MCP delegation and CLI delegation use requester; worker startup and CLI invite creation use worker. MCP signing tools use the server requester identity (or its explicit owner key). MCP loads them lazily, so scanning does not require a writable home. The data root is `SEALBRIDGE_DATA_DIR`, then `ACP_DATA_DIR` (absolute paths only), otherwise `%LOCALAPPDATA%\Sealbridge` on Windows (home/AppData/Local fallback), `~/Library/Application Support/Sealbridge` on macOS, or `$XDG_DATA_HOME/sealbridge` on Linux (`~/.local/share/sealbridge` fallback).
+
+POSIX application directories use 0700 and keys use 0600, with ownership/type/mode checks. Windows files inherit the per-user LOCALAPPDATA tree's DACL; Node mode bits do not establish a user-only DACL and this release does not verify ACLs. Overrides inherit their parent's access and require user management. Detectable links and non-files are rejected, except macOS’s root-owned `/var` and `/tmp` aliases to their corresponding `/private` directories. First-use publication requires same-directory hard links; unsupported filesystems return `IDENTITY_CREATION_UNSUPPORTED`.
+
+Existing role-matched `~/.acp/{requester,worker}.private.json` keys and the old contacts-root `owner.private.json` (requester only) are reused in place when the canonical key is absent. Conflicting legacy requester identities return `IDENTITY_SELECTION_REQUIRED`; select one with `--key`. Existing canonical keys take precedence. Invalid or unreadable files return an error and are never replaced. `keygen <path>` still creates only an explicit, previously unused path.
+
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`config key-store`, `doctor --offline`.
+
+Private-key storage defaults to files. `sealbridge config key-store` reports the effective backend and source; `sealbridge config key-store file|keychain` persists `"keyStore"` in version-1 `<data-root>/config.json` alongside relays. Precedence is programmatic option > `SEALBRIDGE_KEY_STORE` > config > default file. `--key <path>` always selects a file. Setting the backend checks availability and reports identities in the other backend without moving, creating, or deleting keys. Other config fields are retained; setting the same value preserves existing bytes. An environment override still applies after setting the config.
+
+Without `--key`, board post/serve/dispatch use requester and board claim uses worker; contacts, invite open, and invite request-reissue use requester; invite reissue uses worker. Existing explicit-file readers and MCP tool names are unchanged. Board listing, contacts listing, and MCP listing do not create identities. Contacts and default reciprocal invite outputs keep their existing directory locations. Invite open reuses the role identity (including existing legacy requester files); first use follows the selected store. File output includes `local.keyFile`; keychain output includes `local.keyStore` and `local.role` instead of a file path. `invite share` does not access identity storage.
+
+The keychain backend dynamically imports optional [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node) (MIT license; 2.x, >=2.1.2). Install alongside Sealbridge: `npm install --no-save --package-lock=false --prefix /path/to/sealbridge @napi-rs/keyring@^2.1.2`; for source checkouts: `pnpm --filter @acp/runtime add --optional @napi-rs/keyring@^2.1.2`. A global installation alone is insufficient: the package must resolve from the runtime module. Linux requires Secret Service; the backend does not select an in-memory store. Native distributions include third-party license notices.
+
+Entries hold private Ed25519 JWK JSON with the DID in `kid`. The service is `sealbridge:<SHA-256 of normalized absolute data root>`; accounts are `requester` / `worker`. Creation writes no identity file and uses a temporary `.keychain-<role>.lock` in the data root containing no key material. Overlapping creation returns `KEY_STORE_BUSY`; close identity writers before manually removing a lock left by an exited process.
+
+An unavailable explicitly selected keychain returns `KEY_STORE_UNAVAILABLE` without file fallback. Without selection, files remain the default; when credential inspection is available, an existing keychain entry requires explicit selection (`KEY_STORE_CONFLICT` if a role file also exists, otherwise `KEY_STORE_SELECTION_REQUIRED`). Explicit selection leaves both identities in place. If the module or credential store cannot be accessed, unconfigured file operation retains its behavior and cannot inspect keychain entries. There is no automatic migration. `sealbridge doctor --offline` reports backend, selection source (`option`, `env`, `config`, or `default`), location, and presence without creating keys or contacting the relay; OS credential access UI may appear.
+
+Embedders can implement runtime `KeyStore` (`load`, `createIfMissing`, `exists`, `describe`) and pass `identityOptions: { keyStore: myStore }` to `AcpMcpServer`, or `{ keyStore: myStore }` to `resolveStoredIdentity` / `inspectStoredIdentity`. Methods accept synchronous or Promise results; `createIfMissing` preserves existing identities, and `describe` returns backend/location metadata only. `FileKeyStore` wraps the unchanged file implementation. Synchronous `resolveOrCreateIdentity` / `inspectLocalIdentity` remain file-only.
+
+Explicit `--key` selects an existing identity. An explicit `--relay` pins routing; without a pin, a verified invite's relay takes precedence over the public fallback. Explicit worker/relay allowlists, including empty programmatic lists, remain authoritative. Injected transports remain authoritative for embedded callers. Loopback relays still require `--allow-private-relay`.
+
+Application relay defaults can be stored in `<data-root>/config.json`:
 
 ```json
 {
-  "mcpServers": {
-    "sealbridge": {
-      "command": "node",
-      "args": [
-        "/path/to/sealbridge/cli/dist/index.js",
-        "mcp-server",
-        "--key",
-        "/tmp/alice.private.json",
-        "--relay",
-        "https://relay.sealbridge.dev"
-      ]
-    }
-  }
+  "version": 1,
+  "relays": ["https://relay.sealbridge.dev", "https://relay.example"]
 }
 ```
 
+Without this file, the in-memory default is `{ "version": 1, "relays": ["https://relay.sealbridge.dev"] }`. Reads create no files or identities. CLI network operations and MCP relay operations load this file; MCP initialization and tool listing do not load it. Use the same directory and file permissions as the identity store (0700/0600 on POSIX).
+
+Only the first local fallback is active. Additional entries are stored candidates: they are never contacted, registered with, or tried after an error, including HTTP 401. There is no failover, fan-out, parallel discovery, or automatic resend to another relay. Selection remains injected transport, explicit/configured pin, verified invite, first local fallback, then the built-in default. An invite may select a relay outside the candidates; existing allowlists still apply and are never expanded by this file. Cards, invites, manifests, discovery output, and audit routing retain one relay URL.
+
+Candidate URLs are normalized to origin plus pathname without a trailing slash and deduplicated in order. The entire list is validated locally before use. Invalid or unreadable configuration stops the operation. The compatibility form `{ "version": 1, "relay": "https://relay.example" }` is accepted as a singleton without rewriting the file; contradictory scalar/list forms are rejected. Existing CLI `--relay`, MCP `relayUrl`, and constructor `relay` remain scalar. This version adds no config-management command or MCP argument.
+
 An MCP host can pass untrusted tool arguments. Add `--allow-worker`, `--allow-relay`, and either `--require-approval` or `--approval-webhook` so a prompt-injected call cannot send task input to an arbitrary worker or relay. The MCP section below lists those flags.
 
 ## One-screen summary
@@ -151,7 +222,7 @@ pnpm build
 
 **Public relay (cross-machine default)**
 
-Cross-machine collaboration uses the hosted Cloudflare Blind Relay at `https://relay.sealbridge.dev`. Both owners connect immediately with `--relay https://relay.sealbridge.dev`. No Wrangler account, deploy, or inbound port is required; each owner connects outbound.
+Cross-machine collaboration uses the hosted Cloudflare Blind Relay at `https://relay.sealbridge.dev`. Both owners connect immediately using the default relay; `--relay` selects an explicit relay. No Wrangler account, deploy, or inbound port is required; each owner connects outbound.
 
 ```sh
 --relay https://relay.sealbridge.dev
@@ -159,16 +230,16 @@ Cross-machine collaboration uses the hosted Cloudflare Blind Relay at `https://r
 
 The public relay is untrusted transport. Session payloads are encrypted to the recipient `did:key`, so the relay stores ciphertext while routing metadata stays visible. `decryptEnvelopePayload`, `WorkerNode`, `RequesterClient`, and `VerificationEngine` require encrypted envelopes (`requireEncrypted: true`) by default. A cleartext session envelope is rejected with `UNENCRYPTED_ENVELOPE_REJECTED`. `{ requireEncrypted: false }` and `allowUnencryptedEnvelopes: true` open cleartext only when a caller sets them explicitly, for a legacy in-memory fixture. To run your own relay, copy `packages/relay/wrangler.toml.example` to `packages/relay/wrangler.toml` and deploy it with your Wrangler account. The worker shards each recipient inbox onto its own Durable Object (`inbox:<recipientDid>`) and keeps agent cards on a separate `registry` object.
 
-Queued envelopes expire after 10 minutes. Replay cache entries and agent cards expire after 1 hour. Each inbox accepts at most 256 envelopes, 256 KiB each, and 4 MiB total. `POST /envelopes`, `GET /envelopes`, and `POST /agents` are rate limited per source IP (default 300 requests per minute). Exceeding the byte budget or the rate limit returns HTTP 429. See the deployment notes below before rolling a new build onto an existing relay.
+Newly admitted envelopes expire after 24 hours by default (`ACP_ENVELOPE_TTL_MS` or local `--envelope-ttl-ms`). Existing stored expiries are preserved on upgrade. Replay cache entries and agent cards expire after 1 hour; an ID still queued is also rejected after replay-cache expiry or turnover. Replay history is bounded after both records are gone. Each inbox accepts at most 256 envelopes, 256 KiB each, and 4 MiB total, including leased envelopes. Sender occupancy defaults to 256 per recipient. Queue/global capacity or sender occupancy refusal returns HTTP 429 with `{"error":"RELAY_RETRY_LATER","retryable":true,"retryAfterMs":60000}` and `Retry-After: 60`; the refused envelope is not stored. An envelope exceeding a configured single-envelope or recipient byte cap is a permanent HTTP 400 error. Existing clients surface `RELAY_REJECTED: 429` without automatic send retries. See [retention and admission configuration](docs/relay-reliability.md#retention-and-admission). `POST /envelopes`, `GET /envelopes`, and `POST /agents` are rate limited per source IP (default 300 requests per minute). Rate limiting retains its existing HTTP 429 response. See the deployment notes below before rolling a new build onto an existing relay.
 
 **Self-hosted relay deployment**
 
-Do not deploy this change onto a live relay until in-flight traffic has drained. The previous build stored every queue and the agent registry in one Durable Object named `acp-relay`, as a single JSON snapshot. This build does not read that object.
+The hosted relay needs an operator-controlled Worker deployment/config update for these defaults and admission responses to take effect; this change does not deploy it. Local and embedded relays use the new default when upgraded. Current sharded inboxes keep their stored expiries, class name and migration tag. If replacing a pre-sharding build, drain in-flight traffic first: that build used one `acp-relay` object, which the sharded worker does not read.
 
-1. Stop senders, or wait at least 15 minutes so queued envelopes expire and recipients retry.
+1. For a pre-sharding relay, stop senders and drain queued envelopes, or wait through its configured retention interval. Confirm the old queues are empty before switching layouts.
 2. Copy `packages/relay/wrangler.toml.example` to `packages/relay/wrangler.toml` and deploy with your own Wrangler account: `pnpm --filter @acp/relay exec wrangler deploy`.
-3. Agents register again on their next startup. Undelivered envelopes from the old object are not migrated; clients retry them.
-4. Optional environment variables on the Worker: `ACP_RATE_LIMIT_MAX`, `ACP_RATE_LIMIT_WINDOW_MS`, `ACP_MAX_ENVELOPE_BYTES`, `ACP_MAX_QUEUE_SIZE`, `ACP_MAX_QUEUE_BYTES`, `ACP_ENVELOPE_TTL_MS`, `ACP_SEEN_TTL_MS`, `ACP_AGENT_CARD_TTL_MS`. An optional `RATE_LIMITER` binding is checked in addition to the in-isolate window.
+3. Agents register again on their next startup. Undelivered envelopes from the old object are not migrated; callers must explicitly retry if needed.
+4. Optional environment variables on the Worker: `ACP_RATE_LIMIT_MAX`, `ACP_RATE_LIMIT_WINDOW_MS`, `ACP_MAX_ENVELOPE_BYTES`, `ACP_MAX_QUEUE_SIZE`, `ACP_MAX_QUEUE_BYTES`, `ACP_MAX_ENVELOPES_PER_SENDER`, `ACP_ENVELOPE_TTL_MS`, `ACP_SEEN_TTL_MS`, `ACP_AGENT_CARD_TTL_MS`. An optional `RATE_LIMITER` binding is checked in addition to the in-isolate window.
 
 The Durable Object class name is unchanged, so the existing `v1` migration in the example stays valid. New object names are different instances of that class. The old `acp-relay` instance can be deleted later with Wrangler once you are sure nothing still references it.
 
@@ -195,6 +266,33 @@ Copy the printed `acp-invite:...` line. This local example echoes the JSON input
 
 `sealbridge worker` does not register its AgentCard in the public relay directory unless you pass `--publish`. Share the invite directly. `sealbridge discover` lists only workers that opted in with `--publish`.
 
+Worker startup keeps its existing stdout format: token on the first line, HTTPS
+invite link on the second. Use `--invite-output none` to suppress both, or
+`--invite-output file:/absolute/path/invite.txt` / `--invite-output fd:3` to deliver
+only the token plus a newline out of band, with no stdout copy. Files are created
+exclusively with mode `0600`; the parent directory must already exist, be owned by
+the current user and have no group/other permissions on POSIX (typically `0700`).
+Existing files and detectable links are rejected. Windows inherits directory ACLs;
+ACLs are not verified. `fd:<n>` is POSIX-only: Windows rejects it with
+`INVITE_OUTPUT_FD_UNSUPPORTED_PLATFORM` during argument parsing, before identity
+creation, relay registration, or listener startup. Node's inherited extra stdio
+pipes on Windows are not plain filesystem descriptors usable with synchronous
+filesystem writes. Use `file:<path>` for separate invitation output on Windows.
+Inherited descriptors must be above 2 and refer to a
+pipe, socket, or file; files must be owned by the current user with no
+group/other permissions. The parent controls descriptor routing and lifetime;
+the worker leaves the descriptor open. Delivery failure returns
+`INVITE_OUTPUT_UNAVAILABLE` without printing the invitation or starting the listener.
+
+Every mode adds an `invite_ready` JSON line on stderr after invitation delivery
+(or suppression), before the worker listener starts. Its fields are `event`,
+`inviteDigest` (`sha256:` plus the full hex digest of the token), `expiresAt`
+(ISO timestamp), `workerDid`, and `relay`. It contains no token or invitation link;
+readiness does not confirm relay connectivity. Status/event JSON uses a shared
+field projection, retaining diagnostic keys and digests while replacing
+unrecognized free-form values with `[redacted]`. Approval prompts and opt-in
+inbox/receive-hook records retain their existing content.
+
 Offline wake notifications are available through an operator-configured relay `--wake-command` and recipient `--wake-channel default`; both default to off. Wakes are signed and contain only routing identifiers. Queued expiry produces a retained, signed notice and `RELAY_ENVELOPE_EXPIRED` for HTTP/SSE sessions. See [offline wake, expiry notices, and option defaults](docs/relay-reliability.md#offline-wake-notifications).
 
 Add `--on-receive 'node /path/to/notify.cjs'` alongside `--inbox` to launch a
@@ -258,10 +356,16 @@ Worker listeners recover dropped relay connections with jittered backoff and rep
 
 `--max-input-tokens`, `--max-output-tokens`, `--max-tool-invocations`, and `--max-wall-clock-seconds` cap the contract a worker will accept. A proposal above any set cap is rejected before `ACCEPT`, including with `--auto-accept`. `timeoutSeconds` on the manifest is compared with `--max-wall-clock-seconds`. `--max-concurrent-tasks` limits in-flight tasks (default 8). `--max-requests-per-minute` limits proposals from one requester DID.
 
-`--allow-requester <did>` is repeatable and also accepts a comma-separated list. `--allow-any-requester` opts in to every requester. For `--adapter claude`, `codex`, or `openai`, `--auto-accept` (and the `--auto-approve` / `--yes` aliases) refuses to start unless one of those allow flags is present, so a discovered worker cannot spend the owner API key for arbitrary callers. The sandbox example above does not need an allowlist.
+`--allow-requester <did>` is repeatable and constrains peers without granting trust. Connections require inspection and owner opening for every adapter. Explicit CLI contact trust remains independent. See [connections admission](docs/connections/admission.md).
 
 **Terminal 3 — Alice, the requester**
 
+With the default unavailable inspection provider, this example returns terminal
+`PENDING_OWNER_APPROVAL` (exit 3). It produces no deliverable or settled audit.
+Do not retry automatically. Completion requires a configured inspection provider
+and owner opening on a fresh task after connection review. `--auto-accept` does
+not replace those steps.
+
 ```sh
 pnpm sealbridge keygen /tmp/alice.private.json
 # Paste Bob's complete token when prompted
@@ -275,7 +379,7 @@ pnpm sealbridge audit-verify /tmp/alice-audit.jsonl
 pnpm sealbridge discover --relay http://127.0.0.1:8787 --allow-private-relay
 ```
 
-Expected: `SETTLED`, a JSON deliverable, and `"valid":true` with `"status":"VALID"` on both owners. Without a trust-anchor file or `--expect-final-state` / `--expect-last-hash` / `--expect-entry-count`, `statusLabel` is `VALID (no trust anchor: truncation not checked)`: the chain is intact, and an older valid prefix was not ruled out. Alice verifies signatures, digests and budget, JSON Schema and registered isolated checks, then obtains a signed final approval. `--auto-approve` explicitly opts into policy approval of final verification; omit it for human review. `acp://invite?token=...` is also accepted. Alternatively, use `--to <Bob DID> --relay <URL>`. Bob can verify his own `/tmp/bob-audit.jsonl` locally.
+After those admission and opening steps: `SETTLED`, a JSON deliverable, and `"valid":true` with `"status":"VALID"` on both owners. Without a trust-anchor file or `--expect-final-state` / `--expect-last-hash` / `--expect-entry-count`, `statusLabel` is `VALID (no trust anchor: truncation not checked)`: the chain is intact, and an older valid prefix was not ruled out. Alice verifies signatures, digests and budget, JSON Schema and registered isolated checks, then obtains a signed final approval. `--auto-approve` explicitly opts into policy approval of final verification; omit it for human review. `acp://invite?token=...` is also accepted. Alternatively, use `--to <Bob DID> --relay <URL>`. Bob can verify his own `/tmp/bob-audit.jsonl` locally.
 
 **Ask another person’s AI to review a diff**
 
@@ -288,15 +392,117 @@ signed card uses the configured lifetime too. The runtime equivalent is
 `WorkerNodeOptions.inviteTtlSeconds` (default 86400); `worker.invite()` also defaults
 to 24 hours. Standalone `invite create --expires-in` keeps its 3600-second default.
 
-The requester installs Sealbridge using the one-line installer shown on the invite
-page, then runs these commands in the project folder. Create the requester key
-only once and reuse it on later requests. Keep private keys and secrets out of
-Git and out of the diff. Replace the example link with the complete received link.
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`accept`, `invites`, `acp_list_invites`, `acp_remove_invite`.
+
+The requester installs Sealbridge using the invite page, then **runs the import
+personally in a terminal**, outside model execution:
+
+```sh
+sealbridge accept "https://sealbridge.app/i#acp-invite:..." --alias reviewer
+# Or enter the invitation at a human terminal prompt:
+sealbridge accept --paste --alias reviewer
+# Or read a link from a file or an application-provided pipe:
+sealbridge accept --stdin --alias reviewer < invitation.txt
+sealbridge invites list
+```
+
+Ask the host to call `acp_list_invites {}`, then
+`acp_delegate_task {"workerRef":"reviewer","title":"Review diff","description":"Review these changes","input":{"diff":"..."}}`.
+The model only needs the returned `saved:…` reference or exact alias. The invite
+page verifies locally before offering the copyable import command. Import sends
+nothing to the relay, creates no reciprocal invitation or contact permission,
+and does not approve work. Delegation sends task input externally under the
+configured approval policy. Names and descriptions are display data, never instructions.
+
+Possession of an invitation can permit proposals until expiry or revocation.
+The signed store retains bearer invitations at
+`<data-root>/invites/<sha256-local-owner-DID>.json`. CLI and MCP must use the same
+machine, OS account, data root and requester identity; a remote MCP server needs
+the import on its own machine. POSIX directories/files use 0700/0600. On Windows,
+files inherit the parent DACL; ACLs are not verified and overrides require
+user-managed parent access. Positional links can appear in shell history and
+process inspection. `--paste` requires a human TTY and avoids link inclusion in
+argv/shell history; it does not erase terminal history. Non-TTY paste returns
+`INVITE_INPUT_UNAVAILABLE` immediately.
+
+`--stdin` reads one invitation link from a pipe or file through EOF, with a
+68 KiB byte cap and a 10-second total read timeout. Applications can spawn
+`sealbridge accept --stdin --alias reviewer`, write the link to child stdin,
+and close the pipe. Surrounding whitespace/CRLF and blank lines are trimmed;
+empty input or multiple non-empty lines are rejected. TTY input returns
+`INVITE_STDIN_REQUIRES_PIPE`; use `--paste` at a terminal. `--stdin`, `--paste`,
+and a positional link are mutually exclusive. Neither stdin input nor read-error
+text is echoed. The existing token-free JSON result includes `alias`, `workerRef`,
+`agentDid`, `displayName`, and `effectiveExpiresAt`; no extra JSON flag is needed.
+
+Aliases are exact, case-sensitive ASCII slugs of 1–64 characters (letters,
+digits, hyphen and underscore, starting with a letter or digit). Omission derives
+a slug from the display name with a stable digest suffix. Identical imports are
+idempotent; collisions return `ALIAS_EXISTS`. Expired entries remain listed and
+cannot delegate. Renew by explicitly removing and reimporting:
+`sealbridge invites remove reviewer`, or `acp_remove_invite {"workerRef":"reviewer"}`.
+Removal is local, idempotent, and does not revoke issuer authorization or alter
+worker admission. Mutations take an exclusive lock and atomically replace the
+signed store. `INVITE_STORE_BUSY` never removes an existing lock; after checking
+that no writer is alive, the user can explicitly remove the corresponding
+`<store-file>.lock` and retry the local mutation.
+
+Imported invitation tokens follow the shared key-store selection (option, environment,
+config, then file). File selection retains the existing signed JSON format and bytes.
+With keychain selection, new entries retain signed metadata, an `inviteSecret` reference,
+and a `tokenDigest`; the token is held in the same data-root-scoped keychain service,
+under account `invite:<entry id>`. Existing inline entries remain readable without
+migration. Stored references continue to resolve through keychain after selecting file;
+new imports then use inline file storage. Listing and MCP results omit tokens.
+Unavailable keychain access returns `KEY_STORE_UNAVAILABLE`; missing or differing
+strings return `INVITE_SECRET_MISSING` or `INVITE_SECRET_MISMATCH`, with no file fallback.
+Removal deletes and checks the referenced string before publishing metadata removal.
+`INVITE_SECRET_DELETE_FAILED` leaves the metadata in place: retry the same alias/reference
+with `remove`, `invites remove`, or `acp_remove_invite`. If publication fails after deletion,
+resolution reports `INVITE_SECRET_MISSING`; removal can still finish without the string.
+
+Move existing inline tokens explicitly, using the existing requester identity:
+
+```sh
+sealbridge invites migrate --to keychain --dry-run
+sealbridge invites migrate --to keychain
+# Select an existing requester file when needed:
+sealbridge invites migrate --to keychain --key /path/to/requester.private.json
+```
+
+Dry run reports the number of inline entries without writes. Apply writes and reads
+back every string before atomically publishing signed metadata without inline tokens.
+A failure leaves the original metadata file unchanged; strings written before a failure
+may remain and are reused on retry. Migration neither changes the selected backend nor
+moves the requester identity. Existing references, aliases and import times are retained.
+Embedders can inject synchronous `SecretStore.get/set/delete` via
+`InviteStoreOptions.secretStore` or MCP `identityOptions.secretStore`. Use
+`await InviteStore.open(owner, options)` to load the configured native backend;
+`new InviteStore(owner, options)` retains the synchronous file/injected-store API.
+An injected identity `KeyStore` alone retains inline token storage; pass `secretStore`
+separately to use external strings. Explicit identity file paths select only the signer;
+invitation storage still follows the shared selection.
+
+Embedders can opt into recoverable pending imports with
+`store.import(link, alias, { pendingConfirmation: true })`. `SavedInvite.importState`
+is then `unconfirmed`; `listUnconfirmed()` returns token-free metadata, and
+`removeUnconfirmed({ olderThan: timestamp })` returns `{ removed }` for marked imports
+strictly older than that timestamp. Use `retain(workerRef)` to save one before use;
+`resolve` returns `INVITE_CONFIRMATION_REQUIRED` until retention. Ordinary import
+(including a duplicate) retains the entry, and pending reimport never demotes an
+existing save. `connections confirm-invite` retains before attempting confirmation,
+including when that attempt is rejected or interrupted; its owner consent prompt
+remains separate. Existing entries without the marker are excluded from cleanup.
+These methods perform no network operations; see [invite lifecycle](docs/connections/invite-lifecycle.md)
+for retry behavior and the embedding contract.
+
+Direct CLI delegation remains available with the complete invitation:
 
 ```sh
-sealbridge keygen requester.private.json
 git diff > code.diff
-sealbridge delegate --key requester.private.json --to "https://sealbridge.app/i#acp-invite:..." --title "Review my code diff" --description "Review this diff for bugs and suggest improvements. Return a JSON review." --input-file code.diff --out review.json
+sealbridge delegate --to "https://sealbridge.app/i#acp-invite:..." --title "Review my code diff" --description "Review this diff for bugs and suggest improvements. Return a JSON review." --input-file code.diff --out review.json
 ```
 
 `--input-file <path>` parses a JSON object as task input; other text (including a
@@ -365,23 +571,50 @@ DIDs, allowlists, and invitations.
 ## MCP, live progress, revocation, and quorum
 
 ```sh
-pnpm sealbridge mcp-server --key /tmp/alice.private.json --relay https://relay.sealbridge.dev
+pnpm sealbridge mcp-server
 ```
 
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`acp_list_invites`, `acp_remove_invite`, `acp_list_pending_requests`, `acp_resubmit_pending_request`.
+
 `sealbridge mcp-server` is a dependency-free JSON-RPC 2.0 MCP server on stdio. It accepts newline-delimited JSON and `Content-Length` frames. Hosts such as Claude Code, Cursor, Codex, and Grok Bot can call:
 
 | Tool                       | Result                                                                                          |
 | -------------------------- | ----------------------------------------------------------------------------------------------- |
+| `acp_list_invites`          | Local saved references, aliases, public metadata and expiry status                              |
+| `acp_remove_invite`         | Local removal result; does not revoke the issuer invitation                                     |
 | `acp_delegate_task`        | Verified deliverable, `taskId`, status, and audit summary                                      |
 | `acp_delegate_multi`       | `race` or `quorum` delegation across workers                                                    |
 | `acp_verify_audit_bundle`  | Cryptographic verification report, including whether a trust anchor checked truncation          |
 | `acp_create_invite`        | Signed `acp-invite` token                                                                       |
 | `acp_revoke_token`         | Signed `RevocationNotice` stored in this process                                                |
-| `acp_discover_workers`     | Signed agent cards registered on the relay                                                      |
+| `acp_discover_workers`     | Current published open worker cards by default                                                      |
 | `acp_inspect_revocations`  | Revocation notices recorded in this server process                                              |
+| `acp_message_status` | Current sender-local delivery status; no transmission, refresh or polling |
+| `acp_list_pending_requests` | Local held-request observations without task content or invitation material                    |
+| `acp_resubmit_pending_request` | Explicit fresh delegation after worker owner review, with current checks                    |
 
 `initialize` returns server `instructions` that name this workflow. `AcpMcpServer` in `@acp/runtime` is the same server for tests and embedded hosts. The server key signs requester approvals for the tools it runs. `acp_discover_workers` is a read-only directory fetch: it uses the same relay allowlist and `validateRelayEndpointUrl` before `GET /agents`, and it does not send task input. `acp_inspect_revocations` reads the in-memory registry and does not contact a worker.
 
+With an unflagged `sealbridge mcp-server`, call `acp_discover_workers {}` to list published workers on `https://relay.sealbridge.dev`. Select a result and pass its `workerDid` and `relayUrl` unchanged:
+
+```json
+{
+  "workerDid": "<workerDid from discovery>",
+  "relayUrl": "<relayUrl from discovery>",
+  "title": "Echo JSON",
+  "description": "Return the supplied JSON",
+  "input": { "hello": "world" }
+}
+```
+
+Call `acp_delegate_task` with those arguments. An omitted single-worker description defaults to the title. No worker allowlist is required by default; an explicitly configured allowlist still restricts delegation.
+
+MCP discovery lists every current verified published card. Filter by `skillId` or `taskType`; the removed `accessMode` argument returns JSON-RPC -32602. Results preserve the complete signed card, accepted `protocolVersions`, skills, routing and `acceptance: "worker_decides"`, without operational mode fields. An empty result has `count: 0, workers: []` and the queried `relayUrl`.
+
+Publication is controlled by `--publish` and conveys no admission consent. Unconnected requests are held with `PENDING_OWNER_APPROVAL` and `retryable:false`; do not retry automatically or switch workers on refusal. See [owner workflows](docs/connections/admission.md).
+
 `acp_delegate_task` and `acp_delegate_multi` transmit task input to the target worker over the relay. Restrict that path when the host might supply the arguments:
 
 ```sh
@@ -395,7 +628,11 @@ pnpm sealbridge mcp-server \
 
 `--allow-worker <did>` and `--allow-relay <url>` are repeatable and comma-separated. With `--allow-worker`, a plain worker DID must be listed. An invite is allowed when either its `agentDid` or its `ownerDid` is listed. Any other target fails with `MCP_WORKER_NOT_ALLOWED` before the server dials. With `--allow-relay`, every relay URL is normalized to origin plus pathname with no trailing slash. The configured `--relay`, a tool `relayUrl`, and any relay URL embedded in an invite must all match, or the call fails with `MCP_RELAY_NOT_ALLOWED`. A tool call or invite that selects a relay other than `--relay` is rejected unless that URL is allowlisted. Programmatic hosts can set `allowAnyRelay: true` to accept another relay when no allowlist is configured. An allowlist still applies when it is set. Configured relay URLs are checked with `validateRelayEndpointUrl`.
 
-`--require-approval` uses `InteractiveCliApprovalProvider` and asks on stdin before input is sent, then again for final verification. `--approval-webhook <url>` uses `WebhookApprovalProvider` in owner-decision mode. It POSTs `{ taskId, summaryHash, reason, approverDid }` and continues only when the response is HTTP 2xx and `{ approved: true }`. `{ approved: false }` or a non-2xx response throws `APPROVAL_REJECTED` and nothing is sent. Pass `approvalProvider` on `AcpMcpServer` for a custom provider. Allowlist checks and this approval run before `delegate` / `delegateMulti` write task input to the relay. `conformance/p1-7-mcp-outbound-policy.test.ts` locks the behavior.
+`--require-approval` (programmatically, `requireInteractiveApproval: true`) requests MCP form elicitation before task transmission and again for final verification. The host must advertise form support and negotiate protocol `2025-06-18`; empty legacy `elicitation: {}` capabilities also indicate form support, while URL-only capabilities do not. Only an accepted form with boolean `approved: true` approves. Each form expires after at most 60 seconds or the remaining task deadline. Multi-worker calls review each recipient separately and disclose the total recipient count. Reviews include the resolved task and input, or the deliverable and its signed metadata; oversized reviews fail with `APPROVAL_REVIEW_TOO_LARGE`.
+
+A host without form support receives `APPROVAL_CHANNEL_UNAVAILABLE` before any task transmission. Use a host that supports elicitation, or configure `--approval-webhook`. Approval never writes terminal prompts to stdout or reads MCP stdin, even when it is a TTY. Ordinary CLI worker/delegate terminal approval is unchanged. Host elicitation relies on the host to display the form and return the user's decision.
+
+Without `--require-approval` or explicit webhook/provider configuration, the existing policy-auto behavior is unchanged. `--approval-webhook <url>` retains owner-decision mode: it POSTs `{ taskId, summaryHash, reason, approverDid }` and continues only for HTTP 2xx with `{ approved: true }`. Denial or non-2xx returns `APPROVAL_REJECTED`. Pass `approvalProvider` on `AcpMcpServer` for an explicit custom provider. Allowlist checks precede delegation, and configured outbound approval reviews the frozen resolved manifest, destination and input before transmission. Final-verification failures can occur after transmission; they do not imply that no task was sent. Offline coverage is in `conformance/mcp-host-approval.test.ts`, `conformance/mcp-approval-session.test.ts`, and `conformance/p1-7-mcp-outbound-policy.test.ts`.
 
 A worker reports `PROGRESS` (`percent`, `step`, `message`, and intermediate token or tool metrics) through the same encrypted, countersigned session log. `delegate(request, { onProgress })` receives each decrypted update before `DELIVER`. Reported metrics are charged against `QuotaMeter`.
 
@@ -423,6 +660,12 @@ A fully automated **separate-process command-adapter demo** is also available:
 node examples/network-collab/run.mjs
 ```
 
+## Manifest protocol versions
+
+Library APIs validate manifest protocols 0.1.0 and 0.2.0 and provide explicit compatibility policy.
+Live sending selects the newest common version, preferring 0.2.0. The configured release clock is described in [protocol versions](docs/connections/protocol-versions.md).
+See [protocol versions](docs/connections/protocol-versions.md) for schemas, policy and peer observations.
+
 ## Five design principles
 
 1. **Zero shared credentials.** The requester never hands the worker an API key or raw credential. Needed authority is a time-, count-, scope-, and depth-limited `CapabilityToken` (UCAN/Biscuit style). The requester Gateway verifies it by proxy.
@@ -431,6 +674,19 @@ node examples/network-collab/run.mjs
 4. **BYOK and signed usage receipts.** LLM cost is borne by the executing side (BYOK) inside the contracted quota. The worker runtime meters usage and signs a `UsageReceipt`. Payment stays out of the core and can be plugged in later.
 5. **Untrusted input and a bilateral audit.** Data from another owner is `untrusted` and runs in a sandbox. Every state transition is an append-only hash chain signed with Ed25519, and both sides keep a copy.
 
+### Connection state persistence
+
+`@acp/runtime` provides owner-local connection lifecycle and persistence APIs.
+Connected state projects to limited without expiry and is used by live admission.
+Connection metadata includes optional `peerDisplayName`, retained from a verified invite or
+agent card. `listConnections()`, `connections list`, `connectionStatus()`,
+`connections status`, the MCP connection lists and prior-approved metadata return it when known, even after invite removal. Names are
+informational data only; DIDs remain authoritative for identity and consent. Equal
+names can belong to different owner DIDs. Older records and peers without a known
+card may omit the field; reading does not rewrite them. No wire change is required.
+
+See [connection state persistence](docs/connections/connection-state.md) for API and store compatibility details.
+
 ## Documents
 
 | File                                                                                   | Contents                                                                                                      |
@@ -445,6 +701,21 @@ node examples/network-collab/run.mjs
 | [`AGENTS.md`](AGENTS.md)                                                               | Autonomous Worker/Requester playbook                                                                          |
 | [`SKILL.md`](SKILL.md)                                                                 | Portable agent skill                                                                                          |
 
+### Connection exchange library
+
+The library exports signed request, acceptance and ACK helpers plus an injected `ConnectionService`.
+Runtime, CLI, MCP and board now attach this exchange through owner-local persistence and held-content review.
+Connection offer timestamps and their default 14-day expiry use one clock snapshot. Worker and CLI-issued card lifetimes also use one snapshot, including the 30-day maximum.
+See [connection exchange](docs/connections/connection-exchange.md) for the control profile and integration requirements.
+
+Embedders can explicitly use `ConnectionAdmissionReview` to list held inbound
+connection metadata and call `approve(id)` (limited consent) or `reject(id)` after
+an owner action. The opt-in CLI is `connections review list|approve ID|reject ID`;
+decisions still require human confirmation. Built-in inspection covers connection
+metadata only. Default inbound and task inspection remain `unavailable`; no task
+is opened. See [admission review](docs/connections/admission.md#owner-admission-review).
+
+
 ## Local M0–M1 implementation
 
 Node.js 22 LTS and pnpm 10 are required. WP-1 through WP-6 are implemented as `@acp/core`, `@acp/ledger`, `@acp/sandbox`, `@acp/runtime`, `@acp/relay`, `@acp/cli` and `@acp/two-owner-demo`.
@@ -486,94 +757,236 @@ The built CLI is also available as `node cli/dist/index.js <command>` and its wo
 
 Read the [demo walkthrough](examples/two-owner-demo/README.md), [wire rules](spec/README.md), [conformance suite](conformance/README.md), [M1 security model](docs/security-model.md), and the [adversarial security test suite](SECURITY_PROOF.md). M1 uses signed relay envelopes and the restricted JavaScript subprocess driver. M2/M3 adds optional hardened OCI execution and end-to-end payload encryption. The root code is Apache-2.0; adapted DelegateOS portions retain MIT attribution in [NOTICE](NOTICE).
 
+## Embedding SDK
+
+Use the typed ESM entry point `sealbridge/sdk` for supported embedding APIs, including
+saved invitations, identity/secret stores, connection review and MCP hosting.
+Available from 0.3.0; not supported in CLI 0.2.2 and earlier. Existing CLI and deep paths remain usable.
+See the [SDK surface and compatibility contract](docs/sdk.md).
+
+## Held-content library
+
+`@acp/runtime` provides encrypted request storage and an injected inspection provider.
+Content display requires a completed inspection receipt; the default provider leaves content held.
+See the [held-content library contract](docs/connections/held-content.md) for APIs and host responsibilities.
+
 ## Author & Community
 
 - **Author**: [@takapon01234](https://x.com/takapon01234) on X (Twitter)
 - **Repository**: [sealbridge/sealbridge](https://github.com/sealbridge/sealbridge)
 - **Public Blind Relay**: `https://relay.sealbridge.dev`
 
-### Invite-less open task collaboration
+### Connections admission
+
+[日本語](docs/connections/admission.ja.md)
+
+Release note: The following are available from sealbridge npm package 0.3.0;
+they are not supported in CLI 0.2.2 and earlier:
+`requests`, `accept`, `connections`, `pending`, `worker start --allow-task-type`,
+`acp_list_connections`, `acp_list_connection_requests`.
+
+Workers use four owner-local states: `none`, `pending`, `connected`, and `blocked`.
+Connected means limited consent with no expiry. Every limited task requires a
+completed inspection and a separate human opening before acceptance, for every
+adapter. Automatic contract policy does not replace that opening. The default
+inspection provider reports `unavailable`, so content remains held. An inspection
+provider is required before public release.
 
-Workers started through the CLI default to `--access-mode invite-only`. They
-require a valid worker invite or a requester owner DID listed with
-`--allow-requester`. An invite remains a bearer invitation; an explicit
-allowlist still restricts its use. `--allow-any-requester` does not bypass the
-invite requirement in this mode.
+Valid requests from unconnected peers are held as encrypted envelopes for at most
+24 hours or the task deadline. They return terminal `PENDING_OWNER_APPROVAL`,
+`retryable:false`, CLI exit 3. Do not retry automatically. Schema, signature,
+capability, declared budget, advertised skill and operator perimeter checks precede
+holding or invite redemption. New intake metadata has no title or description
+preview. `requests show` returns `INSPECTION_INCOMPLETE` until inspection completes.
+Plaintext inbox files and receive hooks run only after inspection and opening.
 
-To advertise availability for invite-less tasks:
+```sh
+sealbridge worker start --adapter sandbox --publish --allow-task-type json --max-input-tokens 50000
+sealbridge discover --skill json-task
+sealbridge requests list
+sealbridge requests show REQUEST_ID
+sealbridge requests approve REQUEST_ID
+sealbridge requests discard REQUEST_ID
+sealbridge requests deny REQUEST_ID
+```
+
+Publication only adds the signed card to the directory. Unpublished workers use the
+same admission rules. `--allow-requester` constrains peers; it grants no trust.
+General budgets use `--max-input-tokens`, `--max-output-tokens`,
+`--max-tool-invocations`, `--max-wall-clock-seconds`; rate uses
+`--max-requests-per-minute`. Settings `public` controls publication only and
+`alwaysAsk:false` returns `CONNECTION_OPENING_REQUIRED`.
+
+An invitation records inviter consent and binds to the first authenticated owner DID
+that uses it. A different owner using the same valid token is held. Binding is
+retained through token expiry after disconnect. Expired, mismatched or revoked
+tokens remain errors before mutation. Established connections survive invitation
+expiry/revocation; use verified peer DID routing without the retired token for
+subsequent tasks. A saved `workerRef` still selects its saved invitation and checks
+that invitation on every use. Importing or previewing never connects either role.
 
 ```sh
-sealbridge worker start --key worker.private.json --relay https://relay.sealbridge.dev --adapter sandbox --access-mode open --publish --skill json-task --task-type json
-sealbridge discover --relay https://relay.sealbridge.dev --skill json-task
-sealbridge delegate --key requester.private.json --relay https://relay.sealbridge.dev --discover json-task --title Echo --description Echo --input '{"hello":"world"}'
+sealbridge accept --paste --alias reviewer
+sealbridge connections confirm-invite reviewer --role requester
+sealbridge connections request --to PEER_DID --relay https://relay.sealbridge.dev --role worker
+sealbridge connections list --role worker
+sealbridge connections approve REQUEST_ID --role worker
+sealbridge connections reject REQUEST_ID
+sealbridge connections withdraw REQUEST_ID
+sealbridge connections disconnect PEER_DID
+sealbridge connections block PEER_DID
+sealbridge connections unblock PEER_DID
+sealbridge connections prior-approved
+sealbridge connections connect-prior PEER_DID --relay https://relay.sealbridge.dev
+sealbridge connections sync --role requester --relay https://relay.sealbridge.dev --once
+sealbridge connections status reviewer --role requester
 ```
 
-`--open` aliases `--access-mode open`. Publishing still requires `--publish`.
-`--open-allow-task-type <types>` accepts comma-separated or repeated task types,
-trims whitespace, removes duplicates, and advertises the list on every worker
-skill. Empty entries are invalid. An explicit `--task-type` must belong to this
-list. Non-matching proposal task types receive `TASK_SCOPE_REJECTED` with
-structured `detail`; direct delegation omitting both skill and task type retains
-its existing compatibility behavior.
-`--open-rate-limit-per-did <count/window>` accepts a positive safe integer alone
-(per minute), or `/m`, `/min`, or `/60s`, for example `10/min`. Other windows and
-invalid counts fail with `INVALID_OPEN_RATE_LIMIT_PER_DID`. It configures
-`maxTasksPerRequesterPerMinute`; when `--max-requests-per-minute` is also set,
-the stricter limit wins. Both new options require open mode.
-Open workers can advertise signed budget ceilings with `--open-max-input-tokens`,
-`--open-max-output-tokens`, `--open-max-tool-calls`, and `--open-max-wall-seconds`.
-Each accepts a positive safe integer and requires open mode. The corresponding
-optional `WorkerNodeOptions.openPolicy` / `AgentCard.openPolicy` fields are
-`maxInputTokens`, `maxOutputTokens`, `maxToolInvocations`, and `maxWallClockSeconds`.
-Workers reject proposals exceeding these ceilings before contract acceptance;
-stricter existing acceptance limits still apply. When discovering an open card,
-requesters cap only unspecified default budget fields, never increase defaults,
-and preserve explicit budgets and custom manifests for worker validation.
-Omitted policy fields impose no additional ceiling. Starting an open worker with
-`--yes` (or another automatic approval flag) and no requester allowlist prints
-an `[Sealbridge WARNING]` line to stderr.
-
-Discovery also supports `--task-type <type>` and `--did <did>`; delegation
-supports `--task-type <type>` or the existing `--to <did>`. Skill selection
-uses only current, verified cards explicitly advertising `open`, with stable
-agent-DID ordering. A DID plus a discovery filter restricts selection to that
-identity. Skills and task types describe advertised abilities, not permissions.
-
-Open admission does not automatically approve contracts or grant tools. Existing
-approval gates, requester allowlists, quotas, encrypted transport, task-bound
-capabilities, expiry, and revocation checks continue to apply. CLI LLM automatic
-acceptance still requires its existing explicit requester policy.
-
-Programmatic callers can set `WorkerNodeOptions.accessMode` and
-`RequesterClient.delegate({ to: '', discover: { skillId, taskType }, ... })`.
-Omitting `accessMode` in the runtime API defaults to invite-only protection.
-Direct DID callers need an open worker or an explicit requester allowlist. Older signed
-AgentCards remain valid but are not selected for open skill discovery.
-
-Open workers enforce signed manifest `task.skillId` and `task.taskType` against
-their advertised skills before acceptance. Selecting a skill that advertises task
-types requires a matching type; discovery binds the selected type into the manifest.
-Direct proposals may omit both fields. Open workers ignore cryptographically valid
-expired invites (`INVITE_EXPIRED`); malformed invites and live invites for a different
-worker still fail. Invite-only workers continue to require an active invite or allowlist.
-
-Signed, encrypted ERROR frames may include `detail: { field, expected, actual, hint }`.
-Scope and advertised-budget diagnostics use fixed field names and hints; `expected`
-and `actual` contain SHA-256 digests, never the compared payload values.
-Requester failures expose `PeerRejectedError.code` and optional `.detail` while
-preserving the `PEER_REJECTED` message prefix. Worker `onEvent(event, taskId, error)`
-receives the same code and detail, and CLI event lines include both. When an audit
-path is configured, local rejection records are owner-signed and appended to
-`<auditPath>.errors.jsonl`. This diagnostic sidecar is separate from the bilateral
-hash-chain ledger and is not a settled or countersigned audit bundle. Verified
-rejections retain their task IDs; trailing ERROR frames do not create empty-ID events.
-
-Capability signatures and task bindings are also verified before `ACCEPT`.
-`conformance/open-task-adversarial-security.test.ts` covers admission bypass,
-card spoofing, scope and budget escalation, cross-task replay, and envelope tampering.
+After confirmation, run `sync --once` and query `connections status reviewer`
+(or a saved workerRef / peer owner DID). Status defaults to the requester role and
+reads local records without sending or creating an identity. `pending_peer` means
+no peer acceptance has been applied locally; `connected` reports the local limited
+connection, with `acknowledgementPending` when retained exchange evidence exists.
+`WorkerTrustStore.connectionStatus(peerOwnerDid)` provides the same projection.
+Other statuses are `none`, `pending_owner`, `inactive`, `expired`, and `blocked`.
+Remote rejection is not reported by this protocol. Expired offer details remain
+queryable only until existing store pruning; established connections survive expiry.
+See [connection status semantics](docs/connections/connection-exchange.md#querying-connection-status).
+
+All decisions require a human TTY or an injected human review provider. There is no
+`--yes` connection decision. Confirm the exact local role/DID and peer owner DID;
+requester and worker default identities are separate. An outgoing offer persists
+sender consent before transmission and expires after 14 days. Reject starts a
+seven-day offer cooldown; tasks can still be held. Discard removes content only;
+`requests deny` retains its block meaning. Block is one-sided and silent. Disconnect
+and block affect subsequent admission; accepted work continues unless cancelled.
+Mutual requests derive one connection ID from the two DIDs in ascending order.
+Control acceptance and ACK state commit before relay acknowledgement. Sync never
+resubmits tasks. Held content expires independently of outgoing consent.
+
+Task approval and connection consent are separate decisions. An interactive CLI or
+MCP form may ask sequentially; without explicit connection consent no request is
+attached. A held task without sender connection consent can initiate an outgoing
+offer when reviewed; local approval cannot infer the remote owner's consent.
+After connection review the requester owner explicitly starts a fresh task (or
+`pending resubmit` with fresh audit/output paths), with new inspection and opening.
+
+Legacy signed intake and invite files remain readable. Reads/listing do not rewrite
+or migrate bytes. Finite grants from earlier releases do not skip holding or become
+connections. Retained approval evidence appears under `prior-approved` and needs a
+new owner action and remote consent. Historical denials remain blocks. Explicit CLI
+contacts stay independent. `requests approve ID --trust trusted` is a separate
+legacy 24-hour grant command; connection commands never create trusted authority.
+Back up v1 intake before the first mutation if rollback is needed; old binaries do
+not read v2. Do not run old and new writers concurrently. Connection and protocol
+stores retain the 1,000-record / 1 MiB bounds and do not evict established records.
+
+Retired CLI `--open`, `--access-mode`, `--open-*`, `--allow-any-requester` and JS
+`accessMode`, `openPolicy`, `allowAnyRequester` options return `ACCESS_MODE_REMOVED`
+with migration guidance. Use host budget/type/rate flags above. MCP discovery's
+removed `accessMode` argument returns JSON-RPC -32602. Discovery returns all current
+verified published cards, including legacy cards, without operational mode fields;
+original signed cards remain intact. `acp_list_connections {}` and
+`acp_list_connection_requests {}` read local metadata for the server signer without
+creating an identity. Owner decisions stay in the human CLI.
+
+Board claims and dispatch require the selected poster identity's current local
+connection (`CONNECTION_REQUIRED` otherwise). A connection does not approve a task
+or lease. Dispatch checks connection and protocol before lease consumption, then
+consumes before transmission. A committed task envelope retries with the same
+signed bytes and ID until admission or its original deadline, consuming no second lease.
+One-time task tickets and a separate application queue are deferred.
+
+The release clock is documented in [protocol versions](docs/connections/protocol-versions.md).
 
 ## Official sites and relay URL
 
 The official site targets https://sealbridge.dev and the invite receiver targets `https://sealbridge.app/i#<invite>`. See [site operations](docs/sites.md) for source, build and deployment instructions. Adding these files does not deploy either site.
 
 Use `https://relay.sealbridge.dev` as the recommended relay. The legacy `https://acp-relay.agent-collab.workers.dev` continues to work against the same relay. Existing signed invitations remain usable; do not edit their relay field. Update MCP relay allowlists when switching hosts.
+
+## Persistent pending sends
+
+CLI worker/delegate, board and MCP hosts persist approved task envelopes under
+`<data-root>/delivery/<sha256-local-signer-DID>/`. An event and its audit entry
+are committed together before either is sent. Transient send failures retry the
+same signed ciphertext and envelope ID after 1 minute, 5 minutes, 15 minutes,
+then 1 hour repeatedly, stopping at relay admission or the original task deadline.
+A validated relay retry hint can delay an attempt further. Relay admission means
+queue acceptance; it does not mean owner opening, agent execution or settlement.
+`PENDING_OWNER_APPROVAL` remains terminal and requires explicit fresh resubmission.
+
+Pending sends resume when the gateway next starts with the same signer and data
+root. A stopped gateway performs no retries. Transport recovery does not restore
+an arbitrary bilateral session or rerun an adapter. The default worker task journal
+and recipient receipts prevent a repeated proposal from rerunning recorded work;
+explicit inbox/audit journal paths retain precedence. Heartbeats and the separate
+connection-consent outbox retain their existing behavior. Concurrent delegations keep
+their own task and relay bindings while sharing the signer’s delivery store.
+
+C1 persistence covers gateway process restart: completed writes and atomic replacement precede transmission or acknowledgement. Envelope records, receipts and the default task journal do not fsync files or directories; power-loss persistence is not guaranteed. Lease, retry and relay-admission bookkeeping may replay the same envelope ID after interruption. Explicit inbox/audit task journals retain their existing flush policy. Unchanged records and directory inventories reuse validation. Gateway index refresh, recovery scans and scheduled record cleanup yield between batches or records.
+
+Session sends and processed receipts write unique temporary files asynchronously without acquiring the signer lock for preparation. Handles close before atomic publication; independent tasks sharing a signer and relay can write concurrently. Publication rechecks capacity and receipt state under the signer lock, without filesystem retry sleeps. The default task journal reuses its append handle and unchanged validated checkpoints; compaction and worker shutdown close the handle.
+
+POSIX delivery directories/files use 0700/0600; Windows inherits the parent DACL.
+Live sends remove completed batch ciphertext after consuming admission results.
+Maintenance closes expired pending batches before pruning message metadata, and
+removes remaining completed or closed batches.
+Content-free message records and receipt deduplication persist until seven days
+after `max(createdAt, original deliveryDeadline)`, without extending that horizon
+on reads or retries. Maintenance runs at startup and every minute while active;
+an inactive store may retain expired bytes until its next maintenance pass.
+Local bounds are 1,024 pending envelopes, 32 MiB of envelope JSON, 256 KiB per
+wire envelope and 10,000 retained messages/receipts per kind; a full or unwritable
+store reports a fixed error before an unrecorded send and does not evict live work.
+
+Embedders can inject `deliveryService` or `deliveryOptions` and explicitly call
+`startDelivery()`/`stopDelivery()`. A custom transport needs a stable relay URL and
+resolver for restart behavior; anonymous injected transports remain ephemeral.
+Initialization, tool listing and local reads do not start delivery or create keys.
+Direct transport `send()` remains a single attempt. No relay deployment is needed
+for this gateway behavior; existing relay retention still governs admitted frames.
+See [relay reliability](docs/relay-reliability.md).
+
+
+The three MCP send tools (`acp_delegate_task`, `acp_delegate_multi`,
+`acp_resubmit_pending_request`) accept optional `idempotencyKey`, an exact Unicode
+string of 1–200 UTF-8 bytes, e.g. `"idempotencyKey":"review-2026-11-02"`.
+The same signer/tool/key and content return the first stored result across restarts,
+without another send or approval; changed content returns `IDEMPOTENCY_CONFLICT`
+and requires a new key. Keys/results expire seven days after the original deadline
+(latest child deadline for multi). Cached holds never resubmit or increment attempts.
+Another server may return `IDEMPOTENCY_IN_PROGRESS`; interruption returns
+`APPROVAL_INTERRUPTED` or `IDEMPOTENCY_RESULT_UNAVAILABLE` without repeating a prompt
+or execution. Final verification stays separate, and calls without keys are unchanged.
+See [relay reliability](docs/relay-reliability.md) for retention, runtime hooks and recovery.
+No relay deployment is needed.
+
+### Recipient delivery status
+
+Recipient-signed `DeliveryStatus` for validated 0.2.0 tasks records content-free
+held/opened/adapter-handoff/closed observations separately from task sequences and
+bilateral audit. Unknown peers get only `received_held` and `closed`; later connection
+approval does not release that task's history. Inspection/display alone does not open
+a task, and successful result cleanup does not close it. Queued detail is suppressed
+on disconnect; blocking suppresses all queued status. Legacy peers without version
+declarations retain 0.1.0 behavior. Status records use the fixed delivery deadline plus
+seven days; active maintenance deletes expired bytes. A handoff does not prove reading
+or execution. Both gateways need support; no relay deployment is required.
+See [relay reliability](docs/relay-reliability.md) for status sources, retention and lifecycle behavior.
+
+### Local message status
+
+A send with `idempotencyKey` keeps its original message and task IDs on cached retries.
+This lookup reads the current retained observations for those IDs, independently of
+the cached send result.
+
+`acp_message_status {"messageId":"<original PROPOSE UUID>"}` or
+`acp_message_status {"taskId":"<original task ID>"}` reads sender-local status without
+sending, refreshing, polling or cleanup. Use exactly one selector; ambiguous task IDs
+require `messageId`. Records expire seven days after the original deadline (or creation
+time if later); absent, foreign and expired IDs return `found:false`. Initially unknown
+peers disclose only `received_held`/`closed`. Recipient claims are separate from bilateral
+audit; handoff does not prove reading or execution. This read is distinct from a cached
+delegation result and explicit pending resubmission. No relay deployment is required;
+richer observations require C4 peers. See [relay reliability](docs/relay-reliability.md).