jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
291 Commits 1 Branch 0 Tags
7f03ee7ca2404b08aadea3292e028b13e7e013e0
Commit Graph

43 Commits

Author SHA1 Message Date
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
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
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
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
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
b374ce1f20 fix(plugins): 附件 id 归一 —— 修 opencode「做完全部活却发不出附件」 
# 现象（全功能演练抓到，根因来自 opencode 自己的内部记录）

opencode 把四个步骤全做完了（2× download_attachment、read 读到内容、
upload_attachment 成功），却在最后一步卡死：`send_mail` 连续 **6 次**失败，
然后放弃整个任务，自述为「attachment_ids 参数有框架级序列化 bug」。

真实形状（从 opencode 的 part 表里取出的原始输入）：

    input.attachment_ids = "[\"10e73e9f-c2a9-4226-bdb5-34ef1b340eb8\"]"   ← 字符串
    error: 字段 "attachment_ids" 类型不对：期望 string 数组，收到 string

模型把数组写成了 **JSON 字符串**，桥原样转发，服务端的严格解码器按契约拒收。

# 修在哪一层

**不在服务端放宽。** 那个「严格」是刻意的，挡的是字段名拼错、结构写错这类真
错误 —— 松开之后真 bug 会被静默接受（同一封邮件少几个附件，HTTP 仍是 200）。

**在桥这一层收。** 桥是适配器：模型侧的形状天生不可靠，而适配器的职责就是把
不可靠的输入归一成契约要求的形状。对模型宽容、对服务端严格 —— 这与
homeagent 那个 Go 插件里的 `stringList` 是同一个判断（那边注释写着「也接受
单个字符串……拒绝它只会换来一次重试，而意图毫无歧义」）。

接受的形状：数组 / JSON 数组字符串 / 单个 id / 逗号或空白分隔 / 混进 null
与数字时丢掉坏的保留好的。空串与 null 一并丢掉，与服务端
`parseAttachmentIDs` 保持一致。

# 三桥同源

新增共用模块 `lib/attachment-ids.js` + 同名测试，已加入
`deploy/check-shared-libs.sh` 的两个清单（实现与测试都必须逐字节相同 ——
只同步实现不同步测试，等于允许一侧偷偷放宽约定）。
三份 md5 一致，检查脚本通过。

# 测试

`test/attachment-ids.test.mjs` 17 条，三桥各一份。含**反向对照**：把 JSON 字符串
分支去掉后必须变红（实测 3 条失败）—— 否则这条判据就是空转，事故会复发。

全量：pi 401 / dsh 361 / opencode 312，0 失败。
 2026-09-12 11:20:13 +08:00
JianFeeeee
a60ab66a40 refactor(plugins): 删掉「摆了一套权限规则却没人调用、且形状没人能消费」的死代码 
# 问题

`lib/permission-mode.js` 里的 `opencodePermissions(mode)` 实现完整、注释详实
（含 6 条实测结论）、还有 9 条测试把行为钉住；opencode 的 `index.js` 第 45 行
确实 import 了它 —— 然后**全文件再没有第二次出现**。

静态审计要花力气才能发现它是死的，而读代码的人会理所当然地以为
「opencode 的 plan 档由这套规则拦着」。实际 opencode 是 advisory。

比 9.17（给了按钮不实现）更深一层：那只是没实现，这个是**看起来像实现**。

# 它不只是没接上，而是接不上

查 1.18.29 的 SDK 类型定义，三条都排除：

  SessionCreateData.body 只有 { parentID, title }；query 只有 { directory }
      → 会话级根本没有 permission，也没有 agent
  permission 只存在于 Config / AgentConfig，且是 map 形状
      → { edit, bash, webfetch, doom_loop, external_directory } → ask|allow|deny
  Permission 事件（permission.updated 的 properties）没有 action 字段
      → { id, type, pattern?, sessionID, messageID, callID?, title, metadata, time }

而函数返回的是 `{permission, action, pattern}[]` —— **与三者都不匹配**，
并且 deny 了 `task`（本版本 permission 的合法键里没有 task）。

所以不是「加一行调用就生效」，而是**输出没有任何消费者**。

# 为什么 opencode 的 per-session 强制做不到（如实说明）

Config / AgentConfig 是配置文件级（全局或项目级）。邮件桥若靠改配置给某条会话
加 plan 限制，会连带锁住这个人**其他所有**会话的同一工具 —— 一条 plan 档的邮件
把人身兼的其他工作一起禁掉，不可接受。

opencode 目前唯一的拦截路径是「它自己先问 → 桥转发 → 服务端按档位 409 →
桥当场 block」，**前提是它的配置恰好是 ask**；若配置直接 allow，桥连
permission.updated 都看不到。这就是它只能是 advisory 的原因，不是缺工作量。

# 改动

- 删除 `opencodePermissions` 及其 doc 注释、`OpencodePermissionRule` 接口声明
  （三份共用库同时改，改后 md5 仍逐字节相同）
- 删除 opencode/index.js 里那行未使用的 import
- 删除 9 条针对该函数的断言（三桥各 9 条）
- **6 条实测结论没有丢** —— 搬进 `docs/PLUGIN-CONTRACT.md` 新增的 §9.18，
  连同上面那三条类型证据与「为什么 per-session 做不到」

删掉而非保留，是因为留下的就是陷阱：函数存在、注释写着「实测过」、
测试还全绿，唯一缺的是调用点 —— 下一个人会以为档位在这里被强制。

# 验证

- `deploy/check-shared-libs.sh` → 共用模块三方同源
- 三桥 `npm test` 全绿：pi 400 / dsh 360 / opencode 311，0 失败
  （删除前 pi 409 / opencode 320，各 −9 即被删断言；dsh 另有并发提交新增测试，
  净 −9 后为 360）
- `node --check` 四个改动文件全过；ESM 动态 import 该 lib 成功，
  导出里已无 `opencodePermissions`，index.js 只引用仍存在的符号
- 本改动不影响运行时行为（删的是一个从未执行的函数与一个未使用的 import）
 2026-09-11 23:59:24 +08:00
JianFeeeee
4050827e5c feat(permission): 新增第三种强制力 partial —— DSH 如实自报，不再冒充 native 
# 问题

审计发现 DSH 自报 mode_enforcement=native，而实测它的 Landlock 沙箱受内核 ABI
版本限制、拦截覆盖不完整（PLAN.md L5 自己写的就是 dsh = Landlock partial）。

只有 native / advisory 两个取值时，这个平台无论标哪个都是在说假话：
  - 标 native → 人会以为 plan 档是硬保证，把它当安全边界依赖；
  - 标 advisory → 又低估了它（确实在拦），而「平台无法强制」会让模型
    在本可依赖的边界上过度保守。
多一个取值比多说一句假话便宜。

# 改动

- Go models：EnforcementPartial = "partial"，ValidEnforcement 接受它；
  NormalizeEnforcement 对显式自报值一律原样保留（partial 降级到任一极端都是假话），
  未知值仍然 fail-closed 到 advisory。
- 三桥共用 lib/permission-mode.js（逐字节同源）：ENFORCE_PARTIAL +
  modeBriefing 三态措辞。partial 版必须同时做到两件事：
  说清「覆盖不完整」，并收回 native 那句「都会被平台拦下」的承诺
  —— 否则模型会以为越界一定被拦，于是不必自己小心。
- 前端 PermissionChip：三个点形区分（实心 / 靶心 / 空心）+ 三套 tooltip 文案；
  认不出的强制力按 advisory（与后端同方向）。
- DSH 插件心跳改报 partial。
- 顺带修正活跃 DSH 会话的历史快照：那批 native 是插件当时的**误报**，
  不是能力变化，因此把 status<>'archived' 的 dsh 会话改为 partial；
  归档会话按设计保留（不重写已结束的历史）。改前已 sqlite3 .backup 备份。

# 验证

- agents.mode_enforcement：dsh 由 native 变为 partial（心跳生效）
- Go 全量、三桥插件 320/362/409、前端 196 全绿（新增 PermissionChip 11 例）
- 三桥共用模块同源校验通过
- 关键判据：partial 的措辞与 native/advisory 两两不同，且不含「无法强制」
 2026-09-11 12:04:06 +08:00
JianFeeeee
429149e118 chore(format): 撤销误入提交的整体重排，并关闭本仓库的格式化器 
# 发生了什么

pi-lens 内置「安全格式化」：它会自动安装 biome 并对**编辑过的文件**跑
`biome format --write`。本机原先没有任何 biome 配置，于是 biome 用它自己的
默认值 —— tab 缩进 + 双引号 —— 把文件整体重写。

我在 19a3161 那次提交里用了 `git add -A`，把这批与功能无关的重排一起扫了进去：
约 7000 行改动散落在 20 个文件上，使那次提交无法审查，还掩盖了
server/internal/handler/permission.go 的一处删行（实为文件末尾空行，无代码丢失）。

# 为什么是「关掉」而不是「配置成我们的风格」

试过把缩进/引号/lineWidth 全部对齐本仓库习惯（biome.json + space/2/single/
lineWidth 120）：`biome format --write` 仍然改动 17 个文件。原因是本仓库从未按
biome 的规则排版过 —— 注释按语义换行、数组与调用按可读性手工折行，
这些无法由格式化器还原。也就是说只要格式化器开着，每次编辑都会产生与内容无关的
大面积 diff，把真正的改动埋掉。

因此 biome.jsonc 里 formatter 与 linter 都关闭：本仓库的静态检查由
tsc / go vet / tree-sitter / ast-grep 与各自测试套件承担，不引入会改动无关行的
自动修复。

（pi-lens 这一版把 format 服务的 enabled 硬编码为 true，没有配置开关，
所以只能在仓库侧用 biome 配置让它不动文件；已验证 `biome format --write`
对这些文件零改动。）

# 本提交内容

把 19a3161 里除「有意改动」外的 20 个文件还原到重排前的样子。
19a3161 中真正有意的改动是 deploy/install.sh 的扩展注册与
plugins/pi-mail-bridge/extension/index.ts 新文件，两者原样保留。

验证：Go 全量、三桥插件（320/362/409）、前端 196 全绿；
`biome format --write` 对还原后的文件零改动。
 2026-09-11 12:03:51 +08:00
JianFeeeee
19a3161ee4 feat(pi): 交互式 pi 会话接入邮件工具（send_mail/read_inbox 等 10 个） 
问题（⑧）：守护进程用 noExtensions:true 起会话，它的邮件工具只给模型在邮件
会话里用；人在 TUI 里敲的 pi 拿不到。结果是平台的建设者自己收不到邮件 ——
一个「邮件驱动」的平台，维护者只能绕到 curl + 密钥直连 Gateway 才能看收件箱。

新增 plugins/pi-mail-bridge/extension/index.ts：把同一套工具（createMailTools）
注册到交互式会话。两者是同一条 AgentMail 身份（agent pi）的两个入口，与 DSH 的
「TUI + 邮箱是同一个 Agent」一致。

密钥解析顺序（交互式 pi 的环境里没有 AGENTMAIL_*）：
  1. 进程环境
  2. AGENTMAIL_ENV_FILE（默认 /etc/agentmail/pi.env）—— 与守护进程同一把密钥，
     因此身份一致
  3. AGENTMAIL_CONFIG_DIR/agent.key 或 ~/.agentmail/agent.key
     （兼容 key 与 key_token 两种字段名；实测本机文件用的是 key_token，
      只认 key 会静默读不到）
拿不到密钥时不注册任何工具并明确告知 —— 挂一组永远 401 的工具比没有更糟。

不注册 connect_to_server：它会重写 Gateway 坐标并重新登记密钥，而交互式会话与
守护进程共用同一身份，一次 TUI 对话不该改到守护进程的配置。

为什么不会重复注册（读 SDK 实现确认，并用探针实测）：
  resource-loader.js 里 noExtensions 为真时只用 cliEnabledExtensions，
  settings.json 的 extensions 数组被排除 —— 即 noExtensions:true 只加载
  命令行 -e 传入的扩展。
  探针：noExtensions=true → 扩展数=0；false → 16 个且含 pi-mail-bridge。

deploy/install.sh 增加幂等的扩展注册步骤（写入 settings.json 的 extensions）。

验证：headless pi 实际调用 read_inbox 返回真实邮件主题；工具清单含
send_mail/read_inbox/read_mail/forward_mail/upload_attachment/download_attachment/
suggest_address/list_contacts/session_participants/read_thread（10 个），
connect_to_server 按设计排除。
 2026-09-11 11:32:47 +08:00
JianFeeeee
f91efd2d8d feat(question): DSH ask_user_question 桥接 + 前端问答面板 + 待办字段全路径透出 
问题（P0）：DSH 有两个独立的人机交互 seam —— approval/request（危险工具审批）
与 ask_user_question → ctx.userQuestions（模型主动提问）。原来只桥接了前者。
邮件驱动的会话没有本地 UI，而 ask() 的 provider 是 DSH host 注册的本地 UI 实现，
于是在那里等人点选永久等不到，那一轮工具调用**静默挂死**。

修法（不抢注全局 provider —— registerProvider 只允许一个活动实例，抢注会让
平台自己的界面失效）：在 tools/execute around-dispatch 里只对**邮件驱动**的
会话接管 ask_user_question，其余原样 next()。失败一律当场报错而不是 next()：
下一个 answerer 是本地 UI，邮件会话没有兜底 UI，放过去就是挂死。

- lib/user-question.js（三桥逐字节同源，14 例测试）：DSH questions[] ↔ AgentMail
  单问题询问邮件的双向映射。多问题时把选项并集摊平、按 label 归属分配回各问题
  （label 认不出来就不猜测放行）；无选项题走自由文本 custom。
- Gateway：kind=question 且无选项时**不再**回落「同意/拒绝」（那会让自由文本
  问题变成两个毫无意义的按钮）；主题按类型区分「权限请求 / 需要回答」；
  推送 payload 带上 permission_kind / multi_select / options。
- mails.permission_kind / permission_multi_select 此前只存在于结构体与写入路径，
  五个读路径的 SELECT/Scan 都没带 —— 前端永远拿到空串，把提问渲染成批准/拒绝。
  container 修正五处并加 repo 测试（含反向验证：删掉任一处字段，测试即失败）。
- 前端 PermissionPanel：question 走「勾选 + 自由文本」，多选/单选、空回答禁止提交；
  approval 路径不变（回归测试覆盖）。

测试：opencode 316 / dsh 349 / pi 405 / 前端 185 / Go 全量 全绿。
 2026-09-11 10:44:18 +08:00
JianFeeeee
c401eb2da2 fix(bridges): SSE 跨分片保帧 + Last-Event-ID；pi worker 有界重投；systemd 故障上报；清理误提交二进制 
三个平台桥原本各自手写 SSE 解析，有两个共同的静默丢事件缺陷：
  1. evt/data 是每次 read() 的局部变量 —— TCP 把一帧
     'event: x\ndata: {...}\n\n' 切在换行处时，前半段的 event 名被丢掉、
     后半段只剩 data，整帧静默丢弃。表现为「新邮件偶尔收不到」
     「权限决策点了没反应」，日志里一个字都没有。
  2. 重连不带 Last-Event-ID —— 断线期间的事件留在服务端 per-agent 环形
     缓冲里永远回放不出来（pi 与 homeagent 已正确使用，DSH/opencode 没有）。

修法：抽出共用 lib/sse-client.js（三桥逐字节同源，check-shared-libs 校验），
把「跨 chunk 保帧状态」与「Last-Event-ID 断点续传」写对一次。pi 桥的
gateway.mjs 也改为复用同一实现（保留 reconfigure 时清断点的语义）。

pi worker 丢任务：worker 未回报 done 就退出（SIGKILL/OOM/崩溃）时，
主进程原来只记一行日志就 pump() —— 那封邮件永远没有回音。改为按
1s/2s 退避有界重投（默认 3 次），到上限记「放弃」并可观测。

systemd 故障上报：四个宿主服务接入 service-failure-notify.mjs 的
ExecStopPost/--report 与 ExecStartPost/--flush。进程内 uncaughtException
捕获不了 SIGKILL/OOM，只能由 systemd 统一覆盖。正常 stop/restart 不发信。

仓库卫生：server/server（24MB 构建产物，f9d757b 误提交）移出版本库。

测试：opencode 302 / dsh 335 / pi 391 全绿（新增 12 例 SSE 帧解析 +
2 例 worker 重投）；Go 全量通过；四平台重启后在线且无错误。
 2026-09-11 10:27:41 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00
JianFeeeee
0c98fab4d5 pi: 档位判定 tool_call hook + 心跳报 native 
- worker.mjs: mailContext 加 permissionMode 字段（从 SSE payload 读入）
- tool_call hook 增加档位判定：
  full → 不拦截任何工具（直接 return）
  plan → 被守卫工具（bash/write/edit）一律 block + 返回原因说明
  workspace → 走原有问人流程（不变）
- index.mjs 心跳上报 mode_enforcement: 'native'
- 导入 normalizeMode/MODE_FULL/MODE_PLAN 从 lib/permission-mode.js
- 377 测试全过
 2026-09-06 19:19:42 +08:00
JianFeeeee
47fe9a5e74 test: session-scan 内存泄漏测试 + ui-sweep 界面验收脚本 2026-09-06 15:18:30 +08:00
JianFeeeee
79c4171c9d feat: L0 线协议冻结 + 附件链路修复 + 人/Agent 区分 
L0 核心：
- 严格解码 Decode(DisallowUnknownFields) 全覆盖 29 个 DecodeBody 调用点
- DecodeLenient 心跳专用：容忍新字段但回报 unknown_fields
- 400 消息列出本端点接受的全部字段（jsonFieldNames 反射 tag）
- 日历 status 校验（create 补字段 + update 拦非法值）
- 新增 strictdecode_test.go 10 例 + blob/list_test.go 6 例

A-4 附件挂载回滚：checkAttachable 在 CreateMail 前校验，失败按
解挂→释放 relay→删邮件→退预算回滚，幽灵邮件这条路堵住了

A-5 反向 GC：blob.Store.List() 枚举磁盘（跳 .upload-*），
SweepUnreferencedBlobs 按 attachments + calendar_attachments 反查，
48h 年龄下限兜上传窗口。已接进每小时 sweep 循环

C 人/Agent 区分：四个读路径 + threadCols 补 from_human / to_human
（EXISTS users 判定），models.Mail 加 ToHuman。前端判据从
workspace 启发式改成显式布尔，mailCounterpart/sessionCounterpart
从 session_workspace 取 path（修 dsh@dsh 拼接 bug）

契约文档：SSE new_mail 补 4 字段（in_reply_to/from_human/
permission_mode/permission_enforcement），B-5 加 B-5.6
（Agent→Agent 不转发），B-3.4 MUST 改条件式，心跳补 mode_enforcement
+ unknown_fields，demo 死链修复 + from_human 检查
验收清单加 Agent→Agent 负向对照项
 2026-09-06 15:18:06 +08:00
JianFeeeee
a44fd6949b feat: 权限档位体系（三档 plan/workspace/full + 四桥 from_session_id） 
L2 核心改动：sessions 表补 permission_mode / permission_enforcement 两列
（sqlite + pg 同步），三桥 lib/permission-mode.js 翻译档位到平台原生配置，
homeagent advisory 模式提示词告知模型实际强制力。四桥全部携带 from_session_id
供 relay 去重与会话回溯。

FromHuman / ToHuman 判据已加入心跳 payload 与 notify/mail.go。
 2026-09-06 15:16:49 +08:00
JianFeeeee
13fcb00acc feat: relay-key 共用模块（三桥 + homeagent） 
Sha256 clamp relay_key 过 160 字节上限，避免服务端 400
被 worker 当暂时失败让位，导致邮件驱动会话无本地 UI 静默挂死。

新增 relay_key.go / relay-key.js + 15 个纯函数测试。
 2026-09-06 15:16:34 +08:00
JianFeeeee
784192d8c4 Agent→Agent 不自动转发 + 提示词区分新活/回复/补投 
## 设计规则：Agent 之间不自动转发

自动转发存在的理由是「人不该等模型记得调 send_mail」—— 收件方是人时这是
纯收益。**收件方是另一个 Agent 时这个理由不成立，而且有害**：双方的插件都
会自动回一封，于是两个模型都以为「我只要把话说完就行」，实际在持续互相唤醒。
生产实测 pi 与 dsh 客套 6 轮直到撞上连续 relay 跳数上限。

规则现在写死在共用模块 `lib/relay-policy.js`（三平台逐字节相同）：
- `autoRelayDecision` — 插件该不该替模型开口
- `replyInstruction` — 提示词怎么跟模型说（人类 vs Agent 各一套措辞）
- `inboundHeadline` — 进来的是新活、回复、还是补投

`from_human` 缺失时保守按 Agent 处理：宁可让模型多调一次 send_mail，
也不能承诺一个不会发生的自动回信让发件方白等。

## Gateway 侧：`in_reply_to` + `from_human`

- `notify.Mail` 新增 `ParentMailID`（非空 = 这是对收件方某封信的回复）
- `notify.Mail` 新增 `FromHuman`（走 `repo.IsHumanUser`）
- SSE payload 里叫 `in_reply_to` / `from_human`
- 四个调用点全部传入：handler/mail（转发后产出的邮件，parentMailID 从
  resolveTarget 取）、handler/me（同理）、handler/forward（传空串，
  因为对收件方而言那封原邮件不在它的线索里）、scheduler/calendar（传空串）
- `ListInbox` 的 SELECT 加 `EXISTS (SELECT 1 FROM users u WHERE u.username = m.from_name)`
  → `models.Mail.FromHuman`，让补拉路径也有这个信号

## 提示词分流

三种处境各一套标题：
- 新活（人类）：「你收到一封新邮件」+ 「回信不用你自己发：…」
- 新活（Agent）：「你收到一封新邮件（对方是一个 Agent）」+ 「插件不会替你
  回信。需要回复时你必须自己调 send_mail…请先判断是否真的需要回复」
- 回复到了：「你上一封信的回复到了。**这不是新任务**。」
- 补投：在标题里说明「离线期间积压」

## homeagent 特殊处理

Go 插件不能直接 `import('../lib/relay-policy.js')`，因此新增 `relay_policy.go`
（Go 对应物）+ `relay_policy_test.go`（11 例，逐条对齐 Node 侧判据）。
`sseLoop` / `catchUp` 两条路径都接上。

## `mailEvent` 命名类型

homeagent 的 SSE 事件解析 / handleNewMail / handlePermissionDecision 三处
原来各写一遍匿名 struct（字段列表几乎相同），加 `from_human` / `in_reply_to`
时漏改一处 → 编译报错但错误信息是两串几乎相同的字段列表，极难定位。
提成 `mailEvent` 命名类型：一处改、三处跟着走。

## 测试

- `lib/relay-policy.test.mjs`（Node）16 例：含「replyInstruction 与
  autoRelayDecision 不得互相矛盾」「Agent 来信的标题要点名且回复要明确反对」
- `relay_policy_test.go`（Go）11 例：逐条对齐 Node 侧
- `turn.test.mjs` +3 例：from_human 缺失时按 Agent 处理 / Agent 来信时改口 /
  回复到了说「不是新任务」；删掉两条旧的「必定自动转发」断言
- 共用脚本 `check-shared-libs.sh` +1 个文件（relay-policy）
- pi 288 / dsh 241 / opencode 217 / homeagent 14 / gateway 8 包全绿
 2026-09-04 23:52:52 +08:00
JianFeeeee
c941fa0f87 DSH 续谈分支不刷回信上下文 → 第二封的回信挂在第一封上 
## 症状

全流程回归时发现：同一条 dsh 会话的第二封邮件，回信主题写的是**第一封**的主题，
`parent_mail_id` 也指向第一封。实测（旧版负向对照）：

  jianf  负向对照 第一封
  dsh    Re: 负向对照 第一封   parent=48c4fedc  ← 对
  jianf  负向对照 第二封
  dsh    Re: 负向对照 第一封   parent=48c4fedc  ← 错，应为「第二封」

模型答的内容是对的（收到甲 / 收到乙），坏的是回信的主题与线索归属 ——
在收件箱里看起来像「同一封信被回了两遍」，而第二封的回复无处可寻。

## 根因

`mailContexts` 只在两处写入：`bindAdopted`（接管时）与新开会话分支。
`deliverMail` 的**续谈分支**（`existing` 且 agent 还活着）不写 —— 于是自动转发
用的还是第一封的 subject / mailID。

pi 与 opencode 都没有这个问题：pi 的 worker 一封一进程，每次重建 mailContext；
opencode 在 `deliverMail` 开头统一刷，注释写的就是「一个会话里可能来过多封信，
只保留最近那封」。DSH 漏了这一处，语义与另两个平台不一致。

## 修法

续谈分支进入 `locked()` 后先刷 `mailContexts`（`kind === 'mail'` 才刷 ——
权限通知不是新来信，不该改回信目标）。

## 顺带：pi 主进程删掉不会被调用的 createMailTools

工具是给模型调的，而重构后主进程没有会话。`connect_to_server` 换坐标的闭环在
pool 的 `onReconfigure` 里（工具跑在 worker，worker 回报给主进程）。
schema 约束由 `test/tool-schema.test.mjs` 直接验 `createMailTools`，
不需要在主进程建一份没人用的副本。

## 验证

- 旧版负向对照：确认第二封的回信 parent 指向第一封（复现）
- 修复后：`Re: 修复确认 甲` parent=d879f429 / `Re: 修复确认 乙` parent=e8f216a2，
  各自归位
- 四平台同发一封（pi 接管会话 + dsh/opencode/homeagent 抄送）：四封回信全部到位
- dsh 219 / pi 269 / tsc 0
 2026-09-04 21:00:11 +08:00
JianFeeeee
8e501f041e pi 桥改为工作进程池 + homeagent 落盘投递账本 
## pi 桥：模型工作下到子进程（并发模型重构）

主进程原来自己跑模型，而 pi 的会话装载是同步的：`SessionManager.open()` 走
`openSync` + `readSync` 循环把整个 `.jsonl` 读进内存并逐行 JSON.parse。实测本机
最大那条会话 23MB，`open` 一次**阻塞事件循环 118ms**；模型跑起来后 SDK 内部还有
更多同步工作。SSE 读循环在那期间完全停住 → 后续邮件卡在 TCP 缓冲区 → 久到
Gateway 认为连接死了 → 重连 → 重放。

上一轮我在几个调用点前加 `setImmediate` 是无效的仪式（让出一次之后同步工作照样
占满线程），已回退。这一轮把模型工作整体搬进子进程：实测同样的活在 fork 出的
子进程里跑，主进程事件循环阻塞 **0ms**。

- 新增 `src/worker.mjs`：一封邮件一个进程，跑完就退。权限询问期间的挂起只影响
  那一个 worker（原来 `await new Promise(...)` 等人决策，整座桥不再收信）。
- 新增 `src/pool.mjs`：**不同会话并发**（上限 3，每个 worker 约 140MB RSS）、
  **同一会话严格串行**（pi 假定「一文件一持有者」，两个进程同时装载同一条会话
  文件会让各自的内存索引看不见对方追加的行 → 会话树分叉）、满载排队不丢邮件、
  硬超时 SIGKILL 回收卡死进程。
- `src/index.mjs` 只剩 I/O 与调度：SSE、心跳、去重、分派。
- 选进程而不是 `worker_threads`：模型会跑 bash/write/edit，一次 OOM 不该带走
  整座桥。两者实测都能建起 AgentSession，但线程与主线程共享堆和生命周期。
- 「接管会话短暂持有」那套机制（adopted / adoptTimers / releaseAdopted + 兜底
  计时器）整个删掉 —— worker 退出**就是**释放，且普通会话与接管会话一视同仁。
- 轮次超时 60s → 10 分钟：60s 那个数字是「主进程要腾出手收下一封」的产物，
  worker 没有这个理由，等真结论更准（带工具调用的一轮跑几分钟很正常）。
- IPC 只传路径与标量（sessionFile / cwd / grants / 命名指纹）—— AgentSession
  跨不了进程边界，worker 每次从 sessionFile 重新装载。

`test/pool.test.mjs` +19 例，真 fork 子进程、用桩 worker（不装 SDK）跑毫秒级：
并发上限、同会话串行、不同会话真并发（判据是两个进程的心跳交错，不是 running
map 里有两个条目）、sessionFile/grants/命名指纹跨 worker 传递、config() 每次重取、
硬超时回收、权限决策路由、决策原文透传、worker 退出后清路由、mailDrivenIDs、
kind 透传、stop 先发 shutdown 再杀。跑过三组负向对照确认用例真能抓回归：
拆掉串行守卫 / 不传 sessionFile+grants / 硬超时不杀，对应用例分别失败。

## homeagent：投递去重必须落盘

用户报的重复投递不是上一轮那个 bug。两段提示词的措辞差异指出了来源：
SSE 那段写「你把本轮工作做完」，补投那段写「你把结论说出来就行」。

`deliveredMails` 是进程内的 map，而 homeagent 的插件跑在**子进程**里：

  1. 18:59:38 邮件落库，旧插件进程的 SSE 收到，注入第一次
  2. 同一秒 homed 被重启，那一轮被掐断（`context canceled`）
  3. 18:59:45 新进程起来，`deliveredMails` 是空的
  4. 心跳报 `pending_mails: 1`（第一轮没跑完 → read_inbox 没执行 → 仍未读）
     → catchUp 注入第二次

**不能只记「投过没有」**：那会把「重复」换成「丢件」—— 第 2 步里发件人没收到
回信，而记录说「已投过」→ 永远跳过。丢件比重复严重，重复至少人能看出来。

新增 `ledger.go`：JSONL 账本记两个状态。`completed` 才跳过；`delivered` 但未
`completed` 的仍然重投，但提示词前面插一段说明「上一轮被中断，别把同一件事做
两次」。落在 SDK 的 `Settings().DataDir()`；拿不到时退回 key 文件目录；目录不可
写时退化为纯内存（不比修复前差，也不该让插件起不来）。

- 判定与记录在同一把锁里：SSE 与 catchUp 两个 goroutine 的竞态
- 每行写完 fsync：这个文件的全部意义就是「进程死了之后还算数」
- 坏行跳过而不是报错退出（崩溃时最后一行可能写残）→ 那封退化为重投，安全
- 14 天保留期；过期过半时「临时文件 + rename」压实
- `shortID()` 替代 `id[:8]`：日志不该有能力 panic 掉投递协程

`ledger_test.go` +14 例，含两组负向对照（只记「投过」→ 丢件用例失败；不读账本
→ 跨进程用例失败）。

## 契约文档

`B-7.7`（MUST）：子进程形式的插件去重必须落盘且区分「投过」与「跑完」，含事故
时序、两状态表、何时标 completed。已知取舍那节标注投递账本是唯一必须落盘的状态。
验收清单加「模型跑到一半重启宿主」一项。

## 生产验证

- pi 三封 → 三条会话：三个 worker PID 并存，回信「收到 1/2/3」各落自己线索
- pi 同一会话两封：严格串行（收到A 19:26:39 → 收到B 19:26:48，全程单 worker）
- pi 主进程事件循环阻塞 1ms（旧版单进程 open 23MB 一次就 118ms）
- homeagent 正常一封：账本 `c:false` → `c:true`，一封回信
- homeagent 处理中重启：日志「上一轮被中断，带说明重投」，**只有一封 Re:**
- homeagent 再次重启：账本 2 条 completed，不再投递，会话邮件数不变
- gateway 7 包 / web 176+26 / pi 269 / dsh 219 / opencode 201 / homeagent 14
 2026-09-04 20:33:44 +08:00
JianFeeeee
255c799a40 feat(adopt): 邮件可投进平台上已存在的会话（TUI 与邮箱同一入口） 
人在平台界面（pi TUI / opencode / DSH GUI）里开的会话，此前无法被邮件投进去。
补全早就把它们列为候选（agent_platform_sessions 镜像，插件心跳上报），
但投递侧的 FindNamedSessionFor 只查 sessions 表 —— 选中后只能得到 404。
候选列表在承诺一件做不到的事。

TUI 与邮箱是同一个 Agent 的两个入口，不是两套隔离的世界。

## Gateway

sessions 表加 platform_id 列 + 部分索引。resolveTarget 的 SessionNamed 分支
本侧查不到时再查镜像，命中则「接管」：本侧建一条会话并绑定 platform_id，
之后每次投递都在 SSE 事件里带 platform_session_id。

- FindPlatformSession(agent, slug, workspace) 查镜像
- FindSessionByPlatformID 防重复接管（一条平台会话只能被接管一次，
  否则同一条对话在邮箱里裂成多条互不相干的线索）
- AdoptPlatformSession 建会话 + 绑定 + 别名复用平台 slug（撞名自动加后缀）
- PlatformIDOf 供 notifyRecipients 读

三处语义决定：
- workspace 以平台会话为准（它的 cwd 创建时就定了）。地址 path 位不同则不命中，
  否则邮件会投进另一个项目的会话
- 主题优先用平台侧标题（它代表整条对话在谈什么，也是补全里显示的）
- 接管计入 AllowNewSession 速率限制 —— 镜像里可能有几百条 slug，
  不计的话它是绕过限流的后门

## 插件

字段解析与失败话术抽成共用模块 lib/adopt.js（三方逐字节相同 + 进同源校验）：
字段名各写一遍时少个下划线就静默退化成「每封邮件新开一条」，而那个错误不抛异常。

- opencode：session.get 确认存在 → 照常 promptAsync（服务端持有会话，单一写者）
- DSH：复用 startAgent 的 resume 分支，会话 id 换成平台自己那个；
  界面上正开着时直接 followup（两个 handle 会各自写日志，replay 过不去）
- pi：SessionManager.open(file) → 跑一轮 → dispose，不放进长期缓存

pi 必须短暂持有：SDK 无任何锁机制（flock/lockfile 命中 0），活着的
SessionManager 不 watch 文件 —— 外部追加的行看不见，算出的 parentId 指向
对方不知道的 entry，会话树分叉。写入是纯 append 所以文件不会坏。
配套三处：isStreaming 时不释放（否则杀掉排队中的下一封）、兜底计时器
（轮次超时 ×2，unref）、接管会话跳过命名同步。

最后一条是实测撞出来的：别名撞名时 Gateway 加后缀，而定稿别名又回写进 pi
会话文件 → 下次心跳上报的 slug 变成带后缀那个，人从补全里选的名字凭空消失。
opencode/DSH 无此环（它们的 slug 只读不写）。

接管后必须加入 mailDriven 集合，否则邮件投进去了却永远没有回音。

## 迁移顺序

idx_sessions_platform 不能写在 init_sqlite.sql 里：那个脚本在
addMissingColumns 之前执行，而已部署的库里 sessions 表已存在
（CREATE TABLE IF NOT EXISTS 不补列）→ 索引建在不存在的列上，
整个迁移中断、服务起不来（生产实测）。依赖补出来的列的索引一律放
migrate.go 的 sqliteAddIndexes。PG 侧用 ALTER TABLE ADD COLUMN IF NOT EXISTS。

## 生产验证

- pi × 2（agent-only-chain / mail-probe-alias）、opencode（glowing-moon）、
  dsh（查看工程与插件适配指南）四条链路接管成功
- dsh 那次回信准确说出了界面上聊过的内容 → 上下文确实装回来了
- 第二封复用同一条本侧会话，平台侧无新增改名条目
- 回归：opencode 普通 .new + 别名续谈 + used_rounds=0（免配额通道未受影响）

## 其他

pi-mail-bridge 补 systemd 单元（此前是 setsid 裸进程，重启机器不会拉起）：
陈锁清理 ExecStartPre、MemoryMax=4G、TimeoutStopSec=10。
配置目录必须与 opencode 分开（共用会让后起的读到对方密钥或撞单实例锁）。

PLUGIN-CONTRACT.md 加 B-3.7 / B-3.8 + new_mail 字段表 + 检查清单验收项。

测试：repo +10 例（adopt_test.go）；三插件各 +7 例（adopt.test.mjs）
 2026-09-04 11:14:44 +08:00
JianFeeeee
a2f3db143b fix(pi): 移除 additionalProperties: false —— 与 pi 的 _ref 注入冲突 
现场：一条会话 23 次 toolCall 只有 2 次成功，21 次报
`Validation failed for tool "read_inbox": - root: must not have additional
properties`，Received arguments: { "_ref": "CAIStw4..." }。

pi 在 toolCall.arguments 里注入 `_ref`（thinking 上下文引用句柄），
而 11 个工具全声明了 additionalProperties: false，typebox 判它非法。

判据：builtin bash 同样收到 _ref 却成功；opencode/dsh/homeagent
三平台 additionalProperties 出现次数都是 0，只有 pi 是 11。
它不是「更严格更好」，而是与 pi 的参数传递机制直接冲突。

**是活锁不是死锁**：模型收到校验失败 → 重试 → 又被拒；每次 toolu_bdrk_*
都是新的，幂等键各不相同，每一次都生成新权限邮件（实测 35 → 39 封）。

链条在第一环就断了：validator 在 consent 之前先拒了 tool_call，
权限钩子根本没机会跑 —— 不是「同意了被忽略」而是**从未被问过**。

踩坑理由写进 createMailTools() 的文档注释（下一个加工具的人很可能顺手写回去）。
新增 tool-schema.test.mjs 5 例，含「注入 _ref 不被拒」。
 2026-09-03 21:11:15 +08:00
JianFeeeee
2996f9af9c fix(plugins): 409 时当场表态 + DSH 补投按会话串行 
**409 = 永远不会成功**（没有人类可路由）。原来三个插件都在失败时让位给
平台本地 UI —— 但邮件驱动的会话**没有 TUI**，让位之后 waterfall 跑到尾
依旧无人应答，仍是无声挂死。

HTTP 客户端必须把 err.status 与 err.body 挂到 error 上：只看 message
字符串分不出「暂时失败（502，该重试）」与「永远不会成功（409）」，
两种都会被当成前者，而前者会永久挂住会话。

三平台表态方式不同但语义统一：
- opencode: output.status = "deny" + output.reason 带服务端原文
- dsh: return 'rejected'（ApprovalOutcome 只认 allowed-once/rejected/
  cancelled，写 'denied' 不报错而是被当未知值静默失效）
- pi: return { block: true, reason }

其余失败（502 等）保持原行为，让位本地 UI。

---

**DSH 补投并发**（同一文件，故并入本次提交）

生产日志：`补投 5 封（共 16 封未读）`，9 秒后三封失败
`message "undefined" is already pending`。串行 for...of 并未真正串行 ——
awaitFirstTurn 在**首个 token** 就放行，turn 尚未结束下一封已 followup。

新增 waitForTurnEnd（等 turn/end 而非首 chunk）与 sessionLocks/locked()
按会话串行化。live-agent 路径原来直接 followup 就返回，现在也进锁。
120s 超时兜底，模型完全无响应时不会把后续邮件永久卡住。

权限场景下锁会持有到人类决策完 —— 这是正确行为：两封都需要授权时
第二封排队，比同时弹两个授权请求更合理。

顺带把 rename-proposal 纳入 check-shared-libs.sh 的同源校验。
 2026-09-03 21:10:48 +08:00
JianFeeeee
f321380fa3 fix: relay 死循环防护 + DSH 工作区注册修复 + homeagent 工具集补齐 + 三插件 connect_to_server 
## relay 死循环防护（两道防线）

### 主防线：免配额只给发往人类的 relay（handler/mail.go）

原设计：relay 走免配额通道（harness 搬运不该算模型自主发信）。
问题：收件方是另一个同样会自动转发的 Agent 时，整个回路里没有任何
一处在计数——生产上跑出过 41 封（会话 f3d824ce），间隔从 15 分钟
缩到 5 秒，且用了 37 封才烧掉 4/20 预算。

改为：repo.IsHumanUser(to.Name) 判定。Agent→Agent 的 relay 照样扣预算。

顺带修次序问题：原来是「先占幂等键再扣预算」，预算耗尽时幂等键
已被占用，加了额度也无法重发。现在预算失败会 ReleaseRelay 还回去。

### 兜底：hop_limit 列接通（repo/relayhops.go）

schema 里早有 hop_limit INT DEFAULT 5，从未有代码读它。
CountTrailingRelayHops 从最新邮件往前扫，遇到第一封非 relay
邮件即停（中间有一封自主发信或人类插话就归零）。

5 测试：空会话 / 只数 relay / 自主发信打断归零 / 达到上限 / 按会话独立

## DSH 工作区注册修复

问题：上一轮加的 workspaceRegistry.create(cwd) 用了兜底值 cwd（来自
resolveWorkspaceCwd，可能是 ~/.dsh/mail-sessions/mail-<uuid>），
而不是会话 header 里的真实 cwd。两者不一致时 attachSession 拒绝，
且 create 已先执行，每封邮件都往注册表里塞一条空的垃圾 workspace。

修复：读 handle.agent.session.header.cwd —— create 路径下是 meta.cwd，
resume 路径下是持久化 header 里那个。

## homeagent 插件：11 工具齐平 opencode

tools.go 新增：read_mail / forward_mail / suggest_address /
list_contacts / session_participants / read_thread / connect_to_server
+ handleConnectToServer（注册到 Gateway 前先用候选坐标试注册，
成功才写回 p.gwURL/p.key，失败不破坏原配置）

关键修：Plugin.name（插件名，homed 注册用）与 Plugin.agentName
（AgentMail 身份，Gateway 密钥绑定用）是两个命名空间。
它们混淆会导致 403：「该密钥已绑定到 Agent 'homeagent'，不能用于
注册 'homeagent-mail-bridge'」。现已分开，并在 systemd drop-in
里显式设 AGENTMAIL_AGENT_NAME=homeagent。

## 三插件补齐 connect_to_server

之前只有 opencode 有。后果：Gateway 换地址或密钥需要重新登记时，
opencode 里的模型能自己修好，其他平台只能干等环境变量被人改。

DSH 版：从 GatewayClient 内部调 register()，成功后写回 client.baseURL
与 client.agentKey 当场生效。

pi 版：新导出 KEY_FILE / saveLocalKey（从 gateway.mjs），connect
工具直接用。

# 测试

relayhops_test.go 5 例
opencode 172 / dsh 188 / pi 214 全绿
check-shared-libs.sh 三方同源（rename-proposal 已纳入校验）
 2026-09-03 15:01:52 +08:00
JianFeeeee
e6fd2fafdc feat: agent 邮件寻址能力全面补齐 + .new 别名替换 
## 别名替换（让 .new 邮件可寻址）

repo/autoalias.go: AutoAliasFor + EnsureSessionAlias
- .new 建完会话立刻给别名（形如 dsh-重构导入路径）
- 名字与主题都要：只用主题跨 Agent 撞名，只用名字看不出聊什么
- sanitizeAliasPart 只留 unicode.IsLetter/IsDigit，其余折 -
- 撞名追加 -2/-3，全占用退 session-<uuid前8位>
- 不复用 SyncSessionAlias：那个假定已存在且跳过 manual
- 条件写入 WHERE alias IS NULL OR ''，并发安全
- resolveTarget 的 .new 与默认会话两条路径都调

notifyRecipients 加三个字段（每个收件方拿到自己那个地址的版本）：
- session_alias / reply_address / self_address
- 别名为空时退回省略 session 位，绝不写 new

FormatAddress(name,path,session) 空 path 也必须留 @ 与 .

## Agent 侧寻址发现（五个只读端点）

handler/agent_discovery.go:
- /agent/contacts + /agent/contacts/suggest（三段式补全）
- /agent/mail/{id} + /agent/mail/{id}/thread
- /agent/sessions/{id}/participants
- 不复用人类路由：scope 不同、审计需求不同
- 一律只读：归档/改名/权限决策仍只有人能做

repo/participants.go: SessionParticipants 逐封扫 from/to/cc
- Roles 用集合、MailCount 只数发信（0=还没开口的人）
- 发件人 path 不取 from_workspace（那列存的是 Agent 名）

repo.SuggestPaths 重写：mails.to_workspace（按 MAX(created_at) 倒序）
+ agents.workspaces 并集。原只读 workspaces，官方插件传 [] 永远空

## 共用模块（三插件逐字节相同）

lib/addressing.js: formatAddress/roleOf/replyAddressFor/selfAddressFor/participantsOfMail
lib/discovery.js: renderNameSuggestions/renderPathSuggestions/renderSessionSuggestions/
                  renderParticipants/renderContacts/renderThread

lib/inbox-format.js: renderMail 新增收件人/身份/可投递地址三段
  - selfName 参数（兼容旧调用不传的情况）

check-shared-libs.sh 纳入 addressing + discovery

## 插件侧

opencode: suggest_address + list_contacts + session_participants + read_thread + read_mail
dsh: 同上 + forward_mail（此前只有 opencode 有）+ upload_attachment 改真 multipart
pi: 同上（createMailTools 加 agentName 参数）

dsh: ctx.agents.create id collision 改为 readSession 探测后 resume
dsh: 关键路径日志改 console.error（ctx.logger 不进 journalctl）

## 测试

repo: autoalias_test.go 11 + participants_test.go 7 = 18 例
plugins: addressing.test 17 + discovery.test 23 + inbox-format.test 31 = 71 例
go test ./... + npm test（opencode 155 + dsh 173 + pi 199）全绿
端到端验证：admin 发 dsh@....new 抄送 opencode@....new
  → dsh 用 session_participants 取到地址 → send_mail 给 opencode
  → 地址取自工具返回值（.crisp-planet），未手工拼写
 2026-09-03 12:09:12 +08:00