feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象（pi/zcode）

## 是什么 agent 统筹开发流程的插件：登记项目 → 开工程线（每条线一个隔离工作目录 + 一个 sidecar 子进程 + 一对通道）→ 投递任务 → 同会话续投 → 评审/合入。 38 个工具：project_*/branch_*/workdir_*/job_*/review_*/test_*/ endpoint_*/agent_*/pi_*/conflict_check。 ## sidecar 后端抽象（本轮核心）传输层（local/ssh）与后端（pi/zcode/自定义）**正交**，四个自由组合： driver.json 描述一个后端：script / cliPath / env / args / llmConfig 三级查找：插件数据目录 → **随包 rawfile** → 内置 pi 描述占位符：{workdir} {dataDir} {pluginDir} {rawfile} {sessionId} ★ 内置 pi 回退**与默认后端解耦**（2026-10-17 修）：原实现写 `if cli == defaultAgentCLI { return builtinPiDriver() }`，把"给谁兜底" 和"默认选谁"耦合到同一常量 —— 一旦有人改默认，pi 当场失去兜底，显式 cli="pi" 开始报「驱动不存在」。现在判断字面 "pi"。默认后端保持 **pi**（我们本地主用）；交付方用 zcode 走两种局部开关： · 单线：commondev_branch_open(cli="zcode") · 按机器：commondev_endpoint_set(host=..., cli="zcode") ## zcode 接入（三条真机判据，全部要求真改工程文件） · TestZcodeFullPipeline（29-34s）：随包 driver + 真实 ZCode CLI · TestZcodeOverSSH（39s）：真 ssh + scp，远端 node 跑 zcode · TestZcodeOverSSHWithPerHostEndpoints（68s）：两个 host 别名配不同 cli_path，走端点表而不是全局 settings ★ 会话库必须隔离到工作区（sidecar.mjs 的 ensureWorkspaceSessionStore）：实测 ZCode 的会话库路径**硬编码 homedir()**，`ZCODE_DATA_BASE_DIR` 对它完全无效（26 个会话全落全局库）。但 `<workdir>/.zcode/config.json` 的 `storage.sessionDbPath` **确实生效**。所以启动前写一份工作区配置，一举解决：多线不共用历史 / 不污染全局 ~/.zcode / 删线不留孤儿会话。只在不存在时写 —— 用户手工放的要尊重。 ## 其他 · rawfile：项目根 rawfile/ 默认全收，解到 <插件目录>/rawfile/，绝对路径拒绝 · 凭证：命名引用 + ${ENV_VAR}，独立 0600 文件，绝不进 config.db(0644) · secretshell：给不受信 agent 用的安全 shell（ackey + safeshell） · 冲突检查 / 评审判据 / 镜像 / 每条线独立 workdir（hash 命名，合并后删除）判据 30+ 条，含 4 条「判据本身的判据」（防止判据假绿）。
2026-10-31 14:27:30 +00:00 · 2026-10-17 16:16:04 +08:00
parent 65d2bd9e61
commit c2474f57a2
55 changed files with 16071 additions and 0 deletions
--- a/example/commondev/examples/custom-cli/README.md
+++ b/example/commondev/examples/custom-cli/README.md
@ -0,0 +1,217 @@
+# 自定义 CLI 后端（示例：ZCode）
+
+> ## ★ 边界：**内嵌只做 pi**
+>
+> 插件**内嵌支持的后端只有 pi**（`runtime/pi/`，不装 driver.json 也照常工作）。
+> 本文及同目录示例是给**想让插件驱动别的 CLI** 的用户用的。
+>
+> 这不是"官方内嵌支持"——它们是**参考实现**：插件不承诺跟着上游 CLI 变更同步更新，
+> 你要根据自己的 CLI 版本调整（尤其参数名与输出格式）。
+>
+> 沿用本仓的一条纪律：**内核/插件只保证机器必须保证的事，策略与平台知识交给能
+> 独立演进的地方**（见 skill `commondev-discipline` 里"平台知识进 skill"的同一条理由）。
+
+## 怎么加一个后端
+
+插件按 **数据**（不是代码）选后端。加一个 CLI 只要放两个文件：
+
+```
+<插件数据目录>/runtime/<cli>/driver.json     ← 声明：起什么命令、什么环境
+<插件数据目录>/runtime/<cli>/sidecar.mjs     ← 实现：把 CLI 包成 JSON-RPC
+```
+
+**插件核心一行都不用改**（这是可验证的：`TestCoreDoesNotHardcodePiLaunchDetails`
+会断言 `startSidecar` 里不出现任何 pi 专有细节）。
+
+开分支时指定后端：
+
+```
+commondev_branch_open(project="X", branch="feat/a", agent_cli="zcode", workdir=...)
+```
+
+### 两种来源：随包分发 vs 本机覆盖
+
+`driver.json` 与 sidecar 脚本都按同一条优先级链找：
+
+| 顺序 | 位置 | 用途 |
+|---|---|---|
+| ① | `<插件数据>/runtime/<cli>/` | **本机覆盖**（最高优先）—— 指到本机真实的 CLI 路径 |
+| ② | `<插件目录>/rawfile/runtime/<cli>/` | **随包分发** —— 升级插件即带上 |
+| ③ | `<可执行文件目录>/` | 开发期 |
+
+**为什么要 ②**：`cliPath` 的随包默认值是 `{rawfile}/zcode/zcode.cjs`，
+而 CLI 有 28MB、按需分发 —— 所以**多数机器上它不存在**，此时必须由 ① 覆盖：
+
+```bash
+# 本机覆盖：只改这两个文件，不影响随包内容（升级插件不会被覆盖）
+mkdir -p <插件数据>/runtime/zcode
+cp <随包>/rawfile/runtime/zcode/sidecar.mjs <插件数据>/runtime/zcode/
+# 然后编辑 <插件数据>/runtime/zcode/driver.json，把 cliPath 指向本机 zcode.cjs
+```
+
+若两处都没有，错误会**列出找过的每个位置**并告诉你改哪里（不要让它静默失败）。
+
+## sidecar 必须实现的契约
+
+JSON-RPC over stdin/stdout，方法与 pi 的 sidecar **完全相同**：
+
+| 方法 | 入参 | 必须返回 |
+|---|---|---|
+| `ping` | — | `{ok, session_id, cli_version?}`（握手，10s 内） |
+| `prompt` | `{text, session_id?}` | `{ok, session_id, reply}` ← **`session_id` 必须回** |
+| `state` | — | `{ok, session_id, messages}` |
+| `close` | — | `{ok}` |
+
+**为什么 `prompt` 必须回 `session_id`**：插件在投递后**断言会话未漂移**
+（设计 §3.3）。不回或回错值，插件会响亮失败——那是防"悄悄换了个会话"的机制。
+
+### ★ 会话 id 有两个**不同**的东西，别混
+
+这是 ZCode 后端实测踩到的真坑（2026-10-16，真机复现）：
+
+| 名字 | 长什么样 | 谁产生 | 能当 `--resume` 目标吗 |
+|---|---|---|---|
+| **插件标签** | `br-<project>-<branch>` | 插件（`--session-id` 传进来） | ❌ **绝不能** |
+| **后端真实 id** | `sess_xxxxxxxx-...` | 后端首轮返回 | ✅ 只有它能 |
+
+初版把 `args.sessionId`（标签）直接当 `--resume` 目标 ⇒ 首轮就执行
+`--resume br-xxx`，ZCode 报 `Session not found: br-xxx`——
+**表现为"第一次投递必定失败"**，第二次才可能好，非常像"偶发网络问题"。
+
+正确形状（示例就是这么写的）：
+
+```js
+let desiredSessionId = args.sessionId || "";  // 插件标签，只用于回报
+let zcodeSessionId   = "";                    // 真实 id，只有它能 resume
+// 首轮：不传 --resume；从 {type:"result"} 行取回 sess_...
+if (zcodeSessionId) argv.push("--resume", zcodeSessionId);
+// 回报时：有真实 id 报它，否则退回标签
+session_id: zcodeSessionId || desiredSessionId || null,
+```
+
+`params.session_id`（插件在 prompt 里传的）**同样是标签**，不要拿它赋值给
+"真实 id"变量——那等于把上面的修法又改回去了。
+
+### ★ 声明的 CLI 路径必须**验存**
+
+`driver.json` 的 `cliPath` 可能指向一个**不存在的**文件（例如随包默认值
+`{rawfile}/zcode/zcode.cjs`，而包里并没带那个 28MB 的 CLI）。
+若 `if (args.cliPath) return args.cliPath` 直接返回，Node 会在 spawn 时抛
+`MODULE_NOT_FOUND`，用户看到的是一坨 `Module._resolveFilename` 堆栈，
+**完全看不出"CLI 不存在"**，也不知道去哪儿配。
+
+正确做法：把"声明的"和"探测到的"一起验存，找不到时**列出找过的每个位置
+及其来源**，并给出修复动作（改哪个文件 / 设哪个环境变量）。
+
+## driver.json 字段
+
+```jsonc
+{
+  "name": "zcode",                  // 后端名（与目录名一致）
+  "script": "sidecar.mjs",          // 相对本目录
+  "node": "auto",                   // auto = 随包优先；ssh 场景会走远端 PATH
+  "sessionNameFlag": false,         // 声明是否支持 --session-name（不支持就不传）
+  "sessionDirSuffix": ".zcode-sessions",
+  "llmConfig": "none",              // pi | zcode | none —— 谁准备 LLM 源
+  "env":  { "ZCODE_DATA_BASE_DIR": "{dataDir}/runtime/zcode" },
+  "args": ["--workdir", "{workdir}", "--session-id", "{sessionId}", "--mode", "guarded"]
+}
+```
+
+占位符：`{workdir}` `{sessionId}` `{sessionName}` `{dataDir}` `{pluginDir}`
+
+- **`sessionNameFlag: false` 是真实的坑**：ZCode CLI 没有 `--session-name`，
+  传了会 `Unknown option` 直接退到 usage——**一行参数毁掉整条命令**。
+- **`llmConfig`**：`pi` = 插件先写 `models.json`/`auth.json`（复用内核 LLM 源）；
+  `none` = 后端自己管。**没有 `zcode` 这个实现**——我们只知道
+  `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` 这个环境变量，**没实测过它的文件格式**，
+  凭猜测写是"静默写坏"（ZCode 起不来会表现为"模型不回复"，排查方向完全错）。
+  要用内核源，请先实测格式再实现写入器。
+
+## ZCode 示例的实测契约（真机 `zcode 0.16.9`，非猜测）
+
+```
+zcode.cjs --prompt <文本> --output-format stream-json --cwd <目录> --mode <值> [--resume <sess_id>]
+```
+
+| 点 | 实况（真机核实） |
+|---|---|
+| `--mode` | 合法值 **`build\|edit\|plan\|yolo\|guarded`**；**不传默认 `yolo`**（`run.ts: DEFAULT_HEADLESS_PROMPT_MODE`）= 绕过全部授权询问。示例用 `guarded`。 |
+| `--output-format` | **存在**（`--help` 里**不显示**，是隐藏参数 —— 别因为 help 没有就以为不存在）。`stream-json` 才有逐事件 NDJSON + **末行** `{type:"result", sessionId, response}`，sidecar 就靠这一行。 |
+| `--resume` | 会话延续。**只接受真实 `sess_...` id**，首轮不能传（见上文会话 id 一节） |
+| `--allowed-tools` | ⚠ **不存在**——只能用 `--disallowed-tools` |
+| `--max-turns` | ⚠ **不存在** |
+| `--session-name` | ⚠ **不存在**（`sessionNameFlag: false`） |
+
+> **教训**：`--output-format` 这一条曾被基于 `--help` 误判为"不存在"，
+> 差点把 sidecar 改成解析非结构化文本。**判定参数存在性必须用真机试跑**
+> （`--prompt hi --output-format stream-json` 直接看输出），`--help` 只覆盖公开参数。
+
+> ⚠️ **超时必须杀进程树**：ZCode 会派生工具子进程（bash 等），
+> 只杀父进程会留下孤儿继续跑，且仍占着工作目录。示例里用 `detached: true` +
+> `process.kill(-pid)` 整组杀。
+
+## 远端（SSH）场景的额外注意
+
+`runtime=ssh` 时用的是**同一份** driver 声明与 sidecar 契约，但：
+
+1. **环境变量必须显式前置**（`ssh host env K=V … node …`）——ssh 不继承本地环境。
+2. **node 用远端的**（裸 `node` 走远端 PATH），不是本地随包分发的绝对路径。
+3. **脚本要先推到远端**（插件会自动 `scp` 一次，见 `pushSidecar`）。
+4. **不交互**：`BatchMode=yes`。没配免密必须立刻失败，否则会挂在密码提示上
+   直到工具调用超时——那表现为"拉起 agent 卡住"而不是"没配免密"。
+
+## 验证
+
+```bash
+cd <插件源码>
+# 结构性判据（不需要真 CLI）
+go test -count=1 -run 'TestCoreDoesNotHardcode|TestSwappingDriverSwapsBackend|TestSSH|TestZcode|TestShippedDriver' ./...
+
+# ★ 真机端到端（需要真实 ZCode CLI + 可用 provider 配置）
+HA_ZCODE_CLI=<...>/zcode.cjs \
+HA_ZCODE_DATA_DIR=<插件数据>/runtime/zcode \
+  go test -tags zcode_e2e -run TestZcodeFullPipeline -v .
+
+# ★ SSH 远端（需要 sshd + localhost 免密）
+HA_SSH_E2E=1 HA_ZCODE_CLI=... HA_ZCODE_DATA_DIR=... \
+  go test -tags zcode_e2e -run TestZcodeOverSSH -v .
+```
+
+`TestSwappingDriverSwapsBackend` 用一个假 CLI 端到端证明：
+换 driver 就能换后端，插件核心零改动。
+
+`TestZcodeSidecarArgvBehavior` 用**假 CLI 记录真实 argv** 来判"首轮不得 `--resume`"——
+为什么不用源码字符串匹配：初版就是匹配字面串，把变量改个名就绕过了（判据假绿）。
+
+## 给 ZCode 配 LLM 源（实测可用的最小配置）
+
+ZCode 用自己的 provider 配置，**插件不碰它**（`llmConfig: "none"`）。
+数据目录由 `ZCODE_DATA_BASE_DIR` 决定，配置落在`<该目录>/.zcode/v2/provider_config.json`：
+
+```json
+{
+  "schemaVersion": 1,
+  "config": {
+    "providerConfigRules": { "providerRules": [ {
+      "providerId": "llmsproxy", "providerName": "llmsproxy", "enabled": true,
+      "config": {
+        "group": "standard-personal",
+        "personalModelIds": ["AUTO"], "modelOrder": ["AUTO"],
+        "access": { "type": "api-key", "apiKey": "sk-..." },
+        "api": { "type": "openai-chat-completions", "baseUrl": "http://127.0.0.1:8081/v1" }
+      }
+    } ] },
+    "defaultModelSelection": { "providerId": "llmsproxy", "modelId": "AUTO" }
+  }
+}
+```
+
+实测踩过的三个坑（全部真机复现）：
+
+1. **`schemaVersion` 必须有**，且 `providerRules` 嵌在 `config.providerConfigRules` 下
+   —— 放顶层会被静默"恢复"成默认值（文件被改写但你没察觉）。
+2. **`group: "standard-personal"` 必须有**。少了它，配置**被读到但不被准入**，
+   报 `Error: Model creation failed`；加 `--verbose` 才能看到真因
+   `Select a model before continuing`。
+3. `api.type` 合法值：`anthropic-messages` / `openai-chat-completions` / `openai-responses`。
--- a/example/commondev/examples/custom-cli/zcode/driver.json
+++ b/example/commondev/examples/custom-cli/zcode/driver.json
@ -0,0 +1,22 @@
+{
+  "name": "zcode",
+  "script": "sidecar.mjs",
+  "node": "auto",
+  "sessionNameFlag": false,
+  "sessionDirSuffix": ".zcode-sessions",
+  "llmConfig": "none",
+  "env": {
+    "ZCODE_DATA_BASE_DIR": "{dataDir}/runtime/zcode",
+    "ZCODE_SESSION_DIR": "{workdir}/.zcode-sessions"
+  },
+  "args": [
+    "--workdir",
+    "{workdir}",
+    "--session-id",
+    "{sessionId}",
+    "--mode",
+    "guarded"
+  ],
+  "note": "llmConfig=none：ZCode 用自己的 provider 配置（插件不猜它的格式）。cliPath 支持占位符；{rawfile} 指随包资源目录 —— 把 zcode.cjs 放进 rawfile/zcode/ 即可随包分发。用户也可在 <插件数据>/runtime/zcode/driver.json 覆盖成本机真实路径。",
+  "cliPath": "{rawfile}/zcode/zcode.cjs"
+}
--- a/example/commondev/examples/custom-cli/zcode/sidecar.mjs
+++ b/example/commondev/examples/custom-cli/zcode/sidecar.mjs
@ -0,0 +1,287 @@
+#!/usr/bin/env node
+// ZCode sidecar：把 **ZCode CLI** 包成与 pi sidecar **同一个 JSON-RPC 契约**的服务。
+//
+// ## 为什么必须同契约
+//
+// 插件的 `startSidecar` / `sc.call("prompt")` 是唯一的调用面 ——
+// 只要这个脚本实现 ping/prompt/state/close，**插件核心一行不用改**
+// 就能跑 ZCode。这就是「通过不同 sidecar 支持不同 CLI」的落点。
+//
+// ## 与 pi sidecar 的关键差异（实测契约，来自 agentmail/zcode-mail-bridge）
+//
+//	pi sidecar              ZCode sidecar
+//	────────────────────    ──────────────────────────────
+//	常驻进程 + prompt()     **每轮起一个新进程**（CLI 是一次性的）
+//	--session-id 建会话     --resume <id> 延续；首轮不给
+//	SDK 直接返回文本        --output-format stream-json，末行 {type:"result"}
+//	无授权概念              --mode **必传**（不传 = yolo，绕过全部授权询问）
+//
+// ## 会话 id 的处理（★ 与插件的契约）
+//
+// 插件在 prompt 后**断言 session_id 未变**（防会话漂移）。
+// ZCode 首轮才产生真实 sessionId，所以这里：
+//   · 首轮：把 CLI 返回的 sess_xxx 回报（插件接受它作为会话标识）
+//   · 后续：用 --resume 传回去，并回报同一个 id
+//
+// ## 超时必须杀进程树
+//
+// ZCode 会派生工具子进程（bash 等）。只杀父进程会留下一堆孤儿继续跑，
+// 而且它们仍占着工作目录。
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--workdir") out.workdir = argv[++i];
+    else if (a === "--session-id") out.sessionId = argv[++i];
+    else if (a === "--session-name") out.sessionName = argv[++i];
+    else if (a === "--cli") out.cliPath = argv[++i];
+    else if (a === "--mode") out.mode = argv[++i];
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const workdir = args.workdir || process.cwd();
+
+// ★ mode 必须显式给：不传时 CLI 默认 **yolo**（源码 src/run.ts:
+// DEFAULT_HEADLESS_PROMPT_MODE），那会绕过全部授权询问。
+// 合法值：build | edit | plan | yolo | guarded。默认用 guarded。
+const VALID_MODES = ["build", "edit", "plan", "yolo", "guarded"];
+const mode = args.mode || process.env.ZCODE_MODE || "guarded";
+if (!VALID_MODES.includes(mode)) {
+  throw new Error(`--mode 必须是 ${VALID_MODES.join("|")} 之一（收到 ${mode}）`);
+}
+
+// CLI 入口：驱动可经 --cli 指定，否则按常见安装位置找。
+//
+// ★ 返回 {path, tried} 而不是裸字符串：**必须知道路径是"声明的"还是"探测到的"**，
+// 才能在报错里说清楚该改哪里。
+//
+// 实测真缺陷（2026-10-16）：随包 driver.json 声明了 `{rawfile}/zcode/zcode.cjs`，
+// 但包里**没有**这个文件（28MB，按需分发）。旧实现 `if (args.cliPath) return args.cliPath`
+// 直接把它当有效路径返回 ⇒ Node 在 spawn 时抛模块解析失败，用户看到的是一坨
+// `Module._resolveFilename` 堆栈，**完全看不出"CLI 不存在"**，更不知道去哪儿配。
+// 声明的路径同样必须验存。
+function findCLI() {
+  const cands = [
+    { p: args.cliPath, source: "driver.json 的 cliPath" },
+    { p: process.env.ZCODE_CLI, source: "环境变量 ZCODE_CLI" },
+    { p: path.join(process.env.HOME || "", ".zcode/runtime/bin/zcode.mjs"), source: "默认探测" },
+    { p: "/opt/ZCode/resources/glm/zcode.cjs", source: "默认探测" },
+    { p: "/usr/local/bin/zcode", source: "默认探测" },
+  ];
+  const tried = [];
+  for (const c of cands) {
+    if (!c.p) continue;
+    tried.push(`${c.p}（${c.source}）`);
+    if (existsSync(c.p)) return { path: c.p, tried };
+  }
+  return { path: "", tried };
+}
+
+// ★ 必须区分两个不同的东西：
+//
+//   desiredSessionId  —— 插件传进来的**标签**（br-<project>-<branch>），
+//                        它是插件台账里的会话名，**不是** ZCode 的会话 id
+//   zcodeSessionId    —— ZCode 真实产出的 `sess_...`，只有它能用于 --resume
+//
+// 初版把 args.sessionId 直接当成 --resume 的目标，于是**首轮就带上
+// `--resume br-xxx`**，ZCode 报 `Session not found: br-xxx` ——
+// 表现为"第一次投递必定失败"，而第二次才可能成功（如果插件把
+// 上一轮返回的 sess_... 传回来了）。
+//
+// 实测（2026-10-16）：真实 ZCode 0.16.9 上首轮即失败。
+// 契约（参考实现在注释里也写了）：**首轮不给 --resume**，
+// 从 `{type:"result"}` 行取回 sess_...，之后才用它续谈。
+let desiredSessionId = args.sessionId || "";
+let zcodeSessionId = "";
+let turnCount = 0;
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+/** 杀**进程树**（ZCode 会派生工具子进程）。 */
+function killTree(child) {
+  if (!child || child.killed) return;
+  try {
+    // 负号 = 进程组；spawn 时 detached 建了独立进程组。
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    try { child.kill("SIGTERM"); } catch {}
+  }
+  setTimeout(() => {
+    try { process.kill(-child.pid, "SIGKILL"); } catch {}
+  }, 3000).unref?.();
+}
+
+/** 跑一轮 ZCode，返回 {sessionId, response}。 */
+function runTurn(text, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const found = findCLI();
+    if (!found.path) {
+      reject(new Error(
+        "找不到 ZCode CLI。已找过：\n  - " + found.tried.join("\n  - ") +
+          "\n请把 driver.json 的 cliPath 指向真实 CLI（本机覆盖写到 " +
+          "<插件数据>/runtime/zcode/driver.json），或设 ZCODE_CLI 环境变量。"));
+      return;
+    }
+    const argv = [
+      found.path,
+      "--prompt", text,
+      "--output-format", "stream-json",
+      "--cwd", workdir,
+      "--mode", mode,
+    ];
+    // ★ 会话延续：首轮不给 --resume（还没有 id），后续都给。
+    // ★ 只有拿到 ZCode 真实 id 才 resume；首轮没有 → 不传。
+    if (zcodeSessionId) argv.push("--resume", zcodeSessionId);
+
+    const child = spawn(process.execPath, argv, {
+      cwd: workdir,
+      detached: true, // 独立进程组 ⇒ 能整组杀
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let out = "";
+    let err = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      killTree(child);
+      reject(new Error(`ZCode 回合超时（${Math.round(timeoutMs / 1000)}s）`));
+    }, timeoutMs);
+
+    child.stdout.on("data", (d) => { out += d.toString(); });
+    child.stderr.on("data", (d) => { err += d.toString(); });
+
+    child.on("error", (e) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+
+      // 逐行解析 stream-json：事件行随时来，末行是 {type:"result"}
+      let result = null;
+      let events = 0;
+      for (const line of out.split("\n")) {
+        const t = line.trim();
+        if (!t || t[0] !== "{") continue;
+        let obj;
+        try { obj = JSON.parse(t); } catch { continue; }
+        if (obj && obj.type === "result") result = obj;
+        else events++;
+      }
+      if (!result) {
+        reject(new Error(
+          `ZCode 未返回 result 行（exit=${code}，事件 ${events} 条）` +
+            (err ? `；stderr: ${err.slice(-400)}` : "")));
+        return;
+      }
+      resolve({
+        sessionId: typeof result.sessionId === "string" && result.sessionId
+          ? result.sessionId
+          : zcodeSessionId,
+        response: typeof result.response === "string" ? result.response : "",
+        events,
+      });
+    });
+
+    // 供 close 时中断当前回合
+    currentChild = child;
+  });
+}
+
+let currentChild = null;
+
+async function handle(method, params) {
+  switch (method) {
+    case "ping": {
+      // 不启动 CLI：握手要快且确定（10s 上限）。
+      // 报出 CLI 版本 —— 插件的 ping 处理会认 pi_version/cli_version/version 三者之一。
+      return {
+        ok: true,
+        cwd: workdir,
+        // 握手阶段还没有 ZCode 会话；报插件给我们的标签即可
+        // （插件侧台账用它，真实 sess_... 在首轮 prompt 后才产生）。
+        session_id: zcodeSessionId || desiredSessionId || null,
+        cli_version: process.env.ZCODE_VERSION || null,
+        session_name: args.sessionName || null,
+        backend: "zcode",
+      };
+    }
+    case "prompt": {
+      const text = params?.text ?? "";
+      // ★ params.session_id 是**插件的标签**（br-xxx），不是 ZCode 的会话 id。
+      // 绝不能拿它当 --resume 目标 —— 那正是首轮必然失败的根因。
+      // 只在还没有真实 id 时记下它，供握手/state 回报用。
+      if (params?.session_id && !zcodeSessionId) {
+        desiredSessionId = String(params.session_id);
+      }
+      const timeoutMs = Number(params?.timeout_ms) > 0
+        ? Number(params.timeout_ms)
+        : 20 * 60 * 1000;
+      const r = await runTurn(text, timeoutMs);
+      // ★ 只在拿到真实 sess_... 时更新；空值不能覆盖已有 id
+      // （否则一次失败就把续谈能力抹掉）。
+      if (r.sessionId) zcodeSessionId = r.sessionId;
+      turnCount++;
+      return {
+        ok: true,
+        // ★ 必须回报 session_id：Go 侧据此断言「会话未漂移」
+        // 报真实 id（有则报它，否则退回插件的标签）。
+        session_id: zcodeSessionId || desiredSessionId || null,
+        reply: r.response,
+      };
+    }
+    case "state": {
+      return {
+        ok: true,
+        session_id: zcodeSessionId || desiredSessionId || null,
+        messages: turnCount,
+      };
+    }
+    case "close": {
+      killTree(currentChild);
+      return { ok: true };
+    }
+    default:
+      throw new Error(`unknown method: ${method}`);
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", async (line) => {
+  line = line.trim();
+  if (!line) return;
+  let req;
+  try { req = JSON.parse(line); } catch { return; }
+  try {
+    const result = await handle(req.method, req.params || {});
+    send({ jsonrpc: "2.0", id: req.id, result });
+    if (req.method === "close") process.exit(0);
+  } catch (e) {
+    send({
+      jsonrpc: "2.0",
+      id: req.id,
+      error: { code: -32000, message: String(e?.message || e) },
+    });
+  }
+});
+
+rl.on("close", () => {
+  killTree(currentChild);
+  process.exit(0);
+});