refactor(pi-bridge): 定下 lib/ 与 test/lib/ 的边界 —— 三个测试侧模块原来会随部署进 /opt

pi 复核后指出：`lib/` 会被 `cp -a "$SRC/." "$STAGING/"` **整份打进生产快照**
（排除清单只有 `test/`、`.git`、`node_modules/.cache`），而我们那三个测试侧模块
（`tmp-space.mjs`、`env-error.mjs`、`session-fixtures.mjs`）都住在 `lib/` 里。
后果不是几 KB，而是"漂移 N 处"这个数字**虚高**、哈希清单变长 ——
而"手抄哈希清单"正是我们刚定性为会过期的东西。

## 规则写成**可判定的**，不写成约定

    lib/      = 从生产入口可达的模块（会进快照）
    test/lib/ = 只被测试引用的模块（test/ 不部署、也不被注册进套件）

`test/lib/reach.mjs` 真去走一遍 import 闭包（种子 = `src/index.mjs` +
源码里 `new URL('./x.mjs', import.meta.url)` 这类**按路径 fork 的子进程入口**）。

★ 顺带纠正 pi 的规则表述：他写的是"被 `src/` import"，但实测 22 个 `lib/` 模块里
有 4 个 `src` **直接**引用数是 0 —— `addressing.js`（被 `lib/inbox-format.js` 引）、
`user-question.js`（走前缀动态 import）、`mail-session-id.js`、`crash-notify.mjs`。
**直接引用数不是可达性**，所以判据真走图而不是 grep。
★ 也纠正他的排除清单名字：脚本里没有 `EXCLUDE_DIRS` 这个变量，就是一条 `rm -rf`。

## 本规则多抓到一个 pi 没发现的

`lib/user-question.js` 也是**只被测试引用**（只有 `test/user-question.test.mjs` 用它）
⇒ 同样会进快照。已一并移到 `test/lib/`。剩下 `mail-session-id.js` 与
`crash-notify.mjs` 是**谁都不用**（生产与测试都不可达）—— 那是遗留物，
不动它们（不属本次范围），但记录在此。

## 新增：因果**无关**的运行期判据

`test/lib/run-suite.mjs`：跑套件并从**同一次运行的 TAP**里数结果行，任何用例名
出现两次就红。为什么需要：静态那条（测试文件不许互相 import）只能发现**已知成因**。
实测跨文件重名**不会被 runner 拦**：两个文件各写一个同名用例 ⇒
`# tests 2 / # pass 2 / # fail 0`，两句 `ok`，零警告。

判据锚在 `^(ok|not ok) <n> - <名字>`（**结果行**），不是"名字出现过"——
pi 先前那条 `grep -c '<名字>'` 给 4 是因为 TAP 里名字既出现在 `# Subtest:` 头、
又出现在结果行，**2 倍效应 + 2 倍噪声恰好同值**，若行种类是 3 就会把两次读成三次。
本脚本自带 `--self-check`（干净样本放行 / 重复样本点名 / 只出现在头里的不算重复 /
名字含 `#` 不被截断）。

`package.json` 的 `test` 改为：
    node test/lib/env-preflight.mjs && node test/lib/run-suite.mjs

## 判据全进套件

`test/layout-boundaries.test.mjs`（新）：生产可达性不碰 `test/`、`test/lib/` 里不许藏
运行时模块、测试文件不许互相 import、`npm test` 必须接上 run-suite 那一层。
原来放在 `env-guard.test.mjs` 里那条"夹具不在测试文件里"已移到这里（集中边界判据）。

## 变异自检（两条都实测红了才留下）

- 造一个与巨行用例**同名**的探针文件 ⇒ `npm test` exit 1 并点名
  `2× ★巨大的 message 行不进内存也不影响解析`；
- 往 `src/gateway.mjs` 加一行指向 `test/lib/run-suite.mjs` 的真 import ⇒
  边界判据红并指出 `生产可达了测试代码：test/lib/run-suite.mjs`。
  两条探针均已删除、`src/gateway.mjs` 用 `git checkout` 还原并 `cmp` 校验一致。

顺带修一处路径：`env-guard.test.mjs` 里 `PREFLIGHT` 仍指向旧的 `test/env-preflight.mjs`
（前置脚本已移入 `test/lib/`）。

验证：`npm test` **462/462**、结果行重复检查 0 个重名、set 全绿。

plugins/pi-mail-bridge/lib/env-error.mjs

@@ -1,55 +0,0 @@
-/**
- * 「临时目录写不进去」⇒ 人话。**纯函数，可被反面样本喂**。
- *
- * # 为什么它必须是一个函数，而不是散在写点里的 try/catch
- *
- * 2026-09-14 实测：`/tmp` 是满的 tmpfs，`bavail` 一度真是 **0**。此时这条
- * `npm test` 红的是
- *
- *     not ok 323 - ★巨大的 message 行不进内存也不影响解析
- *       error: 'ENOSPC: no space left on device, write'
- *
- * 那条红的**形状指向内存**（用例名里就写着"不进内存"，而它恰好是往临时目录
- * 写文件的用例）⇒ 下一个踩到的人会去 `session-scan.mjs` 找一个**不存在**的
- * 内存缺陷。翻译成人话（"这是环境问题，不是内存缺陷"）就治这个。
- *
- * # 为什么抽出来（只有一个调用点也值得抽）
- *
- * **不是为了复用，是为了可被反面样本喂**：`translateEnvError` 能被直接喂一个
- * 构造出来的 ENOSPC 错误，验"该翻译的翻译了、不该翻译的原样返回"。
- * 反例：第一版把这个判断留在 `session-scan.test.mjs` 里，判据只能靠**读源码文本**
- * （断言文件里出现 `/ENOSPC/`）—— 而那段解释性注释里本来就有 "ENOSPC" 这个词，
- * 于是**删掉整个翻译逻辑、只留注释，判据照样绿**。这正是
- * `permission-note.test.mjs` 警告过的"钉装饰不钉机制"。
- *
- * # 为什么不去和 `deploy/check-deploy-drift.mjs` 的 `describeEnvError` 合并
- *
- * 判据相同、措辞不同，看起来该合并 —— 但不合：**`deploy/` 的独立性比去重值钱**
- * （那份文件头整段在讲"服务不该依赖仓库是否存在"，`deploy/` 下的工具同理，
- * 让它 import 插件目录里的模块等于把它绑死在插件的目录结构上）。
- * **第三份拷贝出现时再考虑共用。**
- *
- * # 变异自检的纪律（这条是踩出来的）
- *
- * 验证本函数"真的被接上"要注入变异（删掉调用、看判据红不红）。做这件事时：
- * **先证明你能撤回来，再注入**；而且**还原路径不能依赖被测对象** ——
- * 2026-09-14 那次把备份写进 `/tmp`（正是当时被占满的那个资源），备份没写成，
- * 变异却已经覆盖了源文件。现在只对"已在 HEAD 里干净提交"的文件做变异，
- * 还原一律走 `git checkout HEAD -- <file>`。
- *
- * @param {unknown} e 捕获到的错误
- * @returns {{ translated: boolean, error: Error }} 翻译过的新错误，或原样返回
- */
-export function translateEnvError(e) {
-  const message = e && typeof e.message === 'string' ? e.message : String(e ?? '');
-  const isEnospc = (e && e.code === 'ENOSPC') || /no space left on device/i.test(message);
-  if (!isEnospc) return { translated: false, error: e };
-
-  const err = new Error(
-    '环境不足：临时目录写不进去（ENOSPC）—— 这是环境问题，不是内存缺陷。' +
-    '药方：TMPDIR=<有空间的目录> npm test'
-  );
-  err.code = 'ENOSPC';
-  err.cause = e;
-  return { translated: true, error: err };
-}

plugins/pi-mail-bridge/lib/session-fixtures.mjs

@@ -1,61 +0,0 @@
-/**
- * 会话文件的测试夹具（**不是测试模块**）。
- *
- * # 一、为什么放在 `lib/` 而不是 `test/` 里
- *
- * `node --test` 默认**每个文件一个子进程**，但 `import` 是进程内的。所以
- * `env-guard.test.mjs` 里 `import { writeSession } from './session-scan.test.mjs'`
- * 会把**整个 `session-scan.test.mjs` 的用例在那个进程里再注册一遍** ——
- * 2026-09-14 实测确认：巨行用例（单条写 ~12 MiB）在 TAP 里出现**两次**
- * （`ok 87` 与 `ok 353`），也就是那条用例被跑了两次、往临时目录写了两次。
- * 这台机器的 `/tmp` 正是被这次事件的主角（tmpfs 满）—— 判据自己加倍压它是自伤。
- *
- * 这跟 `translateEnvError` 被抽到 `lib/env-error.mjs` 是同一个手法、同一个理由：
- * **可被别的模块引用，而不被注册进套件。**
- *
- * # 二、写点必须全部被兜住
- *
- * `session-scan.test.mjs` 的第一版只把 `writeFileSync` 包在 try 里，
- * 而 `mkdirSync` 在 try 之外 —— 目录建不出来时（ENOSPC 也可能从这里出来）
- * 抛的仍是原始英文堆栈。所以这里**整段**包一层，与 `selfCheck()` 那条同一个形状：
- * **覆盖范围不能取决于"我以为的入口/哪一行"**。
- *
- * ENOSPC 一律翻译成"环境不足"（`lib/env-error.mjs`）—— 不管套件是怎么被调起来的
- * （`npm test` 会先跑 `test/env-preflight.mjs`，但 `node --test 'test/*.test.mjs'`
- * 会绕过它，那就只剩这一道）。
- */
-
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-import { translateEnvError } from './env-error.mjs';
-
-/**
- * 写一条会话文件。`lines` 是 header 之后的行（对象，会被 JSON 化）。
- *
- * `write` 只为测试存在（默认 `writeFileSync`）：让"ENOSPC 被翻译"这件事
- * 能被**行为**判据验证 —— 喂一个必然 ENOSPC 的假写，而不是去 grep 源码文本
- * （注释里本来就有 "ENOSPC" 这个词，文本判据会被注释满足）。
- *
- * @param {string} root 根目录
- * @param {string} cwdSlug 该 cwd 的子目录名
- * @param {string} fileName 文件名
- * @param {object} header 会话 header
- * @param {object[]} lines 后续行
- * @param {(file: string, body: string) => void} [write] 写实现（测试用接缝）
- * @returns {string} 写出的文件路径
- */
-export function writeSession(root, cwdSlug, fileName, header, lines = [], write = writeFileSync) {
-  const dir = join(root, cwdSlug);
-  const file = join(dir, fileName);
-  const body = [JSON.stringify({ type: 'session', version: 3, ...header })]
-    .concat(lines.map((l) => JSON.stringify(l)))
-    .join('\n');
-  try {
-    mkdirSync(dir, { recursive: true });
-    write(file, `${body}\n`);
-  } catch (e) {
-    throw translateEnvError(e).error;
-  }
-  return file;
-}

plugins/pi-mail-bridge/lib/tmp-space.mjs

@@ -1,94 +0,0 @@
-/**
- * 临时目录空间：**测量与判据分开**。
- *
- * # 为什么要有这个东西
- *
- * 2026-09-14 实测（本机）：`/tmp` 是 tmpfs，9.8G 被占满，`bavail` 只剩
- * **0.70 MiB**（`statfs` 实读）。此时跑 `npm test` 会红一条
- * `★巨大的 message 行不进内存也不影响解析`，报 `ENOSPC`。
- *
- * 那条红**看起来像内存缺陷**（用例名里就写着"不进内存"，而它恰好是往临时目录
- * 写文件的用例）。下一次踩到的人会去读 `session-scan.mjs` 找内存 bug —— 找的是
- * 一个**不存在**的东西。环境不足伪装成断言失败，是这个文件存在的全部理由。
- *
- * # 判据的形状（与仓库既有约定一致）
- *
- * - 这里只有**纯函数**：喂进"还剩多少字节"，吐出"够不够"。测量在
- *   `measureAvailBytes()`（同文件导出，因为它要能被喂"不存在的目录"做反面样本），
- *   纯函数才可被反面样本喂。
- * - **读不到不判红**：`availBytes` 为 `null`（`statfsSync` 抛错 / 平台不支持 /
- *   `statfs.bsize` 为 0 ⇒ 测量层返回 `null`）时返回 `ok: true` 并注明"不据此判定"。
- *   **不知道 ≠ 不对** —— 不确定就放行，否则会在不认识的文件系统上制造一条总在亮的
- *   红灯，而"总在亮的红灯"会被人学会忽略（`deploy/check-deploy-drift.mjs` 文件头骂过）。
- * - ★ 但**可用字节数为 0 不是"没测到"**，是"真的没有"：它必须判红。第一版把
- *   `<= 0` 一并当"不知道"，于是 `bavail` 只剩 712 字节时前置自检放行、紧接着
- *   17 条用例 ENOSPC 全红 —— 守卫装在最该拦的时候放行，等于没装。
- *   （2026-09-14 踩的；这条注释写错过一次，pi 读第一遍就误读成了"0 也算不知道"，
- *   所以这里把两个 case 分开写死。）
- */
-
-import { statfsSync } from 'node:fs';
-
-/** 单条用例的最大临时写入量（实测）：`test/session-scan.test.mjs` 那条用例
- *  写 3 条 3 MiB 的行（两条巨行 + 一条正常行）⇒ 约 12 MiB。 */
-export const MEASURED_MAX_CASE_WRITE = 12 * 1024 * 1024;
-
-/**
- * 前置自检要求的最小可用空间。
- *
- * 取"实测用例写入量 × 2 + 8 MiB 机动"＝ 32 MiB，**不是**总容量的百分比：
- * 百分比在 9.8G 的 tmpfs 上会给出一个和这套测试毫无关系的数，而这里要挡的是
- * "一条 12 MiB 的用例写不进去"。×2 是因为临时目录可能同时有别的写入方
- * （本机 `npm test` 之外还跑着 agent 的会话文件）。
- */
-export const MIN_FREE_BYTES = MEASURED_MAX_CASE_WRITE * 2 + 8 * 1024 * 1024;
-
-const mib = (n) => `${(n / 1048576).toFixed(1)} MiB`;
-
-/**
- * 测量：进程**实际能写**的字节数。读不到返回 `null`。
- *
- * 放在这里（而不是 `test/env-preflight.mjs` 里）的唯一理由是**可被反面样本喂**：
- * `measureAvailBytes('/definitely/not/here')` 这条判据在任何机器上都跑得了，
- * 而"读不到 ⇒ null ⇒ 放行"这一支否则就没有不依赖机器状态的判据覆盖
- * —— 端到端那条一旦因 `/tmp` 被清空而跳过，就没人管这一支了。
- *
- * @param {string} dir 要量的目录，默认 `os.tmpdir()`
- * @returns {number|null} 可用字节数；读不到/不支持/`bsize` 为 0 ⇒ `null`
- */
-export function measureAvailBytes(dir) {
-  try {
-    if (typeof statfsSync !== 'function') return null;   // Node < 18.15
-    if (typeof dir !== 'string' || dir === '') return null;
-    const s = statfsSync(dir);
-    if (!s || !s.bsize) return null;                     // bsize=0 ⇒ 量不出字节数
-    // 用 `bavail`（非特权进程可用的块数），**不是** `bfree`（含 root 保留块）：
-    // 这里回答的是"我写不写得进去"，不是"机器上空闲多少"。
-    return s.bavail * s.bsize;
-  } catch {
-    return null;                                         // 不知道 ≠ 不对
-  }
-}
-
-/**
- * @param {{ availBytes: number|null, needBytes?: number }} args
- *   `availBytes` 为 `null` 表示"没测到"（读不到、平台不支持、`bsize` 为 0）。
- * @returns {{ ok: boolean, known: boolean, note: string }}
- */
-export function judgeSpace({ availBytes, needBytes = MIN_FREE_BYTES }) {
-  // `null` / `NaN` 才是"没测到"。**注意 0 不是"没测到"** ——
-  // `statfsSync` 说不出话时会抛（已在测量层转成 null），它若返回 0，
-  // 意思就是"真的一点空间都没有"（实测踩过：把 `<= 0` 一并当"不知道"，
-  // 于是 `bavail` 只剩 712 字节时前置自检放行，接着 17 条用例 ENOSPC 全红）。
-  if (availBytes === null || availBytes === undefined || Number.isNaN(availBytes)) {
-    return { ok: true, known: false, note: '没测到可用空间（读不到或平台不支持）—— 不据此判定' };
-  }
-  if (availBytes >= needBytes) {
-    return { ok: true, known: true, note: `可用 ${mib(availBytes)} ≥ 需要 ${mib(needBytes)}` };
-  }
-  return {
-    ok: false,
-    known: true,
-    note: `可用 ${mib(availBytes)} < 需要 ${mib(needBytes)}`,
-  };
-}

plugins/pi-mail-bridge/lib/user-question.js

@@ -1,176 +0,0 @@
-/**
- * `ask_user_question` ↔ AgentMail 询问邮件 的双向映射（纯函数）。
- *
- * # 为什么需要它
- *
- * DSH 的 `ask_user_question` 走 `ctx.userQuestions` 这个 UI seam，而邮件驱动的
- * 会话**没有本地 UI**。不桥接的后果是模型主动提问后永久挂死：`ask()` 的
- * promise 永远不 resolve，那一轮工具调用卡在那里，人却什么也看不到。
- *
- * # 两个模型的形状差异
- *
- * DSH：`{ questions: [{ id, question, header?, options?: [{label, description?}],
- *                       multiSelect? }] }` → `{ answers: [{ id, selected[], custom? }] }`
- *   - 一次可以问**多个**问题，每个问题可有自己的选项与多选语义
- *   - 答案按问题 id 回填，选项用 label 字符串
- *
- * AgentMail：一封询问邮件 = 一个问题 + 一个选项列表 + 一个 multi_select 标志
- *   - 只有单问题结构，因此多问题时必须摊平
- *
- * # 摊平策略（多问题时）
- *
- * 选项取所有问题 label 的并集（去重、保持首次出现顺序），并把每个问题的
- * 原文、选项与说明枚举进 context 正文。回信时按「label 属于哪个问题」把
- * 选择分配回去。这比「一问一封邮件」简单得多 —— 后者要等人分别回复多封
- * 才能凑齐一次 `ask()` 的答案，而 `ask()` 是**单次**调用，凑不齐就还是挂死。
- *
- * # fail closed
- *
- * 认不出的答案一律不猜测；没有匹配到任何选项的问题返回空选择 + 把自由文本
- * 放进 custom，而不是随便挑一个 label 放行。
- */
-
-/** 问题是否带可选项。 */
-export function hasOptions(question) {
-  return Array.isArray(question?.options) && question.options.length > 0;
-}
-
-/** 一个 DSH 问题的可选项 label 列表（保序）。 */
-export function optionLabels(question) {
-  if (!hasOptions(question)) return [];
-  return question.options
-    .map((o) => (typeof o === 'string' ? o : o?.label))
-    .filter((l) => typeof l === 'string' && l.length > 0);
-}
-
-/** 一个问题的展示标题：header 有就用它做前缀，否则只用 question。 */
-export function questionTitle(question) {
-  const header = typeof question?.header === 'string' ? question.header.trim() : '';
-  const text = typeof question?.question === 'string' ? question.question.trim() : '';
-  if (header && text) return `${header}: ${text}`;
-  return header || text || '(未提供问题)';
-}
-
-/**
- * 把 DSH 的 questions 摊平成一封 AgentMail 询问邮件的正文与元数据。
- *
- * @param {Array<object>} questions DSH AskUserQuestionItem[]
- * @returns {{ question: string, options: string[], context: string, multiSelect: boolean }}
- */
-export function flattenQuestions(questions) {
-  const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
-  if (list.length === 0) {
-    throw new Error('ask_user_question 至少需要一个 question');
-  }
-
-  const lines = [];
-  const options = [];
-  const seen = new Set();
-  let anyMulti = false;
-
-  list.forEach((q, i) => {
-    const title = questionTitle(q);
-    lines.push(`${i + 1}. ${title}`);
-    const detail = typeof q?.detail === 'string' ? q.detail.trim() : '';
-    if (detail) lines.push(`   ${detail}`);
-
-    const labels = optionLabels(q);
-    if (labels.length > 0) {
-      lines.push(`   可选项：${labels.join(' / ')}${q.multiSelect ? '（可多选）' : ''}`);
-      for (const label of labels) {
-        if (!seen.has(label)) {
-          seen.add(label);
-          options.push(label);
-        }
-      }
-    } else {
-      lines.push('   （请直接填写回答）');
-    }
-    if (q?.multiSelect === true) anyMulti = true;
-  });
-
-  // 多问题时必须允许多选：不同问题的选项要能一起勾选。
-  const multiSelect = list.length > 1 ? options.length > 0 : anyMulti;
-
-  const question = list.length === 1 ? questionTitle(list[0]) : `${list.length} 个问题待回答`;
-  const context = [
-    list.length === 1 ? '' : '模型提出了多个问题，请在「回复」里一并回答：',
-    ...lines,
-    '',
-    options.length > 0
-      ? '可直接勾选下方的选项；补充说明写在备注里。'
-      : '这题没有预设选项，请把回答写在备注里。',
-  ].filter((l) => l !== '').join('\n');
-
-  return { question, options, context, multiSelect };
-}
-
-/**
- * 把人类的决策回写成 DSH 的 answers[]。
- *
- * @param {Array<object>} questions 原始 DSH questions（回填 id 用）
- * @param {string} decision 人类选的选项原文（多选时前端用换行分隔）
- * @param {string} [note] 自由文本/备注
- * @returns {{ answers: Array<{id: string, selected: string[], custom?: string}> }}
- */
-export function answersFromDecision(questions, decision, note) {
-  const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
-  const labels = String(decision || '')
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
-  const custom = typeof note === 'string' ? note.trim() : '';
-
-  // 单问题：忠实映射（选项 → selected，备注 → custom）。
-  if (list.length === 1) {
-    const q = list[0];
-    const id = String(q?.id ?? '0');
-    if (!hasOptions(q)) {
-      // 无选项题：人类把答案写在决策文本或备注里，都属于「自由文本回答」。
-      const text = custom || labels.join('\n');
-      return { answers: [{ id, selected: [], ...(text ? { custom: text } : {}) }] };
-    }
-    return {
-      answers: [{
-        id,
-        selected: labels,
-        ...(custom ? { custom } : {}),
-      }],
-    };
-  }
-
-  // 多问题：按 label 归属把选择分配给各自的问题；备注归给第一个问题。
-  let customUsed = false;
-  const answers = list.map((q, i) => {
-    const id = String(q?.id ?? String(i));
-    const labels_q = optionLabels(q);
-    const selected = labels.filter((l) => labels_q.includes(l));
-    let qCustom;
-    if (custom && !customUsed) {
-      qCustom = custom;
-      customUsed = true;
-    }
-    // 无选项题且人没写备注：退而把决策文本整段给它（否则它的答案永远是空的）。
-    if (qCustom === undefined && !hasOptions(q) && note === undefined) {
-      const text = labels.join('\n');
-      if (text) qCustom = text;
-    }
-    return { id, selected, ...(qCustom ? { custom: qCustom } : {}) };
-  });
-
-  return { answers };
-}
-
-/**
- * 决策是否「什么都没答」——用来在提交前拦住空回答（不把空答案喂给模型）。
- *
- * 允许多选时空 selected 但有 custom 也算答了；两者都空才算没答。
- */
-export function isBlankAnswer(questions, decision, note) {
-  const labels = String(decision || '').split('\n').map((s) => s.trim()).filter(Boolean);
-  const custom = typeof note === 'string' ? note.trim() : '';
-  if (labels.length > 0 || custom) return false;
-  // 全部问题都没有选项、人也没写字 → 确实什么都没答
-  const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
-  return list.some((q) => hasOptions(q)) || list.length === 0;
-}