feat: remote access for mobile clients via zcode-acp-hub

AGENTS.md

@@ -9,15 +9,15 @@ methods and streams events back as ACP `session/update` notifications.
 
 ## Commands
 
-| Task | Command |
-|------|---------|
-| Build | `pnpm build` |
-| Typecheck | `pnpm typecheck` |
-| Test (all) | `pnpm test` |
-| Test (single file) | `npx vitest run tests/<file>.test.ts` |
-| Lint | `pnpm lint` |
-| Format (changed files only) | `pnpm prettier --write <path>` |
-| Smoke test | `pnpm smoke` |
+| Task                        | Command                               |
+| --------------------------- | ------------------------------------- |
+| Build                       | `pnpm build`                          |
+| Typecheck                   | `pnpm typecheck`                      |
+| Test (all)                  | `pnpm test`                           |
+| Test (single file)          | `npx vitest run tests/<file>.test.ts` |
+| Lint                        | `pnpm lint`                           |
+| Format (changed files only) | `pnpm prettier --write <path>`        |
+| Smoke test                  | `pnpm smoke`                          |
 
 **Package manager**: pnpm. **Node**: >=22. **Module system**: ESM (`"type": "module"`).
 
@@ -35,6 +35,7 @@ src/
 ├── handlers/             ACP method handlers
 │   ├── session.ts        session/new, session/prompt (turn loop), load, resume
 │   ├── slash.ts          Slash-command interception (/compact, /mcp, etc.)
+│   ├── account.ts        account/usage_stats — plan quota for remote clients
 │   ├── extensions.ts     ZCode extensions (fork, rewind, compact, steer, …)
 │   ├── dispatch.ts       InternalEvent → ACP session/update dispatch
 │   ├── io.ts             Client notification helpers
@@ -51,8 +52,15 @@ src/
 │   ├── projection-differ.ts  Snapshot diff for turn-completion reconciliation
 │   └── tool-helpers.ts       Diff builder, location extractor
 ├── interaction/          Permission, ExitPlanMode, AskUserQuestion handling
+├── remote/               Remote access (opt-in via ZCODE_ACP_REMOTE=1)
+│   ├── broadcast.ts      ClientRegistry + broadcast proxy (notify fan-out, request first-wins)
+│   ├── config.ts         ENV parsing (gate, mandatory token, hub/bridge ports)
+│   ├── endpoint.ts       Loopback ACP endpoint + hub registration heartbeat
+│   └── hub-server.ts     zcode-acp-hub: auth, discovery, byte-level WS proxy, ?probe=1 liveness
 ├── quota/                GLM Coding Plan usage API client (/quota command)
-└── bin/quota.ts          Standalone zcode-quota CLI
+└── bin/
+    ├── hub.ts            Standalone zcode-acp-hub daemon entry
+    └── quota.ts          Standalone zcode-quota CLI
 ```
 
 **Key boundary**: `backend/` talks to the ZCode subprocess. `handlers/` talks to
@@ -85,6 +93,15 @@ ZCode protocol types into ACP notifications directly — always translate.
   `withPreemptLock`. Don't bypass it — two simultaneous turns corrupt the listener.
 - **AGENTS.md is workspace-scoped**: the global `~/.zcode/AGENTS.md` also exists;
   this file takes precedence for this repo.
+- **WS proxy frame type**: the SDK's WS server drops non-text frames, and
+  `ws.send(buffer)` defaults to a BINARY frame. The hub proxy must forward with
+  `{ binary: isBinary }` — losing the flag silently eats every proxied message.
+- **Broadcast loser promises settle late**: after first-response-wins, aborted
+  loser requests resolve/reject only when the peer answers the cancellation.
+  Every raced promise needs a no-op `.catch` or Node crashes on
+  unhandledRejection. See `src/remote/broadcast.ts`.
+- **Remote failures never touch stdio**: any remote-side failure (port, hub,
+  token) must warn and disable remote only — the editor link stays up.
 
 ## Docs to read before sensitive changes
 

CONTEXT.md

@@ -0,0 +1,61 @@
+# zcode-acp-server
+
+A bridge that connects the ZCode agent backend to ACP-compatible editors. The
+bridge process is the session authority; editors and remote clients attach to
+it.
+
+## Language
+
+**Bridge**:
+A running zcode-acp-server process owning one ZCode backend subprocess, the
+session registry, and the turn loops. One editor connection = one bridge.
+_Avoid_: server (ambiguous with the ACP agent role), hub
+
+**Primary Client**:
+The editor connection over stdio that spawned the bridge and owns its
+lifetime (Zed, JetBrains). When it disconnects, the bridge exits.
+_Avoid_: host, master client
+
+**Remote Client**:
+Any additional ACP client attached over the network to watch and drive the
+same sessions as the Primary Client.
+_Avoid_: secondary client, web client (the web UI is just one kind)
+
+**Session Authority**:
+The property that session state (id mappings, turn loops, pending
+interactions) lives inside the Bridge process, not in any client or external
+store.
+_Avoid_: session owner, session store
+
+**Broadcast**:
+Delivering every agent-originated notification to all attached clients
+(Primary + Remote), and delivering interaction requests to all of them with
+first-response-wins semantics.
+_Avoid_: fan-out (fine informally, but Broadcast is the canonical term)
+
+**Hub**:
+The machine-level singleton daemon that is the only public entry point for
+remote access. It does token auth, instance discovery, and byte-level
+WebSocket proxying — it holds no session state and understands no ACP.
+_Avoid_: gateway, broker
+
+**Instance**:
+One registered bridge as seen through the Hub. A remote connection binds to
+exactly one instance; instance switching means reconnecting.
+_Avoid_: agent, server, worker
+
+**Replay**:
+Delivering a session's stored history to an attaching client as session/update
+notifications. Serves both the initial attach and reconnect catch-up.
+_Avoid_: history sync, restore, backfill
+
+**Turn**:
+One span of session history from a user message up to (not including) the next
+user message. The alignment unit for replay cuts — a replay never starts
+mid-turn. Leading non-user messages belong to the first turn.
+_Avoid_: round, exchange, message (a turn contains many messages)
+
+**Cursor**:
+An opaque handle identifying the oldest replayed Turn, used to page further
+back into history. Valid only while the history it points into is unchanged.
+_Avoid_: token (collides with the auth token), offset, bookmark