diff --git a/docs/API.md b/docs/API.md
index 3184f41..4631d35 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -6281,3 +6281,58 @@ window.__AGENTMAIL_TOKEN__ = '<user_key>';   // 省略则走 Cookie
      落地: 发信前**先**跑一次 `select mail_id … like '<前缀>%'`，把**整串**粘进去；
            前缀匹配（`like 'xxxxxxxx%'`）**只用于查**，**不用于投递**。
   ```
+
+---
+
+- ★★★ 记一条**我自己的**流程事故 + 一条**推翻我上面那条账本**的更正（都出自本轮自查）:
+
+  ## (A) ★★★ 我**把信错投进了兄弟会话** —— 挑信时**漏了 `session_id` 过滤**
+  ```
+  我挑"待回 pi 信"用的查询:
+     from_name='pi' and (无子回复)  order by created_at desc
+  ★ **没有 `session_id` 过滤** ⇒ 它把**另一个 dsh 会话** `21c398ee` 的信也挑了出来 ⇒
+     我回了 `ac300230`（**属于 21c398ee，不属于我 d042cc4c**）⇒ 我的回信 `f16cce24` 落在了**兄弟会话**里
+  ⇒ 实测: 全库"待回 pi 信"里，**只有 0 封属于我的会话**（那 8 封全是 21c398ee 的）；
+     而**我的会话 d042cc4c 自己的待回**是另一批（`5404b64e` 等 17 封）
+  ⇒ ★ 形状: 与"**对象选错了，而操作本身完全正确**"同族（我这几轮已记过两次:
+     查错库、查错树）—— 这次是**查错了会话**。而它**比前两次更隐蔽**:
+       前两次我读到的对象至少是**同一种东西**（另一个库/另一棵树）；
+       这次我读到的是一封**完全合法、确实没人回、内容也相关**的信 ——
+       **唯一的问题是"它不是发给我的"**，而这个信息**只存在于 `session_id` 那一列**，
+       而我在查询里**恰好没选它**。
+  ⇒ ★★ 纪律: **挑"待回给我的信"必须带 `session_id = <我的会话>`**；
+     不带它挑出来的，是"**这台机器上所有没被回的 pi 信**"，不是"我的待办"。
+     （另: 错投**已造成实际影响** —— 兄弟会话的 pi 回了 `95e67bff` 继续那条线索，
+      即我那条 `f16cce24` **进入了对方的推理链**。我**不删**它（删了会更乱），
+      但此后凡涉及该线索，我以**兄弟会话为准**。）
+  ```
+
+  ## (B) ★★★ 推翻我 `028059e` 那条账本的一处**定性**: "读域 ⊂ 擦除域"这个说法**太窄，且误导修法**
+  ```
+  我 `028059e` 写: "读域 ⊂ 擦除域 ⇒ 每次心跳都是一次'整表顶替'"（把它读成**缺陷**）
+  ★ 兄弟会话的更正（我**独立复核成立**）: **整表替换是**有意设计****，而且**有测试钉着**:
+       platform_sessions.go:**44-47** 函数文档: "整表替换而非增量合并：镜像是平台当前状态的快照。
+         增量合并会让已经删掉的平台会话永远留在候选列表里 … session 位是三态语义，指向不存在的会话会直接 404"
+       platform_sessions_test.go:**219** `func TestReplacePlatformSessionsIsFullReplace`
+     实测 `go test ./internal/repo/ -run TestReplacePlatformSessions` ⇒ **ok** ✓
+  ⇒ ★ 所以"擦除多余"是**错的**（会导致错误修法: 改成并集 ⇒ 复活那条 404 缺陷）
+  ⇒ 真形状（我收兄弟的表述，它比我准）: **不是"域不等"，是"整表替换的粒度选错了"**:
+       替换域 = **`agent_name`**（:63），而**上报者本身是按 directory 分的**（index.js:1147 每实例只 list 一个目录）
+       ⇒ 设计时"一个 agent 一个上报者"成立；现在 opencode 一个 agent 下有**多个 project 各一份心跳**
+       ⇒ 那句"镜像是**平台**当前状态的快照"里的"平台"，在每个上报者眼里只是**它自己那个项目**
+       ⇒ 形状: **一个上报者把自己看到的世界当成了整个平台的世界**（拿局部冒充整体）
+  ⇒ 而**修法方向因此不是"别擦"，是"擦的域要 == 读的域"**（per-source replace）
+     ⇒ ★ 我先前那条"schema 自己按 (agent_name, workspace) 建索引 ⇒ 实现漏一维"**仍然成立**，
+       且现在它是**支持该修法**的证据（不是"擦除多余"的证据）—— 同一个观察，**结论方向被我读反了**
+  ```
+  ## (C) 一处**我标为"未对齐"、实际有答案**的（兄弟解掉，我复核）
+  ```
+  我 `028059e` 标: "TrueAgent 我采到 n=100，而 opencode.db 该 worktree 有 **284** ⇒ 我没能对齐"
+  ★ 兄弟的解: **不是分页，是两个 project 共用同一个 directory 字符串** ——
+     我实测 `session.directory='/home/program/agentmail'` 的行 = **110**，
+     按 `project_id` 拆: `1715b5c1…`(worktree=`/`) = **73** + `9fdb8357…`(worktree=`/home/program/agentmail`) = **37**
+     ⇒ 而插件的 `session.list({directory})` 走的是 **project.worktree** 过滤 ⇒ 得 **37**
+  ⇒ ★ 即: "**directory 列**"与"**project 归属**"是**两个键**；我的 SQL 与插件的 API **都不错**
+  ⚠️ 但 TrueAgent 那格我**仍未对齐**（100 vs 284）；兄弟给的是**候选解释**（`ORDER BY`/截断），
+     与 agentmail 那格**不是同一个机制** ⇒ 我仍然**不**声称 TrueAgent 已对齐
+  ```