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。

plugins/zcode-mail-bridge/test/workspace.test.mjs

@@ -0,0 +1,128 @@
+/**
+ * 工作目录解析的回归测试。
+ *
+ * 这是「dsh 指定工作目录完全失效，所有对话都落在未分组下」那次故障的直接回归：
+ * 插件曾无视寻址里的 path 位，每封邮件自己拼一个 ~/.dsh/mail-sessions/mail-<uuid>，
+ * 而 DSH 按 cwd 分组，于是所有邮件会话既不属于任何项目、彼此也不同组。
+ *
+ *   node --test test/
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveWorkspaceCwd, ensureCwd, mailSessionFallback } from '../lib/workspace.js';
+
+// 兜底目录现在由调用方给（各平台不同）。DSH 用 mailSessionFallback，
+// opencode 用插件启动时的 directory。
+const fallbackOf = key => mailSessionFallback(key);
+
+test('存在的绝对路径直接用作 cwd', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
+  try {
+    const got = resolveWorkspaceCwd(dir, fallbackOf('mail-1'));
+    assert.equal(got.cwd, dir);
+    assert.equal(got.grouped, true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('不变量：同一 path 的多封邮件得到同一个 cwd（这才能同组）', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
+  try {
+    const a = resolveWorkspaceCwd(dir, fallbackOf('mail-aaa'));
+    const b = resolveWorkspaceCwd(dir, fallbackOf('mail-bbb'));
+    assert.equal(a.cwd, b.cwd, 'fallbackKey 不同却应得到同一个 cwd');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('path 为空时回退到兜底目录', () => {
+  const got = resolveWorkspaceCwd('', fallbackOf('mail-2'));
+  assert.equal(got.cwd, fallbackOf('mail-2'));
+  assert.equal(got.grouped, false);
+});
+
+test('path 缺失/非字符串时回退', () => {
+  for (const v of [undefined, null, 42, {}]) {
+    const got = resolveWorkspaceCwd(v, fallbackOf('mail-3'));
+    assert.equal(got.grouped, false);
+    assert.equal(got.cwd, fallbackOf('mail-3'));
+  }
+});
+
+test('不变量：不存在的目录不创建，回退到兜底', () => {
+  // 一个笔误（/home/porgram/x）不该在磁盘上落下真目录 ——
+  // Agent 会在里面一无所获地干活，比明确回退更难排查。
+  const got = resolveWorkspaceCwd('/nonexistent/path/xyz-should-not-exist', fallbackOf('mail-4'));
+  assert.equal(got.grouped, false);
+  assert.equal(got.cwd, fallbackOf('mail-4'));
+});
+
+test('不变量：相对路径被拒绝', () => {
+  // cwd 的相对基准是 harness 进程的启动目录，systemd 下通常是 /，
+  // 那是个与邮件语义完全无关的量。
+  for (const rel of ['relative/path', './x', '../y', 'src']) {
+    const got = resolveWorkspaceCwd(rel, fallbackOf('mail-5'));
+    assert.equal(got.grouped, false, `${rel} 不该被当作工作目录`);
+  }
+});
+
+test('指向文件而非目录时回退', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
+  const file = join(dir, 'a-file');
+  writeFileSync(file, 'x');
+  try {
+    const got = resolveWorkspaceCwd(file, fallbackOf('mail-6'));
+    assert.equal(got.grouped, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('两端空白被修掉', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ws-test-'));
+  try {
+    const got = resolveWorkspaceCwd(`  ${dir}  `, fallbackOf('mail-7'));
+    assert.equal(got.cwd, dir);
+    assert.equal(got.grouped, true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('ensureCwd 只建兜底目录，不碰寻址指定的目录', () => {
+  const base = mkdtempSync(join(tmpdir(), 'ws-ensure-'));
+  try {
+    const target = join(base, 'made-by-ensure');
+    ensureCwd(target, false);
+    // 建出来了
+    const got = resolveWorkspaceCwd(target, '');
+    assert.equal(got.grouped, true, 'ensureCwd 应已创建该目录');
+
+    // grouped=true 时不该创建（那种目录本来就存在）
+    const never = join(base, 'should-not-exist');
+    ensureCwd(never, true);
+    assert.equal(resolveWorkspaceCwd(never, '').grouped, false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('兜底为空串时返回空 cwd（交给平台自己决定）', () => {
+  // opencode 没配 directory 时就是这种情况：session.create 不带 query.directory，
+  // 由平台按自己的默认规则选目录。比硬塞一个我们猜的路径好。
+  const got = resolveWorkspaceCwd('', '');
+  assert.equal(got.cwd, '');
+  assert.equal(got.grouped, false);
+});
+
+test('mailSessionFallback 同一 key 稳定、不同 key 不同', () => {
+  assert.equal(mailSessionFallback('a'), mailSessionFallback('a'));
+  assert.notEqual(mailSessionFallback('a'), mailSessionFallback('b'));
+  assert.match(mailSessionFallback('a'), /mail-sessions/);
+});