zcode-acp-server 0.14.3 → 0.17.1

package/README.md

@@ -9,6 +9,14 @@ A standalone [Agent Client Protocol](https://agentclientprotocol.com/) (ACP) ser
 
 The server launches the ZCode headless app-server (`zcode app-server --stdio`) as a subprocess, translates its internal event stream into ACP `session/update` notifications, and bridges ZCode's interaction channel to ACP — preferring `elicitation/create` when the client supports it, and falling back to `session/request_permission` otherwise — so an editor gets a first-class, native coding-agent experience.
 
+## Why zcode-acp
+
+- **Native editor experience** — streaming diffs, permission prompts and plan mode in Zed / JetBrains' own agent panel. No side-by-side terminal.
+- **The official harness, not a reimplementation** — drives the real `zcode app-server`: native tools, skills, MCP and slash commands, auto-compaction, session resume/fork.
+- **Beyond the editor** — a full bilingual terminal REPL (`zcode-acp`, English/中文, works over SSH), phone/web access to the same sessions (`zcode-acp-remote`), opt-in writes-only sandbox. Credentials stay in `~/.zcode`.
+
+Because it drives the real ZCode client, your GLM Coding Plan comes along untouched — current perks (the 150% quota bonus, priority routing over raw API) and the plan's flat-rate economics apply exactly as in the official app. No API keys in editor settings.
+
 ## Status
 
 In active development. Core bridging, slash commands and ZCode extensions,
@@ -26,15 +34,27 @@ in place; see the project board for what's next.
 ## Install
 
 ```bash
-git clone <repo-url>
+npm install -g zcode-acp-server
+```
+
+This installs both bins: `zcode-acp-server` (what your editor launches) and
+`zcode-acp` (the unified CLI). Configure your ACP client to launch it — see
+**Configure Zed** below or your editor's ACP docs.
+
+<details>
+<summary>Install from source instead</summary>
+
+```bash
+git clone https://github.com/william0wang/zcode-acp.git
 cd zcode-acp-server
 pnpm install
 pnpm build
 ```
 
 The compiled entry point is `dist/index.js` (also exposed as the
-`zcode-acp-server` bin). Configure your ACP client to launch it — see
-**Configure Zed** below or your editor's ACP docs.
+`zcode-acp-server` bin).
+
+</details>
 
 ## Configure Zed
 
@@ -46,11 +66,10 @@ Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
   "agent_servers": {
     "ZCode": {
       "type": "custom",
-      "command": "node",
-      "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
+      "command": "zcode-acp-server",
       "env": {
-        // Point at the ZCode CLI bundled inside the desktop app (not on PATH by default).
-        // See the platform-specific path below.
+        // Only needed for custom installs — the CLI is auto-discovered from
+        // the desktop app bundle or PATH (see the table below).
         "ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
       },
     },
@@ -58,6 +77,9 @@ Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
 }
 ```
 
+Running from source instead? Use `"command": "node"` with
+`"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"]`.
+
 Restart Zed and pick **ZCode** from the agent dropdown.
 
 ### `ZCODE_BIN` per platform
@@ -97,6 +119,56 @@ most setups need no `ZCODE_BIN` at all — set it only for custom installs:
 | `ZCODE_ACP_HUB_PORT`               | `8377`              | Port of the machine-level hub daemon. Map exactly this one port in your tunnel.                                                                                                                                                                                                                                                                                                              |
 | `ZCODE_ACP_HUB_HOST`               | `127.0.0.1`         | Hub bind address. `0.0.0.0` exposes a token-only, unencrypted surface — only for a containerized tunnel agent on a private interface (see [Remote Access](#remote-access)).                                                                                                                                                                                                                  |
 | `ZCODE_ACP_REMOTE_PORT`            | `8378`              | First loopback port for the bridge's ACP endpoint. Each bridge (each editor window) auto-increments to the next free port.                                                                                                                                                                                                                                                                   |
+| `ZCODE_ACP_SANDBOX`                | _(unset)_           | Set to `1` to confine the agent's file writes with a macOS Seatbelt sandbox globally; per-project, set `"enabled": true` in `<workspace>/.zcode/acp/sandbox.json` instead (see [Sandbox](#sandbox)).                                                                                                                                                                                         |
+| `ZCODE_ACP_LANG`                   | _(inherited)_       | Language of the bridge's user-facing strings (popups, status/hint lines, command menu descriptions): `zh` or `en`. When unset, the bridge inherits the ZCode app's language (`localePreference`/`locale` in `~/.zcode/v2/setting.json`), then falls back to the `LC_ALL`/`LC_MESSAGES`/`LANG` locale, defaulting to English.                                                                 |
+
+## 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`).
 
 ## Remote Access
 
@@ -145,12 +217,38 @@ discovery ~30s after it stops.
 
 ```text
 GET /api/instances              → [{"id","port","pid","startedAt","workspace",
-                                    "sessions":[{"sessionId","title?","updatedAt"}]}]
+                                    "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
@@ -380,7 +478,7 @@ Editor configs referencing `zcode-acp-server` keep working unchanged.
 
 This server is compatible with the [ACP Registry](https://agentclientprotocol.com/get-started/registry). It advertises a single `agent`-type auth method at `initialize` time — the GLM API key is read from `~/.zcode/v2/config.json` by the ZCode backend, so **no editor-side credentials are required**.
 
-The registry submission assets live under [`registry/zcode-acp-server/`](registry/zcode-acp-server/) (`agent.json` + `icon.svg`). Once the package is published to npm, copy that directory into a fork of [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) and open a PR — the CI validates the `agent.json` schema, icon, and that `initialize` returns a non-empty `authMethods`.
+The registry submission assets live under [`registry/zcode-acp/`](registry/zcode-acp/) (`agent.json` + `icon.svg`). Once the package is published to npm, copy that directory into a fork of [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) and open a PR — the CI validates the `agent.json` schema, icon, and that `initialize` returns a non-empty `authMethods`.
 
 ## Develop
 
@@ -443,6 +541,8 @@ recorded in [CHANGELOG.md](CHANGELOG.md).
 
 ## 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.
+- [claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) / [codex-acp](https://github.com/agentclientprotocol/codex-acp) — official ACP adapters for the Claude and Codex CLIs; zcode-acp is the same idea for the ZCode CLI.
 - [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) — a community Python implementation that bridges ZCode to the MCP/ACP ecosystem. The design of this server references its bridge architecture and several handling strategies.
 
 ## Acknowledgements

package/README.zh-CN.md

@@ -9,6 +9,14 @@
 
 本服务端以子进程方式启动 ZCode 无头 app-server（`zcode app-server --stdio`），将其内部事件流翻译为 ACP `session/update` 通知，并把 ZCode 的交互通道桥接到 ACP —— 当客户端支持时优先使用 `elicitation/create`，否则回退到 `session/request_permission` —— 从而让编辑器获得原生的、一流的编码助手体验。
 
+## 为什么选 zcode-acp
+
+- **编辑器原生体验** —— 流式改动以真实 diff 呈现，权限确认、计划模式都走 Zed / JetBrains 自己的 agent 面板，无需并排终端。
+- **官方 harness，而非重新实现** —— 驱动真实的 `zcode app-server`：原生工具、skills、MCP 与斜杠命令、自动压缩、会话恢复/分叉。
+- **不止于编辑器** —— 完整的双语终端 REPL（`zcode-acp`，中/英可切换，SSH 下可用），手机/网页访问相同会话（`zcode-acp-remote`），可选的只限写入沙箱。凭据留在 `~/.zcode`。
+
+由于驱动的是真实 ZCode 客户端，你现有的 GLM Coding Plan 原样生效——当前的套餐权益（150% 额度加成、高于直连 API 的请求优先级）和包月计费方式都和在官方 App 中一致。编辑器设置无需任何 API key。
+
 ## 状态
 
 早期开发中。核心框架已就绪，功能正在陆续加入。进度请看项目看板。
@@ -23,14 +31,25 @@
 ## 安装
 
 ```bash
-git clone <repo-url>
+npm install -g zcode-acp-server
+```
+
+会同时安装两个 bin：`zcode-acp-server`（编辑器调用）和 `zcode-acp`（统一 CLI）。
+在你的 ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你的编辑器的 ACP 文档。
+
+<details>
+<summary>改为从源码安装</summary>
+
+```bash
+git clone https://github.com/william0wang/zcode-acp.git
 cd zcode-acp-server
 pnpm install
 pnpm build
 ```
 
-编译产物入口为 `dist/index.js`（同时作为 `zcode-acp-server` bin 暴露）。在你的
-ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你的编辑器的 ACP 文档。
+编译产物入口为 `dist/index.js`（同时作为 `zcode-acp-server` bin 暴露）。
+
+</details>
 
 ## 在 Zed 中配置
 
@@ -42,11 +61,10 @@ ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你
   "agent_servers": {
     "ZCode": {
       "type": "custom",
-      "command": "node",
-      "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
+      "command": "zcode-acp-server",
       "env": {
-        // 指向桌面应用内置的 ZCode CLI（默认不在 PATH 上）。
-        // 各平台路径见下方表格。
+        // 仅自定义安装时需要——CLI 会从桌面应用内置路径或 PATH 自动发现
+        // （见下方表格）。
         "ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
       },
     },
@@ -54,6 +72,9 @@ ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你
 }
 ```
 
+从源码运行？改用 `"command": "node"` 与
+`"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"]`。
+
 重启 Zed，然后从 agent 下拉菜单中选择 **ZCode**。
 
 ### 各平台的 `ZCODE_BIN` 路径
@@ -91,6 +112,46 @@ ZCode CLI 内置于桌面应用中，默认不会加到 `PATH`。用 `ZCODE_BIN`
 | `ZCODE_ACP_HUB_PORT`               | `8377`           | 机器级 `zcode-acp-hub` 的端口。隧道只映射这一个端口。                                                                                                                                                                                                                               |
 | `ZCODE_ACP_HUB_HOST`               | `127.0.0.1`      | hub 绑定地址。`0.0.0.0` 会暴露仅 token 保护的明文面——只用于容器化隧道 agent 所在的私网接口（见[远程访问](#远程访问)）。                                                                                                                                                             |
 | `ZCODE_ACP_REMOTE_PORT`            | `8378`           | bridge ACP 端点的起始回环端口。每个 bridge（每个编辑器窗口）自动递增取下一个空闲端口。                                                                                                                                                                                              |
+| `ZCODE_ACP_SANDBOX`                | _（未设置）_     | 设为 `1` 全局启用 macOS Seatbelt 沙箱限制 Agent 的文件写入；项目级则在 `<工作区>/.zcode/acp/sandbox.json` 里设 `"enabled": true`（见[沙箱](#沙箱)）。                                                                                                                               |
+| `ZCODE_ACP_LANG`                   | _（继承）_       | 桥的用户可见文案（弹窗、状态/提示行、命令菜单描述）语言：`zh` 或 `en`。未设置时继承 ZCode APP 的语言设置（`~/.zcode/v2/setting.json` 的 `localePreference`/`locale`），再退回 `LC_ALL`/`LC_MESSAGES`/`LANG` 区域设置，默认英文。                                                    |
+
+## 沙箱
+
+两个开关任一生效（仅 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`）。
 
 ## 远程访问
 
@@ -128,10 +189,29 @@ token 鉴权、实例发现、字节级 WebSocket 代理——不保存会话状
 心跳，心跳停止约 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 合并。
+按 OR 合并。`/api/instances` 的每个实例带 `origin` 字段（`"editor"`＝编辑器
+stdio 桥，`"serve"`＝远程创建的无头桥），客户端可据此标注。
 
 **隧道。** 面向单端口隧道（Cloudflare Tunnel、frp）设计：只映射 hub 端口。
 frp 的 `tcp` 模式原样透传 WebSocket；Cloudflare Tunnel 会断开空闲连接，
@@ -210,7 +290,7 @@ export OPENCODE_GO_AUTH_COOKIE="Fe26.2**你的cookie值"
 
 本服务端兼容 [ACP Registry](https://agentclientprotocol.com/get-started/registry)。它在 `initialize` 时声明一个 `agent` 类型的认证方法——GLM API key 由 ZCode 后端从 `~/.zcode/v2/config.json` 读取，**编辑器侧无需配置任何凭据**。
 
-Registry 提交资产位于 [`registry/zcode-acp-server/`](registry/zcode-acp-server/)（`agent.json` + `icon.svg`）。包发布到 npm 后，将该目录复制到 [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) 的 fork 中并提 PR——CI 会校验 `agent.json` schema、图标，以及 `initialize` 返回的 `authMethods` 非空。
+Registry 提交资产位于 [`registry/zcode-acp/`](registry/zcode-acp/)（`agent.json` + `icon.svg`）。包发布到 npm 后，将该目录复制到 [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) 的 fork 中并提 PR——CI 会校验 `agent.json` schema、图标，以及 `initialize` 返回的 `authMethods` 非空。
 
 ## 开发
 
@@ -266,6 +346,8 @@ commit 约定和 PR 检查清单。重要变更记录在 [CHANGELOG.md](CHANGELO
 
 ## 相关项目
 
+- [glm-acp-agent](https://github.com/stefandevo/glm-acp-agent) —— 自包含的 ACP agent，直接调用 GLM API；zcode-acp 则桥接真实的 `zcode app-server`，继承其完整的官方 harness。
+- [claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) / [codex-acp](https://github.com/agentclientprotocol/codex-acp) —— Claude 与 Codex CLI 的官方 ACP 适配器；zcode-acp 是同一思路在 ZCode CLI 上的实现。
 - [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) —— 一个社区 Python 实现，将 ZCode 接入 MCP/ACP 生态。本项目参考了它的桥接架构和若干处理策略。
 
 ## 致谢

package/dist/backend/index.d.ts

@@ -3,5 +3,6 @@ export { ZcodeBackend, type ServerRequest, type EventListener } from "./client.j
 export { EventStreamListener, TurnMonitor, type NextId } from "./listener.js";
 export { resolveZcodeCommand } from "./resolve.js";
 export { loadZcodeCredentials, mergeEnvWithCreds, type ZcodeCredentials } from "./credentials.js";
+export { SANDBOX_ENV, appendSandboxAllow, armSandboxArgv, buildSandboxProfile, collectSandboxWorkspaces, projectSandboxEnabled, readSandboxConfig, resetSandboxDecisionForTest, sandboxActive, sandboxConfigPath, type SandboxConfig, } from "./sandbox.js";
 export type { ZcodeRequest, ZcodeNotification, ZcodeResponse, ZcodeInbound, ZcodeSessionInfo, ZcodeCreateResult, ZcodeSessionListItem, ZcodeListResult, ZcodeEvent, ZcodeEventType, ZcodeSubscribeResult, ZcodeSnapshot, ZcodeProjection, ZcodeMessage, ZcodeMessagePart, ZcodeMessagesResult, ZcodeReadResult, ZcodeInteractionPermissionParams, ZcodeInteractionUserInputParams, ZcodeInteractionResponse, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClG,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,gCAAgC,EAChC,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,aAAa,EACb,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,gCAAgC,EAChC,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/backend/index.js

@@ -3,4 +3,5 @@ export { ZcodeBackend } from "./client.js";
 export { EventStreamListener, TurnMonitor } from "./listener.js";
 export { resolveZcodeCommand } from "./resolve.js";
 export { loadZcodeCredentials, mergeEnvWithCreds } from "./credentials.js";
+export { SANDBOX_ENV, appendSandboxAllow, armSandboxArgv, buildSandboxProfile, collectSandboxWorkspaces, projectSandboxEnabled, readSandboxConfig, resetSandboxDecisionForTest, sandboxActive, sandboxConfigPath, } from "./sandbox.js";
 //# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAA0C,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAyB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAA0C,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAyB,MAAM,kBAAkB,CAAC;AAClG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,aAAa,EACb,iBAAiB,GAElB,MAAM,cAAc,CAAC"}

package/dist/backend/sandbox.d.ts

@@ -2,12 +2,20 @@
  * Seatbelt sandbox for the zcode backend subprocess (ADR-0011).
  *
  * The backend runs every Bash/Edit/Write tool with the user's full
- * privileges; one careless command destroys real data. When
- * ZCODE_ACP_SANDBOX=1, the bridge wraps the single backend spawn point with
- * a generated `sandbox-exec` profile using a writes-only restriction model:
- * reads and process execution stay open, file writes are denied everywhere
- * except an explicit whitelist. Children inherit the sandbox, so one wrap
- * covers the backend, its tool subprocesses, and model workers.
+ * privileges; one careless command destroys real data. The bridge wraps the
+ * single backend spawn point with a generated `sandbox-exec` profile using a
+ * writes-only restriction model: reads and process execution stay open, file
+ * writes are denied everywhere except an explicit whitelist. Children inherit
+ * the sandbox, so one wrap covers the backend, its tool subprocesses, and
+ * model workers — deletion (rm/mv/truncate) is a write-class syscall, so it
+ * is stopped by the write denial regardless of which binary performs it
+ * (name-banning executables would be trivially bypassed and is deliberately
+ * not done).
+ *
+ * Arming is dual-switch (see sandboxActive): ZCODE_ACP_SANDBOX=1 forces it
+ * globally, or a workspace opts in via `enabled: true` in its own
+ * .zcode/acp/sandbox.json — the template is auto-created with enabled:false,
+ * so opting in is always an explicit user edit.
  *
  * Whitelist (frozen at spawn, rebuilt on backend restart):
  * - workspace roots of all live sessions (union of server.sessionCwds)
@@ -16,6 +24,7 @@
  * - system temp + regenerable cache dirs (zero-value targets, constant
  *   toolchain traffic)
  * - each project's `.zcode/acp/sandbox.json` `allow` list
+ * - bridge-lifetime once-allows granted via the dynamic allow flow
  *
  * `<workspace>/.zcode/acp/` is a DENY island inside every allowed workspace:
  * the sandbox forbids writes there while the bridge — outside the sandbox —
@@ -28,24 +37,54 @@
 /** The one and only env switch. Every other knob is project config. */
 export declare const SANDBOX_ENV = "ZCODE_ACP_SANDBOX";
 export interface SandboxConfig {
+    /**
+     * Project-level switch: true arms the sandbox for this workspace without
+     * the global env. The auto-created template ships false — opting in is an
+     * explicit user edit.
+     */
+    enabled: boolean;
     /** Absolute realpaths OUTSIDE the workspace granted permanent write. */
     allow: string[];
+    /**
+     * Absolute realpaths the user chose NEVER to grant ("永不放行") — the
+     * popup is suppressed for these. Visible config, not hidden memory: the
+     * user can review or undo a denial by editing this file.
+     */
+    deny: string[];
     /** true = .git sits behind the allow popup instead of default-writable. */
     strictGit: boolean;
 }
 /** Path of the per-project sandbox config inside a workspace root. */
 export declare function sandboxConfigPath(workspaceRoot: string): string;
 /**
- * Read the project sandbox config, auto-creating it with defaults on first
- * sandboxed run. Tolerates absent/garbage files (falls back to defaults) —
- * a broken config must never keep the sandbox from arming.
+ * Read the project sandbox config, auto-creating the template (enabled:
+ * false) on first touch so the user finds the file and can flip the switch —
+ * the PRESENCE of the file is never the switch, only `enabled` is, so the
+ * auto-create cannot arm anything by itself. A malformed or non-object file
+ * falls back to enabled:true WITHOUT rewriting it: corruption must fail
+ * CLOSED (the user opted in; losing that to a half-saved file would silently
+ * disarm), and clobbering the user's mid-edit bytes with a template would be
+ * worse than the transient read. A symlinked/hardlinked config is treated
+ * the same way (armed, persistence disabled) — see configIntegrityOk. So is
+ * a config that was armed and then became unreadable or disappeared — only
+ * the agent could do that from inside the sandbox.
  */
 export declare function readSandboxConfig(workspaceRoot: string): SandboxConfig;
 /**
  * Bridge-side persistence for "always allow" (the deny island keeps the
- * agent from writing this file itself). Dedupes by exact string.
+ * agent from writing this file itself). Round-trips the whole config so the
+ * enabled flag survives the write. Dedupes by exact string. Returns false
+ * when persistence is impossible (symlinked config, unwritable path) — the
+ * caller then downgrades to a bridge-lifetime once-allow.
+ */
+export declare function appendSandboxAllow(workspaceRoot: string, allowedPath: string): boolean;
+/**
+ * Bridge-side persistence for the popup's "永不放行" choice — the visible
+ * counterpart of appendSandboxAllow: a denied path is RECORDED in the
+ * config (never hidden in bridge memory), so the ask never resurfaces for
+ * it and the user can review or undo the decision by editing the file.
  */
-export declare function appendSandboxAllow(workspaceRoot: string, allowedPath: string): void;
+export declare function appendSandboxDeny(workspaceRoot: string, deniedPath: string): boolean;
 /**
  * Resolve a path to its filesystem truth. Seatbelt matches real paths, so a
  * symlinked prefix (/tmp → /private/tmp) would silently fail to match —
@@ -58,13 +97,21 @@ export interface SandboxArmInput {
         root: string;
         config: SandboxConfig;
     }>;
-    /** Extra writable roots from configs of workspaces not arming now. */
+    /** Extra writable roots: allowlists from other workspaces + once-allows. */
     extraAllow: string[];
+    /**
+     * Directory the profile file itself lives in — self-denied LAST so the
+     * sandboxed agent cannot race/symlink/occupy the next respawn's profile
+     * (see armSandboxArgv). $TMPDIR is agent-writable, so without this the
+     * profile path would be attacker-reachable.
+     */
+    profileDir?: string;
 }
 /**
- * Build the SBPL profile text. Deny-rules take precedence over allow-rules
- * (verified empirically), which is what makes the `.zcode/acp/` deny island
- * inside an allowed workspace stick.
+ * Build the SBPL profile text. SBPL resolves overlapping rules by LAST
+ * match (verified empirically: an allow emitted after a deny re-permits the
+ * write), so the layout is: base deny-all, then every allow, then the deny
+ * carve-outs (island, strictGit) LAST so nothing can override them.
  */
 export declare function buildSandboxProfile(input: SandboxArmInput): string;
 /** Resolved arm input for the CURRENT spawn: union of all live workspaces. */
@@ -76,16 +123,38 @@ export declare function collectSandboxWorkspaces(cwdRoots: Iterable<string>): {
     extraAllow: string[];
 };
 /**
- * Whether the sandbox is active for this bridge run: env set AND macOS.
- * Non-macOS with the env set warns once and returns false (unsandboxed).
- * Decided once; later env changes don't re-arm mid-run.
+ * The project-level switch: `enabled: true` inside the workspace's sandbox
+ * config (auto-created on first touch, template ships false). Reading also
+ * materializes the template for discovery. Once the sandbox is armed the
+ * deny island keeps the agent from flipping the switch back off.
+ */
+export declare function projectSandboxEnabled(workspaceRoot: string): boolean;
+/**
+ * Whether the sandbox should arm for this bridge: ZCODE_ACP_SANDBOX=1
+ * (global, cached) OR any given workspace root opted in via
+ * sandbox.json `enabled` (project switch, re-checked per call so a flip
+ * mid-run is seen). macOS-only: elsewhere a requested sandbox warns once and
+ * runs unsandboxed.
  */
-export declare function sandboxActive(): boolean;
-/** Test hook: reset the cached platform/env decision. */
+export declare function sandboxActive(roots?: Iterable<string>): boolean;
+/** Test hook: reset cached decisions and warn-once sets. */
 export declare function resetSandboxDecisionForTest(): void;
 /**
- * Wrap a backend argv with sandbox-exec. Writes the profile to a temp file
- * owned by this bridge process (regenerated per backend respawn).
+ * Arm a backend argv: build the profile into a FRESH unpredictable dir and
+ * wrap with sandbox-exec. The dir sits DIRECTLY under $HOME with a
+ * `.zcode-acp-sbx-` prefix — OUTSIDE every whitelisted path (it is a SIBLING
+ * of `~/.zcode`, not inside it). That location is the load-bearing defense:
+ * $TMPDIR and the cache dirs are agent-writable, and a PRIOR sandboxed
+ * generation (a setsid survivor of the old process group) keeps its own
+ * profile's allows — so a profile placed there could be raced, symlinked,
+ * FIFO'd, or occupied no matter how fresh its name (reproduced across
+ * generations even with mkdtemp + O_EXCL + a self-deny, which each generation
+ * only applies to its own dir). The agent can also kill the backend at will
+ * (signals are not file-writes) to control respawn timing; with the profile
+ * unreachable from ANY generation, that primitive buys nothing. O_EXCL ("wx")
+ * additionally refuses pre-placed symlinks from a pre-arming process, and
+ * the profile still self-denies its own dir last (defense in depth for the
+ * workspace-root-is-$HOME edge, where home itself is writable).
  */
-export declare function wrapWithSandbox(argv: string[], profile: string): string[];
+export declare function armSandboxArgv(argv: string[], input: SandboxArmInput): string[];
 //# sourceMappingURL=sandbox.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backend/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,uEAAuE;AACvE,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAc/C,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa,CAoBtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAgBnF;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,sEAAsE;IACtE,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CA0BlE;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GACzB;IAAE,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBtF;AAID;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAevC;AAED,yDAAyD;AACzD,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CASzE"}
+{"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"}