zcode-acp-server 0.2.0 → 0.3.1

package/docs/REMOTE-CLIENTS.md

@@ -0,0 +1,264 @@
+# Remote Clients — Integration Guide
+
+How to attach any out-of-editor client — browser SPA, mobile app, CLI, desktop
+tool — to bridge sessions over the network. This document IS the contract:
+everything here is implemented by `zcode-acp-hub` and the bridge's remote
+endpoint; anything not written here is not part of the contract.
+
+ACP method semantics are defined by the [ACP spec](https://agentclientprotocol.com);
+this guide covers only the transport, discovery, and the multi-client behaviors
+on top of it. For how ACP methods map to the ZCode backend, see
+[PROTOCOL.md](PROTOCOL.md).
+
+## Topology
+
+```text
+remote client ──WS── tunnel ── hub (single entry, one mapped port)
+                                  │ byte-level proxy, no ACP semantics
+                                  ▼
+                    bridge ACP endpoint (loopback, never exposed)
+                                  │ same AgentApp as stdio
+ACP editor ────── stdio ──────────┘
+```
+
+- The hub is the **only** public entry. It does token auth, instance discovery,
+  and byte-level WebSocket proxying — no session state, no ACP semantics
+  (ADR-0002). The bridge endpoint is loopback-only; nothing dials it but the
+  hub.
+- One WS connection is bound to **one bridge instance** for its whole lifetime.
+  Switching instances means opening a new connection.
+- The bridge process lives and dies with the editor that spawned it (ADR-0001):
+  close the editor and every remote attachment drops. There is no standalone
+  server that outlives the editor.
+
+## Security model
+
+- One shared bearer token (`ZCODE_ACP_REMOTE_TOKEN`) guards both the discovery
+  API and the ACP WebSocket. Possession of the token equals **full control of
+  every agent session** — prompting, answering permissions, tool-driven file
+  writes. Treat it like a password: long, random, never committed.
+- The hub speaks plain HTTP/WS. TLS is expected from the tunnel in front
+  (Cloudflare Tunnel terminates it; with frp, terminate TLS in front or keep
+  the network trusted). The token on cleartext HTTP over an untrusted network
+  is a credential leak.
+- `/api/*` responses carry `Access-Control-Allow-Origin: *` — the token is the
+  security boundary; there is no origin restriction.
+
+## Discovery API
+
+| Endpoint             | Auth     | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `GET /api/health`    | none     | Liveness probe; `200` body `ok`.                             |
+| `GET /api/instances` | required | Registered bridge instances. Add `?probe=1` to verify first. |
+
+HTTP auth: `Authorization: Bearer <token>` or `?token=<token>`.
+
+`/api/instances` returns a JSON array (sorted by start time):
+
+```json
+[
+  {
+    "id": "72341",
+    "port": 8378,
+    "pid": 72341,
+    "startedAt": 1723800000000,
+    "workspace": "/Users/me/proj",
+    "sessions": [{ "sessionId": "5f0c…", "title": "Fix login bug", "updatedAt": 1723800012000 }]
+  }
+]
+```
+
+- `id` is the bridge process id — stable for that editor window's lifetime,
+  unique per window.
+- **On refresh, call `/api/instances?probe=1`**: the hub TCP-probes each
+  registered bridge's loopback port and prunes unreachable ones before
+  answering. A plain `GET` returns the heartbeat-based view, which can list a
+  hard-killed bridge for up to the 30s heartbeat TTL.
+- `sessions[].sessionId` is the ACP session id: pass it to `session/load`
+  after connecting. `title` is adopted from the backend for resumed sessions
+  and set after a fresh session's first turn — it can still be absent for a
+  session that has never completed a turn.
+- `sessions` only lists sessions with real interaction. Editors restart into a
+  stored placeholder and materialize an empty backend session — those stay
+  hidden and appear within one heartbeat (~10s) after their first prompt (or
+  a titled resume/load).
+- Poll every 3–5s. There is no push notification for registry changes yet.
+- Fields are **additive-only** across releases — ignore fields you don't know.
+
+Lifecycle timings: a bridge re-registers every 10s (the registration doubles as
+heartbeat); an instance disappears ~30s after its heartbeats stop; the hub
+exits after ~10 idle minutes with no instances and no proxies, and the next
+bridge re-spawns it on demand.
+
+## Connecting
+
+```text
+ws(s)://<hub-host>/acp?instance=<id>&token=<token>
+```
+
+- Native clients may send `Authorization: Bearer <token>` instead of the query
+  parameter; browsers cannot set WS headers, which is why `?token=` exists.
+  Prefer the header when you can — it keeps the token out of URLs and logs.
+- Handshake failures (bad token, unknown instance id) destroy the socket
+  before open. Treat any non-open outcome as "re-discover, then retry".
+- Framing: one JSON-RPC message per **text** frame. Binary frames are ignored.
+- The hub sends WebSocket pings every 30s on both legs (tunnels drop idle
+  links). Browser and native WS stacks answer pongs automatically — nothing to
+  implement, but don't disable pongs.
+
+## ACP session flow
+
+1. `initialize` — `protocolVersion` MUST be the **number** `1` (a string is
+   rejected). Nothing else may be sent before it.
+2. Attach or create:
+   - `session/load { sessionId, cwd, mcpServers }` with an id from discovery —
+     replays the conversation history (text + tool summaries) as
+     `session/update`s, so a freshly attached client can render the full
+     story. `cwd` and `mcpServers` (even `[]`) are required — the SDK's params
+     schema rejects the request without them.
+   - `session/new { cwd? }` — a new session on that bridge.
+   - `session/list` enumerates the bridge's known sessions.
+3. Drive: `session/prompt`, `session/cancel`, `session/set_config_option`
+   (model / mode / thought level), slash commands in the prompt text —
+   see [PROTOCOL.md](PROTOCOL.md).
+
+## Account quota (`account/usage_stats`)
+
+Non-standard, additive (Proposal 0002). Plan quota is **account-level**, so it
+is a pull-only request — callable any time after `initialize`, no session
+required. Fetch once after attach and on demand; quota changes are slow, there
+is no push.
+
+The response mirrors the `zcode-quota` CLI card's data model — one GLM section
+plus one Opencode Go section — so clients can reproduce the CLI layout
+exactly:
+
+```json
+→ { "id": 7, "method": "account/usage_stats", "params": {} }
+← { "id": 7, "result": {
+      "glm": {
+        "kind": "success",
+        "level": "pro",
+        "items": [
+          { "key": "token_5h", "label": "5h", "usedPercent": 35,
+            "nextResetTime": 1723812000000 },
+          { "key": "mcp", "label": "MCP", "usedPercent": 10, "usedCount": 3,
+            "totalCount": 30, "nextResetTime": 1723812000000,
+            "detail": [{ "modelCode": "search-prime", "usage": 2 }] }
+        ]
+      },
+      "opencode": {
+        "kind": "success",
+        "windows": [
+          { "key": "rolling", "label": "5h", "usagePercent": 5,
+            "resetsAt": 1723812000000 },
+          { "key": "weekly", "label": "Week", "usagePercent": 25,
+            "resetsAt": 1724071200000 }
+        ]
+      }
+    } }
+```
+
+- `glm` (`kind`: `success` | `auth_error` | `rate_limited` | `unavailable`):
+  on success, `level` is the plan level and `items` carries one entry per
+  window (`5h` / `Week` / `MCP`) with `usedPercent` (0–100) always present;
+  `usedCount`/`totalCount`/`nextResetTime` (epoch ms) and the per-model
+  `detail` breakdown only when the API reports them.
+- `opencode` (`kind`: `success` | `not_configured` | `auth_error` |
+  `unavailable`): on success, `windows` carries the rolling (`5h`) / weekly
+  (`Week`) / monthly (`Month`, when exposed) windows; the dashboard's relative
+  countdown is resolved to an absolute `resetsAt` (epoch ms). `not_configured`
+  means the user never set OpenCode Go credentials — omit the section, like
+  the CLI does.
+- Provider failures are per-section `kind` strings, not JSON-RPC errors —
+  render the same status line the CLI would (e.g. auth expired) and retry
+  later. Only transport-level failures reject the request.
+- Cached ~10s server-side (same caches as the `/quota` command).
+
+## Slash-command handling
+
+Only the commands the bridge advertises via `available_commands_update` (plus
+`skill`/`init` and `$`-skills) are treated as commands. Any other `/`-leading
+prompt — e.g. a pasted directory path — is delivered to the model as plain
+text with an invisible zero-width-space prefix; clients see the text verbatim
+in replay and echoes. Clients should not special-case this.
+
+## Tail replay and history pagination
+
+Replaying a long session's full history is O(history) on every attach and
+reconnect. The bridge supports tail replay (non-standard, additive — omit
+everything below and you get the full replay):
+
+- **Tail limit**: `session/load` with `_meta.zcode.limit` (NOT top-level —
+  the SDK's params schema strips unknown top-level keys; `_meta` is the
+  preserved extension channel). It counts **messages**, and the replay is
+  aligned back to the start of the turn containing the oldest message — never
+  a mid-turn cut. `0` attaches with metadata only. Clamped to `[0, 500]`.
+- **`replayMeta`** rides top-level in the result:
+
+  ```json
+  {
+    "replayMeta": {
+      "cursor": "…",
+      "hasMore": true,
+      "replayedMessages": 47,
+      "replayedTurns": 12,
+      "totalMessages": 1893,
+      "totalTurns": 412
+    }
+  }
+  ```
+
+- **`session/load_earlier`** (`{ sessionId, before, limit }`, limit defaults
+  to 50) delivers one page of `session/update`s strictly older than `before`,
+  oldest → newest — prepend them. Same `replayMeta` shape in the result;
+  `hasMore: false` ends pagination. Requires the session to be attached in
+  this bridge; it never triggers an implicit backend resume.
+- **Cursor expiry**: a cursor is valid only while the history it points into
+  is unchanged — turns appended after it was minted (the session moved on)
+  keep it valid. After the session compacts or truncates, `load_earlier`
+  returns a `"cursor expired"` error — the recovery is a fresh `session/load`.
+
+While a replay batch is in flight, live updates for the same session queue
+behind it: batches are atomic and never interleave with the live turn.
+
+UI-side recipes for consuming all of this — state model, prepend handling,
+scroll pagination, reconnect recovery — live in
+[REPLAY-GUIDE.md](REPLAY-GUIDE.md).
+
+## Multi-client semantics
+
+The stdio editor and every remote client are peers on the same sessions:
+
+- All agent notifications (`session/update`) are broadcast to every client.
+- Permission and elicitation requests go to **every** client and the **first
+  response wins**. Losers receive `$/cancel_request` for the pending request
+  id — close the dialog and drop it. Never leave a request unanswered forever.
+- Capabilities are OR-merged across clients: a remote client advertising e.g.
+  `elicitation.form` upgrades the shared interaction for the whole bridge.
+- Concurrent prompts for one session are serialized by the bridge — two
+  clients prompting at once cannot interleave turns.
+
+## Failure & recovery
+
+| Symptom                                | Cause                                                                                                                                                                                                                                                                    | Client action                                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| WS closes                              | bridge exited (editor closed) or network drop                                                                                                                                                                                                                            | Poll `/api/instances`; if the instance is gone, its sessions are gone too — drop it from the UI.    |
+| Instance missing from `/api/instances` | Heartbeats stopped >30s, or `?probe=1` found the bridge port unreachable                                                                                                                                                                                                 | Remove the instance from the UI.                                                                    |
+| Connect fails for a while              | Hub process died; a bridge re-spawns it on the next heartbeat (typically ≤10s, worst case ~1min under the spawn throttle). Also expected for a few seconds after a bridge upgrade: the hub notices a newer bridge, restarts, and is re-spawned from the upgraded install | Retry with backoff.                                                                                 |
+| Disconnect mid-turn                    | Mobile network flap, background suspension                                                                                                                                                                                                                               | The turn continues server-side. Reconnect and `session/load` — history replay is the recovery path. |
+
+Updates emitted while you are disconnected are not individually re-delivered;
+`session/load` replay is the catch-up mechanism.
+
+## Platform notes
+
+- **Browser**: a page served over `https://` can only open `wss://` — take TLS
+  from the tunnel. CORS is `*`, so any static host works; the client needs no
+  backend of its own.
+- **Mobile**: background suspension kills the socket; on resume, reconnect and
+  `session/load` the previously open session. Store hub URL + token locally;
+  reconnect with exponential backoff. The 30s hub pings keep NAT mappings warm
+  while foregrounded.
+- **CLI / native tools**: prefer the `Authorization` header; a one-shot
+  `session/prompt` + update stream is a perfectly fine first client.

package/docs/REPLAY-GUIDE.md

@@ -0,0 +1,131 @@
+# Replay guide — building a client UI on tail replay
+
+Audience: frontend implementors (web, mobile, CLI TUI) of any ACP client for
+this bridge. The **wire contract** (field names, errors, framing) lives in
+[REMOTE-CLIENTS.md](REMOTE-CLIENTS.md) — this guide does not repeat it; it
+shows how to _consume_ it: the UI state model, scroll-up pagination, and
+reconnect recovery.
+
+## What changed and why you care
+
+Before tail replay, every `session/load` (initial attach AND every reconnect)
+replayed the **entire** history as `session/update` notifications. A measured
+280-message session cost ~800 notifications; sessions only grow. With tail
+replay the same attach ships only the visible tail and older history arrives
+on demand. Live numbers from the reference e2e run (471-message / 82-turn
+session, `limit: 30`):
+
+- `session/load` replayed 36 messages (30 requested, aligned to a turn start)
+  as 118 notifications, and returned `replayMeta` — projected full replay for
+  that session is ~1350 notifications (~91% cut).
+- A follow-up `session/load_earlier` page delivered 30 more messages / 10
+  turns as 51 notifications.
+
+Everything is additive: omit `_meta.zcode.limit` and you get the old
+full-replay behavior unchanged.
+
+One more replay-only behavior: harness-injected `<system-reminder>` blocks
+(TodoWrite nudges, context handoffs) that the runtime appends to user turns
+are stripped before replay, and user messages that contained nothing else are
+dropped entirely. You never receive them as `user_message_chunk`, so there is
+nothing to filter client-side — the user's transcript shows only what they
+actually typed.
+
+## Attach strategy
+
+Pick the limit from your UI budget, not from the history size:
+
+- `limit: 0` — metadata-only attach. You get `replayMeta`
+  (`totalMessages`, `totalTurns`, `hasMore: true`, cursor at the end of
+  history) and zero replayed messages. Render an empty/"load older" state.
+- `limit: N` — replay at most the last N **messages**, aligned back to the
+  start of the turn containing the oldest one. Expect
+  `replayedMessages ≥ N` when alignment extends the batch (the e2e run asked
+  for 30 and got 36). Never a mid-turn cut: a tool call always arrives with
+  its updates.
+- No `_meta` — full replay (legacy/Zed path).
+
+The response always carries `replayMeta`. `hasMore: false` means the whole
+history is already in front of you — hide the "load older" affordance.
+
+## UI state model
+
+Three id kinds arrive in `session/update` notifications; each kind merges
+differently:
+
+| Update kind                                  | Id field     | Merge rule                                                              |
+| -------------------------------------------- | ------------ | ----------------------------------------------------------------------- |
+| `user_message_chunk` / `agent_message_chunk` | `messageId`  | append text to that message's bubble                                    |
+| `agent_thought_chunk`                        | `messageId`  | append; ids carry a `thought_` prefix, so thoughts are their own stream |
+| `tool_call` / `tool_call_update`             | `toolCallId` | first `tool_call` creates the card, later updates mutate it             |
+
+- `messageId`s are the backend's stable message ids (the e2e run saw zero
+  fallback ids across hundreds of messages) — key your message list by them
+  and dedupe on every insert.
+- One message = several chunks (text, thoughts, tool calls). Group chunks by
+  `messageId`/`toolCallId`, not by arrival order alone.
+- Ordering rule: replay batches and `load_earlier` pages arrive **oldest →
+  newest and must be prepended**; live-turn updates arrive newest-last and
+  append. The bridge serializes a replay batch against the live turn for the
+  same session (they never interleave), so you can apply live updates while a
+  pagination page is in flight without ordering races.
+- `usage_update` / `available_commands_update` are session-level metadata,
+  not list items.
+
+## Scroll-up pagination
+
+```
+state: cursor = attachResult.replayMeta.cursor
+       hasMore = attachResult.replayMeta.hasMore
+
+onScrolledNearTop():
+  if !hasMore or requestInFlight: return
+  res = request("session/load_earlier", { sessionId, before: cursor, limit: 50 })
+  prependUpdates(res.deliveredSessionUpdates)   // keep the user's scroll anchor
+  cursor  = res.replayMeta.cursor
+  hasMore = res.replayMeta.hasMore
+```
+
+- `limit` defaults to 50; clamp is `[0, 500]`.
+- `hasMore: false` ends the loop. A redundant extra call is harmless: it
+  returns an empty page with `hasMore: false`.
+- Keep a scroll anchor when prepending, or every page will yank the viewport
+  to the top.
+
+## Cursor expiry — the one error to handle
+
+A cursor dies only when the history **shrank** (compaction, truncation):
+`session/load_earlier` then fails with `-32602 "cursor expired"`. Turns
+**appended** after the cursor was minted (the conversation moved on) keep it
+valid — you do NOT need to refresh the cursor after every live turn.
+
+Recovery for `"cursor expired"`: re-run `session/load` with your tail limit
+and rebuild the visible list from its `replayMeta`; deeper history comes back
+through normal pagination. Treat it as a rare event, not a flow.
+
+Never parse the cursor — it is opaque. (For the curious it round-trips
+`{ v, index, totalTurns, id? }`, but the shape may change without notice.)
+
+## Reconnect recipe
+
+1. Re-discover the instance (`/api/instances`) — the bridge pid changes on
+   editor restart. Then `initialize` (`protocolVersion`: the number `1`),
+   then `session/load { sessionId, cwd, mcpServers: [] }` — `cwd` and
+   `mcpServers` are required even when empty.
+2. Attach with `limit` = your viewport budget, not what the user had scrolled
+   to. Diff against your cached messages by `messageId` (ids are stable
+   across restarts of both bridge and backend).
+3. Live updates fill the tail from here. If the user scrolls into history you
+   no longer have, `load_earlier` from the new cursor refetches just those
+   pages — do not try to restore the full old scroll depth on reconnect.
+
+## Checklist
+
+- [ ] `limit` rides in `_meta.zcode.limit` (top-level unknown keys are
+      stripped by the SDK schema — silently).
+- [ ] `session/load` params include `cwd` and `mcpServers` (even `[]`).
+- [ ] Message list keyed/deduped by `messageId`; tool cards by `toolCallId`.
+- [ ] Pagination pages prepended, live updates appended.
+- [ ] `"cursor expired"` handled by full re-attach.
+- [ ] Cursor stored per session, never parsed, never persisted across app
+      runs (it is only meaningful to the bridge that minted it).

package/docs/TROUBLESHOOTING.md

@@ -67,13 +67,13 @@ a hardcoded version string — read the message text to identify the root cause.
 
 **Common causes:**
 
-| Message fragment                 | Cause                                                                      |
-| -------------------------------- | -------------------------------------------------------------------------- |
-| `reader exited (backend dead)`   | The zcode subprocess crashed/exited. Restart the editor session.           |
+| Message fragment                 | Cause                                                                                                                                                                                                                                                      |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reader exited (backend dead)`   | The zcode subprocess crashed/exited. Restart the editor session.                                                                                                                                                                                           |
 | `timeout`                        | The per-attempt 10s subscribe deadline elapsed. The bridge retries transient timeouts up to 3× (the backend can be briefly busy finalising a cancelled turn after a preempt / `session/stop`); if all retries fail, the backend was unresponsive for ~30s. |
-| `pipe broken`                    | The stdin pipe to the zcode subprocess broke (process died mid-write).     |
-| `method not found (code -32601)` | The CLI genuinely is too old (< 0.14.8). Upgrade.                          |
-| session-level business error     | The target session no longer exists or was evicted.                        |
+| `pipe broken`                    | The stdin pipe to the zcode subprocess broke (process died mid-write).                                                                                                                                                                                     |
+| `method not found (code -32601)` | The CLI genuinely is too old (< 0.14.8). Upgrade.                                                                                                                                                                                                          |
+| session-level business error     | The target session no longer exists or was evicted.                                                                                                                                                                                                        |
 
 **Troubleshooting steps:**
 
@@ -308,6 +308,51 @@ and check the provider endpoint reachability).
    - Table name: `tasks`
    - Fields: workspace_key, task_id, title, task_status, ...
 
+### Remote access: hub unreachable / 401
+
+**Symptom:** A remote client cannot list instances or connect; `curl
+http://127.0.0.1:<hub-port>/api/health` fails, or `/api/*` returns 401.
+
+**Troubleshooting steps:**
+
+1. 401 means a token mismatch — `ZCODE_ACP_REMOTE_TOKEN` must be identical in
+   the bridge env, the hub env (if run manually), and the client request.
+2. A dead hub self-heals: the next bridge heartbeat (≤10s; worst ~1min under
+   the spawn throttle) re-spawns `zcode-acp-hub`. Retry with backoff rather
+   than restarting anything by hand.
+3. Confirm the ports match: the client must reach `ZCODE_ACP_HUB_PORT`
+   (default 8377) through the tunnel, and the tunnel maps exactly that one
+   port.
+4. Remote silently disabled? `ZCODE_ACP_REMOTE=1` without a token logs a
+   warning and leaves the bridge stdio-only by design.
+
+### Remote access: stale instance in the list / connect fails
+
+**Symptom:** `/api/instances` lists a workspace whose editor is already gone,
+or a WS connect to it fails.
+
+**Troubleshooting steps:**
+
+1. Hard-killed bridges (Zed force-kill, crash) never unregister — the hub's
+   heartbeat TTL drops them within ~30s.
+2. For an immediately-honest list, call `GET /api/instances?probe=1`: the hub
+   TCP-probes each registered port and prunes unreachable bridges first.
+   Clients should use this on refresh.
+3. A few-seconds outage after upgrading the package is expected: a newer
+   bridge triggers the hub's version-handshake restart, then re-spawns it.
+
+### Remote access: a conversation opens empty
+
+**Symptom:** one session (typically an older one) opens EMPTY on a remote
+client while other sessions show content.
+
+**Cause:** the backend subprocess only serves `session/messages` for sessions
+it has loaded via `session/create`/`session/resume`. Older bridges trusted the
+in-memory id mapping as "live" and skipped the resume RPC — a mapping
+re-registered from the durable store without a resume (or left behind by a
+failed one) therefore replayed nothing. Fixed by explicit backend-loaded
+tracking; the backend also logs a warning now when `session/messages` errors.
+
 ## Log Debugging
 
 ### Enable verbose logging

package/docs/adr/0001-bridge-lifetime-follows-primary-client.md

@@ -0,0 +1,14 @@
+# Bridge lifetime follows the Primary Client
+
+When remote access is enabled, remote clients attach to a bridge that the
+Primary Client (the editor over stdio) spawned. We decided the bridge process
+lives and dies with its Primary Client: when the editor disconnects, the
+bridge (and every remote attachment) exits, even if remote clients are
+mid-turn.
+
+Rationale: session authority lives inside the bridge process. Keeping a
+bridge alive after the editor leaves means the editor's reconnect spawns a
+second bridge with its own backend subprocess, and both compete for the same
+ZCode session files. Tying lifetime to the Primary Client matches the
+existing mental model — the editor owns the session, remote clients are a
+live window onto it.

package/docs/adr/0002-stateless-hub-over-per-bridge-acp-endpoints.md

@@ -0,0 +1,23 @@
+# Remote access: stateless hub over per-bridge ACP endpoints
+
+Remote clients must reach any active bridge through a single tunneled port
+(Cloudflare Tunnel / frp); exposing one port per bridge does not survive that
+constraint. We decided each bridge serves its own ACP endpoint on loopback
+only (auto-incrementing ports from 8378), and a machine-singleton hub
+(`zcode-acp-hub`, fixed port 8377, auto-spawned detached by bridges, idle-exits
+after ~10 minutes without registrations) does exactly three things: token
+authentication, instance discovery, and byte-level WebSocket proxying
+(`WS /acp?instance=<id>` → the chosen bridge).
+
+The hub has no ACP semantics and no business state; session authority stays
+in the bridges. A remote connection binds to one instance for its whole
+lifetime; switching instances means opening a new connection. We rejected a
+globally-routing gateway that aggregates sessions across bridges and speaks
+ACP itself — it would re-create session management outside the bridges, which
+is the "fat hub" design this project deliberately avoids.
+
+The hub is the only public entry point, so it is the only place that enforces
+the token; the tunnel maps exactly this one port. WebSocket ping/pong
+heartbeat (~30s) is mandatory on both hub and proxy connections because ACP
+streams are silent when idle and proxy layers (notably Cloudflare) drop idle
+connections.

package/docs/adr/0003-tail-replay-meta-and-cursor-pagination.md

@@ -0,0 +1,40 @@
+# Tail replay: extension params ride in _meta, history pages by cursor
+
+`session/load` replays full history to attaching clients, so attach and
+reconnect cost grow with session age (Proposal 0001). Extending the protocol
+for tail replay required three decisions that are now wire contract and hard
+to reverse.
+
+**Extension parameters on spec methods ride in `_meta.zcode`, not top-level.**
+The ACP SDK registers spec methods like `session/load` with a zod
+`z.object` params schema (`zLoadSessionRequest`), and zod's default behavior
+strips unknown keys during `.parse()` — a top-level `limit` would be silently
+removed before our handler ever sees it. `_meta` is the one channel the schema
+preserves (`record(string, unknown)`), and it is also where the ACP spec
+points extension payloads. Responses need no escape hatch: the SDK's response
+mapping for `session/load` is a passthrough, so `replayMeta` rides top-level
+in the result. Our own non-standard method `session/load_earlier` takes a
+bridge-provided parser, so its params stay top-level — the asymmetry is
+intentional and documented in REMOTE-CLIENTS.md.
+
+**`limit` counts messages, aligned back to turn boundaries.** Clients render
+messages (the app shows the last ~30), but turns are the atomic semantic unit
+(a cut must not orphan a tool_call from its updates). The bridge replays at
+most the last `limit` messages, extended backwards to the start of the turn
+containing the oldest one; `limit: 0` attaches with metadata only. A turn
+spans from a user message to the next; leading non-user messages belong to the
+first turn. We rejected turn-count limits — tool-heavy turns make them
+unpredictable for UI budgets.
+
+**Cursor pagination over a full fetch, with expiry.** The backend's
+`session/messages` has no pagination, but the fetch is local stdio IPC — the
+expensive part is the wire to the client, so the bridge fetches all, slices in
+memory, and ships only the tail. The cursor is an opaque base64 of
+`{ id?, index, totalTurns }`: it validates only while the history it points
+into is unchanged (compaction/truncation expires it). An expired or unknown
+cursor returns a fixed `"cursor expired"` error the client maps to a full
+re-`session/load` — we rejected a push-only update log with id-gap fill as
+heavier machinery for the same result. During any replay batch the bridge
+holds a per-session replay lock (patterned on `preemptLocks`) that live-turn
+dispatch for the same session also acquires, so a batch is never interleaved
+with live updates.