zcode-acp-server 0.18.0 → 0.18.2

package/README.md

@@ -124,355 +124,29 @@ most setups need no `ZCODE_BIN` at all — set it only for custom installs:
 
 ## Sandbox
 
-Two switches arm the sandbox (macOS only), whichever comes first:
-
-- globally: `ZCODE_ACP_SANDBOX=1`, or
-- per project: `"enabled": true` in `<workspace>/.zcode/acp/sandbox.json`.
-  The bridge auto-creates that file with `"enabled": false` the first time
-  you open the workspace — flip the flag to opt this project in, no global
-  env needed. Flipping it mid-run takes effect on the next prompt (the
-  backend restarts sandboxed); flipping back takes effect the next time the
-  backend restarts on its own.
-
-Once armed, the zcode backend subprocess — and every Bash/Edit/Write it
-performs, including all child processes — runs wrapped in a
-Seatbelt (`sandbox-exec`) profile that denies file writes everywhere except:
-
-- the workspace root(s) of your live sessions,
-- `~/.zcode*` (the backend's own sessions/db/logs),
-- the system temp directory and regenerable tool caches (`~/Library/Caches`,
-  `~/.cache`, `~/.npm`, `~/Library/pnpm`, `~/.node-gyp`),
-- paths granted via the per-project config or the allow popup.
-
-Reads and process execution stay open: deletion (`rm`, `mv`, truncation) is a
-write-class syscall, so the write denial stops it regardless of which binary
-performs it — including `/bin/rm`, `python shutil.rmtree`, or shell
-redirections.
-
-When a write outside the whitelist is attempted, the tool fails with
-`Operation not permitted` and the bridge asks via the editor's permission
-popup with four choices: allow **once**, allow **always**, reject **once**,
-reject **always**. The "always" choices are persisted by the bridge into
-`<workspace>/.zcode/acp/sandbox.json` (created on first run — allows to the
-`allow` list, rejections to a `deny` list that suppresses future asks; edit
-the file to undo either). "Once" choices and dismissed popups persist
-nothing and will ask again. The agent itself cannot edit
-that file — the sandbox denies
-writes to `.zcode/acp/` inside the workspace while the bridge (outside the
-sandbox) writes it on your behalf. After an allow, the backend restarts with
-the widened profile (a few seconds; the bridge auto-continues the interrupted
-task). Set `"strictGit": true` in the config to also put `.git` behind the
-popup.
-
-This targets accident prevention, not malice: indirect escapes (an
-agent-edited `.bashrc`, build scripts, or git hooks that you later run
-yourself outside the sandbox) are out of scope — treat its output like any
-other code review. Verify a profile manually with
-`bash scripts/verify-sandbox.sh` (macOS, after `pnpm build`).
+Optional macOS Seatbelt confinement for everything the agent writes: dual
+switch (`ZCODE_ACP_SANDBOX=1` globally, or `"enabled": true` in the
+auto-created `<workspace>/.zcode/acp/sandbox.json` per project), allow/reject
+popups for out-of-whitelist writes persisted visibly in that config, and
+automatic backend restart + task continuation after an allow. Full manual:
+[docs/SANDBOX.md](docs/SANDBOX.md).
 
 ## Remote Access
 
-With `ZCODE_ACP_REMOTE=1` the bridge additionally accepts ACP connections over
-WebSocket, so a phone or browser can watch and drive the **same sessions** as
-your editor. Zed (or any ACP editor over stdio) remains the primary client and
-owns the process: when the editor disconnects, the bridge — and every remote
-attachment — exits with it.
-
-A ready-made client — Android APK plus a self-hostable web build — lives at
-[william0wang/zcode-acp-remote](https://github.com/william0wang/zcode-acp-remote).
-
-```text
-phone / browser ──WS── tunnel ── hub (127.0.0.1:8377, single entry)
-                                   │ byte-level proxy
-                                   ▼
-                     bridge ACP endpoint (127.0.0.1:8378+n)
-                                   │ same AgentApp as stdio
-Zed ──────── stdio ────────────────┘
-```
-
-Enable it per-agent in Zed's settings (Zed merges these into the agent's
-environment):
-
-```json
-"agents": {
-  "ZCode": {
-    "command": "zcode-acp-server",
-    "env": {
-      "ZCODE_ACP_REMOTE": "1",
-      "ZCODE_ACP_REMOTE_TOKEN": "<a-long-random-secret>"
-    }
-  }
-}
-```
-
-**Hub.** The first bridge with remote enabled spawns the hub daemon as a
-detached, machine-level singleton on `ZCODE_ACP_HUB_PORT` (it can also be run
-manually). It does three things only: token auth, instance discovery, and
-byte-level proxying (ACP WebSocket plus read-only session files) — no session
-state, no path semantics. It exits after ~10 idle minutes and is re-spawned
-on demand. Each bridge registers every 10s as a heartbeat and drops out of
-discovery ~30s after it stops.
-
-**Discovery API** (for client authors; fields are additive-only):
-
-```text
-GET /api/instances              → [{"id","port","pid","startedAt","workspace",
-                                    "origin","sessions":[{"sessionId","title?","updatedAt"}]}]
-GET /api/instances?probe=1      → same list, but unreachable bridges are pruned first
-WS   /acp?instance=<id>         → proxied to that bridge's endpoint
-GET /api/instances/{id}/fs/…    → read-only session files (list + raw bytes, ADR-0004)
-```
-
-`origin` labels how an instance was started: `"editor"` (a bridge an editor
-spawned over stdio) or `"serve"` (a headless bridge created remotely, see
-below).
-
-**Remote session-create** (ADR-0014). A remote client can start a NEW agent
-session in any of the machine's known projects — no editor required:
-
-```text
-GET  /api/projects              → [{"workspacePath","sessions","lastActive"}]
-POST /api/instances {workspacePath} → {"id","reused"}
-```
-
-`/api/projects` aggregates the App's tasks index: every workspace that ever
-ran a session (system temp trees, `~/.zcode` itself, and vanished
-directories filtered out), newest activity first. The list gates the POST —
-paths outside it get 403 (a convenience bound, not a security boundary: a
-token holder can already drive an editor-bridge session in any cwd; the
-trust boundary is the token). On create the hub
-spawns `zcode-acp serve` — a headless bridge — in the project's cwd; it
-registers back within seconds and is reachable like any other instance. A
-live serve instance for the same workspace is reused instead of re-spawned
-(`reused:true`). The serve bridge lives for remote interest only: it exits
-~10 minutes after the last client detaches and the last turn finishes, and
-its `session/new` always uses the project cwd regardless of what a client
-sends.
-
-`sessions` lists the project's **currently running** conversations (live
-editor tabs and remote attachments) under the same ACP session ids the
-editor uses — attaching by id joins the conversation's live notification
-stream, and the hub dedupes sessions shared by several bridges of the same
-project.
-
-Auth is `Authorization: Bearer <token>` or `?token=` (browsers cannot set WS
-headers); `/api/*` sends `Access-Control-Allow-Origin: *` — the token is the
-security boundary. A proxied connection stays bound to one instance; switching
-instances means reconnecting. Remote clients can also pull plan quota via the
-non-standard `account/usage_stats` ACP method (no session required), and
-browse/download the files of a session's project through the `/fs` routes
-above. During replay, compaction summaries and rewritten tool calls arrive as
-collapsed `tool_call` updates instead of walls of text
-(`docs/REPLAY-GUIDE.md`).
-
-Building a remote client — web, mobile, or CLI? The full integration contract
-(endpoints, framing, lifecycle timings, failure recovery, platform notes)
-lives in [docs/REMOTE-CLIENTS.md](docs/REMOTE-CLIENTS.md).
-
-**Semantics.** All agent notifications are broadcast to every client.
-Permission / elicitation requests go to every client and the **first answer
-wins**; losing clients receive `$/cancel_request` so their dialogs close.
-Concurrent prompts for one session are serialized exactly as they are for a
-single editor. Capabilities declared by any client are OR-merged.
-
-**Tunnels.** Designed for one-port tunnels (Cloudflare Tunnel, frp): map the
-hub port only. frp's `tcp` mode passes WebSocket as-is; Cloudflare Tunnel
-drops idle WebSocket connections, so the hub sends 30s keepalive pings on both
-legs. The bridge endpoint itself is loopback-only and never exposed.
-
-**Binding beyond loopback.** The hub speaks plain HTTP/WS — the token travels
-and authorizes in cleartext, so `ZCODE_ACP_HUB_HOST=0.0.0.0` (needed only when
-the tunnel agent runs in its own container) is exactly as safe as the network
-it lands on. Keep the bind loopback unless that interface is private to the
-tunnel agent, and put TLS in front before mapping it anywhere untrusted.
+With `ZCODE_ACP_REMOTE=1` the bridge additionally serves the **same sessions**
+over WebSocket through a machine-level hub daemon — a phone or browser can
+watch, drive, and even create sessions in any known project while Zed stays
+the primary client. Discovery API, tunnels, auth, and semantics:
+[docs/REMOTE.md](docs/REMOTE.md); the client integration contract:
+[docs/REMOTE-CLIENTS.md](docs/REMOTE-CLIENTS.md).
 
 ## Unified CLI (`zcode-acp`)
 
-Every surface of this package is available under one command — `zcode-acp` —
-installed alongside the `zcode-acp-server` bin your editor configures.
-
-### Interactive REPL
-
-Bare `zcode-acp` opens an interactive terminal chat against this same bridge
-(built with [Ink](https://github.com/vadimdemedes/ink), the same renderer
-Claude Code and Gemini CLI use). Completed messages print once into the
-terminal's **native scrollback** — smooth wheel scrolling, text selection,
-search, and history that survives exit are all just your terminal, unchanged.
-Only a compact dynamic footer ever repaints: the live-turn tail (capped at
-half the screen), queued-prompt panel, completion menu, and the prompt box.
-
-```bash
-zcode-acp            # chat in this directory
-```
-
-A startup welcome panel (version, session directory, seeded config, key
-hints) lands in scrollback first. Streaming output has code-fence coloring,
-dim thinking lines, and live tool rows. The prompt line wraps across rows
-with a CJK-aware block cursor — `←`/`→` (or Ctrl-B/Ctrl-F) move inside the
-typed text, Backspace/Delete edit at the caret, Ctrl-A/Ctrl-E jump to the
-line's ends, Ctrl-U clears the line; completion keeps precedence while its
-menu is open. The status row carries a compact plan-quota readout
-(`5h 16% · wk 4%`) refreshed every 10 minutes — `/quota` prints the full
-card. Pasted or dragged-in content (error logs, file drops) is sanitized and
-size-capped before it reaches the editor, so long pastes batch cleanly.
-`esc` interrupts a running turn (immediately — the bridge resolves the prompt
-as cancelled without waiting for the backend); `Ctrl-C` also interrupts, and
-while idle press it twice to quit. `/exit` leaves; the session itself persists
-in the ZCode backend and is available to your editor.
-
-Sending a follow-up right after an interrupt waits for the backend to finish
-the cancelled generation first — a `[上一个回复仍在生成，等待结束后发送…]`
-note explains the pause (the Aug-28 app-server accepts mid-generation sends
-as steer input but drops them when the old turn ends; the bridge polls until
-the session is idle, up to 90s, so the message actually runs).
-
-Messages typed while a turn is running (or the session is still starting) are
-queued, not lost: each shows up in the transcript immediately and a `⏸ queued`
-panel above the prompt box lists everything waiting to run. When the current
-turn ends the queue drains one prompt at a time — through the same command
-parsing as direct submits, so queued `/help` and `/exit` still work.
-
-`/sessions` lists this project's previous conversations in an 8-row sliding
-window (position counter, plus "N newer above / N older below" hints); arrow
-keys move over the full list even though only part of it renders. Resuming
-loads the most recent tail of the conversation (last 50 messages, turn-aligned)
-instead of dumping thousands of lines at once — when older history exists the
-note says exactly what was loaded:
-`resumed "<title>" — showing last 50 of 1234 messages`.
-
-The full-width prompt box mirrors the editor's dropdowns: its bottom row shows
-the current `model · mode · thought level`, and typing `/` opens an interactive
-completion menu — `↑`/`↓` move, `enter` picks the highlighted entry (or `tab` /
-`→`; typing the exact form already sends), `esc` dismisses. After picking
-`/model`, `/mode`, or `/thought` the same menu lists the config options (the
-current one marked `●`) and **enter on a row switches immediately** — no second
-confirmation. Argument-free commands (`/exit`, `/help`, `/sessions`, `/new`,
-`/compact`, `/mcp`, `/quota`) run on pick as well; every other completion
-(skills, plugins) only fills the line, since those usually expect arguments.
-The arg-less forms still print a static listing over the same slash-command
-path the editor uses. `/help` lists every command the bridge advertises,
-including plugin commands. `/new` swaps in a fresh session without leaving
-the terminal (the old conversation stays in `/sessions` and in scrollback).
-
-Submitted prompts are history: `↑`/`↓` (with the completion menu closed)
-recall them per project across restarts — the first `↑` stashes the draft
-and `↓` past the newest entry restores it. Pasted text folds to a single
-line (newlines and tabs become spaces), so a multi-paragraph paste lands in
-the box as one prompt instead of firing line-by-line. While a reply streams,
-the footer shows a live status row — `⠋ working… (12s · esc to interrupt)` —
-so stretches with no streamed output (long tool calls) still visibly tick.
-
-Unexpected internal errors never take the REPL down silently: they print to
-stderr and surface as an `-- error absorbed: …` note in the transcript while
-everything keeps running. Only repeated failures within ten seconds trip a
-breaker that shuts the UI down cleanly.
-
-While remote access is enabled, turns started from other clients (the mobile
-app, a second editor) render live in the REPL too, and questions or permission
-requests answered elsewhere dismiss the local picker automatically.
-
-Without a TTY (pipes, Windows editor shims — where the bin name is lost from
-`argv`), bare `zcode-acp` falls back to the stdio server, so editor configs
-pointing at either bin name keep working. Ask for the REPL explicitly with
-`zcode-acp repl`; without a TTY that errors instead of falling back.
-
-### Quota cards
-
-Check plan usage from the terminal — no editor or running server needed. By
-default it shows both **GLM Coding Plan** and **Opencode Go** in one card;
-pass a provider to focus on one.
-
-GLM credentials are read from `~/.zcode/v2/config.json`. Opencode Go
-credentials come from environment variables (the dashboard needs a browser
-cookie — see [Opencode Go setup](#opencode-go-setup) below).
-
-```bash
-# Both providers (default): GLM + Opencode Go in one card
-zcode-acp quota
-
-# Focus on one provider
-zcode-acp quota glm        # GLM Coding Plan only
-zcode-acp quota go         # Opencode Go only (rolling + weekly + monthly)
-
-# Live monitor: clear the screen and refresh every 30s (default)
-zcode-acp quota -w
-zcode-acp quota go -w      # watch Opencode Go only
-
-# Refresh at a custom interval (seconds; minimum 10)
-zcode-acp quota --watch --interval 60
-
-# Plain monochrome bars (color is the default on a terminal)
-zcode-acp quota --plain
-```
-
-By default the CLI renders heat-colored (green→yellow→red) progress bars with
-the usage numbers overlaid inside the bar, so each line stays short. Pass
-`--plain` (or `-p`) for the classic monochrome `█`/`░` layout. Color is also
-disabled automatically when stdout is piped or redirected, so captured output
-stays clean.
-
-The watch mode clears and redraws the card in place, like `top`/`htop`. Press
-`Ctrl-C` to exit. The 10s minimum exists because the quota API is cached for
-10s internally — a shorter interval would just keep returning the stale cached
-value.
-
-When the package isn't globally installed, run the built file directly:
-
-```bash
-node dist/cli.js quota -w
-```
-
-### Opencode Go setup
-
-Opencode Go has no JSON API for subscription usage — the CLI scrapes the
-authenticated dashboard at `opencode.ai/workspace/<id>/go`, so it needs your
-browser `auth` cookie. Credentials are read from two sources, **merged
-field-by-field with environment variables taking precedence** over the config
-file:
-
-- **Config file**: `~/.pi/agent/opencode-go.json` — same convention as the
-  `@beyona/pi-zai-usage` Pi extension, so if you already configured it there
-  you're done.
-  ```json
-  { "workspaceId": "wrk_your_workspace_id", "authCookie": "Fe26.2**your_cookie_value" }
-  ```
-- **Environment variables** (override the matching file field):
-  ```bash
-  export OPENCODE_GO_WORKSPACE_ID="wrk_your_workspace_id"
-  export OPENCODE_GO_AUTH_COOKIE="Fe26.2**your_cookie_value"
-  ```
-
-How to get the values:
-
-1. **Workspace ID** — open `https://opencode.ai`, navigate to your Go
-   workspace, and copy the `wrk_…` id from the URL
-   (`https://opencode.ai/workspace/<wrk_…>/go`).
-2. **Auth cookie** — open browser DevTools (F12) → Application → Cookies →
-   `opencode.ai` → copy the value of the cookie named `auth` (it starts with
-   `Fe26.2**`).
-
-Without credentials, the default dual-provider mode silently shows GLM only
-(no error). Running `zcode-acp quota go` without credentials prints a setup hint.
-
-### Hub and server subcommands
-
-`zcode-acp hub` runs the remote-access hub daemon manually (normally
-auto-spawned by bridges — see [Remote Access](#remote-access)). `zcode-acp
-server` speaks ACP on stdio — that is what editors invoke through the
-`zcode-acp-server` bin; you rarely need it by hand.
-
-### Upgrading from 0.11
-
-0.12.0 folds the old standalone bins into the unified CLI (see
-[ADR-0007](docs/adr/0007-unified-cli-entry-and-bin-pruning.md)):
-
-| Old (≤0.11)          | New (0.12)                            |
-| -------------------- | ------------------------------------- |
-| `zcode-acp-server`   | unchanged (kept for editor configs)   |
-| `zcode-quota [args]` | `zcode-acp quota [args]` (same flags) |
-| `zcode-acp-hub`      | `zcode-acp hub`                       |
-
-Editor configs referencing `zcode-acp-server` keep working unchanged.
+One command for every surface: an interactive terminal chat REPL with native
+scrollback (`zcode-acp`), plan quota cards (`zcode-acp quota`, GLM + Opencode
+Go), the remote hub daemon (`zcode-acp hub`), and the stdio server editors
+invoke (`zcode-acp server`). REPL keys, completion, history, and quota setup:
+[docs/CLI.md](docs/CLI.md).
 
 ## ACP Registry
 
@@ -528,6 +202,9 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture docum
 
 - [Architecture](docs/ARCHITECTURE.md) — event stream, dual-path deduplication, module responsibilities
 - [Protocol](docs/PROTOCOL.md) — ZCode JSON-RPC protocol details
+- [Sandbox](docs/SANDBOX.md) — full sandbox manual (switches, whitelist, popups, verification)
+- [Remote Access](docs/REMOTE.md) — hub, discovery API, tunnels, remote session-create
+- [Unified CLI](docs/CLI.md) — REPL, quota cards, hub/server subcommands
 - [Remote Clients](docs/REMOTE-CLIENTS.md) — remote access integration contract (discovery, transport, recovery)
 - [Replay Guide](docs/REPLAY-GUIDE.md) — building a client UI on tail replay
 - [Development](docs/DEVELOPMENT.md) — local development, debugging, adding extension methods
@@ -539,6 +216,13 @@ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
 code style, commit conventions, and the PR checklist. Notable changes are
 recorded in [CHANGELOG.md](CHANGELOG.md).
 
+Thanks to everyone who has contributed (updated automatically from the
+[contributors graph](https://github.com/william0wang/zcode-acp/graphs/contributors)):
+
+<a href="https://github.com/william0wang/zcode-acp/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=william0wang/zcode-acp" alt="Contributors" />
+</a>
+
 ## Related Projects
 
 - [glm-acp-agent](https://github.com/stefandevo/glm-acp-agent) — a self-contained ACP agent that calls the GLM API directly; zcode-acp instead bridges the real `zcode app-server`, inheriting its full official harness.

package/README.zh-CN.md

@@ -117,174 +117,26 @@ ZCode CLI 内置于桌面应用中，默认不会加到 `PATH`。用 `ZCODE_BIN`
 
 ## 沙箱
 
-两个开关任一生效（仅 macOS）：
-
-- 全局：`ZCODE_ACP_SANDBOX=1`；
-- 项目级：`<工作区>/.zcode/acp/sandbox.json` 里设 `"enabled": true`。该文件
-  在首次打开工作区时由桥自动创建（默认 `"enabled": false`）——把开关翻成
-  `true` 即可单独启用本项目，无需全局环境变量。运行中途翻开关，下一次
-  prompt 生效（后端以沙箱重启）；翻回 `false` 则在后端下次自然重启时停用。
-
-启用后，zcode 后端子进程——连同它执行的每一次 Bash/Edit/Write 及所有子进
-程——被包进 Seatbelt（`sandbox-exec`）沙箱：除以下位置外**一律禁止文件写入**：
-
-- 各活跃会话的工作区根目录；
-- `~/.zcode*`（后端自身的会话/数据库/日志）；
-- 系统临时目录与可再生的工具缓存（`~/Library/Caches`、`~/.cache`、
-  `~/.npm`、`~/Library/pnpm`、`~/.node-gyp`）；
-- 项目配置或放行弹窗授权的路径。
-
-读取和进程执行不受限：删除（`rm`、`mv`、截断）属于写类系统调用，写禁令
-会拦下它——无论用哪个二进制执行（`/bin/rm`、Python `shutil.rmtree`、shell
-重定向都一样）。
-
-当 Agent 尝试写白名单之外的位置时，工具报 `Operation not permitted`，桥
-通过编辑器权限弹窗给出四个选项：**仅此一次**、**始终允许**、**拒绝一次**、
-**始终拒绝**。两个“始终”由桥代写进 `<工作区>/.zcode/acp/sandbox.json`
-（首次运行自动创建——放行记入 `allow` 列表，拒绝记入 `deny` 列表并不再
-询问；编辑该文件即可撤销）；两个“一次”及关闭弹窗不保存任何东西，下次
-仍会询问。Agent 自己改不了这个文件——沙箱禁止写工作区内的
-`.zcode/acp/`，而桥在沙箱外。放行
-后后端以加宽的 profile 重启（几秒），桥自动继续被中断的任务。配置里设
-`"strictGit": true` 可让 `.git` 也走弹窗。
-
-沙箱目标是防误删误写，不是防恶意：间接逃逸（Agent 改了你的 `.bashrc`、构
-建脚本或 git hook，随后由你自己在沙箱外执行）不在防护范围——请像代码评审
-一样对待它的产出。可用 `bash scripts/verify-sandbox.sh` 手工验证
-profile（macOS，先 `pnpm build`）。
+可选的 macOS Seatbelt 写入隔离：双开关（全局 `ZCODE_ACP_SANDBOX=1`，或项目
+级在自动创建的 `<工作区>/.zcode/acp/sandbox.json` 里设 `"enabled": true`），
+白名单之外的写入会弹放行/拒绝确认，"始终"决定可见地持久化在该配置里；放行
+后后端自动以加宽的 profile 重启并续接被中断的任务。完整手册（英文）：
+[docs/SANDBOX.md](docs/SANDBOX.md)。
 
 ## 远程访问
 
-设置 `ZCODE_ACP_REMOTE=1` 后，bridge 会额外通过 WebSocket 接收 ACP 连接，
-手机或浏览器即可观看并驱动与编辑器**相同的会话**。Zed（或任何 stdio ACP
-编辑器）仍是主客户端并拥有进程：编辑器断开时，bridge 连同所有远程连接
-一起退出。
-
-```text
-phone / browser ──WS── 隧道 ── hub (127.0.0.1:8377, 唯一入口)
-                                │ 字节级代理
-                                ▼
-                  bridge ACP 端点 (127.0.0.1:8378+n)
-                                │ 与 stdio 同一个 AgentApp
-Zed ──────── stdio ────────────┘
-```
-
-启用方式：在上文「配置 Zed」的 `env` 里追加（Zed 会把这些合并进 agent
-的环境变量）：
-
-```json
-"ZCODE_ACP_REMOTE": "1",
-"ZCODE_ACP_REMOTE_TOKEN": "<一段足够长的随机密钥>"
-```
-
-相关环境变量（详见上文表格）：`ZCODE_ACP_REMOTE`（开关）、
-`ZCODE_ACP_REMOTE_TOKEN`（必填 token）、`ZCODE_ACP_HUB_PORT`（hub 端口，
-默认 8377）、`ZCODE_ACP_HUB_HOST`（hub 绑定地址）、
-`ZCODE_ACP_REMOTE_PORT`（bridge 端点起始端口，默认 8378）。
-
-**Hub。** 第一个启用远程的 bridge 会以 detached 方式拉起机器级单例
-`zcode-acp-hub`（监听 `ZCODE_ACP_HUB_PORT`，也可手动运行）。它只做三件事：
-token 鉴权、实例发现、字节级 WebSocket 代理——不保存会话状态、不解析 ACP。
-空闲约 10 分钟后退出，需要时再被拉起。每个 bridge 每 10 秒注册一次作为
-心跳，心跳停止约 30 秒后从发现列表移除；客户端刷新时也可调用
-`GET /api/instances?probe=1` 主动探测，立即清理不可达的实例。
-
-**远程创建会话**（ADR-0014）。远程客户端可以在本机的已知项目里直接开一个
-新会话——不需要任何编辑器在场：
-
-```text
-GET  /api/projects                  → [{"workspacePath","sessions","lastActive"}]
-POST /api/instances {workspacePath} → {"id","reused"}
-```
-
-`/api/projects` 聚合 App 的任务索引：所有跑过会话的项目（过滤系统临时
-目录、`~/.zcode` 自身和已不存在的目录），按最近活跃排序。这份列表约束
-POST——列表之外的路径一律 403（注意这是便利性约束而非安全边界：持有
-token 者本就能以任意 cwd 驱动 editor bridge 会话，真正的信任边界是
-token 本身）。创建时 hub 会在项目目录下拉起 `zcode-acp serve`（无头 bridge），
-数秒内注册回 hub，之后像普通实例一样可连接；同项目已有存活的 serve 实例
-则直接复用（`reused:true`）。serve bridge 只为远程连接而活：最后一个客户端
-断开且最后一个 turn 结束约 10 分钟后自动退出；其 `session/new` 无论客户端
-传什么都使用项目目录（cwd 端到端钉死在项目内）。
-
-**语义。** 所有 agent 通知广播给每个已连接客户端；权限 / elicitation 请求
-发给所有客户端，**先应答者生效**，其余客户端收到 `$/cancel_request` 关闭
-对话框。同一会话的并发 prompt 与单编辑器一样串行化。任一客户端声明的能力
-按 OR 合并。`/api/instances` 的每个实例带 `origin` 字段（`"editor"`＝编辑器
-stdio 桥，`"serve"`＝远程创建的无头桥），客户端可据此标注。
-
-**隧道。** 面向单端口隧道（Cloudflare Tunnel、frp）设计：只映射 hub 端口。
-frp 的 `tcp` 模式原样透传 WebSocket；Cloudflare Tunnel 会断开空闲连接，
-hub 因此在两段链路上每 30 秒发送 keepalive ping。bridge 端点本身只监听
-回环地址，永不直接暴露。
-
-要构建远程客户端（Web、移动端或 CLI）？完整的集成契约（端点、帧格式、
-生命周期时序、故障恢复、平台注意事项）见
+设置 `ZCODE_ACP_REMOTE=1` 后，bridge 会额外通过机器级 hub 守护进程把**相同
+的会话**暴露到 WebSocket——手机或浏览器可以旁观、驱动、甚至在本机已知项目里
+直接创建新会话，Zed 仍是主客户端并拥有进程。发现 API、隧道、鉴权与语义：
+[docs/REMOTE.md](docs/REMOTE.md)；客户端集成契约：
 [docs/REMOTE-CLIENTS.md](docs/REMOTE-CLIENTS.md)。
 
-## 独立配额查询 CLI（zcode-quota）
-
-除了 ACP server，本包还附带一个 `zcode-quota` 命令，可在**终端**里直接查询
-用量——无需编辑器，也无需 server 运行。默认在一张卡片里同时显示
-**GLM Coding Plan** 和 **Opencode Go**；传入 provider 参数可只看其中一个。
-
-GLM 凭证读取自 `~/.zcode/v2/config.json`。Opencode Go 凭证来自环境变量
-（dashboard 需要浏览器 cookie——见下方 [Opencode Go 配置](#opencode-go-配置)）。
-
-```bash
-# 双平台（默认）：GLM + Opencode Go 合并为一张卡片
-zcode-quota
-
-# 只看某一个 provider
-zcode-quota glm            # 仅 GLM Coding Plan
-zcode-quota go             # 仅 Opencode Go（rolling + weekly + monthly 三窗口）
-
-# 常驻监控：清屏并每 30s 刷新（默认）
-zcode-quota -w
-zcode-quota go -w          # 只监控 Opencode Go
-
-# 自定义刷新间隔（秒，最小 10）
-zcode-quota --watch --interval 60
+## 统一 CLI（zcode-acp）
 
-# 纯文本单色进度条（终端默认是彩色）
-zcode-quota --plain
-```
-
-默认情况下 CLI 会渲染热力配色（绿→黄→红）的进度条，并把用量数字叠在条内，
-这样每行更紧凑。传 `--plain`（或 `-p`）切回经典的 `█`/`░` 单色布局。当 stdout
-被管道或重定向时，彩色也会自动关闭，保证捕获到的输出干净。
-
-watch 模式会原地清屏重绘卡片，效果类似 `top`/`htop`。按 `Ctrl-C` 退出。
-之所以设最小间隔 10s，是因为配额 API 内部有 10s 缓存——更短的间隔只会一直
-返回过期的缓存值，没有意义。
-
-未全局安装时，可直接运行构建产物：
-
-```bash
-node dist/bin/quota.js -w
-```
-
-### Opencode Go 配置
-
-Opencode Go 订阅用量没有 JSON API——CLI 抓取的是登录后的 dashboard 页面
-`opencode.ai/workspace/<id>/go`，因此需要你的浏览器 `auth` cookie。设置两个
-环境变量：
-
-```bash
-export OPENCODE_GO_WORKSPACE_ID="wrk_你的工作区id"
-export OPENCODE_GO_AUTH_COOKIE="Fe26.2**你的cookie值"
-```
-
-获取方式：
-
-1. **Workspace ID**——打开 `https://opencode.ai`，进入你的 Go 工作区，从 URL
-   里复制 `wrk_…` id（`https://opencode.ai/workspace/<wrk_…>/go`）。
-2. **Auth cookie**——打开浏览器开发者工具（F12）→ Application → Cookies →
-   `opencode.ai` → 复制名为 `auth` 的 cookie 值（以 `Fe26.2**` 开头）。
-
-未设置这两个变量时，默认的双平台模式会**静默退化为只显示 GLM**（不报错）。
-若明确运行 `zcode-quota go` 但未配置，会打印一条配置提示。把它们加到 shell
-配置文件（`~/.zshrc` / `~/.bashrc`）即可持久化。
+本包所有能力收敛在一条命令下：交互式终端聊天 REPL（原生滚动回溯）、套餐
+用量卡片（`zcode-acp quota`，GLM + Opencode Go）、远程 hub 守护进程
+（`zcode-acp hub`）以及编辑器调用的 stdio server（`zcode-acp server`）。
+REPL 按键、补全、历史与配额配置详见 [docs/CLI.md](docs/CLI.md)。
 
 ## ACP Registry
 
@@ -336,6 +188,9 @@ CI 会在每次 push 和 pull request 时运行 `typecheck`、`lint`、`build`
 
 - [架构](docs/ARCHITECTURE.md) —— 事件流、双路径去重、模块职责
 - [协议](docs/PROTOCOL.md) —— ZCode JSON-RPC 协议细节
+- [沙箱](docs/SANDBOX.md) —— 沙箱完整手册（开关、白名单、弹窗、验证）
+- [远程访问](docs/REMOTE.md) —— hub、发现 API、隧道、远程创建会话
+- [统一 CLI](docs/CLI.md) —— REPL、配额卡片、hub/server 子命令
 - [开发](docs/DEVELOPMENT.md) —— 本地开发、调试、新增扩展方法
 - [故障排查](docs/TROUBLESHOOTING.md) —— 常见问题排查
 
@@ -344,6 +199,13 @@ CI 会在每次 push 和 pull request 时运行 `typecheck`、`lint`、`build`
 欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建、代码风格、
 commit 约定和 PR 检查清单。重要变更记录在 [CHANGELOG.md](CHANGELOG.md)。
 
+感谢每一位贡献者（由[贡献者图谱](https://github.com/william0wang/zcode-acp/graphs/contributors)
+自动生成，覆盖全部历史贡献者）：
+
+<a href="https://github.com/william0wang/zcode-acp/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=william0wang/zcode-acp" alt="贡献者" />
+</a>
+
 ## 相关项目
 
 - [glm-acp-agent](https://github.com/stefandevo/glm-acp-agent) —— 自包含的 ACP agent，直接调用 GLM API；zcode-acp 则桥接真实的 `zcode app-server`，继承其完整的官方 harness。

package/dist/backend/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backend/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAiBH,uEAAuE;AACvE,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAc/C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAoCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa,CA+EtE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAyBtF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAyBpF;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB7C;AAOD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC3D,4EAA4E;IAC5E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAqClE;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG;IACpE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAqBA;AAiBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAmB,GAAG,OAAO,CAchF;AAED,4DAA4D;AAC5D,wBAAgB,2BAA2B,IAAI,IAAI,CAMlD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAc/E"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backend/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAiBH,uEAAuE;AACvE,eAAO,MAAM,WAAW,sBAAsB,CAAC;AA2B/C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAoCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa,CA+EtE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAyBtF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAyBpF;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB7C;AAOD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC3D,4EAA4E;IAC5E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAqClE;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG;IACpE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAqBA;AAiBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAmB,GAAG,OAAO,CAchF;AAED,4DAA4D;AAC5D,wBAAgB,2BAA2B,IAAI,IAAI,CAMlD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAc/E"}

package/dist/backend/sandbox.js

@@ -49,6 +49,18 @@ const DEFAULT_CACHE_DIRS = [
     "~/Library/pnpm",
     "~/.node-gyp",
 ];
+/**
+ * Well-known system temp trees, default-writable. Tools hardcode `/tmp`
+ * (a symlink to /private/tmp) or use /var/tmp, and $TMPDIR only names the
+ * process's own /var/folders leaf — without these, `mktemp` in a script or a
+ * compiler scratch file hits an EPERM popup for plain scratch space
+ * (observed: /private/tmp/adv_backup). /private/var/folders is the per-user
+ * temp+cache tree ($TMPDIR's parent, includes DARWIN_USER_CACHE_DIR); the
+ * specific $TMPDIR leaf stays allowed for tightness. Listed in RESOLVED
+ * form — SBPL subpath filters match REAL paths, and /tmp and /var/tmp
+ * resolve into the /private entries.
+ */
+const DEFAULT_TEMP_DIRS = ["/private/tmp", "/private/var/tmp", "/private/var/folders"];
 /** Backend state roots that must stay writable for the bridge to function. */
 const ZCODE_STATE_DIRS = ["~/.zcode", "~/.zcode-beta", "~/.zcode-plugin"];
 /** Path of the per-project sandbox config inside a workspace root. */
@@ -294,7 +306,7 @@ export function buildSandboxProfile(input) {
             allows.push(`(allow file-write* (subpath ${sb(resolveReal(allowed))}))`);
         }
     }
-    for (const p of [...ZCODE_STATE_DIRS, ...DEFAULT_CACHE_DIRS]) {
+    for (const p of [...ZCODE_STATE_DIRS, ...DEFAULT_CACHE_DIRS, ...DEFAULT_TEMP_DIRS]) {
         allows.push(`(allow file-write* (subpath ${sb(resolveReal(p))}))`);
     }
     for (const allowed of input.extraAllow) {