zcode-acp-server 0.1.0 → 0.3.0

package/docs/REMOTE-CLIENTS.md

@@ -0,0 +1,260 @@
+# 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.
+- 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

@@ -5,6 +5,7 @@
 ### Backend fails to start
 
 **Symptom:**
+
 ```
 [zcode-acp] backend: started zcode app-server (pid=12345)
 [zcode-acp] backend: reader exited (stdout closed)
@@ -13,12 +14,14 @@
 **Troubleshooting steps:**
 
 1. Check the ZCode CLI version:
+
    ```bash
    zcode --version
    ```
    - Must be >= 0.14.8
 
 2. Check whether `zcode` is on PATH:
+
    ```bash
    which zcode
    ```
@@ -31,22 +34,60 @@
    - Confirm a `provider` is enabled
    - Confirm `models` are defined
 
+### Authentication / credential errors (401, provider auth failed)
+
+**Symptom:** turns fail with authentication errors (e.g. `401`, `provider auth failed`, `invalid api key`), or `~/.zcode/v2/config.json` is missing.
+
+**Why:** This bridge advertises agent-managed auth — it reads the GLM API key from `~/.zcode/v2/config.json` and forwards it to the ZCode subprocess. No editor-side API key or environment variable is involved. If the credentials file is absent, empty, or carries an expired/invalid key, every turn will fail at the first model call.
+
+**Troubleshooting steps:**
+
+1. Confirm the credentials file exists and has an enabled provider:
+
+   ```bash
+   cat ~/.zcode/v2/config.json
+   ```
+   - There must be a `provider` entry with `"enabled": true`
+   - Its `options.apiKey` must be present and non-empty
+
+2. If the file is missing or the key is stale, **install and log into the ZCode desktop app** — it writes a fresh `config.json` with a valid enabled provider. There is no manual API-key configuration in the editor.
+
+3. If you need to override the key/base URL without touching `config.json`, set `ZCODE_BASE_URL` and provide the key via the provider config (see `src/backend/credentials.ts` for the merge order).
+
 ### session/subscribe fails
 
 **Symptom:**
+
 ```
-session/subscribe failed (ZCode CLI 0.14.8+ required)
+session/subscribe failed: <backend error message> [(code <N>)]
 ```
 
+The error message carries the backend's real failure reason. It is **no longer**
+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.                                                                                                                                                                                           |
+| `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.                                                                                                                                                                                                        |
+
 **Troubleshooting steps:**
 
-1. Confirm ZCode CLI >= 0.14.8:
+1. **Read the error message** — the fragment identifies the cause (table above).
+
+2. If the message indicates `method not found`, confirm ZCode CLI >= 0.14.8:
+
    ```bash
    zcode --version
    ```
 
-2. If the version is correct but it still fails, check whether the zcode
+3. If the version is correct but it still fails, check whether the zcode
    app-server supports subscribe:
+
    ```bash
    cd /path/to/project
    zcode app-server --stdio
@@ -54,7 +95,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    { "id": 1, "method": "session/subscribe", "params": { "sessionId": "test", "deliveryKind": "desktop-continuous", "includeSnapshot": true, "afterSeq": 0 } }
    ```
 
-3. Check whether other zcode processes are running:
+4. Check whether other zcode processes are running:
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # caution: this kills all zcode processes
@@ -67,6 +108,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Confirm the client declares `terminal_output`:
+
    ```typescript
    // should be present in clientCapabilities:
    { "_meta": { "terminal_output": true } }
@@ -87,9 +129,11 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Check whether `EventStreamListener` subscribed successfully:
+
    ```
    [zcode-acp] backend: started zcode app-server (pid=12345)
    ```
+
    If this log is missing, the backend did not start.
 
 2. Check whether `session/event` pushes arrive:
@@ -106,6 +150,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Check whether zcode sent an interaction request:
+
    ```
    [zcode-acp]   -> interaction/requestPermission (zcode_id=100)
    ```
@@ -120,6 +165,43 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    - `⚠ elicitation/create failed: ...` → the client does not support it or the request failed
    - `⚠ request_permission failed: ...` → the fallback path failed
 
+### Turn fails with `model_request_failed` / network error
+
+**Symptom:** A turn ends with an error like `model_request_failed` / "Network
+connection failed for the provider request" / "Turn execution failed". Instead
+of stopping the session, the bridge retries transient failures automatically.
+
+**What happens:**
+
+When the ZCode backend emits `turn.failed` with a transient cause (provider
+network blip, rate limit, brief outage), the bridge retries the turn up to
+**5 times** (6 total attempts) with exponential backoff capped at 4s
+(1s / 2s / 4s / 4s / 4s). Each retry re-sends the prompt and surfaces a
+`[网络异常，正在重试 (n/5)…]` hint so the user knows the turn is being retried
+rather than hanging.
+
+Transient errors are identified by the nested `error.cause.code`
+(`model_request_failed`, `provider_not_configured`, `rate_limit`, `timeout`,
+`ECONNRESET`, etc.) or by network/connection/timeout keywords in
+`error.cause.message`. Non-transient failures (e.g. `prompt is running`) still
+surface as hard errors immediately.
+
+After retries are exhausted, the bridge **degrades gracefully**: it emits a
+user-visible `[请求失败：…。会话仍可用，请重新发送消息重试。]` message and returns
+`end_turn`, so the session stays usable — resend the message to try again.
+
+**Debugging:**
+
+```
+ZCODE_ACP_DEBUG=1
+```
+
+Look for `[retry] transient turn failed, re-sending (attempt N/6)` lines to
+confirm the retry path is active. If transient failures persist across all
+retries, the underlying provider/network issue needs investigation (see
+[Authentication / credential errors](#authentication--credential-errors-401-provider-auth-failed)
+and check the provider endpoint reachability).
+
 ### `/` completion menu is empty
 
 **Symptom:** Typing `/` shows no command completion.
@@ -147,6 +229,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    - backend reader death
 
 2. Manually inspect zombie processes:
+
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # cleanup
@@ -197,6 +280,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 
 2. If the lock is still stuck on an older bridge, the zcode subprocess must be
    killed manually:
+
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # caution: kills all zcode processes
@@ -224,6 +308,39 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    - 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.
+
 ## Log Debugging
 
 ### Enable verbose logging
@@ -239,13 +356,13 @@ export function log(msg: string): void {
 
 ### Common log patterns
 
-| Log | Meaning |
-|------|------|
-| `backend: started zcode app-server (pid=...)` | Backend started successfully |
-| `backend: reader exited (...)` | Backend reader exited (backend may have crashed) |
-| `session/new -> sess_xxx` | New session created successfully |
-| `[event] turn.started` | Turn started |
-| `[event] turn.completed (resultType=...)` | Turn completed |
-| `-> interaction/... (zcode_id=...)` | Interaction request received |
-| `<- replied to zcode (N request(s))` | Interaction request replied |
-| `⚠ ...` | Warning / error |
+| Log                                           | Meaning                                          |
+| --------------------------------------------- | ------------------------------------------------ |
+| `backend: started zcode app-server (pid=...)` | Backend started successfully                     |
+| `backend: reader exited (...)`                | Backend reader exited (backend may have crashed) |
+| `session/new -> sess_xxx`                     | New session created successfully                 |
+| `[event] turn.started`                        | Turn started                                     |
+| `[event] turn.completed (resultType=...)`     | Turn completed                                   |
+| `-> interaction/... (zcode_id=...)`           | Interaction request received                     |
+| `<- replied to zcode (N request(s))`          | Interaction request replied                      |
+| `⚠ ...`                                       | Warning / error                                  |

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.