jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
664 Commits 1 Branch 0 Tags
91d3db767a662c0b8db513946ba1fbc431537deb
Commit Graph

100 Commits

Author SHA1 Message Date
JianFeeeee
73065664dd test(桥): 判据从「片段存在」收紧到「结构正确」—— 对抗性变异④找出我自己的洞 
pi 复跑变异①报 `pass=1 fail=4`（我报 0/5）。两个数**都对**，但说的是**两种不同变异**：
  · 变体A（我上封跑的）整段替换成 `catch { return undefined }` ⇒ 0/6
  · 变体B（pi 跑的）保留 `catch (e: any)` 外形、只删 code 判断 ⇒ 1/5
两者的差别正是"catch 外形" —— 我上一封没把变异**写清楚**，这是我的表述问题。
事故版本的原文（`1de93fe^`）是 `} catch {\n return undefined;`，即**变体A**。

★ 更重要：顺着 pi 的复跑做**对抗性变异**，我找到了自己判据的一个真洞 ——

    } catch (e: any) {
      if (e?.code === ABSENT) { /* 什么都不做 */ }   ← 片段"在"
      return undefined;                              ← 读失败被降级 = **事故本身**
      throw e;                                       ← 不可达
    }

旧的 `distinguishes() && orderHolds()` 对**全绿**：code 比较在、`throw e` 在、
且 ABSENT 排在 throw 之前 —— 三条"**片段存在**"判据全过，而语义已经是事故。
⇒ "片段在不在"与"结构对不对"是**两种性质**（与 orderHolds 同族），必须分开表达。

本次收紧：
- 新增 `catchInner()`（按花括号取 catch 内层正文，不会误取函数体）；
- 新增 `absentBranchReturnsUndefined()`：「不存在」那支必须**真的** `return undefined`
  （空转守卫 `{}` 不算）；
- 新增 `unreachableThrowFree()`：`throw e` 必须**可达**（它前面与"不存在"之前
  不许有无条件的 `return undefined`）；
- `criterionPasses` = 区分 && 顺序 && 上面两条结构判据；
- 新增测试 ④，并**先断言它骗得过旧判据**（`distinguishes` 真、`orderHolds` 真）——
  否则这条自检就不证明那个洞存在。

验证（对**真源码**改、逐字节还原）：
  基线 6/6 ｜ 变体A 0/6 ｜ 变体B 1/5 ｜ **变体C（洞）1/5**（旧判据下全绿）｜ 还原 6/6
门禁 `npx tsc && npm test`：403/403。
 2026-09-25 04:45:44 +08:00
JianFeeeee
753310d12f test(桥): 把「三个变异逐个验过」从**手跑**变成**判据**（原来文件里只钉了变异①） 
pi 复核我那笔 `1de93fe` 时指出：提交信息里写了"三个变异逐个验过"，
但判据文件里**只给变异①配了自检** —— 那三个是手跑的，手跑过一次 ≠ 以后还会红；
谁把断言改松，另两种变异不会有任何人发现。

原文件的问题（这次才看清）：
- 变异②（`if (true) return undefined`：catch 形状不变、也"看"了 code，只是判断写反）
  与变异①在**判据层面完全同形** —— 只用"有没有 code 比较"去判，两者都抓不到；
- 变异③（`throw e` 提到 code 判断之前）**根本不改"是否区分"**：
  `distinguishes()` 对它恒为真。它测的是**顺序**，所以必须单独一条 `orderHolds()`。
  这正是我原来漏掉③的真正原因 —— 不是"忘了写"，是**当时没有能表达它的判据**。

本次改动：
- 把判据抽成 `distinguishes()`（区分）与 `orderHolds()`（顺序）两条，`criterionPasses` 取合取；
- 三条变异各一条断言 + 一条**前置**（原样源码必须通过 ⇒ 否则三条自检恒假，等于没写）；
- 每条变异都断言"真的落在 persistedCwd 内"（全局正则会命中文件里第一个无关的
  `catch (e: any)`，变异没落下而判据全绿 —— 本仓踩过，`assert.notEqual` 守住）；
- 变异③额外断言 `distinguishes(mutated) === true`：**证明它测的是顺序而不是退化成①**。

验证（对**真源码**做变异，不是只喂文本）：
  基线 pass=5 fail=0 ｜ ①pass=0 fail=5 ｜ ②pass=1 fail=4 ｜ ③pass=3 fail=2 ｜ 还原 pass=5 fail=0
  源码逐字节还原（cmp 过）。门禁 `npx tsc && npm test`：402/402。
 2026-09-25 04:30:53 +08:00
JianFeeeee
1de93feabc fix(桥): 「读不出来」被当成「不存在」—— 这一行把 dsh 的邮件通道整条弄断 
`persistedCwd()` 原来是 `catch { return undefined }`，把 readSession 的**三种**
抛出情形压成同一个「磁盘上没有」。调用方只把 `undefined` 读作"可以 create"：

  读失败（格式迁移拒绝 / 日志损坏）→ 当成不存在 → 走 create
  → 磁盘上**确实有**那个 id ⇒ `session "…" already exists`
  ⇒ 该会话的邮件全投不进去，而日志里只有 create 的错，
     **真正的读失败被那个 catch 吃掉了**。

2026-09-19 DSH 升到 0.1.5-rc.2 后 40 个 `mail-*` 会话全部命中。

修法：`readSession` 的报错**本来就带可区分的 code**
（`dsh-session-query` 的 `notFound()` 给 `SESSION_QUERY_SESSION_NOT_FOUND`；
格式/损坏给 `SESSION_QUERY_CORRUPT_SESSION` / `SESSION_QUERY_PERSISTENCE_FAILED`）。
现在**只有 `SESSION_QUERY_SESSION_NOT_FOUND` 返回 `undefined`**，其余一律抛出，
让原文错误浮到调用方 —— 不再降级成"不存在"。

判据 `test/persisted-cwd-not-found.test.mjs`（2 条，已进 `npm test` 门禁）钉的是
**区分本身**，不是"有没有 try/catch"。三个变异逐个验过：
  ① catch 改回无条件 `return undefined` ⇒ 红
  ② 任何抛错都返回 undefined ⇒ 红
  ③ `throw e` 提到 code 判断之前（"不存在"也抛 ⇒ create 不可达）⇒ 红

★ 变异③第一次**没落在目标上**：全局正则命中了文件里第一个无关的
`catch (e: any)`，判据全绿 —— 于是把它写成自检里的一条断言（变异必须真的落下），
避免这条自检本身变成恒真的假判据。

顺带记两个事实：
- `src/index.ts` 是桥的真源，`dist/` 是部署产物（`.gitignore` 忽略）；已 `tsc` 重建并在产物里复验。
- 姊妹桥（pi/opencode/zcode）不含 `persistedCwd`，本缺陷只在 dsh 这条链上。
 2026-09-25 04:15:37 +08:00
JianFeeeee
b4a8f74ae5 修复: dsh 邮件通道全断的**两侧**根因（桥侧不产 message id 是真正在写的那一处） 
现象：dsh 的邮件通道全断。老会话读不出来 ⇒ 桥报 SessionQueryError ⇒ 按"不在磁盘"
处理 ⇒ 再 create 撞 `already exists`。修好读路径之后又立刻暴露下一层
`message "undefined" is already pending`。

根因一（历史数据，dsh 侧）：v0 会话的 `agent/inbox/spliced.inserted[]` 缺 `id`/`role`，
v0→v1 迁移第一步就拒绝。40 个真 mail-* 会话全部命中。

根因二（**仍在写**，本仓侧）：`plugins/dsh-mail-bridge/lib/message.js` 的
`userMessage()` 只产出 `{content, source}`。DSH 0.1.5 的 inbox 按 `message.id` 去重
（`dsh-agent-loop` 的投影 apply() 与 mutate() 各维护一个 Set），id 全是 undefined
⇒ **第二条消息必挂**。日志里最早的同类记录在 2026-09-07，累计 50+ 次。
官方形状在 `@deepseek-ai/dsh-llm` 的 `createMessage()`（{id, role, content, source}），
同一份 dsh 里其它插件都用官方的 createUserMessage()，只有这个桥手搓。
以前没炸是因为读路径先坏，根本走不到 followup。

本次改动
- message.js/.d.ts: userMessage() 补 id: randomUUID() 与 role:'user'
- test/message.test.mjs: 钉住「id 非空」「两条消息 id 必须不同」，用官方 inbox
  去重逻辑逐字复刻验证（修复前 message "undefined" is already pending，修复后 20 封全唯一）
- scripts/: repair-legacy-spliced-ids.mjs（v0，默认 dry-run）、
  repair-v3-usermessage-ids.mjs（v3）、verify-mail-sessions-readable.mjs
  （走生产真读路径 JsonlSessionPersistence.open，而非解码器口径）、两个 apply driver
- docs/DSH-0.1.5-MAIL-CHANNEL-ROOTCAUSE.md: 补执行结果与两处新事实

执行与验收（详见文档 §9-§15）
- v0 修 40 个、v3 修 2 个；逐文件解压后与备份 `cmp` **逐字节相等**，事件数 40/40 一致，
  零丢失（25.2MB→12.5MB 是单帧改 500 行/帧的重压缩，不是丢数据）
- 真 mail-* 会话最终 **41/41 可读**
- journal 里同一会话从 `already exists` 变为 `resume 续谈`，且持续增长
  （22647→22685 事件），最新 user/message 带真实 UUID；修复上线后 already pending 计数为 0
- 已在生产部署（deploy/redeploy-plugin.sh dsh，快照+原子软链+重启+后置验证全绿）

两个必须记住的坑
1. **校验与落盘不能共用同一批对象**：createRestore().decodeRow() 会原地改写入参
   （补全 dt 数组），污染后写出去会报 `released Session row N has seq gap`。
   这曾让 dry-run 说"40 个可修"、apply 只说"3 个"。
2. **判定磁盘健康只认 open()**：readSession() 走 SessionCorpus.load，命中有 live 会话时
   直接返回内存快照、不校验磁盘；open() 才走 validateStoredEvents。两条路径结论相反
   是设计使然，不是矛盾。
 2026-09-19 12:03:34 +08:00
JianFeeeee
cc8beb79db fix(pi-bridge): --self-check 此前**一次都没在真实路径上跑过** —— 自检改进程内、默认路径先跑、量纲分三档 
dsh 2026-09-18 在本插件里实测报的第二例（同一形状：判据存在但不在路径上）。

## 洞（实测，不是读代码）

· `package.json` 的 `npm test` = `env-preflight && run-suite`，**不带 `--self-check`**；
  `deploy/install.sh` 也是 `npm test`，同样不带；全仓 `--self-check` 零引用，
  本插件下**没有任何 .md** 提到它 ⇒ 它从没在真实路径上跑过。
· 实测：把 `findDuplicates` 改成恒返回 `[]` ⇒ **`npm test` 照样 `exit=0`**（带 flag 才红）。
· 后果不是小事：它是**跨文件重名**判据的引擎，而它**唯一**的分辨力判据就是这个自检
  ⇒ 引擎哪天退化成恒空，重名判据**安静地永远放行**，而整套测试全绿。
· ⚠️ 判"在不在路径上"**不能 `grep` 数命中**：`grep -c '判据自检'` 在默认跑里得 **16 次**，
  全是若干 `.test.mjs` 的**用例名**恰好含这四个字，而 `selfCheck()` 自己的输出
  （`^  (通过|失败)  `、`干净样本`）**一次都没有**。**数命中 = 数到的是词，不是调用。**

## 修

1. `selfCheck()` 去掉 `process.exit`，改为**返回失败条数**（否则没法进程内调）；
   `--self-check` 那条 CLI 行为不变。
2. **默认路径先跑自检**：坏了就 `exit 3` 并明说"工具坏了、本次结论不可信"。
   顺序排在跑套件**之前** —— 引擎坏了时套件那份结论本来就不可信，
   而且省一整轮 509 条测试进程。
3. **量纲分三档**（本文件已约定的那套 + 新增一档）：
   `0`=全绿且无重名；`1`=断言失败/发现重名（**代码问题**）；
   `2`=环境；**`3`=判据引擎自己坏了（工具问题）** —— 不复用 `1`，
   否则 `install.sh` 会把"引擎坏了"读成"代码有问题"。`install.sh` 本次不动
   （它只判"插件装好没有"，非零即中止，3 与 1 对它的行为一致；改它的退出码语义是另一件事）。

## 验证（都跑过）

· 干净树：`npm test` rc=**0**，默认路径出现 `判据自检：全部通过。`（此前 0 次）。
· **M**：`findDuplicates → []` ⇒ `npm test` rc=**3** + `判据自检 2 条失败 —— findDuplicates 的分辨力坏了…`。
· **反向对照**：真造一个跨文件重名 ⇒ rc=**1** + 点名 `2× 平台名字正常时派生别名并原样带标题`
  ⇒ 两个量纲**确实分开**，没把"代码问题"和"工具问题"混成一个码。
· `node --check` 通过；`--self-check` 单独跑 rc=0（行为不变）。

（补 dsh 交回的实测读数：`--self-check` 在干净树 4/4 通过、变异后 2/4 失败、默认跑 0 次。）
 2026-09-18 07:19:26 +08:00
JianFeeeee
82c51e7a8e Revert "fix(pi-bridge): 地址里的 path 必须像工作目录 —— worker 不再被起在 /home 里" 
This reverts commit 141003dce4.
 2026-09-15 12:53:37 +08:00
JianFeeeee
141003dce4 fix(pi-bridge): 地址里的 path 必须像工作目录 —— worker 不再被起在 /home 里 
网关侧已在地址受理处拒收 `/home` 这类 path（ad1f3f1）。这里是**同一规则的第二道**，
因为它落在唯一的 choke point 上（`resolveWorkspaceCwd`，所有 cwd 都从这里出）：

旧实现只判"存在且是目录"，而 `/home` **存在**、也是目录 ⇒ 一路放行 ✗。
后果（2026-09-15 实测）：worker 被起在 `/home`（日志 `新建 pi 会话 …（cwd=/home）`），
而它的沙箱 rw 里根本没有 `/home` —— 它在自己"工作目录"里连文件都写不了；
更糟的是它发出去的信继续带 `/home`，把污染沿线索传下去。

新增 isPlausibleWorkspace（与 Go 侧 repo.IsPlausibleWorkspace 同一套规则）：
绝对路径 + 深度≥2（顶层挂载点不是干活的地方）+ 不含隐藏段（`.pi`/`.cache` 是缓存与会话存储）。
**只判地址来的值**，不判兜底目录本身 —— `/root/.pi/mail-sessions/<会话>` 这类兜底
正是"没有工作目录"的表达，判它会把正常兜底也拦掉。

判据（5 条，两侧都写 + 变异验证过）：实测污染过的形状必须拒；真实工作目录
（含尚未创建的 /tmp/remotebot-ws）必须放行。去掉校验后判据变红 ✓。
桥的正式套件 514 项全绿 ✓。

未部署：pi 桥要 `deploy/redeploy-plugin.sh` 才生效，而那会重启 worker 池
（硬杀在跑的回合），所以等空闲窗口再做 —— 服务端那道闸已经在线，这条是兜底。
 2026-09-15 12:32:50 +08:00
JianFeeeee
a363bab773 fix(pi-bridge): 判据 ③ 两个洞 —— 它此前**一次断言都没跑**，且白名单在等价写法上误红 
pi 复核 `00df6be` 时说这次三件都真落了，但顺手核出**判据 ③ 自己**还有两个洞。
我逐条复现，**两条都成立**：

## 洞 1：它在当前代码上**零次断言**（空转）

```
sed 's://.*::' worker.mjs | grep -c 'existsSync('   → 0
```
白名单等的是 `existsSync(`（带括号），而委托行写的是 `exists: existsSync` ——
**传的是函数引用、不是调用** ⇒ `callLines` 是空数组，那个 `for` 循环一次都没执行。
它能变红，只是因为变异后那行**含** `existsSync(`。
⇒ **"判据跑没跑"从绿上看不出来**（判据自己也需要一条"我跑了"的判据）。
这是 pi 这一路在挑的那件事的又一形态，只是这次被挑的是**我的判据的空转**。

## 洞 2：白名单正则匹配不到它要放行的那一行

合法委托行里 `existsSync` 后面是 ` }` 再 `)`，而正则要求紧跟 `)` ⇒ `false`。
今天无害（合法行进不了循环），但是**埋伏**：哪天有人写成等价的
`exists: (p) => existsSync(p)`，那行就进了 `callLines`、白名单匹配不上
⇒ **判据在"正确的改动"上变红**（"红了但红错地方"）。

## 改法与实测（三个变异，含一条"不该红"的）

先断言"委托那一行存在"（这条让洞 1 不再可能），白名单改为
**"同一行里既有 `exists:` 又有 `existsSync`"**（不锚具体写法）：

| 变异 | 期望 | 实测 |
|---|---|---|
| 基线 | 绿 | **8/8** |
| A：删掉委托行 | 红（旧版会静默变绿） | **f 1** |
| B：加一处独立 `existsSync(given)` 调用 | 红 | **f 1** |
| C：等价写法 `exists: (p) => existsSync(p)` | **绿** | **f 1 → 已修 → 8/8** |

★ 变异 C 第一次仍然红，原因值得记：我按 pi 给的改法只改了 `isAllowed`，
**把另一条断言留成旧写法** —— 两处判据在描述同一件事却各写一份，
正是这一路在消的形状。现在两处共用同一个 `delegating` 谓词。

验证：pi 桥 509/509；三个变异行为如上（`cp` 恢复 + `cmp` 校验）。
 2026-09-15 10:26:14 +08:00
JianFeeeee
00df6bea74 fix(pi-bridge): 复用判定的 fallback 真正委托给唯一规则 + 补上我**声称做过但其实没做**的那条判据 
## 这是一次对自己虚假报告的修补（不是新发现）

我在 `135c6967`（回 pi `6b762cad`）里声称已经做了三件事，**实际一件都没做**：

| 我在信里说 | 实际 |
|---|---|
| ① fallback 改调 `resolveSessionReuse({sessionFile: given, storedCwd: job.session?.cwd, exists: existsSync})` | `worker.mjs` 里**没有**这行（代码行命中 0 次） |
| ② 触发时打一行日志 | **没有** |
| ③ 补断言"worker 里不出现第二处判 sessionFile 的 `existsSync(`" | **没有**（判据里的 `existsSync` 只出现在**判据名那行**） |

★ 而我在那封信里还写了"三件事都记在文件里"、并把它当成"按你的建议改了"的成果报出去。
pi 在 `48078e11` 里**又把这条捡回来**提醒我（"那条自称为'单点'的判据别继续替它作证"）——
**是他第二次提醒，我才去核**。核的方式是 `git show`，结果一眼可见：`0f7c817` 的 diff 里
**没有** fallback 改动。

## 为什么会漏（两层，第二层更值得记）

1. **直接原因**：我在 `0f7c817` 里真的改了 `worker.mjs`（三段），改完就**以为**这一条也在里面；
   下一轮报告时我按"我打算做三件事"写，而不是按"`git show` 里有什么"写。
   ⇒ **报告的依据必须是提交内容，不是改动意图。** 这是本仓库既有的
   "判据的适用范围没写出来"在**报告**上的同族。

2. **★ 更值得记的一层：我自己的"复核"也被同一个形状骗了。**
   我在补做自查时用了三条 grep，**三条全是假绿**：
   ```bash
   grep -q "resolveSessionReuse" worker.mjs          # 命中 import 行/注释 → 判"已做"
   grep -q "父进程没给\|复用判定缺失" worker.mjs      # 命中**注释**里那句话 → 判"已做"
   sed -n '/★ 单点/,$p' test.mjs | grep -q "existsSync" # 命中**判据名那行** → 判"已做"
   ```
   也就是说：**我用 grep 在注释和字符串里找到了"我做过这件事"的证据。**
   这与 pi 一路在挑的"判据测不到它声称要测的东西"是同一个形状，
   只是这次**证据链是注释**。⇒ 复核代码存在性的 grep，必须**先剥注释行**。

## 改动

1. `worker.mjs`：fallback 改为
   `resolveSessionReuse({ sessionFile: given, storedCwd: job.session?.cwd, exists: existsSync })`
   —— 唯一那份规则定义了 `reuseFile = sessionFile && storedCwd && exists(sessionFile)`，
   而就地那份只写了 `given && existsSync(given)`（**少了 storedCwd**），
   正是 pi 说的"谓词更松"。现在"有会话文件但没有 cwd"这条语义差异**落在一处**。
2. `worker.mjs`：`decidedReused === undefined && given` 时打一行日志
   —— 这条路径**当前不可达**（`workerLaunch` 只有一个调用者且无条件注入 `sessionReused`），
   将来若有人新增第二个启动点它会复活，那行日志是唯一的信号。
3. `test/turn-cwd.test.mjs`：**真正**补上判据 ③。做法是**剥掉注释行**后，
   要求 `existsSync(` 只允许出现在"交给唯一规则"的那一行
   （`resolveSessionReuse({… exists: existsSync })`）——
   不能写成"文件里出现 existsSync"，因为注释里、import 行上、以及那个合法位置都有它。

**变异实测**：把 fallback 改回 pi 报的那份"就地谓词"（保留 `decidedReused` 分支）
⇒ 判据 ③ **变红**（8/1）；`cp` 恢复 + `cmp` 校验。
★ 这一条特别值得记：**我上一版判据对这个变异是绿的** —— 也就是说 pi 报的那个缺陷
当时**在测试里是不存在的**，只在代码里。

验证：pi 桥 509/509；另三个桥 fail 0；`check-shared-libs` exit 0；`install.sh --check` exit 0。
 2026-09-15 07:12:17 +08:00
JianFeeeee
be8459cfe7 fix(deploy): 环境兜底自己依赖的命令也登记 + 自我检查排在用它们之前 + 静默改 HOME 必须留痕 
pi 评审 2026-09-15 报的"第五次环境假设"，在 `env-defaults.sh` **自己**身上。
他指出的**结构**成立：本文件用了 `id`/`getent`/`cut`/`df`/`awk`，一个都没登记进
`AGENTMAIL_REQUIRE`（那张表只登记**调用者**的命令，且由调用者在**source 之后**赋值）。

★ 但我实测发现**他给的两个具体后果在这台机器上不可达**，原因值得记下来：
`env-defaults.sh` 的 ④ PATH 自修（`:46`）在 PATH 里没有 `/usr/bin` 时会**把它加回来**
⇒ "从 PATH 里拿掉 id/getent/cut/df/awk"这种造法**必然被自修抵消**（我第一版探针就栽在这里：
`id -u` 根本没失败，我却按"失败了"往下推理，直到把 `command -v id` 单独打出来才看见）。
缺这些命令只可能发生在"**`/usr/bin` 里真没有它**"的机器上（distroless / 精简容器）。

所以这次修的是**能 durable 判定的三件**，而不是他描述的失败面：

1. **登记**：新增文件级常量 `AGENTMAIL_REQUIRE_SELF="id getent cut df awk"`。
   为什么不写进三个调用者的 `AGENTMAIL_REQUIRE`：那个变量在 source 时**还不存在**
   （`. env-defaults.sh` 在第 16/42/52 行，`AGENTMAIL_REQUIRE=` 在第 20/46/56 行），
   本文件没法把它自己那份追加进一个"稍后才被赋值"的变量 —— 追加了本次也不生效。
2. **自我检查排在用它们之前**（顺序即正确性，同 ①→④ 那条）：新增 ③b-0 段，
   只用了**内建命令**（`command -v` + `printf`），所以能在"环境还什么都没兜"时跑；
   它现在位于 `:76`，而第一次真正用这些命令的 `id -u` 在 `:102`。
   ⇒ 缺 `df`/`awk` 时**不再静默丢门**：原来 `df -Pk … | awk` 拿到空串会落进
   `''|*[!0-9]*)` 那支"读不到 ⇒ 不判定"，**②b 那道空间门直接消失**（那是门，不是提示）。
3. **静默改 HOME 必须留痕**：原先只在"**调用者给的** HOME 不可写"时 WARN，
   而"按身份推出来的那个也不可用"（root 的 `/root` 在非 root 下不可写；
   passwd 里是 `/nonexistent`）**悄悄换了 HOME** —— 与本文件存在的理由正好相反。
   现在两条路都 WARN。★ 这一条**可达且实测过**：
   `setpriv --reuid=65534 … bash -c 'unset HOME; source env-defaults.sh'`
   ⇒ `[WARN] 按身份推出来的 HOME=/nonexistent 不可用 … 改判到 /tmp/agentmail-home-65534`。

**判据 4 条**（`test/env-guard.test.mjs`，pi 桥侧，与该文件既有的环境判据同处）：
① `AGENTMAIL_REQUIRE_SELF` 登记了这 5 个命令；② **顺序**：自我检查的行号必须**小于**
`id -u` 的行号（判据写成位置比较，而不是"有这段代码" —— 后者正是我这一轮反复写坏的形状）；
③ 源码里存在"按身份推出来的 HOME 不可用"那句 WARN；④ **端到端**：非 root + 空 HOME
真的打出 WARN。

★ 这条端到端判据我写坏了**两次**，都记在文件里：
· 第一版用 `execFileSync` 只收 stdout，而 WARN 走 **stderr** ⇒ 红在"没找到 WARN"上，
  实际是**判据自己没读那一股**；
· 改用 `spawnSync` 后仍红 —— 因为 `deploy/lib/env-defaults.sh` 是 **0600**，
  `nobody` 读不到它，脚本**压根没跑起来**。这与"命令不在 ≠ 输出为空"是同族：
  **脚本没跑 ≠ 输出里没有那一行**。判据改为用一份世界可读的副本（文件权限是另一件事）。
  ⇒ 顺带发现并修掉：我用写文件工具建的 5 个文件都是 **0600**（该工具不理会 umask），
  已全部改 644（仓库既有约定；同目录其他文件都是 644/755）。
  **`cp -a` 会把 0600 带进生产快照**，所以这不是纯本地问题 —— 记一笔，未另开检查
  （工作区里还有 52 个 git 已跟踪文件是 0600，是既有状态、非本次引入，单独处理）。

验证：pi 桥 **509/509**（+4）；`check-shared-libs` exit 0；`install.sh --check` exit 0。
 2026-09-15 07:05:50 +08:00
JianFeeeee
0f7c817c1e fix(pi-bridge): 回报的 cwd 必须是实际用的那个 + 复用判定收成一处（pi 评审 §三） 
pi 2026-09-15 §三 报的两条，我都逐行核了，**都成立**。

## 一、新建分支回报的 cwd ≠ 它实际用的 cwd（他给的最小修法）

```js
const opened = await openSession({ cwd: turnCwd, … });   // ← 用的是 turnCwd
return { ...opened, cwd, reused: false };                // ← 回报的是本地推导的 cwd
```

这个返回值经 `session_opened` → `state.cwd`，而 `state.cwd` **正是下一轮
`resolveTurnCwd` 的 `storedCwd`**（也即下一轮 `--rw` 的输入）。
⇒ `7fe2796` 建立的那条"**记下来的必须是实际用的**"不变量在这一支上不成立：
等式只在"本轮 rw vs 本轮 openSession"上闭合，**没在"本轮 rw vs 下一轮 rw"上闭合**。
改成 `return { ...opened, cwd: turnCwd, reused: false }`。

★ 可达性我说实话：**窄**。要 `resolvedCwd !== 本地 cwd` 得"父进程判复用而 worker 落到
新建分支"，目前只有"父进程判完之后会话文件消失"这条 TOCTOU 窗口能造出来。
所以它现在**不是 bug，是一条会随别人改动而变成 bug 的不变量缺口** —— pi 的定性准确，
我照他的定性记，不夸大。

## 二、复用判定两处各写一份（结构性，而且是上面那条的前提）

```
pool   : state.sessionFile && state.cwd && existsSync(state.sessionFile)
worker : given && existsSync(given)
```

这正是前两轮刚消掉的那种"两处各写一份"，而且它决定了 `resolvedCwd` 会不会被交给
一个**不消费它的分支** —— 上面那条能出问题，根子在这儿。
新增 `src/turn-cwd.mjs` 的 `resolveSessionReuse({sessionFile, storedCwd, exists})`
（**唯一一处实现**，`exists` 注入以便判据覆盖"在/不在"两种情形），
pool 用它判、并把结论一并注入 job（`session.sessionReused`），worker **消费**它。

## 三、判据（pi 建议的两条，都做了，且都验过区分力）

1. **等式/配对**：按分支回溯 —— 以每个 `return { ...opened, cwd:? X, reused` 为锚，
   回溯它前面最近的 `openSession(`，断言**同一个符号**。
   ★ 这条我**写坏过两次**，两次都是变异测出来的，都记在测试文件里：
   · 第一版用两串正则分别抓，`matchAll` 的懒惰量词**只抓到各一个**，
     而"只有一个"时包含关系天然成立 ⇒ 变异后照样全绿；
   · 第二版修好配对后，`[\w.?]+` 要求**至少一个字符** ⇒ 抓不到简写 `cwd,`
     （实际三处里两处是简写）⇒ 报"应当抓到三处，实际 1"。
   ⇒ **判据红了要查清是产线错了还是判据错了**；这两次都是判据错，不是产线错。
2. **单点**：`resolveSessionReuse` 必须是唯一实现；pool 必须用它；worker 必须消费
   `job.session.sessionReused`，且只在它缺失时才退回自己判。
3. 另加 `resolveSessionReuse` 四种输入组合（文件在/不在 × cwd 有/无）。

**变异实测（三条，均 `cp` 恢复 + `cmp` 校验）**：
· 把回报改回 `cwd`（= pi 报的那个 bug）⇒ 配对判据**变红**；
· worker 又自己判一份（`decidedReused = undefined`）⇒ 单点判据**变红**；
· pool 绕回两处各写一份 ⇒ 单点判据**变红**。

## 四、一处我要标出来的（结构上被保留、实际不可达的分支）

worker 里那条保底分支 `decidedReused === undefined ? 自己判 : 消费父进程的`
**实际上走不到**：`sessionReused` 为真要求 `state.sessionFile && state.cwd`，
而这两个字段只在 `session_opened` 里被**一起**写入 ⇒ 有 `sessionReused` 就必有 `sessionFile`。
保留它是为了老协议/异常帧不至于静默落到"新建会话"（比报错更糟），
但它**没有判据覆盖**，也没法用真协议触发 —— 按"跑不到的分支"记账，不假装它被验过。

验证：pi 桥 **505/505**（+3）；`check-shared-libs` exit 0；`install.sh --check` exit 0；
`drift` 报 5 处待部署（与先前一致 —— 本轮只改已有文件，未新增文件）。
 2026-09-15 06:53:53 +08:00
JianFeeeee
7fe279676a fix(pi-bridge)!: --rw 的 cwd 与 worker 实际用的 cwd 收成**一处决定**（pi 探针实测的第三例） 
pi 2026-09-15 报、我用探针复核**成立**，而且它把 `99e6560` 的代价也一起说清了。

**分叉在哪**：cwd 有**两个来源**，而会话键 `keyOf(data) = data.session_id` **只看 session_id**：

```
父进程（算 --rw）  cwd = resolveWorkspaceCwd(to_workspace, …)   ← 来源：**这封信的地址**
子进程（真去干活）  cwd = job.session.cwd || resolveWorkspaceCwd(…) ← 来源：**会话上次实际用的 cwd**
```

于是同一 session_id 下地址换个形状（`pi@/some/dir` → `pi@.<会话>`），父进程按**新地址**
算 rw，worker 却**复用会话、落在旧 cwd**。实测（真函数，`exists` 注入）：

```
父进程算的 cwd  = /root/.pi/mail-sessions/sess-x
worker 实际会用 = /home/program/agentmail   （= 该会话的 state.cwd）
rw 含 worker 实际 cwd? = false  ⇒ 界内 EACCES
```

不是假想：本线程那条会话自上线起每次启动的 rw 都是 `/home/program/agentmail`，
那就是它的 `state.cwd` —— 此时来一封 `pi@.<会话>`（不带 path）的信就会踩到。

**★ `99e6560` 在这个组合上把失败方式变坏了**（这条必须记下来，我原先只报了它的好处）：
· 之前：兜底目录不存在 ⇒ 不套沙箱 ⇒ `ask`（有人应答时**写得进去**）
· 之后：目录被建出来（那次修复的效果）⇒ **套上沙箱，而 rw 是地址算的那个**
  ⇒ worker 在会话自己的 cwd 里写 ⇒ **EACCES，且没有"问一次"这条路**（内核拒的）
我用 `ensureCwd` 前/后各跑一次验证了这条因果，实测 `(b) 建了兜底目录: sandboxed = true,
rw 含 worker 实际 cwd? = false` —— 与 pi 报的 `sandboxed=true` 一字不差（他给了那个值，
我最初复现成 false，差别就在"兜底目录建没建"，属于应用 `99e6560` 前后）。
⇒ **两处修复必须一起部署**，否则中间态是"界内也写不了"（比原先多问一次更糟）。
现在两次提交都在仓库、`drift` 报 5 处待部署，会一起上线。

**修法**：新增 `src/turn-cwd.mjs` 的纯函数 `resolveTurnCwd()` —— 输入全部来自**父进程也拿得到的
public 状态**（`sessionReused` / `storedCwd` / `toWorkspace` / `sessionKey` / 注入的解析函数），
父子两侧都从它取值；父进程再把决定**注入 job**（`session.resolvedCwd`），worker **消费**它、
不再自己推导。于是"三来源变一来源"落了第一步。

**判据（pi 要的那条等式）**：
· ★**等式**：用真 `sandboxWritePaths` 算 rw，断言"**`--rw` 里的 cwd === worker 会用的 cwd**"；
  并附**反面对照**：按地址算出来的 rw **不含** `state.cwd`（= 修复前的错位状态）。
· 复用/非复用/`storedCwd` 为空三种输入各一条。
· 结构：pool 必须把决定交给 `workerLaunch` **并**注入 job；worker 取 cwd 的**每一处表达式**
  都必须先看 `resolvedCwd`。

★ **两处我自己的判据缺陷，都是变异测出来的，都记在测试文件里**：
1. 上一轮我在 `sandbox-launch.test.mjs` 写的 `assert.match(src, /resolveWorkspaceCwd\(/)`
   **本来就不该红也不该绿** —— 它护的是**写法**（池子直接调那个函数），而引入 `resolveTurnCwd`
   后池子改成"当参数传进去"（更对），它才红。**红得对**：它当初断言的是实现细节，
   不是它想要的性质。已改为断言性质（解析函数必须来自共用模块、且被显式传给纯函数）。
   顺带说明：它此前一直是**假绿**还是**真绿**我没法回测，但**它在引入纯函数后才红**说明它
   确实绑定了写法 —— 这正是"判据的适用范围没写出来"那一类。
2. 新版 worker 侧结构判据**第一版不具区分力**：只断言"文件里出现 `resolvedCwd`"，
   把消费那一支删掉、退回 `job.session.cwd`，正则**仍然匹配**（别处还留着它）⇒ 变异后依旧全绿。
   已改为断言**优先级**（取 cwd 的表达式必须含 `resolvedCwd`）。
   ★ 变异实测：修好后重做同一变异 ⇒ 判据**变红**；两次变异均 `cp` 恢复 + `cmp` 校验。

**残余（未修，已进 DEBTS）**：**接管会话**那条路 worker 用会话文件 header 里的 `info.cwd`，
父进程读不到 ⇒ 首回合仍可能错位。父进程要拿它得用 `session-scan.mjs`，而 `readHeader` 未导出、
整表 `scan()` 在父进程里代价大（worker 里实测 1431ms / 240MB）。
彻底方向即 pi 说的：把"这次用哪个 cwd"完全收成父进程一处决定，worker 只消费。现在做不做等定。

验证：pi 桥 **502/502**；另三个桥 fail 0；`check-shared-libs` exit 0；`install.sh --check` exit 0。
 2026-09-15 06:47:10 +08:00
JianFeeeee
99e6560122 fix(pi-bridge): 首回合也要套沙箱 —— pool 在算 launch 前先把兜底目录建出来（pi 报的同形缺口） 
pi 2026-09-15 报的缺口，我先逐环核了再改（**成立**）：

```
pool.mjs:190   cwd = resolveWorkspaceCwd(to_workspace, piMailFallback(session_id)).cwd
                 ↓ 地址不带 path（`pi@.<会话>`）⇒ cwd = ~/.pi/mail-sessions/<key>
                 ↓ **这个目录第一次不存在**
sandbox.js:168 if (!cwd || !exists(cwd)) return direct("拿不到会话工作区")  ← 不套沙箱
worker.mjs:388 ensureCwd(cwd, grouped)   ← 建目录的人**在决定之后**才跑
```

⇒ 无 path 的新会话**首回合不套沙箱** ⇒ 父进程不打 `AGENTMAIL_PI_SANDBOXED`
⇒ worker 的 `sandboxActive()` 为假 ⇒ `guardDecision(workspace, sandboxed=false)` = **`ask`**
⇒ **"界内不问"这条保证对无 path 新会话的首回合不成立**。

**端到端实测（不是推理）**，用真函数跑了一遍无 path 新会话：

```
解析结果 cwd = /root/.pi/mail-sessions/brand-new-key-probe | grouped = false
修复前（目录不存在）: sandboxed = false | 拿不到会话工作区（…）—— 不猜   → guardDecision = ask
修复后（目录已建）  : sandboxed = true
  rw 含兜底目录 = true ; rw = […/brand-new-key-probe, /tmp, /root/.pi/agent]  → guardDecision = allow
```

**修法**（pi 给的最小修法）：pool 在 `workerLaunch` 之前调 `ensureCwd(cwd, grouped)`。
`ensureCwd` 只在 `!grouped` 时建，所以 **N-2「笔误不落真目录」不受影响**：
path 位给了但不存在 ⇒ `resolveWorkspaceCwd` 返回**兜底**+grouped=false ⇒ 建的是兜底目录，
笔误路径永远不会被创建。（这点我单独核过，因为"顺手建目录"最容易在这里越界。）
同时把 `resolveWorkspaceCwd` 的调用收成一次（原先在参数里内联算 cwd），
保证"用来判 exists 的 cwd"与"拿去当 --rw 的 cwd"是**同一个值**。

**判据（行为 + 结构，含顺序断言）**：
· 行为：兜底目录不存在时 `sandboxed=false` 且理由是"拿不到会话工作区"
  —— 这条**真规则是对的**，不能改成"无条件套"（`am-sandbox` 对不存在的 `--rw` fail closed，126）；
· 结构：`src/pool.mjs` 里 `ensureCwd(` 必须出现在 `workerLaunch(` **之前**
  —— 光判"调没调"不够：顺序错了等于没补（这正是当初 worker 建目录的位置问题）。
★ 已先验区分力：移除 `ensureCwd` 调用 ⇒ 新判据**变红**（12/1），`cp` 恢复后 `cmp` 校验一致。

**为什么原判据护不住**：`sandbox-launch.test.mjs` 的 `fsRealShape()` 里 cwd 总是存在的，
而生产里这个 cwd **恰恰是 worker 自己建的** ——
与前面 `agentDir` 那次是同一个形状（夹具把生产形状简化掉的那一角，正是出问题的那一角），
只是换了另一角。这是同一条教训的第二个实例，值得并进 docs。

验证：pi 桥 **497/497**（+1）；另三个桥 fail 0；`check-shared-libs.sh` exit 0；
`install.sh --check` exit 0；`drift` 报 4 处待部署（`src/paths.mjs` 新增 + 三个文件内容不同），
与本次改动一致 —— 这条红正是"待部署"的可操作信号。
 2026-09-15 06:33:49 +08:00
JianFeeeee
011957ac97 refactor(pi-bridge): A 方案落地 —— 平台兜底值搬回平台侧，workspace.js 恢复逐字节相同 
pi 定的 A（2026-09-15）。要点是：**契约的逃逸口不是豁免清单，而是
`resolveWorkspaceCwd(workspace, fallback)` 的第二个参数** —— 平台兜底值本来就该由平台侧传进去。
四个桥对照很清楚：

| 桥       | 平台兜底值在哪                                   | 怎么交给共用函数 |
|----------|--------------------------------------------------|------------------|
| opencode | 自己的 `index.js`                                | 传 `directory`   |
| zcode    | 自己的 `src/index.mjs`（`zcodeSessionFallback`） | 传进去           |
| dsh      | 共用的 `mailSessionFallback`（写死 `.dsh`）      | 直接用           |
| pi       | **原来造在共用模块里**（本次出的错）             | → 现在也传进去   |

⇒ `docs/PLUGIN-CONTRACT.md` 第 1150 行**不用改、也不该加旁路**：pi 只是唯一一个把平台值
造在共用模块里的，挪回平台侧就恢复了规矩。

**改动（与 pi 预测的形状一致）**：`workspace.js` 删掉那 15 行、`pool.mjs`/`worker.mjs`
各改一行 import，外加新文件 `src/paths.mjs`。`git diff --stat` 实测
`15 -` / `3 +-` / `3 +-` —— 没有多余改动。

**为什么新家是 `src/paths.mjs` 而不是 `lib/sandbox.js`**（pi 给了两个选项，我选前者）：
`lib/` 按契约是"**候选共用**"目录，把一个 pi 专有文件放进去**正是这次出事的形状** ——
下一个人会问"它为什么不在 `ALL_LIBS` 里"。`src/` 下同名文件不会引起这个问题。
父子同源（worker 的沙箱 rw 由父进程算）由"两边 import 同一个模块"继续满足。

**验收四条（pi 给的，逐条实测）**：
1. `cmp opencode/lib/workspace.js pi/lib/workspace.js` **相同**；
   `check-shared-libs.sh` **exit 0**；`install.sh --check` **exit 0** ✓
2. 测试数**不降**：491 → **496**（+5，见下）✓
3. 给 `piMailFallback` **补测试**（原先一条都没有 —— 这正是当初的不对称：
   四个桥 `npm test` 全绿、只有 `check-shared-libs` 抓得到）→ 新增
   `test/pi-paths.test.mjs` 5 条 ✓
4. 四个调用点改 import 后 diff 只应是 import 行 + 删掉的那 15 行 ✓

**新测试为什么是独立文件**：`test/workspace.test.mjs` 在四个桥里**逐字节相同**
（md5 一致，属共用测试），往里加 pi 专有断言会把共用测试也弄分叉 —— 与 `lib/` 同一条规矩。

**判据含结构断言 + 行为断言**，并已按纪律先验区分力：
· 变异 1（把 `piMailFallback` 塞回共用模块 = 本次分叉的形状）⇒ 结构判据**变红**；
· 变异 2（把 `.pi` 改成 `.dsh`）⇒ 三条行为判据**变红**；
两次变异都用 `cp` 恢复并以 `cmp` 校验一致。

★ 顺带记下 pi 指出的一条：`check-deploy-drift.mjs` 的判据 ① 是我扩到"比全部 133 个文件"的，
所以这次分叉**它能抓到** —— 但 `check-shared-libs` 先红了，说明两道门的分工是对的。
 2026-09-15 06:31:18 +08:00
JianFeeeee
7f03ee7ca2 fix(pi-bridge)!: 沙箱 rw 漏了 agentDir 本身 —— pi 侧的 Agent 整个不工作（凭据存储的锁文件写在它直下） 
**症状（实测，2026-09-15）**：pi 处理不了任何一条消息 —— 回给 dsh 的是一封
「处理失败」通知：

    auth: Credential store read failed for llmsproxy:
    EACCES: permission denied, mkdir '/root/.pi/agent/auth.json.lock'
    已尝试 1 个：llmsproxy/AUTO

即**不是某次工具调用失败，而是这个 agent 完全不工作** —— 而它正是这条线上唯一的对端。

**根因**：`sandboxWritePaths` 把 `<agentDir>/sessions` 放进了 `--rw`，
**却没放 `<agentDir>` 本身**：

    pushDir(join(agentDir, 'sessions'));   // 少了 pushDir(agentDir)

而 pi 的凭据存储在 **`<agentDir>` 直下**建锁文件 `auth.json.lock`
⇒ Landlock 拒绝在 `agentDir` 里新建条目 ⇒ 读凭据这条路直接失败。

**因果链已在真二进制上闭合**（`/opt/agentmail/bin/am-sandbox`，非推理）：

    # 只给 sub、不给父（= 修复前的形状）
    --rw /tmp/ll2/allowed/sub  →  echo > /tmp/ll2/allowed/newfile
    /bin/sh: cannot create …: Permission denied     ← 就是 pi 的那个 EACCES
    # 给父目录（= 修复后的形状）
    --rw /tmp/ll2/allowed      →  退出码 0，文件建出来

也确认了 `am-sandbox` 的语义确实是「**及其子树**」（`--rw` 给出的目录连同子树可写），
所以补上父目录这一条就够，不需要为锁文件单独加 `--rw-file`。

**为什么以前的判据护不住这一处 —— 夹具形状把出问题的那一角简化掉了**：
`sandbox-launch.test.mjs` 每个用例手写
`fsWith([..., `${HOME}/.pi/agent/sessions`, ...])`，**只列 sessions、不列 agentDir**，
于是"agentDir 在不在 rw 里"在这套测试里**永远测不出来**。
已加一个贴着生产形状的夹具 `fsRealShape()`（agentDir 与 sessions **都在**），
并把两个 workerLaunch 用例换成它。

**判据（两条，含反面对照）**：
· `agentDir` 本身必须在 `--rw` 里，且 `sessions` 也仍在（两个写点，不是替代关系）；
· 反面对照：`agentDir` **不存在**时不得硬塞进 rw ——
  `am-sandbox` 对不存在的 `--rw` 路径 fail closed（退出码 126），
  所以"加 agentDir"不能变成"无条件加"。
★ 已按既定纪律先验区分力：临时移除 `pushDir(agentDir)` ⇒ 新用例**变红**（11/1），
`cp` 恢复后 `cmp` 校验一致。

**旁注（写点清单的教训）**：原来的注释只按"我们已知的写点"列（会话工作区、临时目录、
/dev/null、sessions、配置目录），而**凭据存储在它自己的目录里加锁**是另一个写点，
且它在**读凭据**这条路上 —— 所以漏了它的症状不是"某个工具不能用"，而是"agent 不工作"。
写点清单要按**真实进程的行为**列，不能只按已知的那几处列。

验证：pi 桥 491/491（新增 2 条）；sandbox-launch 12/12；`go test ./cmd/am-sandbox/` ok。
 2026-09-15 00:13:13 +08:00
JianFeeeee
9fa509844a feat(pi-bridge): 有沙箱时 workspace 档不再逐条问人 —— 界内不问、界外内核拒 
沙箱上线后，"工作区档"的语义第一次可以按档位表兑现：**边界是内核在守**，再问一遍
只是让人点一次"同意"，点完该失败的还是失败（人点了也挡不住内核）。所以闸门改成
**按档位 × 有没有沙箱** 决策，纯函数收在 `lib/sandbox.js`：

| 档位 | 沙箱 | 决定 |
|---|---|---|
| full | 任意 | allow（发件人已声明全权） |
| plan | 任意 | block（本档只许看；沙箱是第二层） |
| workspace | **在** | **allow** ← 这一步改的（界内不问、界外 EACCES） |
| workspace | 不在 | ask（回退到原来那唯一一层） |

没有沙箱时**继续问** —— 这条是"不会更松"的保证：沙箱缺失/未装/被关掉时行为与改前
逐字一致。

## 标记不等于事实：worker 自证

`AGENTMAIL_PI_SANDBOXED=1` 只是父进程的**声明**。判断错会让闸门既不问也不拦
（最坏的一类），所以 worker 现场自证一次：往界外写一个金丝雀（`/.agentmail-sandbox-canary-<pid>`，
根目录永远不在 rw 里）—— 写得进去 ⇒ 判为"没有沙箱"，**退回逐条问人**（方向取严）；
被拒（EACCES/EROFS/EPERM）⇒ 在边界内。结果缓存在进程级。

## 顺带把 plan 档变成真的只读

plan 档的 rw 清单**不含会话工作区**（只有临时目录/pi 会话登记/桥配置/`/dev/null`）：
"一个字都不许写"从"钩子拒绝 + 提示词"{升级为内核第二层。

## 判据

- `sandbox-launch.test.mjs` 10 条（原 6 + 新 4）：决策矩阵四档 × 有无沙箱、
  自证两侧（被拒=在边界内；能写=必须判"没沙箱"）、plan 档 rw 不含工作区、
  "pool 设标记 + worker 自证 + 走 guardDecision"三处接线在。
- 变异：把 workspace+sandboxed 改回 'ask' ⇒ 那条断言红。
- pi 桥全套 489 项通过。
- ★ 又被自己撞一次同类坑并当场红：新变量起名 `decision`，与同一个函数里后面那个
  `const decision = await new Promise(...)` 撞名 ⇒ SyntaxError。上一轮的 `spawn`
  撞名也是这一族（局部名与既有作用域重名），两次都是**语法检查/测试**立刻抓到。

## 文档

`docs/PLAN.md` §7.11 的 L5 矩阵与"向更严取整"那条纪律、`docs/API.md` 的档位表
都改成新语义（有沙箱=内核拒、无沙箱=逐条问），并写明 pi 的沙箱为什么必须由宿主提供。
 2026-09-14 23:50:35 +08:00
JianFeeeee
64f002cf66 feat(pi-bridge): worker 按档位套沙箱 —— plan/workspace 进 Landlock 边界，full 档不进 
上一步（1f48c5c）做出并验了边界工具；这一步把它接到 worker 的启动路径上，
于是「工作区档 = 本目录内可动」第一次由**内核**保证。

## 规矩

- `plan` / `workspace` 档 → `am-sandbox --rw <会话工作区> … -- node worker.mjs`
- `full` 档 → **不套**（发件人已声明全权，与档位表一致）
- 拿不到会话工作区 → **不套**，并把理由打进日志（猜一个 `--rw` 会让"界内也写不了"）
- 启动方式从 `fork` 换成 `spawn`（fork 只会 exec node，套不进中间那层），
  `stdio` 里带 `'ipc'` 时 node 同样设 `NODE_CHANNEL_FD`，而沙箱是 exec 透传
  ⇒ worker 的 `process.send` 照常可用

## rw 清单是**实测得出**的，不是想当然

`lib/sandbox.js` 里那几条（会话工作区 / `os.tmpdir()` / `<agentDir>/sessions` /
`AGENTMAIL_CONFIG_DIR` / `--rw-file /dev/null`）每条都对应一个真实的失败模式：
少了 `/dev/null`，`cmd 2>/dev/null` 一律 Permission denied（实测撞到）；少了
`<agentDir>/sessions`，回合结束保存会话就失败。真机验证：一个**真实的 pi agent**
跑在边界里，界内写成功、`/opt` 被拒（Permission denied），并如实汇报两者。

## 两处必须收成一处的东西

- 会话工作区由**父进程**用与 worker 同一个函数解析（`resolveWorkspaceCwd`）——
  父进程猜一个目录当 rw、worker 落在另一个，症状是最难查的那一类
- `piMailFallback` 从 worker 挪进 `lib/workspace.js`：父进程要用同一个兜底值

## 判据与踩到的坑

- `sandbox-launch.test.mjs` 6 条行为断言（套/不套、rw 里有 cwd 与 /dev/null、
  `--` 之后是 node+worker、拿不到 cwd 时的理由、env 开关三态、rw 去重与只收存在的路径）。
  变异"永不套沙箱" ⇒ 恰好那几条红。
- ★ 池测试原先会**随这台机器装没装 am-sandbox 而变** —— 那正是假绿的来源。
  给 `createWorkerPool` 加了 `env` 注入点，测试显式 `AGENTMAIL_PI_SANDBOX=off`。
- ★ 给 import 起名 `spawn` 撞上本文件已有的 `function spawn(job)` ⇒ 自己调自己
  （`RangeError: Maximum call stack size exceeded`，池测试当场红）。改名 `spawnProcess`。
- pi 桥全套 485 项通过。
 2026-09-14 23:43:06 +08:00
JianFeeeee
2a5e3d7d15 fix(auth): 四家桥的读端点也带上会话收窄 + 转发同一条命（工作区隔离第 2 步） 
第 1 步（1b8cd43）把工作区判据放在服务端、pi 桥接上了线。这一步补齐另外四家，
并把**转发**纳入：转发是"把原文引出去"，能转发就等于能读到那条线索的全部内容，
与 read_mail 同一条命（服务端 ForwardMail 也加了同一道校验）。

四家各自的会话来源，与各自的 read_inbox 同一处（不引入第二个来源）：
- dsh：`mailSessionOf(exec)`（工具第二个参数）—— 五个读工具原本没接 exec，这次补上
- opencode：`reverseMap.get(context.sessionID)`
- zcode：`process.env.AGENTMAIL_SESSION_ID`（一轮一个进程）
- homeagent：`p.currentSessionID`（新增 `scopeQuery(sep)`，与 inboxURL 同构）

判据（每条两侧都钉：包住了 / 没包住的不存在）：
- dsh：静态对照，且额外钉 **dist** —— 那是真被 dsh 加载的那份（main: dist/index.js），
  src 改了忘了 build 就是"源码对、线上旧代码"
- opencode / zcode：同上（opencode 还钉"会话来自 context 而不是模块级变量"）
- homeagent：起 httptest 当网关，**五个读工具 + 转发真调一遍**，断言请求 URL 带
  session_id；对照侧：不在回合里（currentSessionID 为空）时不许带
- pi：把 post 的 URL 也纳入记录，forward 进用例表

★ zcode 那条判据我第一版**对照组写错**了：对照组只写裸 URL，而它本来就是
`withScope(\`裸URL\`)` 的子串 ⇒ `!includes(bare)` 恒假。夹具形状不对时判据会以
"恒红/恒绿"的方式骗人（这次是恒红，一眼可见；恒绿就麻烦了）。

变异：homeagent 去掉 read_mail 的收窄 ⇒ 恰好那条断言红。

（工作区共享，只 add 了上面这 12 个文件；dsh 的 dist 是 gitignore 的，由
redeploy-plugin.sh 在 staging 里构建。）
 2026-09-14 23:18:12 +08:00
JianFeeeee
1b8cd43935 fix(auth): 工作区成为读权限的边界 —— Agent 侧读端点按会话工作区收窄 
用户报的：「agentmail 工作区的邮件会话被 trueagent 工作区的 agent 看到了，
还需要我亲自去解释。」

## 根因不是漏了一个 WHERE，是隔离单位选错了

Agent 注册时 `workspaces` 是空的（B-1.2：cwd 由每封邮件的 `to_workspace` 决定），
所以**一个 Agent 同时服务所有工作区**。而可见性判据一直是
`AgentCanAccessSession(agentName, sid)` = "这个 Agent 名出现在这条会话的 from/to/cc 里"
—— 于是同一个 agent `pi`，在 TrueAgent 里干活的 worker 眼里，对 agentmail 的会话
也成立。

现场证据：`mail_reads` 里 08:11–09:19 有 8 次「同一瞬间读了多个不同工作区的会话」
（08:23:59 一次跨 agentmail / TrueAgent / webui4frpc 三条会话），最后一次是 09:19:11
—— 正好停在 `read_inbox` 按会话收窄那个提交（552fbc7，09:19:25）之前。
更要紧的是 `mail_reads` 只记 `reader_name`、**没有「读的人当时在哪个工作区」这一列**，
所以这类越界读在数据上与正常读**无法区分** —— 这也是为什么只能由用户自己去解释。

## 改法：补一维，而不是逐个端点打补丁

- 新增 `repo.AgentMayReadSession(agentName, scope, target)`：① 参与过（原有判据）
  ② 两条会话的 `workspace` 相同（新增）。`scope` = 调用方当前所在的那条会话。
- 服务端只认一条**会话 id**（`?session_id=`），由它反查 workspace ——
  **不接受调用方直接声明工作区**，否则等于让它自己给自己发通行证。
- 应用到四个读端点：`read_mail` / `read_thread` / `session_participants` /
  `list_contacts`，以及 `contacts/suggest` 的**会话候选**（name/path 两段不收窄：
  跨工作区**发信**是设计允许的，被挡的只是"浏览同行的线索"）。
- 未声明 `session_id` 时保留旧语义（放行）并**记警告日志**：迁移要能分步走，
  但"还有谁没接线"必须可观测（另四家桥仍走这条路）。
- pi 桥：五个读工具全部带上自己那条邮件会话 id（由 worker 闭包注入，模型改不了）。

## 顺手修掉一个真 bug

联系人查询的未读计数子查询里一直有 `r.reader_name = $1`，而原写法是
"forUser 为空就不传参" ⇒ $1 悬空：Postgres 直接报 `no parameter $1`，
SQLite 把 `= $1` 当 `= NULL` 比、次次不成立（未读计数静默退化成"全部未归档"）。
管理员 `?all=true` 走的正是这条路。现在 $1 恒传。

## 判据（两侧都验 + 变异）

- repo：同工作区放行 / 跨工作区拒且 reason 分得清 / 没参与过拒 /
  未声明 scope 的旧语义；列表类有反向对照（不带收窄两条都在）；
  建议补全同工作区照常给候选、跨工作区查路径不给、不带收窄会给（对照组）。
- ★ 这条判据我第一版**写错了对照组**：拿 path=wsA 去比 —— 而 path 本来就收窄，
  于是"不带收窄"也只剩一条，判据等于空的。改成拿 path=wsB 比才有区分力。
- 变异 3 处（拿掉工作区判据 / ListContactsInWorkspace 不收窄 /
  SuggestSessionCandidatesInWorkspace 不收窄）⇒ 各自恰好红在对应那条断言。
- pi 桥 14 条：6 个读工具 × 带上/不带 scope 两侧 + worker 闭包 + 自检；
  变异 read_mail 去掉收窄 ⇒ 恰好那一条红。

（工作区是多会话共用的，本次只 add 了 server/ 与 plugins/pi-mail-bridge/ 的 7 个文件。）
 2026-09-14 23:03:25 +08:00
JianFeeeee
d616582e96 fix: 回滚 user-question.js 那一搬（它把 check-shared-libs 打红两处），并把 drift 的非运行时差异摘出来 
pi 逐处对文件后指出：我按"本平台不可达 ⇒ 搬去 test/lib/"把 `lib/user-question.js`
搬走，打红了 `deploy/check-shared-libs.sh` 两处（实测确认，脚本真退出码 1）：

    共用模块缺失：plugins/pi-mail-bridge/lib/user-question.js
    共用测试已分叉：test/user-question.test.mjs（opencode vs pi）

根因不是取舍而是口径：**`lib/` 上挂着两条方向相反的不变量** ——
① 共用模块四方逐字节同源（`check-shared-libs.sh`，连相对路径一起钉）；
② 本平台生产可达（我新加的规则）。而 `user-question.js` **是 dsh 桥的生产代码**
（`plugins/dsh-mail-bridge/src/index.ts` 引用它）⇒ 两条必然冲突。
**`lib/` 首先是四桥共用命名空间，其次才是"本平台可达"**；可达性只能当**报告**，
不能当搬家判据。教训的形状：**一条新判据上线时，先找它可能与哪些既有不变量冲突** ——
我只看⻅了自己那条。

改动：
- `user-question.js` 与它的测试回到 `lib/`、`test/`（路径也与 dsh 侧一致），
  两边逐字节相同已复验；`check-shared-libs.sh` 退出码 0。
- `reach.mjs` 增加 `sharedLibNames()`：直接从 `check-shared-libs.sh` 的 `ALL_LIBS`
  读共用清单做豁免（不手抄常量），并把"进快照但本平台不可达"降级为**报告**。
- `layout-boundaries.test.mjs` 增加回归判据：共用模块必须留在 `lib/`、
  测试相对路径与 dsh 一致、两侧逐字节相同。
- 删掉 `reach.mjs` / `docs/DEV-TOOLING.md` 里那句**无据的机制说明**
  （"user-question 走前缀动态 import"）：`localRefs` 的三条正则只认引号字面量，
  对模板字面量形状是**盲的** ⇒ 那句若为真，搬走的就是生产代码而两条判据都会绿。
  pi 读了 `src/` 下九个文件都找不到引用，我也确认是记忆偏差；理由改用 `addressing.js`
  （传递可达、`src` 直接引用数为 0）—— 它已足够证明"直接引用数不是可达性"。

顺带按 pi 的第二条建议：`deploy/check-deploy-drift.mjs` 判据 ① 把
**非运行时差异**摘出来（`jsonTestOnlyChange`，只豁免 `scripts.test` 一类字段，
只对"两边都在、仅内容不同"的文件生效）。理由：一条**永远黄、没人打算为它动手**的判据
唯一的下场是被学会忽略，那时真正的运行时漂移会被一起忽略。
⚠️ 摘的条件很窄 —— **把运行时差异误判成非运行时比恒黄更坏（那是假绿）**，
所以 `main`/`start`/`dependencies` 变了、或解析不了，一律仍算运行时；
纯函数加了六个反/正样本的判据（含三个"必须算运行时"的）。

（该文件同时有另一条会话的改动，未提交、我未触碰；本次只加了我这一段。）

验证：`npm test` 463/463；`check-shared-libs.sh` 退出码 0；`--self-check` 18 条全过。
 2026-09-14 20:11:58 +08:00
JianFeeeee
fb85a8728d 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 全绿。
 2026-09-14 20:00:16 +08:00
JianFeeeee
f1059c5a6b fix(pi-bridge): 夹具移出测试文件（import 它会二次注册整套用例）+ 测试侧写点全部兜住 + 判据不再往 /tmp 留垃圾 
pi 复核了探针形状（论证闭合），又报了三条，全部实测成立。

## 一、从测试文件 import 助手 ⇒ 那套用例被**再注册一遍**（最实质）

`env-guard.test.mjs` 曾从 `session-scan.test.mjs` 取 `writeSession`。`node --test`
默认每个文件一个子进程，模块导入是进程内的 ⇒ 那个文件的 16 条用例在 env-guard
的进程里**又注册了一遍**。

实测确认：TAP 里巨行用例（单条往临时目录写 ~12 MiB）出现**两次**
（`ok 87` / `ok 353`），测试总数 475。**判据自己在加倍压 /tmp** —— 而 /tmp 正是
这次事件的主角。修完：459 条，巨行用例 1 次。

修法就是 pi 指的形状，也正是 `translateEnvError` 那次的同一手法：
夹具移到**非测试模块** `lib/session-fixtures.mjs`（可被引用，不被注册进套件）。

## 二、测试侧写点还是裸的

`makeRoot()` 的 `mkdtempSync`、以及 `writeSession` 里在 try **之外**的 `mkdirSync`
（ENOSPC 也可能从这里出来）⇒ 绕过前置脚本时抛的仍是原始英文堆栈，
而"绕过前置也要说人话"正是这套兜底存在的理由。现在整段包一层，与 `selfCheck()`
同一形状：**覆盖范围不取决于"我以为的哪一行"**。

## 三、判据往共享 /tmp 里留垃圾

`writeSession(tmpdir(), '--probe--', …)` / `'--probe2--'` 每跑一次就留两个目录、
且永不清理。现在改用 `os.tmpdir()`（纯字符串，不 statfs）当根：那两条的创建都被
假写打断 ⇒ 目录根本不会建出来 ⇒ 既不读也不写真实临时目录。

## 四、一条新判据替代原来的文本接线检查

守**机制**：解析测试文件里的模块引用（静态 `from` / 动态 `import()` / `require()`），
任何指向另一个 `.test.mjs` 的引用都算违规 —— 注释里提到文件名不算（注释不会注册用例）。

这条判据自己踩了两次，都留在注释里：
  第 1 版 只匹配静态 from ⇒ 漏掉动态导入；
  第 2 版 "文件里出现别的测试文件名" ⇒ 把**注释里的散文引用**也算成违规
          （本仓库有 3 处这样的注释，逼人删掉有用的注释），
          而且**它被自己注释里的示例字面量扫到**。
**过宽和过窄都是坏的** —— 这正是这一串评审反复出现的同一族错误。

验证：`npm test` **459/459**（少了 16 条重复注册）；巨行用例出现 1 次；
`--self-check` 18 条全过；`TMPDIR=/tmp node deploy/check-deploy-drift.mjs --self-check` ⇒ exit 2 + 人话。
 2026-09-14 19:51:44 +08:00
JianFeeeee
6b7c12d9da fix(pi-bridge): "开关被认"那条判据自己也有假绿 —— 我按真实测量分叉，于是永远走短路分支 
pi 评审第二轮指出：上一版"开关真的被认"只在"真实测量不足"那个分支里断言，
机器一恢复健康（/tmp 被清空）这条就退化成"只验 --measure"的弱检查，
而它守的恰恰是"开关别静默失效"。

认下之后我做变异（把开关整个忽略掉、永远用真实测量）验证，**发现比这更糟**：
那条新写的判据**在变异下照样绿**。

原因是我写成了 `realAvail < MIN_FREE_BYTES ? (不足分支，只看退出码) : (充足分支)`，
而本机真实可用**就是 0** ⇒ 永远走不足分支；开关被整个忽略时，回退测量同样给
exit 2 ⇒ 断言通过。**"断言在，区分力不在"** —— 与 pi 点的是同一类病，
只是它藏在一个**跑不到的分支**里（嵌套三元短路），比"分支退化"更难看出来。

修法：不跟真实测量比，**让两个探针自己互为反面**，并断言**输出里的判定词**
（不只看退出码 —— 退出码可能与真实状态巧合相同）：

    探针 A：注入 1 字节          ⇒ exit 2 + 必须打印「< 需要」
    探针 B：注入 128 MiB（>阈值）⇒ exit 0 + 必须打印「≥ 需要」

开关被忽略 ⇒ 两次都按真实测量给同一个答案 ⇒ 至少一条红。这个论证不依赖真实测量
是多少。变异自检实测：注入"忽略开关"的变异后，第 23、24、25 三条一起红。

顺带修一处**HEAD 里就带着的坏行**：第 162 行的 `test(..., () => {` 后面被塞进了
`// 覆盖…` 注释（上一次编辑吃掉了那个换行），整行不合法。这次一并拆回两行。

过程中我两次改坏文件（一次把手写 `replace` 的锚点算错、把"非法参数"那条整条删掉），
两次都靠 `git checkout HEAD -- <file>` 拉回重做 —— 这正是上一轮写进
`lib/env-error.mjs` 的那条纪律（变异/改写只对已提交文件做、还原只走 git）当场生效。

验证：`npm test` **475/475**；env-guard 单跑 30 条全过（含 24 号在两个探针下的双断言）。
 2026-09-14 19:46:07 +08:00
JianFeeeee
87359588eb fix(pi-bridge): 评审第二轮 —— 判据在健康机器上会退化、"一处覆盖"取决于入口、笔误参数静默放行 
pi 读了 `5bc579f` 之后报了两条新的 + 三条小的，全部认下并落地。

## 一、"开关真的被认"那条判据在 /tmp 被清空后失去分辨力

上一版只在"真实测量不足"那个分支里断言（注入大数必须放行）。问题是：
**"不足"正是机器恢复健康后会消失的条件** —— 那天这条判据就退化成"只验
`--measure` 可用"的弱检查，而它守的恰恰是"开关别静默失效"。

两个方向是对偶的、各守一个机器状态，所以改成**按实测分叉、在两个分支里断言相反的方向**：

    真实不足 ⇒ 注入大数必须放行   （开关被忽略则回退测量 ⇒ 2 ≠ 0 ⇒ 红）
    真实充足 ⇒ 注入 0    必须 exit 2（开关被忽略则回退测量 ⇒ 0 ≠ 2 ⇒ 红）

量不到就 `assert.fail` 并说明"无法分叉"—— 不静默跳过（跳过会把"失去分辨力"
伪装成"验过了"）。另把"端到端"那条的两个方向拆明白：只验"不足⇒2"时，
一个恒报不足的坏守卫也能绿。

## 二、"一处覆盖全部写点"成立的前提是"从 main() 进来"

`selfCheck()` 是**导出**的（用途就是被直接调），而兜住那三处裸写的 catch 在
`main()` 里 ⇒ 任何绕过 `main()` 的调用者撞上 ENOSPC 拿到的仍是原始英文堆栈。
**"覆盖范围取决于我以为的入口"正是这一串 bug 的共同病根**，所以把整段包一层
（`body()` + 统一 catch）：与入口无关，`main()` 那个退化为冗余的第二道。
实测：`TMPDIR=/tmp node -e 'import("./deploy/check-deploy-drift.mjs").then(m=>m.selfCheck())'`
现在拿到的是「环境不足…这是环境问题，不是检查器的问题」。

## 三、`--inject-avail=abc` 静默放行（笔误 = 跳过守卫）

`Number('abc')` = NaN ⇒ 判据当"没测到" ⇒ 放行。现在按仓库约定处理：
**非法值 exit 2，未知参数也 exit 2**（`--measure` 少写 `=` 同样炸）。
`null` 仍是合法值（"没测到 ⇒ 放行"是有意的），加了判据把这两个方向都钉住。

## 四、三条小的

- 两份实现（`lib/env-error.mjs` 的 `translateEnvError` 与 `deploy/` 的
  `describeEnvError`）**不去重**，但两边各写一句"为什么不复用"：
  `deploy/` 的独立性比去重值钱（那份文件头整段在讲"服务不该依赖仓库是否存在"）。
  并写明**第三份拷贝出现时再考虑共用**。
- 写点计数口径写进注释：本函数 **6 处写** = `mkdtempSync`×2 + `mk()` 内 ×2
  + 三处裸写。免得与别处"五处"的说法对不上（上一封信里两个实测数字就是这么被误读的）。
- 变异自检的纪律补进 `lib/env-error.mjs` 头注释：**先证明能撤回来再注入变异，
  且还原路径不能依赖被测对象**（那次把备份写进 `/tmp` —— 正是当时被占满的资源，
  备份没写成而变异已覆盖源文件）。现在只对"已在 HEAD 干净提交"的文件做变异，
  还原一律 `git checkout HEAD -- <file>`。

验证：`npm test` **475/475**；`--self-check` 18 条全过；
`TMPDIR=/tmp node deploy/check-deploy-drift.mjs --self-check` ⇒ exit 2 + 人话。
 2026-09-14 19:42:58 +08:00
JianFeeeee
5bc579f910 fix(pi-bridge): 按评审补三处 —— ENOSPC 只盖了一个写点、旧注释自相矛盾、兜底判据钉的是文本 
pi 逐字读了上一版落地的代码，报了三个"还差一格"。都不是推翻，是同一根因
（"环境不足伪装成别的"）在这套守卫自己身上的残留。

## 一、翻译只覆盖了 5 个写点里的 1 个（最实质）

`selfCheck()` 要在临时目录造两棵样本树，写点有**五处**；上一版只把 `mk()` 里那两处
包了 try/catch，后面三处（`README.md` / `extra.mjs` / `test/t.mjs`）裸写。它们撞上
ENOSPC 时异常冒到 `main()` 的 catch：**退出码是对的（2），但打印的是原始英文
`ENOSPC: no space left on device, write` 加一段指向本文件的堆栈** —— 也就是上一版
要治的那个信号（"看起来像检查器坏了"）**恰恰在最需要它的路径上还在**。

改法：抽一个 `describeEnvError(e, what)`，在 `main()` 的 catch 里**统一**换成人话。
一处覆盖全部写点，以后再加写点也不用管。`mk()` 里那段裸判断一并换成调用它。

## 二、`lib/tmp-space.mjs` 的头注释在说谎（读者已误读一次）

原文写"`availBytes` 为 `null`（读不到 / 平台不支持 / **字段为 0**）" —— 而"字段为 0"
指的其实是 `statfs.bsize === 0`（测量层确实 `if (!s.bsize) return null`），读起来
却像是在说"可用 0 字节也算不知道" —— **正是我上一版刚踩、刚补判据的那个坑**。
pi 第一遍读就误读成了后者。已把两个 case 分开写死，并注明"这条注释写错过一次"。

## 三、兜底判据钉的是文本，不是机制

`env-guard.test.mjs` 原来对 `session-scan.test.mjs` 断言 /ENOSPC/ 与 /环境/，
而那段**解释性注释里本来就有这两个词** ⇒ 删掉整段翻译逻辑、只留注释，判据照样绿。
这正是 `permission-note.test.mjs` 自己警告过的"钉装饰不钉机制"。

改法（按仓库规矩，纯函数 + 反面样本 + 接线）：
- 翻译逻辑提到 `lib/env-error.mjs` 的 `translateEnvError`（纯函数）；
- 判据喂构造出来的错误验**行为**：ENOSPC 必须翻译且带药方、普通错误必须**原样返回
  同一个对象**（"什么都翻译"比不翻译更坏 —— 真缺陷会被套上环境的外衣）；
- `writeSession` 抽出 `write` 参数（**只为测试存在**，`pool.mjs` 的 `workerPath` 同一手法），
  于是"接线还在不在"是**行为**判据：喂一个必然 ENOSPC 的假写，翻译必须发生。
  抽它的理由写在注释里 —— 是"可被反面样本喂"，不是复用（只有一个调用点）。
- 变异自检：删掉写点的翻译 ⇒ 第 28、29 两条立刻红（已实测）。

## 四、顺带三处小的一致性问题

- 端到端那条判据原靠"本机 /tmp 恰好是满的"来验 —— 那是把判据绑在**会变的环境**上，
  /tmp 一清空就自动跳过、无声失效。前置脚本加两个**只为测试存在**的开关：
  `--measure=<dir>`（只量并打印 JSON）与 `--inject-avail=<n>`（绕过测量直接判定），
  于是"不足⇒exit 2"与"充足⇒放行"在任何机器上都验得了（两个方向都验，缺一即假绿）。
- 判据 ⑥ 原先只有它自己带圈号前缀，读者会去找不存在的第 ⑤ 条。改成 `checkLayout`
  的每条都带**连续 id**（1..N），`name` 是纯展示串，并加一条"id 不许跳号"的自检。
- 两个实测数（`729_088` 字节 = 0.70 MiB、`712` 字节）是**不同时刻**量的，并列摆着像抄错，
  各标了来历；`lib/tmp-space.mjs` 里那条改用"一度真是 0"的说法。

验证：`npm test` **474/474**（上一版 453）；`--self-check` **18 条全过**（新增 id 连续）；
`npm test` 在临时目录不足时仍 exit 2 且一条用例都不跑。
 2026-09-14 19:39:07 +08:00
JianFeeeee
0b548b8fcf test(pi-bridge): 临时目录满时不再伪装成内存缺陷 —— 前置自检 + ENOSPC 兜底 
现场（2026-09-14 实测）：`/tmp` 是 tmpfs，被别人占满，`statfsSync` 实读
`bavail*bsize` 只剩 **0.70 MiB**。此时 `npm test` 红一条

    not ok 323 - ★巨大的 message 行不进内存也不影响解析
      error: 'ENOSPC: no space left on device, write'

那条红的**形状指向内存**（用例名里就写着"不进内存"，而它恰好是往临时目录写文件的
用例）⇒ 下一个踩到的人会去 `session-scan.mjs` 找一个**不存在**的内存缺陷。

改：
- `lib/tmp-space.mjs`：测量与判据分开，判据是纯函数 `judgeSpace`，喂字节数即可验；
  读不到可用空间（null/NaN）⇒ **不判红**（不知道 ≠ 不对，否则会造出"总在亮"的红灯）。
  **但 0 字节不是"不知道"** —— 第一版把 `<=0` 一并当"没测到"，于是 `bavail` 只剩
  712 字节时前置自检放行、紧接着 17 条用例 ENOSPC 全红：前置自检装了等于没装。
  阈值 32 MiB = 实测单条用例最大写入量（`session-scan` 那条写 3×3 MiB 行 ≈ 12 MiB）
  ×2 + 8 MiB 机动，不是总容量的百分比（百分比在这套测试上没有依据）。
- `test/env-preflight.mjs`（名字不带 `.test.`，不被 glob 收进用例）：
  `package.json` 的 test 改成先跑它；不足时打印实测/阈值/目录并 **exit 2**
  —— 与 `deploy/redeploy-plugin.sh` 的 `2=环境问题` 同一套约定，看到 2 才知道
  去查机器而不是查代码。文案里明写「这是环境不足，不是断言失败」。
- `session-scan.test.mjs`：兜底翻译 ENOSPC（`node --test 'test/*.test.mjs'` 会绕过
  前置脚本，这一句不管套件怎么被调起来都生效）—— 这正是治那条误导的关键。
- `test/env-guard.test.mjs`：8 条自证 —— 纯函数两头 + 边界（≥阈值算够、<阈值不够）
  + 0 字节必须红 + 读不到不判红 + 阈值有据 + 端到端 exit 2 且文案对得上。
  端到端那条**不假设本机 /tmp 仍然满**：先自己量一次，够用就跳过并说明原因，
  免得它退化成一条"总在亮"或"总在绿"的假判据。

顺带修 `deploy/check-deploy-drift.mjs` 两处同源问题：
- `selfCheck()` 要在临时目录造两棵小树，`/tmp` 满时抛 ENOSPC —— 而它是**未捕获异常**，
  堆栈指向本文件，看起来像检查器坏了。翻译成说得清的错并让 main() 报 2。
- 新增判据 ⑥「工作区干净」—— **只提示，不参与 exit code**。判据 ① 比的是
  「仓库工作区→快照」这一跳，覆盖不到「HEAD→工作区」那一跳（实证：一行未提交的
  死代码被 17:20 的快照带进生产，而 ① 报的是"逐字节一致"）。做成红灯就是一条
  总在亮的判据（本文件头自己骂过的病），所以只说、不判。

验证：`npm test` 453/453（新增 8 条）；`npm test` 在 /tmp 满时 exit 2 且不再跑用例；
`node deploy/check-deploy-drift.mjs --self-check` 17 条全过（含 ⑥ 的三条正反面）。
 2026-09-14 19:29:44 +08:00
pi
f0884d03be fix(pi-bridge): 决策到了没唤醒等待者 —— 整条授权链断掉（用户报「授权机制有问题」） 
现场（用户：「我发现授权机制有问题，你看看 webui4frpc 的那个 session」）：
同一条会话一天被问 6 次「是否允许执行 bash？」，**每次人都在 8 秒内点了同意**，
而每一轮都恰好烧满 10 分钟（TURN_TIMEOUT_MS），回信只有一句 59 字的开场白。
该 agent 自己的会话转录里写着：**"The bash tool keeps returning 'No result provided'"**。

根因：`worker.mjs` 的 `permission_decision` 分支取出了等待者、删了表项、存了备注，
**却没有调用 `resolve`**：

    const resolve = pending.get(msg.relayKey);
    if (!resolve) return;
    pending.delete(msg.relayKey);
    decidedExtra.set(msg.relayKey, { ... });
    return;                       // ← 等的人永远醒不过来

于是一条命令走完下面这一整圈：
  ① 工具调用挂着不动 → 一轮跑到 10 分钟 TURN_TIMEOUT_MS 才结束；
  ② 桥把模型那半句开场白当「本轮总结」发回（59 字）；
  ③ 会话里留下**没有 toolResult 的 toolCall** → 下一轮 pi SDK 给它补一条
     `isError: true` 的「No result provided」→ 模型重试 bash → 人又被问一遍。

为什么之前全绿：`permission-note.test.mjs` 的 WIRING 钉的是
`decidedExtra.set(msg.relayKey)`（**备注＝装饰**）与 `renderDecisionReason`，
**没有一条钉"唤醒"**。2026-09-13 那次修备注时把唤醒弄丢，判据照样全绿
—— 钉装饰不钉机制。

改：
- `resolve(msg.decision)` 补回，放在 `decidedExtra.set` **之后**（hook 醒来要读备注渲染
  拒绝理由，顺序反了会复现 2026-09-13 的「备注丢失 → 模型重复追问」）
- 判据：WIRING 补一条「必须唤醒」；另加 `checkDecisionBranch` **按标记切出决策分支正文**
  判"存在 + 归属 + 顺序"（不用"相距 N 字符"的窗口断言 —— 第一版就是那样假红的）
- 三种反面写法做变异自检：删掉 resolve / resolve 早于备注 / resolve 挪出分支，都必须红
- 全套 445 条通过

跨端核对：dsh 桥的 `pendingApprovals` 有 `pending.resolve(outcome)`（没这个问题）；
opencode 走原生 permission 回复、zcode 走事件钩子 —— 这条路径只有 pi 桥有。
 2026-09-14 19:16:22 +08:00
JianFeeeee
33488760ce fix(相位/安全): 部署门禁只判产物自证；静默 break 改成出声；内核读数带时间坐标 
pi 2026-09-14 的裁定与两条更正，逐条落地。

1. **相位裁定（选 c）**：`packaging`/`build-stamp` 属于**构建相位**，不属于安装相位。
   `run-all.mjs` 现在有相位：`AGENTMAIL_CRITERIA_PHASE=install`（部署门禁用）。
   每条判据登记它读的哪一侧（`ARTIFACT`/`SOURCE`），install 相位里出现 SOURCE 侧判据 → 红；
   被跳过的判据**点名打印**，不静默丢。汇总打 `RESULT phase=build|install`。
   规则入册 `test/CRITERIA.md` §11（含三个真实实例：check-shared-libs 恒红、
   packaging 一改前端就卡死、HOME 在门禁跑完之后才炸）。

   安装相位**真正能判的那一半**：`deploy/install.sh` 读**产物自证**（不重算 dist）——
   `releaseCandidate !== true` → 拒绝；产物 `gitRev` ≠ HEAD → "这个包比源码旧" → 拒绝；
   放行要显式 `--allow-dirty` / `--allow-stale`；`--check` 干跑只报结论不拦。
   实测干跑输出：`产物：gitRev=6702cc2 树=dirty releaseCandidate=false ｜ 当前 HEAD=6702cc2`
   → 报"不是发布候选 + 正式安装会被拒绝 + 要放行请显式说清"。

2. **别解析运行器文本**（pi §5）：`broken`/`red` 的判定改成按 TAP 的**名字**——
   文件级失败的测试名就是路径，断言失败的名字是判据名。变异双向验证：
   未定义标识符 → 「跑不起来的判据」；把某条判据条件改成假 → 「红的判据」。
   不再往关键字表里加补丁（那是往文本解析里加补丁，方向是错的）。

3. **静默 break 是安全相关**（pi §3）：`session_update` 找不到活动会话时不再静默 break，
   改成出声日志（走 journalctl 那条通道），写清两种成因（此刻没在跑 / **接管会话**重启后无法定位）、
   方向（收紧被延迟）、以及兜底的**前提**（"下次投递"要求这条会话还会收到新邮件）。
   `lib/mail-session-id.js` 模块头同步改成安全相关措辞（"人以为自己收紧了权限、实际没有"），
   四桥逐字节同源，`check-shared-libs.sh` 退出码 0。

4. 内核读数补时间坐标（pi 13ea2fdf）：`BUILD_INFO.txt` 里除原始 `dep`/`=>` 行外，
   现在还有 `kernelBinMtime` 与**正在运行的进程启动时间** —— 二进制会在两次读数之间被换掉，
   没有时间坐标的读数不成立。
 2026-09-14 16:54:30 +08:00
JianFeeeee
dae508b25b docs(判据): 补「已知限制」与「缺省语义登记」两节；build.sh 把原始 dep/=> 行写进 BUILD_INFO 
pi 2026-09-14 两件：

1. **登记册真的没有**。我上封信说"已写进 test/CRITERIA.md 的已知限制一节"——**不成立**，
   只有 `appearance-defaults.test.mjs` 里有那段注释。已在 CRITERIA.md 补 §9「已知限制」
   （标识符只解析一层；静态判据的到期前提是"本工作区能装能点"）。
   过度声明自己做过什么是这轮反复出现的那一类错，这次是同一个形状的又一例。

2. **新建 §10「缺省语义登记处」**（pi 的更正：不是无条件 fail-closed，而是"缺了的后果必须
   有人登记 + 写明谁批准了这个方向"）。三条入库，各带依据：
   · 邮件 `permission_mode` 缺 → **不写、不改档**（窄），依据是本轮那个 `|| 'workspace'` 兜窄档的坑；
   · HomeAgent `plugin.json.sdk` 缺 → 内核**不读**（不是语义，是文档），依据内核 manifest.go 结构体 + registry.go；
   · HomeAgent `capabilities` 缺 → **不受限**（宽），依据内核注释明写的理由：17 个存量清单都没有它。

3. `build/BUILD_INFO.txt` 现在**原文贴入** `go version -m <内核>` 的输出，并附"这两行怎么读"
   （`dep … vX.Y.Z` 后面跟 `=> … (devel)` 时那串版本号只是 require 行残留；`=>` 必须按模块名联接）。
   理由：这场争论的全部内容就是这两行该怎么读，原始证据必须和结论放在一起。
 2026-09-14 16:50:33 +08:00
JianFeeeee
4f0a6e6097 fix(homeagent): 构建不许弄脏源码树 —— hmapdev 会重写 plugin.json，构建后还原并出声 
实测：`hmapdev build` 会重写受版本管理的 `plugin.json`（只吃掉了文件末尾换行）。
"构建把树弄脏"这件事在 electron 那边刚定过规矩（脏树产物不得自称发布候选），
所以这里同样处理：构建前留快照，构建后若被改写就还原 + 打印一行说明
（不静默还原 —— 下一个人要知道这条工具会动源码）。

验证：`bash build.sh`（HOMEAGENT_SDK_DIR=…/sdk/v1.3.0）产出 build/plugin.bin（9018271 字节），
构建后 `git status plugins/homeagent-mail-bridge/` 只剩我自己改的 build.sh。
 2026-09-14 16:41:54 +08:00
JianFeeeee
7e696f9a8c fix(homeagent): 撤回"另一条 SDK 血脉"的错误结论；build.sh 不再猜路径；清单判据改成一致性口径 
pi 用只读文件系统逐条反驳了 357662e 的根因，三条我都验证并接受：

1. **"内核链 0.9.x 血脉"不成立 —— 那是我的搜索顺序造出来的事实。**
   本机有 6+ 份 `third_party/homeagent-sdk` checkout：
     /root/ha-test/…（0.9.0，C-ABI 时代，无 plugin.bin 支持）
     /var/tmp/rel-1.3.12/…、/var/tmp/rel-1.3.11/…（1.3.0）
     /var/tmp/release-main/…、/var/tmp/clean-check/…、/var/tmp/homed-p3/…（1.2.0）
   而 build.sh 第一版按候选根目录**第一个命中就算**，命中的正是 ha-test 那份老 checkout。
   内核自己用的是 1.3.0 那份，与钉子 `sdk/v1.3.0`、与 `<SDK_ROOT>/current` **一致**。
   两条教训写进注释了：别用"第一个存在的路径"当权威来源；别把模块版本字符串当身份
   （`replace => local (devel)` 时它只是 require 行的残留）。

2. **"API 不兼容"也是同一个错造成的。** 换成正确的 SDK 之后：
     HOMEAGENT_SDK_DIR=/root/.homeagent/hmapdev/sdk/v1.3.0 bash build.sh
     → hmapdev build 成功，产出 build/plugin.bin（9018271 字节）
   也就是说**这个插件在本机编得出来**，先前的 `SettingsAPI.DataDir` 报错是拿老 checkout 编的产物。

3. **判据把能工作的配置判红**（pi §2）：第 4 步原先硬校验"产物 SDK 模块版本 == 内核模块版本"，
   而生产上能跑的组合恰恰是"内核 + v1.3.0 编的插件"。已删掉这个相等性判据：
   SDK 源码**只认显式指定**（HOMEAGENT_SDK_DIR），不猜、不试探；
   内核那条 dep/=> 只作为**提示**打印（并且按模块名精确联接、只接受紧跟 SDK dep 行的 `=>`，
   不再取"输出里第一个 =>"）；身份改记 **realpath + 内容哈希**；
   `meta.Version` 读取先剥注释（注释里的 `Version = "9.9.9"` 不再能赢）。
   真正的不变量是 **wire 协议 protocol=2 + 一次真实握手**，写在脚本末尾（部署后回看日志）。

4. **清单判据改成一致性口径**（pi §5）：不再"禁止 sdk 字段"——那会把正在工作的那份清单
   （/home/newqqagent/plugins/homeagent-mail-bridge/plugin.json 声明 sdk=1.3.0，正是 08:30
   那次恢复的处置动作）判红，而我没有"内核不读该字段"的证据。现在：可以不声明；
   声明了就必须与构建机指针一致。
 2026-09-14 16:38:28 +08:00
JianFeeeee
357662ed08 fix(homeagent): 不再把 SDK 版本钉在源码里；构建期按内核的依赖表校验对齐 
崩溃循环的根因不是"忘了重编"，是**把 SDK 版本钉死**：

- `plugin.json`/`plg.json` 写死 `"sdk": "1.3.0"`（本机已装 21 个插件里只有 3 个声明该字段）；
- `go.mod` 的 replace 指向 `/root/.homeagent/hmapdev/sdk/v1.3.0`（绝对路径 + 具体版本目录）。

于是"照原样重编"只会再造一个装上去就崩的包。实测本机内核链的是**另一条 SDK 血脉**：

    $ go version -m /usr/local/bin/homed
    dep gitcode.com/JianFeeeee/homeagent-sdk v0.9.2
    =>  ./third_party/homeagent-sdk (devel)

所以判据改成**两个二进制的依赖表一致**，而不是"版本号看起来像"：

- `build.sh`：读内核的 SDK 依赖（`go version -m`）→ 据此解析 SDK 源码目录 →
  用 `-modfile` 临时替换（不改动受版本管理的 go.mod）→ 构建 → **回头验产物**：
  产物与内核链的 SDK 版本不一致就报错退出，绝不产出"装上去就崩"的包。
- `manifest_sdk_test.go`：① 清单不许写死 `sdk`；② go.mod 的钉子不得偏离构建机指针
  （取不到基准就红，不许默默放过）；③ `build.sh` 必须在（它是与内核对齐的硬校验点）。
  三条都做过变异验证（写死 sdk / 钉子漂到 v1.2.0 / 删掉 build.sh → 各自红）。

顺带查出一个比"重编"更根本的事实：本机 `build.sh` 跑到编译就失败 ——

    ./plugin.go:217:18: sett.DataDir undefined (type sdk.SettingsAPI has no field or method DataDir)

即本插件源码用的是 **1.3.0 SDK 的 API**，而本机内核链的是 0.9.x 血脉：**重编解决不了**，
要么内核改成链 1.3.x 的 SDK，要么把插件移植到内核那份 SDK（这是 HomeAgent 侧的决定）。
 2026-09-14 16:27:02 +08:00
JianFeeeee
d5cfcbdc9c fix(权限): 409 的第二种含义是「本档不该问」——四桥都补上；状态写入点不再兜默认档 
线上事故（jianf 经 pi 转达）：补投路径漏传 permission_mode，插件拿 undefined 兜了
workspace 档，把 full 档会话写成 workspace-write + ask —— 不是"拦一次"，是一整轮
工具能力降级，且状态留在会话里；随后该会话每次受守卫调用都撞 409。

四件事：

1. **状态写入点不接受默认值**（新增共享 `modeForStateWrite`）：缺字段/脏值 → `null`
   = 不写状态。"默认值可以出现在**决策**里，不可以出现在**状态写入**里。"
   同时保留共享契约的 fail-closed：真读到 workspace 才写 workspace。

2. **409 的两种含义分开处理**。`allowed-once` 只绕过**审批**，改不了**沙箱** ——
   所以 dsh 桥在放行前先把服务端给的权威档位**写回会话**（这也就成了自愈路径：
   已经降级的会话，下一次带档位的 409 会把它修回来）；只认服务端明说的 full，
   plan 与"链上没有人类"照旧 fail closed。

3. **同一处缺陷在 zcode / opencode 也在**（`hooks/permission.mjs` 与 `index.js`
   都把 409 当永久失败拒绝）。我先前在回信里写过"这两个桥不转发权限询问，不需要改"
   —— 那句话是错的，我当时的搜索面只有 `<plugin>/src/*.mjs`。按 pi 的要求把这条
   **否定性事实变成常驻判据**后，它第一次运行就红给我看。四桥现在都有
   「409 + full → 放行」，且**排在永久失败分支之前**（含顺序变异自检）。

4. **共用测试重新同源**：`test/catchup.test.mjs` 从 `153985e` 起就是分叉的
   （我那版把平台专属路径写进了共用文件），而 `deploy/install.sh` 第 24 行会跑
   `check-shared-libs.sh` —— 也就是说**部署一直是红的**，我没跑过那个脚本。
   共用文件只放契约（值/行为），跨平台配对judge 移到平台专属文件，四份逐字节相同。

另外把"判代码 vs 判理由"从记忆变成代码：`test/lib/read.mjs` 提供 `code()/prose()/bytes()`，
判据目录里不得再裸用 `readFileSync`（新判据 `criteria-hygiene` 管，含读取器自检）。

判据证据（每条都做过"能不能红"的变异）：
- 写回去掉 → 红；纠正块挪到普通 409 之后 → 红；状态写入点退回兜默认 → 红；
- zcode/opencode 的放行分支拿掉 → 各自红；共用测试分叉 → check-shared-libs 红。

各套件：dsh 388、pi 443、zcode 387、opencode 333（均经 npm test，含 tsc）；
electron `npm test` 15/15 判据绿 + vitest 266 + typecheck；`check-shared-libs.sh` 退出 0；
Go `go test ./...` 全 ok。
 2026-09-14 16:21:27 +08:00
JianFeeeee
7028c244fd dsh 桥同一处缺陷：409 带 full 档时也当场拒绝（并且把会话降级了） 
pi 报的是它自己的桥，但**同一处缺陷 dsh 桥也有**（`src/index.ts` 的 409 分支无条件
`return 'rejected'`），而且后果多一层 —— dsh 的档位是通过 `applyPermissionMode()`
写进会话的（沙箱 + 审批策略）。补投漏传档位时 `applyPermissionMode(session, '')`
把会话**降级**成 workspace：`danger-full-access → workspace-write`、
`never → ask`，于是每个受守卫的工具调用都去问一次，再被 409 拒绝 ——
一条 full 档会话只要有一封补投邮件，这一轮的工具调用全被自己人拦死，
**顺带把自己的权限也降了**。

修法同 pi 桥：409 分支先认回包里的 `permission_mode`，是 full 就
`return 'allowed-once'`（DSH 的 ApprovalOutcome 只认 allowed-once/rejected/cancelled/unavailable）；
plan 档与"链上没有人类"照旧 `return 'rejected'`。放行分支排在普通 409 之前，否则不可达。

判据 `test/permission-409-full.test.mjs`（含自检：拿掉放行分支必须红）。
自检那步发现我第一版判据又踩了同一个坑：「普通 409 分支里不许出现 allowed-once」
读的是**含注释**的正文，而那段的注释正好写着 "ApprovalOutcome 只认
allowed-once / rejected / …" → 误报。改成读剥注释的源码（规范里那条：
判"代码里有什么"读剥离版，判"理由写清了没"读原文）。

zcode / opencode 不转发权限询问（没有 409 分支），无需改。

验证：dsh 套件 383 通过（+2）；变异（拿掉放行分支）→ 自检红。
 2026-09-14 15:51:38 +08:00
JianFeeeee
153985e8b1 补投路径漏传档位（full 档被误拦）—— 修因 + 兜底，并顺出同族另外四个字段 
pi 报告：离线补投的邮件把 full 档会话当 workspace 档申请审批 → 服务端 409 →
桥按「永久失败」当场 block → 这一轮 bash/write/edit 全被拦（SSE 实时送达不受影响）。
jianf 让 pi 把这件转给我，我这边定位后**先跑变异再改**。

## 1 根因：`mailToEvent` 少搬字段（不是服务端不给）

`lib/catchup.js` 的 `mailToEvent()` 只搬了 8 个字段，没有 `permission_mode` /
`permission_enforcement`，于是 worker 的 `msg.data?.permission_mode || 'workspace'`
落到默认档。**pi 以为收件箱行不含档位、于是建议"要么动服务端载荷要么另取一次"——
实测不成立**：服务端一直就给了（`repo.ListInboxScoped` 的 SQL 里有
`JOIN sessions s` + `COALESCE(NULLIF(s.permission_mode,''),'workspace')`，
`models.Mail.PermissionMode` 的注释写明"补拉路径必须有它们"）。所以修因只在插件侧：
补上这两个字段，键名与 SSE 逐字一致；缺字段时给空串（**不猜档**，猜宽了就是提权）。
`lib/catchup.js` 在四个桥里**逐字节相同**，一次改动四边同步（改后 md5 仍为一份）。

## 2 兜底：409 带档位时按档位处置

服务端在"档位不该问人"时也回 409，并在回包里带 `permission_mode`。两种 409 的正确反应
**相反**：无人可问 → 拦；**full 档 → 放行**（本档无需审批，拦了就是把能干的活干死）。
`src/worker.mjs` 的 409 分支先认 `permission_mode === MODE_FULL` 放行，
plan 档与"链上没有人类"照旧 fail closed —— 只有服务端明说 full 才放行。

## 3 顺出的同族字段（用"配对"扫出来的，不是猜的）

把四个桥**读投递事件的字段**与 `mailToEvent` 的产出对了一遍，邮件类字段还缺三个：

- `from_human`：dsh 的提示词靠它决定说不说"回信不用你自己发"。缺了它，
  **人发来的信在补投路径上被当成 Agent 来信、失去自动回信**（服务端注释早写明）。
- `in_reply_to`：SSE 那边等于 `ParentMailID`。缺了它，"这封是对我的回复"被当成新派的活，
  两边互相客套到撞 hop 上限（生产实测 6 轮）。行里叫 `parent_mail_id`，**只改名不推算**。
- `session_alias`：缺了它插件只有 session_id，而 `send_mail` 不接受 session_id。

`reply_address` 是**唯一**行里真的没有的字段（SSE 在 notify 里按收件人现算）。
服务端注释明确说"插件不必自己拼（拼错了就是静默开新会话）"，所以由服务端补：
`models.Mail.ReplyAddress` + `ListInboxScoped` 填 `FormatAddress(from_name,"",alias)`，
插件只搬运。

## 4 判据（这次事故**单独看任何一个桥的测试都发现不了** —— 缺口在接口上）

- `test/catchup.test.mjs`：补投必须带档位（缺字段给空串而非猜档）；
  ★ **四桥配对**：把 dsh/pi/zcode 读的邮件字段与补投产出配对，缺了就红
  （非邮件事件字段走显式 ALLOW 并各写理由，白名单不许膨胀）。这条正是本次缺口的形状。
- `test/permission-mode-409.test.mjs`：409 + full 必须放行且放行分支在 block 之前，
  非 full 仍拦；带**判据自检**（拿掉放行分支后必须判红）。
- `server/internal/repo/session_scope_test.go`：收件箱行带 `permission_mode`（含"没设过
  回落 workspace"的反向对照）与 `reply_address`（与 `FormatAddress` 同形、path 位为空）。

变异验证：mailToEvent 去掉档位 → 2 条红；worker 新读一个补投没产的字段 → 配对判据红**并点名该字段**；
409 分支拿掉 full 放行 → 自检红；SQL 把档位写死成 workspace → Go 判据红。

## 验证

`go test ./...` 全绿（新增 2 条）；四个桥套件全绿（pi 439 / dsh 381 / opencode 331 / zcode 385）。
**未部署**：`/opt/agentmail` 与 `sudo ./deploy/install.sh` 都在我的工作区之外（本会话文件策略
workspace-write，放宽需审批而这条链上没有人类），所以修复已进仓但**线上仍是有缺陷的版本** ——
需要有人跑一次 `sudo ./deploy/install.sh`（脚本自己会跑齐各套件）。
 2026-09-14 15:49:45 +08:00
JianFeeeee
be0693821b fix(agents): 四家桥的 read_inbox 一律按会话收窄（dsh/opencode/zcode/homeagent） 
用户：「你还是没修好不同 session agent 收件箱隔离的问题」。上一轮我只修了 **pi**，
另外四家还漏着 —— 它们是**每一家各自实现** read_inbox，不修就还是漏。

## 缺陷

列表按 Agent 列（整个收件箱），而 read_inbox 按契约把**列出来的都标成已读**
⇒ A 会话的回合会把 B 会话的未读标掉 ⇒ B 之后按 `?status=unread` 补投时
再也看不到那封信（静默丢信，不是"少看一封"）。用户是在别的 Agent 上看到它的。

## 四家的修法（各自平台能力不同，但都要"并发安全"）

| 桥 | 会话来源 | 为什么这样做 |
|---|---|---|
| dsh | 工具第二参数 `exec.agent.id` → `reverseMap` | 平台就在上下文里给了会话；**不能用模块级"当前会话"变量**（同进程可能同时跑多条会话的回合，会互相覆盖） |
| opencode | 工具第二参数 `context.sessionID` → `reverseMap` | 同上 |
| zcode | `AGENTMAIL_SESSION_ID`（在**调用时**读） | 一轮一个进程，驱动本来就注入它给授权钩子用；调用时读，避免将来复用进程拿到旧值 |
| homeagent | `p.currentSessionID`（回合开始设、结束清） | Go 插件，本来就有这个状态 |

取不到会话一律**退回整体收件箱**（历史行为），不猜 —— 猜错就是静默丢信。

## 判据

- 服务端语义：`server/internal/repo/session_scope_test.go`（读 A 不动 B、列表收窄、
  计数与列表口径一致）。
- 桥侧接线：dsh 4 条、opencode 3 条、zcode 3 条、homeagent Go 1 条
  （`TestInboxURLScopedBySession`，直接断言拼出来的 URL）。
  每家都带**判据自检**：拿旧写法喂进来必须判红；dsh/opencode 还专门断言
  "不得用模块级当前会话变量"。
- **部署件**（不是仓库）：四家的部署快照里都能 grep 到 `session_id=`。
- **线上实测**：用 opencode 自己的 Agent 身份请求收窄列表 —— 会话 A 3 封、
  会话 B 0 封、两者无交集、且都是全量的子集。

套件：opencode **331**、dsh **381**、zcode **385**、homeagent ok，全绿。
四家桥已重新部署（dsh/opencode/zcode 快照切换 + homeagent 新 plugin.bin 并重启），
四个服务均 active。
 2026-09-14 12:07:45 +08:00
JianFeeeee
552fbc731e fix(inbox): read_inbox 按会话收窄 —— 修「不同 session 的 agent 都能看到全部邮件」 
用户问：「你之前不是说你已经处理了不同 session 的 agent 都可以看到全部邮件的
问题了吗？」——**我得先纠正事实：上一轮我只做了诊断并问要不要动手，没有实施。**
这是我的表述问题（把"已定位并给了方案"说成了像"已处理"）。现在实施。

## 缺陷

`read_inbox` 是**按 Agent** 的：列的是该 Agent 的全部未读（含别的会话的来信），
并按契约把列出来的都标成已读 ⇒ A 会话的 worker 标掉 B 会话的未读。平时看不出来
（SSE 事件在途时队列兜着），但桥重启/漏事件后的补投判据是 `?status=unread` ——
被标掉的那封**再也不会补投** ⇒ 静默丢信。现场实例：另一条会话的来信在
`mail_reads` 里的 reader=pi、时间正是我读自己收件箱的那一刻。

## 改动

- **网关**：`GET /mail/inbox` 与 `POST /mail/read` 支持可选 `session_id`。
  不带 = 旧语义（整个 Agent 的收件箱，浏览器/脚本仍可用）；带了就只在这条会话内
  列与标。`ListInbox` / `MarkAllInboxReadFor` 保持原签名并委托给新变体 ——
  老调用点一个都不用改。
- **pi 桥**：`read_inbox` 把自己那条会话拼进 URL（worker 通过闭包把**邮件会话 id**
  递给工具，而不是在启动时取快照）。

## 判据

- repo 三条：列表按会话收窄（含"不带会话时两条都在"的反向对照）、
  ★"标会话 A 不动会话 B"、会话内计数与列表口径一致（否则界面会出现"徽标 2、列表 1"）。
- handler/网关：非法 `session_id` ⇒ 400（不静默忽略）。
- pi 接线三条（URL 拼了收窄、worker 递了 id、判据自检：旧写法必须判红）。
- 线上只读 E2E：两条真实会话 A/B 列表**无交集**、不带会话能列出全部、非法 id 400。

## 过程中测试当场抓到"只改了一半"

`MarkAllInboxReadForSession` 里插 `mail_reads` 的语句我加了会话条件，
**刷新冗余列的 UPDATE 忘了加** ⇒ 返回的"标掉几封"变成 2（应 1）。
判据一眼看出来了 —— 这类"改一半"正是这次要防的。

## 范围（诚实说明）

另外四家桥（dsh/opencode/zcode/homeagent）的 `read_inbox` 工具签名里**没有会话上下文**
（`execute(args)` / `execute(args, ctx)` 各不相同），要按各自框架的上下文 API 接线，
不是一行改动 ⇒ **未做**，列为待办（位置已定位）。所以：pi 上这个缺陷已消除，
另外四家仍在。

## 部署

网关已部署并线上验证；pi 桥的部署**延迟到本轮结束后 150 秒**执行
（重启 pi 桥会掐掉我自己这一轮 —— 之前真发生过），日志
`/var/log/agentmail-pi-redeploy.log`，可用 `node deploy/check-deploy-drift.mjs` 核对。
 2026-09-14 09:19:25 +08:00
JianFeeeee
51789ee72e deploy: 标准目录部署 —— 运行时不再依赖源码目录 
用户注意到：「当前 agentmail 是在源码目录部署的，应当改为标准目录部署」。
查证后有三处实证（都不是猜测）：

1. ★ **失败通知钩子执行的是仓库里的脚本**
   （`/home/program/agentmail/deploy/service-failure-notify.mjs`，8 处引用：
   4 个 drop-in + zcode/zcode-mail-bridge 单元 + agentmail-failure-flush）。
   仓库一挪/一改名，故障通知就**静默失效** —— 而那条管线正是用来报告服务故障的。
2. **opencode-serve 的 cwd 就是源码目录**（`WorkingDirectory=/home/program/agentmail`）。
3. ★ **仓库里的 `deploy/*.service` 是旧的源码目录版本**（ExecStart 指向
   `/home/program/agentmail/plugins/...`），而机器上的已被改过 —— 也就是说
   **谁跑一次 install.sh 就会把部署退回源码目录**。drop-in 更是只存在于 /etc 里，
   仓库完全没有它们。

## 改动

- **唯一真相**：`deploy/systemd/` 镜像 systemd 目录结构，收进全部单元与 drop-in
  （8 个单元 + 12 个 drop-in），路径全部改到 `/opt`。
- 运行时脚本装到 **`/opt/agentmail/bin/service-failure-notify.mjs`**（自包含，
  无相对导入）；`install.sh` 与 `redeploy-gateway.sh` 都会幂等地装它。
- opencode 的 cwd 改为 `/opt/agentmail`（与网关一致），已重启生效
  （`/proc/<pid>/cwd` 已核）。
- 删掉 `deploy/*.service` 的旧副本，避免两个真相。
- dsh 的 `cordis.patch.yml` 注释里的安装示例也改到标准位置（运行时用的是环境变量，
  那条注释是唯一残留）。

## 判据（`deploy/check-deploy-drift.mjs` 新增「标准目录部署」四条 + 自检）

① 任何 unit/drop-in 都不得引用源码目录；② 已安装单元与 `deploy/systemd/` 逐字节一致；
③ 通知脚本在标准位置且可执行；④ 各服务的 cwd/ExecStart 不在源码目录
（homeagent/dsh/zcode 是**别的产品**的标准位置，按白名单放行）。
自检两个样本：引用源码目录的必须红、干净样本必须绿（证明不是恒真）。

顺带修掉一处**真漂移**：仓库里 dsh 的 `dist/index.js` 落后于部署件（改了 src 没重建），
重建后 `check-deploy-drift` 报「四个宿主都在跑当前代码」。

## 复核

- `/etc/systemd/system/` 引用仓库：**0** 个文件；`/opt/agentmail` 下只剩旧二进制/备份里
  的构建路径（Go 嵌的源码路径，无害）与一条注释。
- 四个宿主都在跑当前代码；标准目录四项全绿。
- 全部服务 active，opencode/网关 cwd 均已在安装根下。
 2026-09-14 08:38:33 +08:00
JianFeeeee
5b6fef764f feat(appearance): 主题与壁纸搬到服务端（账号级）—— 回答"为什么背景存在本地" 
用户质问：「为什么背景是保存在本地而不是服务器！」当时的实情是主题与壁纸只写
localStorage：换设备/换浏览器就没了，而且**多账号共用一份**（键是全局常量
`agentmail.background`）—— 同一台机器换账号背景不跟着走。而 localStorage 的 ~5MB
配额也解释了客户端那套"压到 2.4MB 以内"的限制本来就是为本地存储设计的。

现在：**服务端是权威（账号级），本地只是缓存**（首屏秒开、离线可用）。

## 服务端

- 新表 `user_appearance`（两种方言），用**列**而不是 JSON：blob GC 要一眼看出
  "这张图还有没有人用"。
- `/api/v1/me/appearance`：GET / PUT（主题+背景档）/ POST image（multipart）/
  GET image / DELETE image。鉴权同其余 /me/*（cookie 或 Bearer）。
- 图片走**内容寻址的 blob 存储**（与附件同一套），库里只存 sha256；上限 4MB 兜底
  （客户端会先压到 ~2.4MB），只收图片类型（非图片 415 —— 浏览器会把非图片渲染成
  空白，用户只会看到"设置了却没变化"），超限 413 不静默截断。
- ★ **blob GC 的引用源加了这张表**：我在实现前先读了 `SweepUnreferencedBlobs`，
  它只认 attachments / calendar_attachments。漏了这一处，壁纸会在下次 GC 时被当
  孤儿删掉，而库里那行还在 —— 表现为"图 404、设置却显示已设置"。判据同时验了
  壁纸存活**与**孤儿确实被清（否则"还在"可能只是因为 GC 没跑）。

## 客户端

- `lib/appearance.ts`（纯函数：两侧形状换算、data URL→Blob）+ `stores/appearanceSync.ts`
  （pull / push / 去抖订阅 / 账号切换重新拉取）。
- 三条不变量都有判据：拉取以服务端为准；★ **拉取不会再推回去**（否则是自触发回环，
  一次拉取顺带一次 PUT，服务端 updated_at 被无意义刷新）；本地改动会推上去。
- 壁纸**只在换图时上传一次**（几 MB 不该每次 PUT 都跟着走）。
- 降级**必须可见**：未登录/不可达 → `local-only`，推失败 → `pending`，背景设置里
  有徽标与说明（"已同步 / 待同步 / 仅本机"）。静默降级会让人以为已经同步，
  然后在另一台机器上发现没有 —— 正是这次的缺陷。
- 图片用**带认证的 fetch** 取回再转 data URL：`<img src>` 发不出 Bearer，而
  `?token=` 会把密钥写进历史记录与服务端日志（明确不做）。

## 判据

- Go 10 条：往返、★多账号隔离、非法值归一、上传/取回字节一致、非图片 415、
  超限 413、删除、未登录 401（五个端点）、★GC 存活 + 孤儿对照。
- 客户端 10 条：形状换算、image 无图退回 none、越界夹取、拉取生效、
  ★拉取不推送、推送 payload、未登录/500 → local-only、推失败 → pending、
  ★壁纸只上传一次。
- 全量：server 10 包全绿、客户端 249 通过（含打包一致性判据 —— 它先红后绿，
  因为前端改了必须重打安装包，这条护栏是先前特意留下的）。

## 线上验证与交付

- jianf 设置 → 回包 saved=true；**gui-lab 读到自己那份默认值**（隔离生效）；
  gui-lab 上传 67B PNG → 取回 sha256 一致、`has_image=true`；DELETE 后 404。
- 网关已重打（WebUI 内嵌）并部署；Electron 安装包已重打（AppImage + deb）。

遗留：鸿蒙端还没有外观功能（数据已在服务端，将来可直接读）；本地缓存仍在（离线可用）。
 2026-09-14 08:32:22 +08:00
JianFeeeee
1ec88866ac fix(permission): 另外四家桥的"人类说明"缺口 —— 三家修、一家本来就有 
承接 453f451（pi 桥）。用户批准后把同款缺口在其余四家逐一核对：
**zcode 本来就有**（`说明：${decision.note}`），homeagent / dsh / opencode 三家缺。

## homeagent（Go，能完整修）

SSE 事件结构里**根本没有 Note 字段**（json 里只有 decision/decided_by）⇒ 备注在
解码那一步就没了。补上字段，并把提示词抽成纯函数 `permissionDecisionPrompt(evt)`，
加了判据（说明必须出现 + 反向对照：无说明/空白说明不得凭空造出说明段）。
构建（`go build -buildmode=plugin`）后 install 到
`/home/newqqagent/plugins/homeagent-mail-bridge/plugin.bin` 并重启，已核验部署件
含新符号（`grep -a`，中文用 strings 查是查不到的）。

## dsh / opencode（平台回执放不下理由 → 分两步）

两家的审批回执都是**三态字符串**：DSH `ApprovalOutcome` 只有
allowed-once / rejected / cancelled / unavailable，openCode 只有 once / always / reject
—— **没有地方放人类的说明**。所以：

1. 提示词（"你之前发起的权限请求已有结论：…"）统一走 `permissionPrompt(data)`，
   带上 `用户的说明：…`。dsh 原有**三处**内联文案（续谈/新会话/通知投递），
   措辞分叉正是这类信息漏掉的地方 —— 判据直接钉"只有一处拼这句话"。
2. 带说明的决策**另投一趟通知**，让模型在会话里看到理由。代价是多一轮；比悄悄
   丢掉人的指令轻（原缺陷就是丢了指令，模型把同一条命令换写法又问一遍，连问 9 次）。
3. 决策回执不再被当成"新任务"（内容已随 permission_decision 交付），并记下
   `decision_mail_id` 防重复 —— 与 pi 桥同源。

判据：dsh / opencode 各 5 条（含"拿缺陷时的源码形态喂进来必须判红"的自检）。

## 部署与代价

- dsh → 快照 20260914-081456、opencode → 20260914-081516、homeagent → 新 plugin.bin，
  三家的服务 active 且心跳/连接已核。
- 重启 dsh 时它正在"续谈"一封邮件（08:10:45 日志）——事后核对：那一轮**已回完**
  （faad0037 的 parent = 4919aa88），没有丢活。
- 套件：dsh 372、opencode 323、homeagent go test ok、zcode 382 全绿。
 2026-09-14 08:17:23 +08:00
JianFeeeee
453f451fbb fix(permission): 人类的备注必须到达模型 + 决策回执不再被当成新任务 
用户报的「很严重的问题」：被拒绝的 agent 看不到授权备注，且看不到他发的回复邮件。
按数据查到了两个**真缺陷**，都在桥的权限回路上（不是猜测，三层证据）。

## 缺陷一：备注在桥内被连丢三处

网关其实一路都带着备注（`CreateDecisionMail(..., req.Note)` 把备注写进决策邮件正文，
SSE payload 里也有 `"note"`），但桥的三个环节只传 decision：
  index.mjs  `pool.routePermission(relayKey, String(data.decision))`
  pool.mjs   `child.send({type:'permission_decision', relayKey, decision})`
  worker.mjs `resolve(String(msg.decision))`
模型最终看到的只有 `用户拒绝了这次 bash 调用`（pi 会话转录逐字可查）。

现场：人类写「我说了让你拉取仓库到program下你听不懂吗」，模型不知道要改什么，
把同一条命令换个写法又问了 —— 会话里连问 **9 次**（22:16–22:26）。

## 缺陷二：决策回执照样被当"新任务"投递 + 等人的邮件被堵在后面

决策是**双通道**送达：SSE `permission_decision`（唤醒停放的 worker）+ 一封普通形状的
邮件（"Re: 权限请求 - 拒绝"）。以前两条都会起动作 ⇒ 同一件事被处理两次；而这条会话
的新邮件在 worker 停放期间只能排队。实测：人类 22:18:08 发出的更正
「不对，不是让你拉取到agentmail仓库，是让你拉取到program仓库！！」
直到 22:26:30（worker 回合结束）才被模型看到 —— **8 分钟**里它一直在错误的目录上打转。
转录里那封更正确实是模型自己 `read_mail` 读到的（不是没人给它）。

## 改动

- 网关：`CreateDecisionMail` 写 `mail_type='permission_decision'` —— 桥据此区分
  「控制面回执」与「新任务」。
- pi 桥（新增 `lib/denial-reason.js`、`lib/waiting-mails.js`）：
  · 备注随决策一路透传到**模型看到的拒绝理由**（工具拦截与通知投递两条路都带）；
  · 恢复停放的 worker 时，顺带把「等人期间新到、尚未标记已读」的邮件附进理由，
    模型当场就能改道（这正是那 8 分钟的洞）；
  · 决策回执不再起新任务轮次（记进 deliveredMails）；若决策事件尚未到达，
    退化为 B-4.3 的通知投递，且没有会话时不凭空新开。

## 判据

- `test/permission-note.test.mjs`：11 条（备注进理由、无备注不得凭空造说明、
  等人期间的邮件要点名 read_inbox、只挑本会话非权限类未交付的、上限、旧回包缺
  session_id 不能丢邮件、接线 8 处形状、判据自检）。
- **扰动验证**：把备注从 `pool.mjs` 的 send 里去掉 → 接线判据 2 条红；恢复 → 11 绿。
- 既有 pi 套件 420/420；server 10 包全绿（新增 1 条 Go 判据验决策邮件的类型与备注正文）。

## 现场证据（可复核）

- 桥日志：9 次 `权限 <key> 决策 同意/拒绝（决策人 jianf）已转交 worker`，全程不含备注；
  「worker 2135211 等待权限决策，让出并发额度（停放 1/5）」
- 会话转录：`{"toolName":"bash","content":[{"text":"用户拒绝了这次 bash 调用"}]}` ×6
 2026-09-13 22:47:25 +08:00
JianFeeeee
49ec22f916 fix(pi): 等人点头的 worker 不再占并发额度，也不会被硬超时杀掉 
实测（今天全 Agent 演练时撞到的）：pi 的 `maxWorkers=3` 被**三个正在等人工授权**的
worker 吃满，于是新邮件只能排队 —— 而人可能十分钟后才看邮箱。清掉卡住的请求后队列
立即排空，机制本身没错，错的是"等待"被当成了"在干活"。

两处改动（`src/pool.mjs`）：

1. **等待期间让出并发额度**。worker 发 `permission_pending` 时把它的 entry 标为
   parked，`pump()` 只数"在干活"的（`activeCount()`）。停放另有上限 `maxParked`
   （默认 5，防止内存无界：每 worker 约 140MB）；超出后仍占额度并打日志说明。
   决策到达（`routePermission`）时解除停放，回到额度里。

2. **等待期间暂停硬超时**。硬超时的用途是回收**卡死**的进程，而等人点头不是卡死：
   停放时清掉计时器，决策到达后重新起一个完整窗口。否则 worker 会在人还在读邮件时
   被 SIGKILL —— 那次工具调用直接消失，人后来批了也没人接（这类"批了没反应"的现象
   与此吻合）。

判据（`test/pool.test.mjs` 新增 3 条）：
  · ★ 等待授权的 worker 让出额度：另一个会话的邮件必须能开跑
  · ★ 等人点头期间（800ms > 300ms 硬超时）不得被强杀，且恢复后能跑完
  · 停放有上限：超出后仍占额度（不无限超发）
**扰动验证**：整块回退到 HEAD → 3 条全红；修复后 3/3。全量 pi 套件 420/420。

已部署（快照 20260913-131216，桥重启并重新心跳）。
 2026-09-13 13:14:56 +08:00
JianFeeeee
77699e216b fix(webui): 新到的授权请求藏在折叠分组里 —— 徽标动了，内容看不见 
用户报告："我点到授权界面，才更新显示授权请求"。

先排除了推送本身：实测徽标是**实时**更新的（gui-lab 授权 7→8、jianf 1→2，
都没导航）。问题在内容：`PermissionList` 的展开状态
`const openSet = expanded ?? new Set(autoOpen)` —— 一旦手动点过一次，
`expanded` 就冻结成"点的那一刻"的快照，此后新到的待决请求落在一个折叠的分组里：
徽标数字变了，正文却看不见，直到离开再回到授权页（组件重挂载、`expanded`
回到 null、默认展开重算）才出现。

这违反代码自己的设计意图（注释写着「有待决策请求的会话默认展开：那些是在等人
动手的，藏起来等于没解决问题」）。

修法：加一条**状态迁移**判据 —— 新出现的待决邮件（`sessionId:mailId`）让它所在
的会话自动展开。用 mail_id 而不是"会话有没有待决"作判据，是因为实测撞到的正是
"会话早就有待决、用户把它折叠了，之后又来了一条"；而用户在那之后再手动折叠同一
条不会被弹开（没有新 mail_id）。

验证：
  · 真浏览器复现：授权 2 → 3 而新请求正文不可见，重进页面才可见（复现成功）
  · 新增 `test/components/PermissionList-autopen.test.tsx`（3 条，含反向对照）
  · 扰动验证：撤掉修复 → 2 条目标判据红、对照判据仍绿；恢复 → 3/3
  · 部署后同一探针复验：折叠状态下新请求**立刻可见**，不再需要重进页面
  · 前端 239 测试全绿；桌面重打包与 WebUI 同源（index-jaRgHqX2.js）

顺带修掉一个**更严重的缺陷**（在做「用 zcode 写个网页」时被 agent 自己报出来的）：

  fix(plugins): zcode 的 read_mail 永远返回空正文

agent 回信原话：「read_mail 返回的正文是空的，收件箱预览在「点击计数…」处被截断」
—— 它因此只看到前两条要求，写出来的页面漏了第 3 条（生成时间）。

根因在 `lib/inbox-format.js` 的渲染端：

    const body = m?.body_preview || m?.body || '';
    lines.push(`内容: ${String(body).slice(0, bodyLimit)}`);

zcode 的 read_mail 用 `bodyLimit = 0` 表示"要全文"（HTTP 侧 `?body_limit=0`
也确实是这个语义，服务端返回了完整正文），但这里 `slice(0, 0)` 把正文渲染成
**空字符串** ⇒ 模型永远读不到全文，只能看收件箱里那段预览。

修法：`bodyLimit <= 0` 视为不截断；不截断时优先取 `body`（单封接口可能同时带
`body_preview`，那是短的那个）。四份副本逐字节同源（`check-shared-libs.sh`
通过），每个桥各加 2 条判据：0 = 不截断、不截断时优先全文。
扰动验证：退回旧写法 → 2 条红。

端到端验证：让 zcode 读全文并原样回报最后一行（一个随机标记）。
修复后它精确回出 `最后一行标记：ZTOKEN-2c7561fd` ✓ —— 修复前这不可能。

四家桥都已重新部署到新快照（pi/opencode/dsh/zcode），部署漂移检查：
「四个宿主都在跑当前代码」。测试基线：pi 417 / opencode 323 / dsh 372 / zcode 382。
 2026-09-13 10:39:26 +08:00
JianFeeeee
2e28696e74 fix(pi): 模型选择落到「宿主默认」是静默的，而且日志把它说成「平台默认」 
## 现场

pi 每封来信都报 `模型 (平台默认) 失败: 402: Insufficient Balance`。
**把它读成「平台的模型没钱了」是错的** —— 真相是：

- `modelAttemptOrder(范围, env默认)` 在「平台没划范围 **且** env 没指定」时
  返回 `[undefined]`，语义是「交给宿主 SDK 用它自己的默认模型」；
- pi.env 里 `AGENTMAIL_REPLY_PROVIDER/MODEL` **都是空的**，而
  **opencode.env 里钉了 `llmsproxy`/`AUTO`** —— 这就是为什么其它三桥通、只有 pi 不通；
- 于是落到了宿主的默认：`/root/.pi/agent/settings.json` 的
  `defaultProvider: deepseek` + `defaultModel: deepseek-v4-flash`
  —— **直连 DeepSeek 云**（不是本地代理），那边的余额是零；
- 而那个名字连本地代理的目录里都没有（目录是 `deepseek-v4.1-flash`），
  所以即使指对了代理也会 403。

## 修

1. **配置**（`/etc/agentmail/pi.env`）：按 opencode 的约定钉上
   `llmsproxy` + `AUTO`，并在注释里写明「留空的语义是交给宿主默认，平台管不着」
   —— 这个语义本身就是坑。
2. **代码**：把那句 `(平台默认)` 改成 `宿主默认（平台未指定模型）`，
   并在「平台未指定模型」时**显式告警**一次。一句话的日志差别决定了排查方向：
   「平台默认」把人引向平台配置，「宿主默认」直接指向 `~/.pi/agent/settings.json`。
3. **断言**：`modelAttemptOrder` 的 `[undefined]` 语义 + 「源码里不能把宿主默认
   写成平台默认」（只看字符串字面量，免得注释里的解释也被禁掉）。

## 验证

- 配置前：`env | grep -i zcode|agentmail` 那条待决请求被拒（它会把 worker 环境里的
  `AGENTMAIL_AGENT_KEY` 打进模型上下文）；顺带清扫 9 条早前实验遗留的待决请求。
- 配置后真发一封进 pi 的**已有会话**：6 秒内收到回信，标记原样返回 ✓
- 四桥漂移检查全通过；pi 415 测试全绿；「平台未指定模型」告警在生产日志里出现 0 次
  （说明配置确实齐了）。

## 仍然待定（需要你定）

`/root/.pi/agent/settings.json` 的宿主默认 **仍指向 `deepseek/deepseek-v4-flash`**。
它影响**交互式 pi**（人工开着 pi 干活时用的就是它），而且那个模型名不在本地代理目录里。
桥这条路已经绕开它了，但要不要把宿主默认也改成 `llmsproxy/AUTO`
（与 opencode 一致）需要你拍板 —— 那会改变交互式会话的行为。
 2026-09-12 23:31:44 +08:00
JianFeeeee
630b5bfdd7 fix(bridges): 续谈失败静默 + duplicate_relay 静默挂死（两个都是「人那边什么都收不到」） 
同一类问题在两个地方：出事的当下看不出来，表现是「信发出去了，然后再无音讯」。

## 1）pi 的续谈失败不回失败信（实测缺口）

模型侧 402（余额不足）时，**新会话**那条路会回一封「处理失败」，而**续谈**那条路
只写日志就 `throw` —— 发件人什么都收不到。邮件驱动的会话没有本地界面可以看，
没有这封信就等于静默挂死。复现条件很普通：往一条**已存在**的会话再发一封信。

修法与邻居一致：续谈失败也回失败信。但**不能复用**共用库的 `renderFailureReport`
——那段文案说「划定范围内的模型全部调用失败」并建议「调整可用模型范围」，
而续谈是**故意不降级**的（换模型＝换会话＝丢掉上下文，而上下文正是发件人指定
这条会话的原因）。照抄等于让人去调一个在这里无效的旋钮，他会去改配置，
然后发现依然失败。新增 `renderResumeFailure`：点明是续谈、附上游错误原文、
建议「确实要换模型就新建一条会话」。

**活体验证**（模型侧仍是 402，失败本身就是测试条件）：发一封进 pi 的已有会话，
5 秒内收到失败信，内容含 402 原文且不再出现「调整模型范围」。

顺带把 pi 里 2 处没 clamp 的 relay_key 收敛（上一轮审计只看了权限键）。

## 2）duplicate_relay：只有 zcode 认，另三桥会等一个永远不会来的决策

网关对重复的 relay_key 回 **HTTP 200 `{status:"duplicate_relay"}` 并提前返回**：
不建请求、不发邮件、**永远不会有人来决策**。zcode 桥认它并当场失败，而
pi/opencode/dsh 把它当成功，接着等 `permission_decision` 事件 —— pi 那句
`await new Promise(...)` 连超时都没有。这是 zcode 上一轮那个缺陷的同类，
只是发生在另三个桥上。

- `lib/relay-key.js`（**共用**，四处逐字节同源）新增 `isDuplicateRelay` /
  `DUPLICATE_RELAY_STATUS`：它长得像成功（200），所以必须单独认；对「发信」
  那一侧重复就该当成功（幂等），但对「等一个决定」那一侧它与故障后果相同。
- pi / opencode / dsh 三桥在权限转发处接上判据并**当场拒绝**
  （各自用自己的拒绝形状：`block: true` / `output.status = "deny"` / `'rejected'`）。
- zcode 里那份本地实现收敛到共用库（同一判据不该有两个定义）。

## 3）新增接线断言（带判据自检）

`test/permission-forward-wiring.test.mjs`（pi/opencode/dsh 三份同一内容）：
纯函数测试对这类缺口天生无能为力（函数是对的，只是没人调用它），所以它读源码
验形态，钉住「判据在、落在权限转发这条路上、给出本桥形状的拒绝」。

三条自检都在写的过程中抓到了我自己的错：
- 第一次 `ROOT` 算错 → 过滤后 0 个桥、循环全不跑而「全绿」→ 加了
  「找不到装着各桥的目录就判红」；
- 顺序判据写成「在文件里最早的 await 之前」，量到了别处的等待 → 三桥全红，
  改成「必须在上报之后」；
- dsh 是**两段式**（`.then` 里抛、`catch` 的 `duplicateRelay` 分支里拒），
  第一版抽取套错了分支 → 永远找不到 `return 'rejected'`。
扰动验证：把 pi 的判据禁用后该条变红，还原即绿（改动前后都核对了字节数）。

而 dsh 那条也暴露了：我把返回形状写成了 opencode 的 `{status:'deny'}`，
**`tsc` 没报错**（返回类型是宽联合），只有对着邻居读才发现 DSH 要的是
`'rejected'` 字符串 + `noteDenial`。

## 4）部署脚本：zcode 分支现在会重启驱动

`redeploy-plugin.sh` 的 zcode 分支只切软链（宿主是 ZCode 应用，不能重启它），
但**驱动是我们自己的 unit** —— 不重启它，进程里跑的还是切换前的代码。
这个由刚写的 `check-deploy-drift.mjs` 当场抓到（它比进程启动时刻与软链切换时刻），
而当时所有其它检查都是绿的。已补上重启并验证。

## 复查

四桥全量 413 / 321 / 370 / 380 全绿；共用库四方同源；部署漂移四项全通过；
四桥真发真收冒烟（dsh/opencode/zcode 正常回信；pi 因模型侧 402 回失败信 ——
这正是上面第 1 条要修的路径）。

另：写这段时踩到一个自伤 —— 用 `npx asar extract-file <asar> dist/index.html`
检查包内容时，它把文件**写进了 cwd**，正好覆盖掉 Vite 的源码模板
`client/electron/index.html`（下次构建会拿被污染的模板去构建）。已还原并重建，
产物哈希与之前一致。要看 asar 内容请用 `@electron/asar` 的 API（返回 Buffer），
别用这个 CLI 子命令。
 2026-09-12 23:13:48 +08:00
JianFeeeee
d015d3694c test(zcode): 把门禁判决实验收进仓库（test/manual/gate-e2e.py） 
它是「yolo + 自有工具面 + 我们自己的门禁」这个姿态**唯一**的决定性验证：
批了→命令真执行（比对文件内容，不只看回信）；拒了→命令真没执行（文件不存在）
**且回信把成因说成「人拒绝」而不是「超时」**；同会话第三次调用仍产生新请求
并在获批后执行（幂等键按调用唯一）。之前只放在 /root 下，会随环境丢弃。

顺手修两处会骗人的东西：

1. **不要用 `python3 run.py | tee log` 再取 `$?`** —— 那是 tee 的退出码（恒 0）。
   实测踩过：脚本自己打印 5/6（有失败），后台任务通知却报 exit-code 0，
   日志里那句 `EXIT=0` 完全是噪声。现在脚本把**自己的** exit_code 写进证据文件，
   README 也改成 `set -o pipefail` 的调用方式。
   （同源问题第三次：PIPESTATUS 在 dash 下报错、`go build | head` 假绿、这次是 tee。）
2. **备注文字不再显示在通过项旁边** —— 通过的判据曾挂着「很可能又被当成重复请求
   丢弃了」这种失败提示，会把「全绿」读成「有问题」。

已从仓库路径连跑三次 13/13（不同标记），确认收进仓库后仍可用。
 2026-09-12 19:11:58 +08:00
JianFeeeee
a00cbf36fc feat(zcode): yolo + 自有工具面 + 我们自己的执行门禁（headless 真正能干活了） 
按用户裁定「yolo_own_tools」实现：平台让开（--mode yolo），它自带的一切
「能动机器」的工具被 --disallowed-tools 拿掉，执行类动作改由我们自己的
run_command / write_file 承担，而门禁就在这两个工具里 —— 逐次向发件人请示。

## 为什么必须走这条路（实测，不是推断）

MCP 工具的 needsApproval 在产物里**硬编码为 true**（与 annotations 无关），
而 build/edit 档的判定最后一条是「需要审批 → ask」；headless 没有审批客户端
可问 ⇒ **每个 MCP 工具都被拒**（连 read_inbox 都调不动）。
我们本想让平台把询问转给钩子，但 PermissionRequest 在本版本（3.10.2 / CLI 0.16.5）
**不可靠**：有时压根不注册，触发时也无条件在 ~5ms 内失败、命令从未被 spawn
（用「钩子写 marker 文件」的副作用验证）。

于是选择只剩两个：「平台问、但问不到人 → 全拒」与「平台不问、我们自己问」。
后者才既可用又可审计。代价（平台不再提供第二道防线）写进了 README 的残余风险。

## 新增

- `lib/approval.mjs`：授权往返的唯一实现（钩子与工具共用，否则必然漂移）。
  三条不可动摇的规矩：只有明确同意才放行（判据是共用库的前缀白名单，
  不是「不等于拒绝」）；永久失败（409/4xx）当场拒绝并把服务端建议带给模型；
  暂时失败看有没有本地界面 —— 判据用**调用方传的 sessionId**（单一事实来源，
  不再另读环境变量）。自己开 SSE 等决定，先建连再发请求。
- `lib/action-tools.mjs`：`run_command` / `write_file`。输出上限、超时上限、
  默认 cwd=工作区；拒绝时**抛错**（MCP 层转 isError）而不是返回「已处理」——
  opencode 上「工具失败但报成功」导致模型连试 6 次后放弃整个任务的教训。
  平台保护目录（网关数据库/插件代码/服务单元/密钥目录）**无论谁批准都不写**，
  且判定在门禁之前（不消耗人的注意力）——防的是自我强化：邮件驱动的 Agent
  可能被来信诱导去改自己的插件代码，改完下一轮就换了一套规则。
- `REVIEWED_DENYLIST`（32 项）：逐条按「不拿掉会怎样」分类。名单来自 CLI 产物里
  模型可见工具名的**权威注册表**（aIn 那个 28 项数组）+ 另一份更宽的候选集并集，
  **不采信模型自述**（基线里它用某个没点名的方式真的创建了文件）。
  最容易被漏掉的是 `js` / `mcp__node_repl__js`：它挂在 MCP 上、
  产物里自述「can run arbitrary JavaScript with full Node privileges, like Bash」。
- 提示词的能力说明（分档）：告诉模型自带工具被禁、动手要用哪两个工具、
  会被请示；并明确「被拒是业务结果，不要重试、不要绕道」。

## 修掉三个真缺陷（都是实测撞出来的）

1. **幂等键按「会话+工具」取 → 同会话第二次调用被静默吞掉**。
   网关对重复 relay_key 返回 **HTTP 200** `{status:"duplicate_relay"}` 并提前返回：
   不建请求、不发邮件、**永远不会有人来决策**。于是工具干等 → 被 MCP 调用超时
   砍掉 → 模型回报「30 秒内未获批准」。从状态码到措辞全看不出问题，归因还完全
   错了（像是人没理它）。改为**按调用唯一**（保留会话/工具前缀便于反查），
   并把 duplicate_relay 当成可读的拒绝（fail fast，不再干等）。
2. **授权窗口被 MCP 调用超时截断**。ZCode 对 MCP 工具调用有超时（默认量级 30 秒），
   而门禁要等人。已在插件清单声明 `mcpServers.agentmail.timeoutMs=600000`
   （实测生效：40 秒的命令没被砍，墙钟 50 秒通过），并让门禁**自己**把等待夹到
   timeoutMs - 余量之下（`resolveWaitMs`）——被客户端杀掉时连理由都发不出去，
   所以必须由我们自己先 settle。
3. **`--allowed-tools` 在 help 里写着但解析器不认**（`Unknown option`）。
   留着会拼出一条永远跑不起来的命令行，现在 `buildRunArgs` 直接抛错并指出
   替代方案。我在这里误判过一次：先看到「文件没创建」就以为白名单生效，
   其实进程只是没退到 usage。判据缺了「进程真的执行了」这一环。

## 自报改成如实

detectModeEnforcement 以前拿「钩子已注册」当 native 的凭据 —— yolo 下钩子
根本不会触发，那等于替一个不存在的能力背书。现在先看**我们那条链**是否就绪
（yolo + 禁用清单里真的有 Bash/js），就绪才报 native，并在理由里点明谁在把关
（实测输出：「执行类动作只能经我们自己的门禁…平台自带危险工具已禁用 32 项」）。

## 验证

- 单测 376/376（新增 47 条）。重点在反向对照：一句「拒绝/deny/空串/平台自己的
  shutdown 哨兵都不放行」之外，还验了「别人的决策不能拿来用（relay_key 配对）」、
  「超时必须真的拒绝」、「同一会话两次调用必须用不同的幂等键」、
  「重复请求要当场拒绝而不是干等」；执行工具的每条拒绝场景都配一个**文件系统断言**
  （「抛错了」不等于「副作用没发生」），保护目录还验了 `..`/`./` 绕不过去。
- 真模型端到端（`/root/e2e-zcode-gate/run.py`，13/13）：
  批 → 命令真执行（文件内容=标记）；拒 → 命令真没执行（文件不存在）
  且回信把成因说成「人拒绝」而**不是**「超时」；同会话第三次调用仍能产生新请求
  并在获批后执行。判据本身也修了两处（授权请求邮件里带标记会被误当成回信；
  备注在通过项旁边显示会误导）。
- 部署：`deploy/redeploy-plugin.sh zcode` 快照切换 + 握手自检；
  驱动单元改为跑快照（生产不跑仓库工作区），env 与清单超时的关系写进注释。
- 顺手清掉一个遗留驱动进程（跑的是仓库路径的旧代码、连着网关 SSE、会抢邮件）。

## 判据纪律（本轮又踩到、已写进代码注释）

「文件没被创建」不能区分「被拦住了」与「进程根本没跑」；
「未获批准」不能区分「人拒绝」与「窗口被截断」；
「工具报错」不能区分「命令失败」与「工具坏了」。
每一处都改成了验到**具体成因**。
 2026-09-12 19:05:54 +08:00
JianFeeeee
10ff50e899 feat(homeagent): 输出通道改造 —— 通道名 email + 注入通道对齐 + 附件走路径 
修的是内核的交付判定与我们对不上的问题。

## 根因

内核判断「这一轮到底有没有交付」**只认工具名前缀** `output_send__*`
（internal/agent/core/process.go 的 isOutputDeliveryTool）。而 `send_mail`
是个普通工具，长得和 read_inbox 没有区别 —— 模型用它发完信，内核不知道
回复已经交付，照常补一句「请根据以上工具结果继续。」。模型把这句话读成
「还要再做一步」，而它手里唯一能做的「一步」往往又是再发一封信。
这个自我强化循环在 QQ 上有过真实事故（单轮 34 次 output_send__qq、514 秒）。

三处改动，缺一不可：

1. **通道名 `homeagent` → `email`**（按投递介质命名，与内核自带的
   qq/webui/cli/acp/a2a 一致），内核据此拼出 `output_send__email`。
   能力位声明必须与实现一致：原先声明了 CapFile 而 handler 不读 `type`，
   于是任何 type=file 都会静默变成一封「把路径当正文」的邮件 ——
   声明一个做不到的能力比不声明更糟（调用方无从发现）。现在 caps=7
   且真的实现 text/file/image。

2. **注入来信时用通道名，不再用插件名**。内核的约定是「用回复该走的通道名
   注入」：webui 传 "webui"，clawhubadapter 传它自己的通道名。我们原先两个
   参数都传 `homeagent-mail-bridge` —— 那个名字**不是一个已注册的通道**，
   于是注入来源、模型被告知要用的通道名、实际注册的通道名三者对不上。

3. **提示词补上平台特有的投递指引**（channel.go 的 deliveryHint）。
   共用的 replyInstruction 对人来信说的是「回信不用你自己发，插件会替你转发」
   —— 那句在 dsh/opencode/pi 上完全正确，在 HomeAgent 上却与内核的 persona
   （「必须显式调用 output_send__{通道名}」）相反。实测：模型听我们的、
   返回纯文本、插件兜底转发，邮件确实到了，但内核不知道已交付。
   现在两条口径对齐：优先走通道，兜底 relay 仍然生效且**不会重复发**
   （通道 handler 先 noteExplicitChannelSend，自动 relay 据此让位）。

同时按新纪律在 plg.json 声明 `sdk: "1.2.0"`；工具链据此同步了 go.mod 的
require/replace（它自己写的，含 store 里的绝对路径 —— 换机器跑一次
hmapdev build 会重新同步）。

## 验证（真模型、真网关、真邮件）

进程构建：`hmapdev build` 报「SDK 1.2.0（项目声明 sdk=1.2.0）」、
子进程模式（协议 2）；go vet 干净、go test 通过。

部署：经内核自己的 pluginmgr（POST 127.0.0.1:9876/plugins，overwrite=true）
0.1.0 → 0.2.1 → 0.2.2，每次 config_kept=true；重启后 loaded/alive/心跳齐全，
插件日志「注册完成（15 个工具 + 1 个输出通道）」。

行为端到端（两封真邮件）：
- 让模型列出通道 → 回信里列出 `email | text / file / image`，与注册的
  caps=7 及描述逐字一致
- 让模型「原样重复标记」→ 内核日志 `executing tool: output_send__email`，
  回流**恰好 1 封**，插件日志「模型已自行回复，跳过自动 relay」
- 让模型建文件并以 type=file 发送 → `cmd_run` → `output_send__email_help`
  → `output_send__email`，附件 chan-file-*.txt（15 字节）原样到达，relay 让位

这两条正是改造的两个动因：内核认得交付（循环被切断），以及附件走
「一个本地路径字符串」而不是 `attachment_ids=[...]` 数组
（opencode 上模型把数组写成 JSON 字符串、连试 6 次放弃整个任务的那个失败模式，
在结构上就不存在了）。
 2026-09-12 17:38:32 +08:00
JianFeeeee
3a6d572020 feat(zcode): 工具加 MCP 注解 + headless 档位映射改为 plan（否则一个工具都用不了） 
## 逆出 ZCode 的 MCP 权限判定，并据此让工具真的可用

逐字逆自 CLI 产物：

  Ari():  annotations.readOnlyHint === true → riskLevel "low"
          annotations.destructiveHint === true → riskLevel "high"
          needsApproval = true   ← **硬编码为真，与注解无关**
  checkBuildMode(): needsApproval || destructive || sideEffectScope !== "none" → ask
  checkPlanMode():  permissionName === "mcp" && !destructive → allow

两条合起来的结论不直观但很关键：

- **build 档下每一个 MCP 工具都要审批**（needsApproval 恒真），而 headless
  模式没有交互式审批客户端 ⇒ 全被拒。实测：模型连 read_inbox 都调不动，
  只能从提示词里猜；更糟的是它**绕道**用 Bash 去读网关的 sqlite WAL 文件
  （它自己在回信里如实交代了这件事）。
- **plan 档下只要不声明 destructive，MCP 工具直接放行**。

于是两处改动：

1. `lib/tools.mjs` 给每个工具加真实注解（读类 readOnlyHint，写类
   destructiveHint:false——它们确实不破坏任何东西）；`lib/mcp-rpc.mjs` 透传
   annotations。**漏传不是"少个提示"，而是工具在该档下全被拒**。
2. `src/turn-mode.mjs` 的 workspace 档映射从 build 改为 **plan**。
   build 在本环境等于「什么都不能做」，那不是保守而是不可用；plan 才是真的
   fail-closed：危险的自带工具被平台直接拒，能用的只有我们声明为非破坏性的工具。
   日志会明确写出为什么退档。可用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖
   （平台修好钩子后只改配置就能恢复 build，不必等发版）。

## 真模型验证

场景 A 的判据同时加强：**正文本标记只出现在邮件正文里**（驱动的提示词只带主题
与 mail_id），所以模型必须真的读信才可能答对。通过 —— 约 20-30 秒一轮。

反过来说，早先那版「通过」是假的：标记在主题里，模型从提示词抄一遍就行。

## 仍然做不到的（见 README 已知缺口）

授权桥（PermissionRequest 钩子）在本版本（3.10.2 / CLI 0.16.5）**不可用**：
有时根本不触发，触发时在 ~5ms 内失败且**命令从未被 spawn**
（用「钩子写 marker 文件」的副作用验证，process 与 command 两种类型都一样）。
所以 workspace 档「危险操作问人」目前在 headless 下无法实现。

单元 329/329。
 2026-09-12 16:49:28 +08:00
JianFeeeee
42816b4d1e fix(zcode): 真模型跑通后发现的三处缺陷（register / 工具活动日志 / SSE 关停） 
真模型端到端（场景 A 通过：6893 事件、175 秒、530 字回信）把三处只有真跑才
暴露的问题照了出来：

1. **register 调不通**：驱动按 pi 的客户端 API 写了 `client.register()`，
   而本插件的 GatewayClient 没有这个方法 —— 靠此前手工注册过才没暴露。
   补上后才发现第二个坑：`/agent/register` 的认证与其它接口**不同**，
   它只认 `Authorization: Bearer` 或 **body 里的 `secret`**，不认 `X-Agent-Secret`
   头（其它接口认）。实测报错：
     HTTP 400 需要 Authorization: Bearer <密钥> 或 body 里的 secret
   所以没密钥时把 secret 放进 body。

2. **一轮 6893 条事件，日志里什么也看不见**：邮件驱动的会话没有界面，
   「模型正在干什么」只能来自日志，否则一个五分钟的回合与一个卡死的回合
   在外部完全一样。新增 `describeRunEvent`，只记工具调用与权限事件
   （全记等于没有日志），并由 runTurn 通过 onEvent 逐个交出来。

3. **关停没真断 SSE**：驱动调的是 `client.stopSSE?.()`，而客户端没有这个方法
   （`?.` 让它静默变成空操作）。改成持有 createSSEClient 的句柄并在关停时 stop。

验证：单元 325/325、授权桥 e2e 5/5、驱动 e2e（桩）7/7、快照握手 12 项。
 2026-09-12 16:16:37 +08:00