feat(zcode): 邮件驱动 —— 收到来信就自动开工，并把结论回信

第三步（补齐一等 Agent 的另一半）：驱动进程订阅 SSE，按邮件起一轮 headless
ZCode，取最终文本回信。

## --mode 是必传的（不传等于关掉授权系统）

ZCode 的权限判定里 `mode === "yolo"` 一律 allow
（"Yolo mode bypasses permission prompts"），而 `--prompt` 的默认 mode **就是 yolo**。
所以驱动不传 --mode 时：授权钩子根本不会触发，整个授权系统**静默消失** ——
不报错，只是没有任何询问，看起来一切正常。

档位映射（依据是 CLI 产物里的规则表，不是猜）：
  plan → --mode plan    （mode.plan.nonReadOnly：非只读一律拒）
  workspace → --mode build（mode.build.highRisk / sideEffect：Bash/Write/Edit → ask）
  full → --mode yolo    （刻意绕过）
buildRunArgs 收不到 mode 直接抛错；测试里有一条反向对照钉住「只有 full 能得到 yolo」，
含大写 FULL（共用库 normalizeMode 严格匹配，落回 default 而不是 yolo —— 好性质，也钉住）。

## 一轮怎么跑

  node <zcode.cjs> --prompt <提示词> --output-format stream-json \
       --cwd <工作目录> --mode <m> [--resume sess_xxx] --max-turns N

用 stream-json 而不是 --json：`--json` 全程无输出，一个卡住的回合与一个正在
干活的回合在外部完全一样，而邮件驱动的会话没有界面，日志是唯一能看见它的地方。
输出契约（逐条事件 + 末尾 {type:"result",sessionId,response}）同样逆自 CLI 产物。
会话延续靠 --resume + 存回的 sess_…：丢了它模型每封信都从零开始。

## 回信策略（与另三桥同源）

- 人来信 → 自动把本轮最终文本回过去（relay:'summary' + relay_key 走免配额通道）
- Agent 来信 → **不**自动回（Agent 间必须自己 send_mail，否则两边把对方的
  「已收到」当待办，无限客套）
- 一轮跑不起来 → **必回**失败信，且给出 ZCode 自己的成因（没登录/缺模型配置/
  CLI 路径不对）。没有本地界面时，什么都不发等于「信发出去了，然后再无音讯」。
  刻意不复用共用库那份 renderFailureReport：它的建议是「调整可用模型范围」，
  对 ZCode 什么也解决不了。
- 模型这一轮自己发过信 → 让位。工具跑在 ZCode 派生的 MCP 服务器**进程**里，
  与驱动内存不通，所以经 lib/explicit-sends.mjs 落盘对齐（不记的后果线上实测过：
  收件箱里两封说同一件事的邮件，311 与 342 字节）。

## 两处健壮性（都是实现时自己发现的真问题）

- 超时必须**必然** settle：既不退也不报错的孩子会让 Promise 永不 settle，
  而队列是串行的 → 那封信永远挂住、后面的信全都不再被处理。
  现在 SIGTERM → SIGKILL → 无论如何收尾；定时器刻意不 unref
  （unref 过的定时器让「没有其它句柄」的进程直接退出，收尾根本没机会跑）。
- 关停时终止在途回合：否则 systemd 杀掉驱动后那个 ZCode 还在跑工具，
  而既没有驱动看着它、也没有本地界面看着它。

## 自报强制力只声明得出来的事

驱动启动时读自己的 hooks/hooks.json，确认 PermissionRequest 已注册才报 native，
否则报 advisory 并在日志里写明原因 —— 不替一个不存在的能力背书。

## 验证

- 单元 320/320（新增 90 项：turn-mode 8、zcode-run 17、driver 19、prompt 14 +
  继承的共用测试；含反向对照）
- 邮件驱动端到端 7/7 × 3 次连跑稳定：桩 CLI 替掉 ZCode，真网关真邮件 ——
  SSE 订阅、去重、工作目录、档位映射、参数拼装（--mode 必须对）、
  stream-json 解析、回信、Agent 来信不回、CLI 失败必回失败信
- 授权桥端到端 5/5 × 3 次连跑稳定
- 共用模块四方同源（新纳入 catchup/relay-dedup/relay-policy/workspace，
  反向验证：让 workspace.js 分叉会被抓住）

## 我自己写错并被测试抓出来的三处（值得记）

1. 验证脚本把人类发信写成了 /api/v1/mail/send（**Agent** 路由）→ 401。
   报错「Missing Authorization: Bearer …」其实已经指明走错了路由表。
2. findReply 按「驱动验证（人）」这种片段找，第二次跑时命中了**上一轮遗留的回信**
   → 正文比对失败、后续参数核对变成「无法判定」。收件箱是跨轮次共享的持久状态，
   必须按唯一 marker 定位（与之前「待决权限列表」那次是同一类错误）。
3. 停旧驱动只发 SIGTERM 不等退出 → 新旧两个驱动同时订阅 SSE，
   同一封信被回两次，判据取到哪封取决于时序 → 时灵时不灵。改成等 exit 事件。
   另：桩脚本用 process.exit 截断管道写入，导致 stderr 时有时无 —— 改用 exitCode。

deploy/check-shared-libs.sh

@@ -27,12 +27,19 @@ PEERS=(plugins/dsh-mail-bridge plugins/pi-mail-bridge plugins/zcode-mail-bridge)
 ALL_LIBS="relay-dedup relay-policy relay-key permission-mode bounded inbox-format session-snapshot workspace model-scope catchup addressing discovery rename-proposal permission-grants adopt sse-client user-question attachment-ids"
 ALL_TESTS="relay-policy relay-key permission-mode bounded inbox-format session-snapshot workspace model-scope catchup addressing discovery rename-proposal permission-grants adopt sse-client user-question attachment-ids"
 
-# MCP 工具服务器 + 授权钩子用到的子集（实现与测试都同步）。
-# 钩子这一层额外需要 permission-mode / relay-key / permission-grants / sse-client ——
-# 档位语义、relay_key 截断、决策判定与 SSE 帧解析都必须与三桥同源，
-# 否则「同意」的含义会在 ZCode 上悄悄变得不一样。
-MCP_LIBS="addressing inbox-format bounded discovery attachment-ids permission-mode relay-key permission-grants sse-client"
-MCP_TESTS="addressing inbox-format bounded discovery attachment-ids permission-mode relay-key permission-grants sse-client"
+# MCP 工具服务器 + 授权钩子 + 邮件驱动用到的子集（实现与测试都同步）。
+#
+# 钩子与驱动这一层额外需要：
+#   permission-mode / relay-key / permission-grants / sse-client
+#     —— 档位语义、relay_key 截断、决策判定、SSE 帧解析
+#   catchup / relay-policy / workspace / relay-dedup
+#     （relay-dedup 在基准那边也没有独立测试，故只比对实现）
+#     —— 停机补投、主动发信去重、回信策略、工作目录解析
+#
+# 这些都不能各平台自己写一份：「同意」的含义、谁该收到回信、同一封邮件
+# 会不会被转两次 —— 分叉的后果都是只在单平台复现的行为差异。
+MCP_LIBS="addressing inbox-format bounded discovery attachment-ids permission-mode relay-key permission-grants sse-client catchup relay-dedup relay-policy workspace"
+MCP_TESTS="addressing inbox-format bounded discovery attachment-ids permission-mode relay-key permission-grants sse-client catchup relay-policy workspace"
 
 # ── 判据：用 cmp，不用 diff ─────────────────────────────────────────
 #

deploy/zcode-mail-bridge.service

@@ -0,0 +1,42 @@
+[Unit]
+Description=zcode mail-bridge (AgentMail ↔ ZCode headless CLI)
+Documentation=file:/home/program/agentmail/plugins/zcode-mail-bridge/README.md
+After=network-online.target agentmail-gateway.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+
+# 驱动自己不需要工作目录（每一轮 cwd 来自邮件寻址的 path 位），
+# 但 systemd 要求一个存在的目录，且相对路径（`../hooks/hooks.json` 的自检）
+# 以进程启动位置为准。
+WorkingDirectory=/home/program/agentmail/plugins/zcode-mail-bridge
+ExecStart=/usr/bin/node /home/program/agentmail/plugins/zcode-mail-bridge/src/index.mjs
+
+# ZCode 靠 HOME 定位 ~/.zcode（OAuth 凭据、cli/config.json、会话库、日志）。
+# systemd 不会自动注入 HOME，不显式给就：
+#   - 读不到登录凭据 → 每一轮都报「Model config is missing」，全部回成失败信
+#   - 插件发现落到 /.zcode → 空目录，MCP 工具一个都没有
+Environment=HOME=/root
+
+EnvironmentFile=/etc/agentmail/zcode.env
+
+Restart=always
+RestartSec=10
+
+# 异常退出邮件上报：进程内的钩子捕获不了 SIGKILL/OOM，只能由 systemd 覆盖。
+# 正常 stop/restart 不上报（脚本内 isAbnormalExit 提前返回）。
+ExecStopPost=-/usr/bin/node /home/program/agentmail/deploy/service-failure-notify.mjs --report --service zcode-mail-bridge.service
+# 补发上次网关不可达时暂存的报告（per-agent spool）
+ExecStartPost=-/usr/bin/node /home/program/agentmail/deploy/service-failure-notify.mjs --flush --service zcode-mail-bridge.service
+
+# 一轮 ZCode 会派生一个 node 进程（模型 + 工具），内存占用比另三个桥高。
+# 给一个上限让它被 OOM killer 挑中而不是拖垮整机；Restart=always 会拉回来。
+MemoryMax=4G
+
+# 停机：驱动收到 SIGTERM 后会终止在途回合（否则会留下跑工具的孤儿），
+# 再关掉 SSE。默认 90 秒太长，15 秒够。
+TimeoutStopSec=15
+
+[Install]
+WantedBy=multi-user.target

deploy/zcode.env.example

@@ -0,0 +1,31 @@
+# zcode 邮件驱动（deploy/zcode-mail-bridge.service）的 EnvironmentFile。
+#
+# 与 pi / opencode / dsh 三桥**同一套变量名** —— 同名同义，排障时才不用
+# 每换一个平台就重新记一遍。
+AGENTMAIL_GATEWAY_URL=http://127.0.0.1:8180
+AGENTMAIL_AGENT_NAME=zcode
+
+# 凭据。用注册时的 secret（X-Agent-Secret）：
+# 管理员密钥（AGENTMAIL_AGENT_KEY）登记后可以换成它，两者服务端都认。
+# 驱动启动时会打印用的是哪一种。
+# AGENTMAIL_AGENT_SECRET=<在 /root/gotmp/zcode-agent-secret.txt>
+
+# 驱动与插件（MCP 服务器、授权钩子）共用这两个目录，**必须一致**：
+# 授权表（「一直同意」）与主动发信记录都落在这里，两边解析出不同路径
+# 就会出现「刚点过一直同意又问你一遍」「模型自己发过了又被自动转发一遍」。
+AGENTMAIL_CONFIG_DIR=/root/.agentmail-zcode
+
+# 没有 to_workspace 时的兜底目录根。每一轮会在它下面按会话 id 建子目录。
+AGENTMAIL_WORKSPACE_ROOT=/root/.agentmail-zcode/workspaces
+
+# 一轮的上限。ZCode 要跑模型 + 工具，比另三个桥宽一些。
+# 必须**小于** systemd 的 TimeoutStopSec 无关，但与限制同一量级以免长跑占满串行队列。
+AGENTMAIL_TURN_TIMEOUT_MS=1200000
+
+# ZCode CLI 入口（纯 CLI，不是 Electron GUI 入口）。
+AGENTMAIL_ZCODE_CLI=/opt/ZCode/resources/glm/zcode.cjs
+
+# 仓库内进程固定用系统 node（/usr/bin/node v22），与官方插件硬编码的
+# 工具链 node 分开，避免某天工具链升级把驱动带走。
+# 注：这里不设 PATH —— 插件清单里 MCP 服务器的 `command: node`
+# 由 ZCode 继承本进程的 PATH 解析，systemd 默认 PATH 含 /usr/bin。