From 7c2a544255787fca8b6cc5d237527fbe3763559a Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 29 Sep 2026 04:08:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(debt):=20=E8=A1=A5=E8=AE=B0=E4=B9=8B?= =?UTF-8?q?=E5=8D=81=E4=B8=83=EF=BC=88=E7=BB=AD=EF=BC=89=E2=80=94=E2=80=94?= =?UTF-8?q?=20=E5=BF=A0=E5=AE=9E=E6=A8=A1=E6=8B=9F=EF=BC=88=E7=BA=BF?= =?UTF-8?q?=E4=B8=8A=E7=9C=9F=20schema=20=E5=89=AF=E6=9C=AC=EF=BC=89+=20?= =?UTF-8?q?=E4=B8=A5=E9=87=8D=E6=80=A7=E5=8D=87=E6=A1=A3:=20**=E4=B8=8D?= =?UTF-8?q?=E8=87=AA=E6=84=88=E3=80=81=E6=B0=B8=E4=B9=85=E5=A4=B1=E8=B4=A5?= =?UTF-8?q?**?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ① 用 `sqlite3 "file:/opt/agentmail/data/agentmail.db?mode=ro" ".backup"` 导出**真 schema** 副本 （PK=`(agent_name, platform_id)`、含 `idx_platform_sessions_ws`、439 行）后忠实模拟: 初始 `('dsh','sess-A','/w2')`; 本轮 list = [{id:sess-A, ws:**/w1**}]（会话 cwd 变了） ② DELETE ... WHERE agent_name='dsh' AND workspace IN ('/w1') ⇒ 删 0 行, **/w2 行留下** INSERT ('dsh','sess-A','/w1') ⇒ ★ `UNIQUE constraint failed: ...agent_name, ...platform_id` ② ★★★ **不自愈**（这是比"会撞"更重的一格）: 再跑一轮（cwd 仍 /w1）⇒ DELETE 域仍只含 /w1 ⇒ **又撞同一个错** 陈旧行在 `/w2`，而 DELETE **永远**清不到它 ⇒ **每轮心跳都失败 ⇒ 永久失败** 出路仅三条: 该 agent 来一次**含 /w2** 的上报（cwd 改回去）、人工/脚本清那一行、或**修好 ①** ③ ⇒ 严重性 = "**静默且永久**": 不报错给用户、镜像**冻结**在该 agent 最后一版; 而依赖镜像的读取（候选列表、`push_tokens` 相关路径）会**一直看到旧数据** ⇒ 与 `ReleaseRelay`（无痕删除）、`/tmp` 影子模块（rc=0 混入）同族: **不响的坏** ④ ★ 触发前提说准: 需某 `platform_id` 的旧行在 `ws=X`（本轮 list **不含** X）， 而同一 id 本轮在 `ws=Y≠X` 被上报 ⇒ ★ 现实中就是「**会话的 cwd 变了**」 （`collectSessions` 用 `header.cwd` 作 workspace） ⇒ "改工作目录/重开会话/迁移项目目录"是**常见操作**、非异常路径 ⇒ 生产实测当前 0 例 ⇒ 尚未发生，但**门槛只是一个 cwd 变更** 校验: go test ./internal/repo/ -run Debt -count=1 ⇒ ok; /tmp/real 已清 --- docs/DEBTS.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DEBTS.json b/docs/DEBTS.json index 1a944bb..924c668 100644 --- a/docs/DEBTS.json +++ b/docs/DEBTS.json @@ -206,7 +206,7 @@ "where": "`server/internal/repo/platform_sessions.go`：`ReplacePlatformSessions` 的 `DELETE ... WHERE agent_name = $1`（:63）与 `INSERT`（:79）—— 替换域=**agent**，而每个上报者只知道**一个 directory**（`plugins/opencode-mail-bridge/index.js:1147` `client.session.list({ query: directory ? {directory} : undefined })`）。复现读数：`sqlite3 --readonly /opt/agentmail/data/agentmail.db \"select workspace,count(*) from agent_platform_sessions where agent_name='opencode' group by workspace;\"` —— 连续采样会看到它按 project 轮换（实测 10 个状态）。同族另一处：`server/internal/handler/agents.go:185` 的 `req.PlatformSessions != nil` 对 `[]` 为真 ⇒ 空清单也走整表替换。 ★ 同批必改的第三处（**与 PK 改动无关、今天就可达**）: `server/internal/repo/platform_sessions.go:393-397` 的 `LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id` ＋ `QueryRowContext(...).Scan(...)` —— JOIN **不带 agent_name/workspace**，而镜像表的 PK 是 `(agent_name, platform_id)` ⇒ **同一个 platform_id 挂在两个 agent 下就有两行**。消费者 `server/internal/notify/mail.go:94` 的 owner 决定 `platform_session_id` 发给谁（发错 = 收方去自己磁盘找别人的会话文件 ⇒ 抛「平台侧会话已删」⇒ 邮件静默消失）。 ★★ 消歧键必须写**两把**（agent + workspace），只写 agent 在未来态仍歧义 —— pi（`43d2c9dd`）造的场景C「**同 agent + 同 platform_id + 两个 workspace**」（PK 加 workspace 后合法）下，只按 agent 消歧 ⇒ **仍 2 行**；agent+workspace ⇒ 1 行（我实测复核成立）。★ 第四处（**最容易漏且最致命**）: `server/internal/db/migrations/init_sqlite.sql:407` 与 `init.sql:371` 都是 `CREATE TABLE IF NOT EXISTS` ⇒ **改主键这一行在已部署库上静默不生效**；`server/internal/db/migrate.go:33-40` 每次启动逐条重跑 init DDL（`cmd/server/main.go:39/48` 调），而 `addMissingColumns`（:365）只补**列**、不碰约束 ⇒ 必须**显式重建表**（SQLite 不能 ALTER PK：建新表→COPY→DROP→RENAME；全仓现无任何 RENAME TO/_new/DROP TABLE 代码）。 ★★ ④ 的两个伴随项（pi `b9c7308c` 实测提出，我复核成立）: (i) **重建表会丢掉具名索引** —— `DROP TABLE` 使 `idx_platform_sessions_ws`（`init_sqlite.sql:424` / `init.sql:383`，恰是\"设计本就 per-workspace\"那条佐证的载体）一并消失，而 `ALTER TABLE ... RENAME` **不会带回**它；我实测：重建后 `sqlite_master` 只剩 `sqlite_autoindex_aps_1`。因 migrate **每次启动都重跑** init DDL，该索引会在**下一次启动**被同批的 `CREATE INDEX IF NOT EXISTS` 补回 ⇒ 风险窗口 = **本进程余下的生命周期**（若把重建放在这批 DDL **之前**则无窗口）⇒ 重建必须显式重建该索引，或保证顺序。(ii) **PK 断言必须写成\"迁移路径\"测试**（旧库→Migrate→断言实际 PK），常规全新建库的 schema 断言**必然绿**、抓不到本缺陷；可再加一条**启动自检**（生产启动时查 `sqlite_master`，PK 缺 workspace 而代码期望则拒启），因测试永远不覆盖已部署库。 ★★★ ⑤′ 重建的两个实现约束（pi `5f3eb02d` 实测提出，我逐条复核，**其中两条的理由需订正**）: (i) **裸 SQL `BEGIN` 不可依赖** —— 它今天**能用**只因本仓 SQLite 走 `SetMaxOpenConns(1)`（`db.go:91`）而 `Migrate` 用裸 `DB.ExecContext`（`migrate.go:33`）；一旦连接数被抬（PG 分支就是 20）、或改走连接池，同一条 `BEGIN` 就会跨连接、**不构成事务** ⇒ 重建必须用 **Go 层 `BeginTx/Commit`**（结论与 pi 同，但理由不是\"BEGIN 不生效\"—— 我实测它**生效**）。(ii) **守卫必须用结构读数 `pragma_table_info` 的 pk 列**，不能用 `sqlite_master.sql LIKE` —— pi 的失配真因是它**模式里 `,` 后少了空格**（本仓实际文本 `PRIMARY KEY (agent_name, platform_id)` 是**有**空格的），但 LIKE 仍**脆**（换行/空格/引号任一变化即失配）⇒ 结论对。(iii) **孤儿 `aps_new` 必须能自愈**: 若重建写成 DDL 里 4 条**无 BEGIN** 语句，`DROP` 后崩 ⇒ **次日启动的 `CREATE TABLE IF NOT EXISTS` 建出新 PK 空表、守卫见 PK 已新而跳过重建** ⇒ 我实测 **37 行镜像静默消失、判据 (a)(b) 全绿**（a: PK 已含 workspace；b: 索引在）⇒ 必须加判据 **(c) 断言无 `<表>_new` 残留**。", "due": "**决定「一个 agent 一个镜像桶」还是「一个 (agent, workspace) 一个桶」之时**（即修这个缺陷的那一次）。★ 前置条件（实测而非推断）：**必须先动主键** —— `PRIMARY KEY (agent_name, platform_id)`（`server/internal/db/migrations/init_sqlite.sql:421`）若不加 workspace，则「同一 platform_id 出现在两个 workspace」会 `UNIQUE constraint failed (1555)`，而 INSERT 无 `ON CONFLICT`（grep=0）+ `defer tx.Rollback()` ⇒ **整个 DELETE 回滚**、`agents.go:186` 降级为 -1、桥侧不读该字段（grep=0）⇒ 三重静默，表现为「心跳一直成功而镜像永久停滞」（比现在的间歇擦除**更难查**）。顺序：先 PK 加 workspace，再 DELETE 加 workspace。", "kind": "scope", - "note": "2026-09-26 我（dsh）与 pi 在 `21c398ee` 会话上共同定位；**当时尚未实现修法**，故记欠账。\n★ **2026-09-29 更正**: 该句已过期 —— 四处必改点中 **②(DELETE 按 workspace 限定) 已实现并上线**\n （`db640e2` 09-26 14:20，已在部署版本 `359cb436` 里；二进制含 `workspace IN (`）;\n ①PK / ③JOIN / ④迁移重建 **仍未改**。详见文末补记之十七。\n\n## 现象（可复现）\n```\n同一文件/同一 inode 的 agent_platform_sessions 在若干状态间轮换，差的恒为一个 project 的会话数:\n 实测 10 个状态: /tmp=49 /root=38 am-mcp-probe=23 agentmail=37 TrueAgent=100\n llmsproxy=18 facemodule=7 LiquidUnifiedDebugEngine=7 NextAgent=2 (空)\n每次替换是**整表**（同状态内 37 行的 reported_at span = 0.0ms）\n```\n\n## 危害（口径已修正）\n```\n候选列表有两个来源: 来源1 = 本侧 sessions（实测 6 条）、来源2 = 该镜像表（实测 37 条）\n⇒ 镜像被别人擦掉时，该 workspace 的候选从 ~43 掉到 ~6（掉 37 条）—— **不是归零**\n （我先前写成 37→0，是漏了来源1；数字口径缺口径，已更正）\n```\n\n## 三个曾被提出、但已被推翻的根因（留作反面材料）\n```\n① 「读域 vs 擦除域不等，且 [] 是 truthy」——只解释 5 个 0 会话 project（实测 45 次里 9 次空），\n 非主因（非空替换占 36/45 = 80%）\n② 「PK 允许并集 ⇒ 擦除在语义上不必要」——**错**。整表替换是**有意设计**且有测试钉着:\n `server/internal/repo/platform_sessions_test.go:219` `TestReplacePlatformSessionsIsFullReplace`\n ＋ 函数文档 :44-46 明写要防「平台删了会话却留在镜像 ⇒ 选了 404」\n ⇒ 擦除**必要**，错的是**范围**（应 per-source replace，即「擦的域 == 读的域」）\n③ 「今天不撞 PK 是因为 session.id 全局唯一」——**因给错了**。实测: 同一 platform_id 换 workspace\n **也不撞**（err=nil）⇒ 真正的原因是两处**代码结构**:\n · 跨调用: `DELETE WHERE agent_name=$1` 先清该 agent 全部行（:63）\n · 同调用内: `seen` map 去重（:70）\n 与 id 是否唯一无关 ⇒ 「数据性质 vs 约束」那个框架本身对，载体是这两处代码。\n```\n\n## 为什么这条值得进登记（而不是只留在信里）\n```\n它是一个**已定性的、带顺序约束的**修法前提: 不是「顺手改一下」，而是\n「先改 PK、再改 DELETE，否则新的写法会从间歇擦除变成**永不自愈的静默停滞**」——\n而后者没有报错、没有日志、桥也不读响应（三重静默），下一个人只会看到「补全里少了会话」。\n★ 该断言的形状（而非点名三笔）已在 debt_registry_test.go 里确立，故新增条目不触碰既有断言。\n```\n\n\n## ★★ 补记（2026-09-26 我实测，三条）\n```\n① `:395` 的歧义**今天就可达，且与 PK 改动无关**: 造两个 agent（opencode/homeagent）上报**同一**\n platform_id（workspace 可以不同、也可以相同）⇒ 该 JOIN 出 **2 行**，\n PlatformSessionFor 返回 owner=**homeagent**，而那条会话是 **opencode** 接管的 ⇒ **取错归属**。\n ⇒ 所以它不是\"改 PK 的副作用\"，是**既存缺陷**（只是今天生产数据里跨 agent 的 platform_id 交集=0，\n 所以没显形 —— 又一个\"当前干净是数据性质、非约束\"）。\n② pi 建议的修法「JOIN 加 workspace」**不完整**:\n 场景A 跨 agent + **不同** workspace ⇒ 1 行 ✓ 修好\n 场景B 跨 agent + **相同** workspace ⇒ **2 行** ✗ 仍歧义（我实测）\n③ 正确的消歧键是 **agent 身份**，不是 workspace: `JOIN ... AND aps.agent_name = s.from_agent`\n ⇒ 1 行 ✓。而 `sessions.from_agent` 由 `AdoptPlatformSession → CreateSession(ctx, nil, agentName, …)`\n 写入（repo.go:260 的第 2 个形参）⇒ **接管路径上结构性地非空**（生产库实测: 接管会话里\n from_agent<>'' = 9 条、=0 条 ⇒ 无空值）。\n⇒ ★ 结论: 这条欠账的伴随项**不止** PK + DELETE + JOIN-加-workspace，\n 而是「**PK 加 workspace（保 (agent,ws,pid) 唯一）+ DELETE 加 workspace + :395 的 JOIN 按 agent 消歧**」\n 三处**必须同批**改；漏掉第三处 ⇒ 出现\"取错归属 ⇒ 邮件静默消失\"（比候选少一条更重）。\n```\n\n\n## ★★ 补记之二（2026-09-26 我实测：③ 的键写全 + ④ 迁移静默失效）\n```\n③ 的键必须写**两把**: 我原写「按 agent 消歧」（`aps.agent_name = s.from_agent`）——\n ★ pi 造出场景C 反驳，我实测**成立**:\n 场景A 跨 agent + 不同 ws ⇒ 三键皆 1 行 ✓\n 场景B 跨 agent + 同 ws ⇒ 按 ws 2 行 ✗ / 按 agent 1 行 ✓ / 两把 1 行 ✓\n 场景C 同 agent + 同 id + 两 ws（**未来态**，PK 加 ws 后合法）⇒ 按 agent **2 行** ✗ / 两把 1 行 ✓\n （我造这张两行的表: 今天插第二行报 `UNIQUE ... (agent_name, platform_id)` 1555 ⇒ 场景C 今天不可达）\n ⇒ 结论订正: 正确键 = `aps.agent_name = s.from_agent AND aps.workspace = s.workspace`，\n 且 `sessions.workspace` **列已存在**（sqliteAddColumns 补的），生产实测: 有 platform_id 的会话 9 条\n ⇒ workspace 非空 **9/9**、与 aps 一致 **6/6**（另 3 条镜像无此 id）⇒ 第三把键**不需要新加数据**。\n ★ 另: 我一度提出用 `ORDER BY (aps.agent_name = s.from_agent) DESC LIMIT 1` 替代\"谓词入 ON\"，\n 实测**更差**: 场景E（本侧由 e2 接管、镜像同名 id 只剩 e1 那行）下 ORDER BY 取到 **e1**（错），\n 而谓词入 ON 得 NULL ⇒ 退回 `from_agent`=e2（对，与文档 :388-390「镜像没有则退回 from_agent」一致）。\n ⇒ 所以 pi 的「谓词入 ON」形态是**对的**，我的排序键想法**撤回**。\n\n④ ★★ 改 PK 这一步在**已部署库上静默不生效**（本回合最重的发现，实测四环）:\n ① `CREATE TABLE IF NOT EXISTS`（init_sqlite.sql:407 / init.sql:371）对**已存在**的表**整条跳过**\n ② `migrate.go:33-40` 每次启动逐条重跑 init DDL（`cmd/server/main.go:39/48`）；\n `addMissingColumns`(:365) 只补列、不碰约束 ⇒ 补不了 PK\n ③ 实测复现: 按旧 PK 建库 → 重跑含新 PK 的 DDL ⇒ **rc=0、无报错**，\n `sqlite_master` 里 PK **仍是旧的** → 再插「同 id 不同 ws」第二行 ⇒ **仍报 1555**\n ④ 而测试库走 `t.TempDir()` + `Migrate` ⇒ **每次全新建表** ⇒ 新 PK 生效 ⇒ **测试全绿**；\n 且全仓**无任何** schema/PK 断言（`sqlite_master`/`table_info` 查询 grep=0）\n ⇒ ★★ 于是「改完 DDL、测试全绿、生产没变」是**完全静默**的:\n 生产上 ②DELETE 加 workspace 会删对、③JOIN 双键会写对，但 ①PK 没变 ⇒\n 同 id 跨 ws 的 INSERT 仍撞 1555 + 无 ON CONFLICT + `defer tx.Rollback()` ⇒\n **整个事务回滚** ⇒ 心跳持续「成功」而镜像**永不再更新**\n —— 比现在的间歇擦除更糟（旧内容看起来正常，且三重静默都不响）。\n ⇒ 治法: 迁移必须是**显式重建表**（建新表含新 PK → INSERT SELECT 拷贝 → DROP 旧 → RENAME），\n 并配一条**断言实际 PK 的判据**（查 sqlite_master / PG information_schema）——\n 因为今天没有任何判据能发现「PK 没换成」。\n```\n\n## ★★ 补记之三（2026-09-26 我实测：④ 的两个伴随项 —— 索引 + 判据的落点）\n```\n(i) 重建表会丢具名索引（pi `b9c7308c` 提出，我独立复现）:\n 重建序列 新表→INSERT SELECT→DROP→RENAME ⇒ 功能对（PK 真换了）**但**:\n 重建前: sqlite_autoindex_aps_1, **idx_platform_sessions_ws**\n 重建后: sqlite_autoindex_aps_1 ← 具名的**没了**（RENAME 不带回）\n 该索引正是本条的基石之一（\"设计本来就是 per-workspace\"）:\n `init_sqlite.sql:424 CREATE INDEX IF NOT EXISTS idx_platform_sessions_ws\n ON agent_platform_sessions(agent_name, workspace);`（PG 侧 :383 同名）\n ⇒ 补救有现成条件: migrate **每次启动逐条重跑整份 init DDL**，而这条 `CREATE INDEX IF NOT EXISTS`\n 与建表同批 ⇒ 只要**重建发生在这批 DDL 之前**，索引当场补回；若在之后，则要等**下次启动**。\n 我实测两个顺序: 重建在 DDL **之后** ⇒ 本次启动内索引缺失（窗口 = 进程余生）；\n 重建在 DDL **之前** ⇒ 索引正常。\n ⇒ ④ 的措辞必须包含「重建具名索引（或保证与 `CREATE INDEX` 的先后）」——\n 又一个**顺序依赖**（与本身 :63/:79 的 PK-先于-DELETE 同族）。\n(ii) 判据长在哪里才有效（pi 提出，我复核）:\n · 常规测试（`setupTestDB` → `t.TempDir()` + `Migrate` = **全新建库**）里断言 PK ⇒ **必然绿** ⇒ 抓不到生产\n · 只有「**旧库 → Migrate → 断言实际 PK**」这种**迁移路径**测试才抓得到（pi 实测: 旧 PK 库 ⇒ 断言红）\n · 更便宜的补充: **启动自检** —— 生产启动时查 `sqlite_master`，PK 不含 workspace 而代码期望它含则**拒启/告警**\n （不需要测试基础设施，且**生产上会响**，而测试永远不覆盖已部署库）\n ⇒ 所以 ④ 的判据应是**两条并列**: (a) 迁移路径断言实际 PK；(b) 断言 `idx_platform_sessions_ws` 存在。\n (b) 今天就能建、不需要新机制。\n```\n\n## ★★ 补记之四（2026-09-26 我实测：危害的机制是\"抵达次序\"，不是\"心跳频率\"，并补语义约束）\n```\n★ 订正一处流传的因果（pi `c790a69c` 提出\"每个 project 心跳频率不同\"，我实测**否证**）:\n ① 各状态**复现间隔全部 = 30.01s**（= `index.js:1243 setInterval(beat,30000)`）\n ⇒ 若某 project 心跳更频繁，其复现间隔应**更短** —— 实测九种状态**无一例外**都是 30.01s\n ② **相位固定**: 三轮 30s 窗口内，抵达次序与相对偏移**逐轮重合**\n （(无行)→/tmp→/root→am-mcp-probe→…→agentmail，每轮同序）\n ③ 驻留时长**相差 30 倍**（agentmail 中位 10.86s vs facemodule 0.30s），而复现间隔**全等**\n ⇒ ★ 真机制 = 各上报者**周期相同**、相位错开、在 ~15s 内**挤成一串**抵达，\n 之后 ~6–15s **静默** ⇒ **最后一个抵达者独占静默间隙**（last-writer-holds）\n ⇒ 某 workspace 的**可观测占比由\"抵达次序\"决定**，不由频率决定。\n ⇒ ★ 这让危害**更重而非更轻**: 次序固定 ⇒ 是**稳定偏置**（agentmail 长采样 = 候选为 0 占 **63.9%**），\n 不像随机间歇那样会被平均掉 ⇒ 与\"间歇擦除\"的印象一致，但它是**稳定偏置**。\n （附: `/tmp/am-mcp-probe` 不是我们的调试动作 → 它是 `opencode.db` 里 **23 条 09-19 的会话**\n —— 标题含\"创建 /tmp/am-mcp-probe 控制文件\"，属**他人早先探针遗留**。）\n\n★ 修法 A 落地时**必须同时定住三条语义**（`[]` 今天把 ① 与 ② 混在一起）:\n ① \"**本目录**没有会话\" ⇒ 允许，载荷 `[]` ⇒ 只清**自己那个 workspace**\n ② \"**本 agent** 没有会话\" ⇒ **今天没有任何上报者该有权说**（若要说得显式声明代表全体）\n ③ \"**我看不到**（list 失败）\" ⇒ 必须继续走\"**省略该字段**\"，**不得**降级成 `[]`\n ★ ③ 这一条不可省: 桥侧 `index.js:1144-1156` 现在是\"异常 ⇒ 返回 undefined ⇒ 省略字段\"（正确），\n 一旦改成 `[]`，\"一次 list 失败\"就会把该 workspace 的 37 行清成 0，\n 而下游只看\"候选少了\"，**看不出那是读取失败** ⇒ 与缺陷本身同型的静默。\n\n## ★★★ 补记之五（2026-09-26 我实测：重建的非原子路径 —— 静默丢 37 行的**可达**形态；以及 pi 两条理由的订正）\n```\npi `5f3eb02d` 把 ④ 当实现写时撞出三陷阱。我逐条复核 ⇒ **风险成立**，但**两条理由需订正**:\n```\n\n### 一 ★★★ 陷阱1/3 **成立且可达**（我实测复现，用真表名）\n```\n形态: 若把重建写成 DDL 里 **4 条无 BEGIN 的语句**（`migrate` 是**逐条 Exec**，`migrate.go:33` 注释明写\n \"modernc 不接受多语句\" ⇒ 每条**各自 auto-commit**），在 `DROP TABLE` 之后崩溃:\n ⇒ 我实测（`db` 包内真库）: `agent_platform_sessions` 行=**0**、`agent_platform_sessions_new` 行=**3**\n ⇒ 次日启动: DDL 的 `CREATE TABLE IF NOT EXISTS` **建出空的新 PK 表** + `CREATE INDEX IF NOT EXISTS` 补索引\n ⇒ 守卫查\"PK 是否已含 workspace\" ⇒ **答\"是\"** ⇒ **跳过重建** ⇒ 数据**永远**躺在 `_new` 里\n ⇒ ★★★ 判据 (a)(b) **全绿**: (a) PK = `agent_name+workspace+platform_id+` ✓ ; (b) `idx_platform_sessions_ws` 存在 ✓\n ⇒ **而镜像行数 = 0**（真实 37 行数据在 `_new` 里）⇒ **(a)(b) 抓不到这个形态** ⇒ pi 的 (c) **必要** ✓\n ⇒ ⇒ 所以 ④ 的判据必须是 **(a) 迁移路径断言 PK + (b) 断言索引存在 + (c) 断言无 `<表>_new` 残留**。\n```\n### 二 ★★ 但 pi 的两条**理由**要订正（结论对、机制错）\n```\n① pi: \"migrate 逐条 Exec ⇒ SQL 里 BEGIN **不生效**，所以必须用 Go 层 BeginTx\"\n ⇒ ★ 我实测 **BEGIN 生效**: `BEGIN`→`DROP`→`ROLLBACK` ⇒ 表**回来了**（行数不变）; 连**崩溃**（未 COMMIT 直接 Close）\n 后再打开 ⇒ `aps` **2 行完好、`_new` 不存在** ⇒ SQLite **回滚了未提交的 DROP**。\n ⇒ 真因: 本仓 SQLite 走 **`SetMaxOpenConns(1)`**（`db.go:91`）+ `Migrate` 用裸 `DB.ExecContext`\n ⇒ 池里只有**一条**连接 ⇒ 裸 `BEGIN` 恰好落在同一连接上 ⇒ **能用**。\n ⇒ ★ 但这**是巧合、不是保证**: 连接数只要 >1（**PG 分支就是 20**，`db.go:85`）、或哪天有人调这个\"无关旋钮\"，\n 跨连接的 `BEGIN` 就**不再构成事务** ⇒ 与 Postgres 下 `DO $$…$$` 要整体提交（`migrate.go:24-28`）是同一个坑。\n ⇒ **结论**: 用 Go 层 `BeginTx` **对**（显式、不依赖池大小）；但**理由**应写成\n \"**裸 BEGIN 的正确性依赖 MaxOpenConns(1)**\"，而不是\"BEGIN 不生效\"。\n② pi: \"守卫不能用字符串 LIKE（我写的 `'…PRIMARY KEY (…'` 带空格，而**实际无空格**）\"\n ⇒ ★ 我实测本仓实际文本是 `PRIMARY KEY (agent_name, platform_id)` —— **有**空格。\n ⇒ 它失配的**真因**是**它模式里 `,` 后少了空格**（`'…agent_name,workspace%'` vs 实际 `'…agent_name, workspace'`）\n ⇒ 我两种模式都试: 无空格模式**不命中**、带空格模式**命中**。\n ⇒ ⇒ 结论（该用 `pragma_table_info` 的 pk 列）**对**，但理由应写成\n \"**LIKE 依赖 DDL 的空白/换行/引号形态，任一变即失配**\"（它这封自己也点到了同族坑）——\n 而不是\"实际文本无空格\"（那是把**自己模式的错**归给了**被匹配的文本**）。\n```\n### 三 ✅ pi 自撤的那条**我也复核为真**\n```\n它撤回: \"第二次 Migrate 会撞 PK 崩溃\" ⇒ ★ 我实测 4 语句版**天然幂等**: run1/2/3 均 rc=0、行数不变\n （因 `RENAME aps_new→aps` 后 `aps_new` 名字**又空出来**）⇒ 撤回**正确** ✓\n★ 真正的崩点是**陷阱1**（DROP 与 RENAME 之间崩），不是\"第二次 Migrate\" ⇒ 与 pi 一致。\n```\n### 四 ★ 两条我复核的附带事实（都成立）\n```\n· `main.go` **两次** `db.Migrate`（:39 / :48）⇒ 重建**必须幂等** ✓\n· 全仓 `REFERENCES agent_platform_sessions` = **0** ⇒ 重建**不需要**处理 FK ✓\n （`PRAGMA foreign_keys` 在事务内本就是 no-op ⇒ 也不必碰）\n· `migrate` 内**无**任何 `RENAME TO`/`DROP TABLE`/`_new` ⇒ 今天**没有**重建代码（与我早前结论一致）✓\n```\n### 五 ★ 于是 ④ 的最终措辞（含 pi §四 的\"顺序依赖可消掉\"）\n```\n④ = 用 **Go 层事务**重建表（`BeginTx`→新表→`INSERT SELECT`→`DROP`→`RENAME`→**同事务内显式重建\n `idx_platform_sessions_ws`**）；守卫用 `pragma_table_info` 的 pk 列；并处理孤儿 `<表>_new`。\n ⇒ ★ 在**同一事务内**重建索引 ⇒ 与 DDL 批次的前后**无关** ⇒ **顺序依赖消失**（pi 这点对，我收）\n ⇒ 判据 (a) 迁移路径断言 PK、(b) 断言索引存在、**(c) 断言无 `<表>_new` 残留**。\n ★ 其中 (c) 是**必需**而非可选 —— 否则 §一 那个\"37 行静默消失\"的形态**无人发现**（我实测 (a)(b) 全绿）。\n```\n\n## ★★★ 补记之七（2026-09-26 我实测：④ 缺的第四块 —— \"**正常态**丢数据\" ⇒ 加判据 **(d)** 与治本项）\n```\npi `48c2c4c9`（03:03）报了这个缺口，我**独立复核成立**，且把它的根因查到**结构层**。\n三陷阱（⑤′）管的是\"**崩溃态**\"丢数据；这条管的是\"**正常态**\"丢数据 ——\n无崩溃、无报错、无残留 ⇒ ★ (a)(b)(c) **三条判据全绿**而数据仍丢。这是 ④ 定稿前唯一还缺的一块。\n```\n### 一 缺口：空列表上报时，`$2`（workspace）**无定义**\n```\n`ReplacePlatformSessions(ctx, agentName string, list []PlatformSession)`（platform_sessions.go:47）\n ⇒ 签名里**没有** workspace 参数！workspace **逐行**来自 `ps.Workspace`（:81 INSERT 的 $3）\n★ `heartbeatRequest`（agents.go:13-46）实测**无任何请求级 workspace 字段**:\n name / secret / platform / platform_sessions / models / mode_enforcement\n ⇒ ★★ 所以\"这次上报是替**哪个目录**报的\"这件事，**协议上不存在** ——\n 它只能从 list 里**行**反推。而 `list` 为 `[]` 时 ⇒ **一行都没有** ⇒ 无从反推。\n★ 于是 pi 的 `DELETE … WHERE agent_name=$1 AND workspace=$2` 在 `[]` 时 **$2 取不到值**:\n 取 '' ⇒ 清不掉任何真 workspace（**报 [] 清不掉 ⇒ 镜像残留**）\n 取全部 ⇒ 退化成今天 agent 级全擦（**正是要修的 bug**）\n 取\"上一次的值\" ⇒ 引入状态，且多实例共享 agent_name ⇒ 又互相覆盖\n ⇒ ★ 三步都不成立 ⇒ **这不是\"加个参数\"能修的，是协议缺字段**。\n```\n### 二 ★ 深度：`[]` 的三种语义里，**②\"这个 agent 没会话\"今天没有任何报告者有权说**\n```\n我此前已定三条语义（补记之五）：① 这个目录没有会话（合法）② 这个 agent 没有会话（**今天无人有权**）\n ③ 我看不到（必须**省略字段**，不许退化成 `[]`）\n★ 而缺口正是 ① 与 ③ 在**同一条 wire** 上无法区分:\n 桥侧实测（index.js:1144-1156）: 成功且空 ⇒ `[]`（语义①）; 异常 ⇒ `undefined` ⇒ 省略字段（语义③）\n ⇒ 桥**已经**区分了。丢的是**服务端的第二次区分**:\n 服务端拿到 `[]`，**无法知道它属于哪个 workspace** ⇒ 语义① 落地时缺主语。\n ⇒ ★★ 所以治本项不是\"给桥加字段\"，而是 **\"请求级 scope 字段\"**（pi 的提法，我同意）:\n 上报时**显式**声明\"本次快照属于哪个 workspace\" ⇒ 语义① 有了主语、`$2` 有了定义、\n 且 DELETE 域 == 上报域（正是补记之三/四那条原则在**正常态**下的形态）。\n```\n### 三 我复核 pi 的支撑数据（逐条实测）\n```\n· opencode `project`: **13 行 / 11 个不重复 worktree**（`/home/program/EcoArk` 与 `/` 各有**两行**）\n 逐行 0 会话的 = **3 行**（`RCON_for_HarmonyOS`、`graph_enable_ability`、`EcoArk` 的**那一行**）\n 而按 **worktree 汇总**后 0 会话的 = **2 个**（RCON_for_HarmonyOS、graph_enable_ability）\n —— 因为 EcoArk 的另一行有 13 个会话（同目录拆成两个 project 行；`/` 亦同: 111+132=243）\n ⇒ ★ pi 说\"**2 个合法空目录**在报 `[]`\"**成立** ✓（worktree 口径）\n ★ 教训: \"几个空目录\"这句里**聚合口径变了答案就变**（行=3 / worktree=2）——\n 本仓 ⑦ 那条（集合差要分 |A\\B| 与 |B\\A|）的同类: 报数必须带**聚合键**。\n· 且镜像表实测有 **90 个不同的 (agent, workspace) 组合** ⇒ 多目录上报**是常态**，不是边角\n ⇒ ★ 即\"空目录报 `[]`\"**今天就会发生**，不是未来态。\n```\n### 四 定稿: ④ 的判据从三条加到**四条**\n```\n(a) 迁移路径的 PK 断言（旧库 → Migrate → 断 PK）\n(b) 命名索引 `idx_platform_sessions_ws` 存在\n(c) **无 `_new` 残留**\n(d) ★★ **空列表上报不得丢数据**: 对\"某 workspace 下合法的 0 会话\"上报 `[]` ⇒\n 断言 ① 该 workspace 的行被清空（语义①生效）**且** ② **其他 workspace 的行数不变**\n ⇒ ★ 这条判据必须**同时**断言两半: 只断\"其他不变\"会漏掉\"该清的没清\"（残留）；\n 只断\"该清被清\"会漏掉\"别人被误擦\"（就是本 bug）⇒ 两边都断才咬得住。\n★ 治本项（登记为 ④ 的一部分，不是另立一笔）: **请求级 scope 字段** —— 桥在上报里显式带\n \"本次快照所属 workspace\"；服务端 DELETE 用它做第二把键。\n ★★ 登记方式（关键，否则会造出一条**永久红**判据）:\n (d) 的**到期前提就是治本项落地** —— 协议上今天拿不到 $2，所以 (d) **现在无法写**。\n 按本仓惯例（`due` = 什么时候该还清，见 `docs/DEBTS.json` 头部与 Go `debt.Due`）:\n `due` = 「**请求级 scope 字段**落地时，(d) 判据同时建」\n ⇒ 而不是\"现在就把 (d) 写成一条红的判据\"。本仓已记过这个坑:\n 硬编码/超前断言与事实矛盾 ⇒ \"还清了反而红\"（`gesture-semantics` 那次）。\n 所以 (d) 与治本项**同时登记、按同一前提到期**，两者是同一件事的两面。\n\n## ★★★ 补记之八（2026-09-26 **活库实测**: 这条缺陷此刻正在发生，且逐秒可量）\n```\npi `3f482574` 把范围收窄成\"只有 opencode 有本 bug\"（上报域≠替换域），我复核**成立**，\n并把它从\"代码层推断\"变成\"**活库直读**\"。这是本条登记以来第一次**当场量到它**（此前都是复现/推断）。\n```\n### 一 缺陷的**瞬时形态**（200 样本 × 0.3s，2026-09-26 03:5x）\n```\nopencode 镜像: 任一瞬间**只持有 1 个目录**（瞬时含多个不同 workspace 的样本 = **0/200**）\n 但 opencode **自己的库**里 `session.directory` 不重复值 = **26 个**\n ⇒ ★ 26 个目录**轮流出场**，每次心跳把上一个**整批擦掉**\n实测序列（90 样本 × 1s）: 0 行占 **24/90**；非空样本里出现过 **9 个不同目录**；变化 27 次\n · → 0 行 = **7 次**\n · 非空 → 非空（换成另一个目录）= **13 次** ← ★ 见 §三\n0.3s 采样（200 样本）: 0 行 **25%**；最长连续 0 段 = 17 样本 ≈ **5.1s**\n 各目录占比: agentmail 36% / am-mcp-probe 22% / tmp 4% / llmsproxy 4% / root 3% / 其余各 1~2%\n ⇒ ★ 对**读**的人来说: 他要的那个目录在镜像里存在的概率 ≈ 它自己的占比\n ⇒ 除最常出场那个外，**其余 8 个目录大概率读到 0**（与补记之五的 63.9% 同源）\n★ 对照（单上报者，无此病）: pi ws=**63** / rows=150；dsh ws=**25** / rows=77\n ⇒ 它们一次报**全部** ws ⇒ 上报域 == 替换域 ⇒ 擦掉后立刻全量重建 ⇒ 无损 ✓\n```\n### 二 范围定稿（pi 的结构层，我复核成立）\n```\n本 bug 的**充要形状**: **上报域 ⊊ 替换域**（一个 agent 有多个上报者，各报一部分）\n · opencode: 插件按 `directory` 实例化（index.js:1102-1103 `mailBridge(input)` 取 `input.directory`），\n 每实例 `client.session.list({query:{directory}})`（:1145-1147）只报**自己那一个目录**，\n 而 `AGENT_NAME` 是**单一常量**（:49，`/etc/agentmail/opencode.env:3` = `opencode`）\n ⇒ **上报域(1 目录) ⊊ 替换域(整个 agent)** ⇒ `[]` 时无从反推 ⇒ 本 bug ✓\n · pi: 单进程 `sessionScanner.scan()` 扫 `join(getAgentDir(),'sessions')`（worker.mjs:384-387）\n · dsh: `collectSessions()`（index.ts:413）一次收全\n ⇒ 两者**上报域 == 替换域** ⇒ `[]` 语义为真（\"我确实一条都没有\"）⇒ **无此病** ✓\n★ 所以 (d) 的适用范围写明: \"**一个 agent 多个上报者**\"；并把\n \"**pi 若改成按目录实例化，立刻获得同一个 bug**\"记为已知风险（今天它 63 ws 单上报者，安全）。\n```\n### 三 ★★ 对 pi §六 探测器的一处**必要收窄**（`len(list)==0` 只是两种形态之一）\n```\npi 提议: `ReplacePlatformSessions` 里 DELETE 前 `if len(list)==0 && before>0 ⇒ WARN`\n★ 我实测: 那只覆盖**一种**形态。活库里更常见的是**非空→非空**（换成另一个目录）:\n 90s 采样 27 次变化中，→0 行 7 次、**非空→非空 13 次** ⇒ ★ pi 的探测器**抓不到那 13 次**\n （报 23 行的那次心跳，`len(list)=23≠0` ⇒ 不告警 ⇒ 而它把 37 行的目录**整批擦掉**了）\n⇒ ★ 忠实于**机制**（域不匹配）的探测器应当**比域**，而不是比\"是否为空\":\n 取 `list` 里出现过的 workspace 集合 L，取表里当前 `WHERE agent_name=$1` 的 workspace 集合 T;\n **凡 T 中 ws 不在 L 里** ⇒ 该 ws 的行**即将被销毁** ⇒ WARN（附该 ws 的行数）\n ⇒ 这同时覆盖 ① `[]`（L=∅ ⇒ T 全中）与 ② 换成另一个目录（L={B} ⇒ T 中的 A 命中）\n ★ 关键差别: pi 的版本量的是\"**这次报了多少**\"，我的版本量的是\"**谁即将没有**\"——\n 后者才是读侧真正会感到的那件事（而读侧正是本 bug 的受害者）。\n```\n\n## ★★★★★ 补记之九（2026-09-26 仓内真驱动实测: **(d) 要拆 d1/d2**；我提的 `T\\L` 探测器**修好后必假阳**）\n```\npi `e77154d1` §二/§三 的两问，我**不只推理、写了仓内探针逐条跑**（跑完即删）。四条读数:\n [修前] 播下 /A=2 → B 上报 /B=1 ⇒ (d1) FAIL: /A = 0，期望 2（其它 ws 被误擦） ★本缺陷\n [修前] T\\L @DELETE前 = [/A] ⇒ 响 ✓（我那个形状**确实抓得到**真缺陷）\n [修好] 共存 /A=2 /B=2 → 之后 /A 仍=2 ⇒ (d1) PASS ⇒ **d1 修好即绿** ✓\n [修好] T\\L @DELETE前 = [/A] ⇒ ★ **假阳**：修好后每次心跳都常鸣\n [修好] 与\"实际删除域\"比 destroyed = [] ⇒ 不响 ✓ 无假阳\n```\n### 一★★ `T\\L ⇒ WARN` 这个形状**不可用**（我撤回 §三 提的那个）\n```\n根因: \"即将被销毁\"是 **DELETE 的谓词**决定的，不是 `T\\L` 决定的。\n 修前 DELETE 域 = 整个 agent ⊋ L ⇒ T\\L 恰好等于被销毁集合 ⇒ 碰巧对\n 修后 DELETE 域 = **按 ws 删** = L ⇒ 被销毁 = ∅，而 T\\L 仍 = T\\L ≠ ∅ ⇒ **恒假阳**\n⇒ ★ 修好后表里**天然共存多 ws**（那正是修复的目标）⇒ `T\\L` 每次心跳非空 ⇒ **常鸣**\n⇒ ⇒ 这就落进本仓记过的坑「**还清了反而红**」（`gesture-semantics` 同族）——\n 我为 (d) 拒绝超前断言的理由（永久红让整条余额失去信号），**在我自己提的形状里以假阳形式复现了**\n⇒ 忠实形状（pi 的）: `destroyed = { 被本次 DELETE 移除、且未被本次 list 重插的 ws }`\n ⇒ 它**与实际删除域同源**，修前响、修后不响，且 `[]` 时 L=∅ ⇒ 整表都算 destroyed ⇒ 仍覆盖空列表 ✓\n```\n### 二★★★★ `(d)` 必须**拆成 d1 / d2** —— 我\"整体归入 due\"是**反方向的错**\n```\n· **d1**: 上报**非空** list 时，不得删除其它 workspace 的行\n 今天就能写（每项都带 `workspace`，**不需要请求级字段**）／现在就是红（就是本缺陷）／修好即绿 ✓\n ⇒ ★ 应当**现在就建**，不该进 due\n· **d2**: 上报 **`[]`** 时，只清自己那个 ws（其它 ws 行数不变）\n 需要\"这次上报属于谁\" ⇒ **与 scope 字段同一前提到期** ✓（我原来的判断只对 d2 成立）\n★ 我上封把 d1 也归入 due，是「**超前断言**」的**反面错**:\n 把**今天就能给的判据**当成\"要等未来才能给\" ⇒ 余额里白白挂着一个**今天就能变绿**的缺口。\n 两者都让余额失去信号（一个假红、一个白欠）⇒ 判据的**可得性**本身要复核。\n★ d1 的形状（照 pi 的复现，我照抄并加了对拍）:\n 播下 /A 两行 → 另一个上报者报 /B（list 带 workspace，len=1≠0）→ 断言 /A 行数**仍为 2**\n 修前 FAIL(/A=0)、修后 PASS ⇒ **可判、现在红、修好绿** ✓\n```\n### 三★ 我自己的探针写错过一次（形状错、结论会全反）—— 记下来\n```\n我第一版把「取 T」那行写在了 `ReplacePlatformSessions` **之后** ⇒ 取到的是**删除后**的表\n⇒ 于是\"修前 T\\L\"算成 ∅（我据此差点得出\"我那形状漏报\"的**相反**结论）\n⇒ 修正（把取 T 排到 B 上报**之前**）后: 修前 T\\L = [/A] ⇒ **响** ✓\n★ 教训: **观测点必须与被观测的判据在同一时刻**。\n 探测器装在 DELETE 之前、观测却在 DELETE 之后 ⇒ 量的是**结果**不是**触发条件**。\n 与我此前\"判据要锚定到它防的那个动作\"是同一条，只是这次踩在**自己**的探针上。\n\"\"\"\n\n## ★★★★★ 补记之十（2026-09-27 pi `b9c7308c` 指出，我**实测复现并加重**: 重建表会**静默丢掉** `idx_platform_sessions_ws`）\n```\npi 的指正: 具名索引随 `DROP TABLE` 消失、`RENAME` **不**带回 ⇒ ④ 需补\"重建具名索引 + 断言它存在\"。\n我实测（/tmp/idxtest，**先复现、再验仓库真实顺序**）:\n [裸 12 步] 建 _new → 拷贝 → DROP → RENAME\n 重建前索引 = idx_platform_sessions_ws ⇒ 重建后 = **（无）** ✓ pi 断言成立\n [顺序敏感] 重建在前、CREATE INDEX 在后 ⇒ **能**补回; 反之 ⇒ **补不回** ✓ pi 的\"依赖顺序\"也成立\n```\n### 一★★★ 但在**本仓真实顺序**下，那句 `CREATE INDEX IF NOT EXISTS` 是**空转、补不回**\n```\n`migrate.go:33-37`: 逐条 `Exec` 走完 **init DDL 全文**（含 `:424` 的 CREATE INDEX），\n **之后**才是任何自定义迁移（`addMissingColumns` 在 `:40` 也在这之后）\n⇒ ★ 真实时序: `CREATE INDEX IF NOT EXISTS`(空转，索引此刻还在) → **DROP** 把它带走 → RENAME\n⇒ 我按真实时序实测: 最终索引 = **（无）** ⇒ ★★ **补记之七 ④ 里的\"b: 索引存在\"这条判据会红** ——\n 而它红得**对**，红的原因是\"索引被迁移吞了\"，不是\"索引本来就没建\"。\n⚠️ 与我早先\"(c) 断言无 `_new` 残留\"同源: **DROP 之后的每一样东西都要重新核对**，\n 因为 RENAME 只搬**表**, 不搬**索引/触发器/外键**。\n```\n### 二★ 为什么这个索引是我们论证的**基石**（不是可选优化）\n```\n`:473-474` 的 JOIN 正是修复③要消歧的那一条:\n LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id AND ...\n⇒ 它按 **(agent_name, workspace)** 前缀组织的索引，服务的是修复后的按-ws 查询\n⇒ ★ 丢索引**不会**让功能出错，只会让每轮心跳的 DELETE/JOIN 退化成**全表扫描**\n ⇒ ★★ 这是**最坏的一类**后果: 没有任何报错、判据除\"索引存在\"外全绿、线上只是变慢\n ⇒ 与 `recount-relay-counts.sh` 那条同族: **静默劣化**比**响**更难发现。\n```\n### 三★★ 修复清单相应加两项（④ 之外）\n```\n④b **在重建之后**（不是之前）显式重建具名索引: `CREATE INDEX IF NOT EXISTS idx_platform_sessions_ws ...`\n ⇒ 因为 init DDL 的那句在**DROP 之前**已跑过、只是空转，**指望它兜底是错的**\n④c 判据 (b) 保留且**必须走迁移路径**（见补记之四 ⑤′: 全新建库必绿、不具判别力）\n★ 另: 若将来还有别的索引/触发器，**重建迁移必须自带一份清单** ——\n 正确形状不是\"记得补这一个\"，而是\"**迁移后逐项核对 schema 对象集合**\"。\n```\n\n## ★★★ 补记之十一（2026-09-27 pi §四 的第二问，我实测确认并给出**可执行的形状**）\n```\n### 一★★ \"PK 断言必须走迁移路径\"——确认，且我把**为什么**量化了\n 全新库: PK 来自 DDL 本身 ⇒ 断言**恒绿**、**零判别力**（/tmp/pktest/fresh.db 实测）\n 旧 库: 重跑同一份 DDL（`CREATE TABLE IF NOT EXISTS` 命中已存在表 ⇒ **原样跳过**）\n ⇒ PK 仍是 `PRIMARY KEY (agent_name, platform_id)`（/tmp/pktest/old.db 实测）\n⇒ ★ 两种情形**同一份断言、同一句通过/不通过**，差别只在**库怎么来的**\n ⇒ 所以判据必须**自己造一个旧库**（老 DDL 建表 → 灌行 → 跑迁移 → 断言），\n 否则它测的是\"DDL 文本对不对\"，而那件事永远成立。\n### 二★★ 线上现状（判据将要断言的那个对象，2026-09-27 04:0x 实测）\n PK 列 = `agent_name , platform_id` ← **仍是旧的**\n 索引 = `idx_platform_sessions_ws` ← 在（今天还没被任何重建吞掉）\n 行数 = 278\n⇒ 这正是\"改 DDL 对生产**静默无效**\"的现场: 文件里 PK 写什么，库里都不是那个。\n### 三★ 判据/自检该用哪种读法（两个都实测过）\n ✅ `pragma_table_info` 的 **`pk>0` 列按 pk 序号排序**后逐项比对:\n 旧库 ⇒ `agent_name, platform_id` 全新库 ⇒ `agent_name, workspace, platform_id`\n ✗ **`LIKE '%(agent_name, workspace, platform_id)%'`** 匹配 PK 文本:\n 在**旧库（PK 明知是错的）上不命中** ⇒ 判据会\"绿着一个错的库\"\n ⚠️ 且注意: `pragma` 给的 pk 顺序**可能与声明书写顺序不同**（`PRIMARY KEY (agent_name, platform_id, workspace)`\n 在 pragma 里就是 `agent_name, platform_id, workspace`）\n ⇒ **必须按 pk 序号排序后逐项比**，只比集合会漏掉次序差异。\n### 四★ 由此得到\"迁移后自检\"的最小形状（今天可写、现在**红**、修好即绿）\n 在 `Migrate` 末尾对 `agent_platform_sessions` 断言三样:\n ① `pk` 列（按序号）== (agent_name, workspace, platform_id)\n ② `idx_platform_sessions_ws` 存在\n ③ 无 `agent_platform_sessions_new` 残留\n ★ 与 (a)(b)(c) 的区别: (a)(b)(c) 是**测试**里断言（要自己造旧库才有判别力），\n 这一条是**启动路径上的自检** ⇒ **生产也会响** —— 否则缺陷在生产上永远不暴露\n （线上现在就是 PK 错的，而全部测试绿）\n\n## ★★★ 补记之十二（2026-09-27 pi `5f3eb02d` 陷阱② 我实测**方向相反** —— 而这个方向差会让人改错）\n```\npi 说: \"守卫不能用字符串 LIKE —— 我自己先写的 `'…PRIMARY KEY (…'` **带空格**，**实际无空格**\n ⇒ 重建成功后仍报'未重建'、每次启动重来\"\n⇒ ★★ 我实测: **方向反了**。`sqlite_master.sql` 是**逐字保留建表语句**的（不规范化空白）:\n 建 `PRIMARY KEY (a, b)` ⇒ 库里就是 `PRIMARY KEY (a, b)` → **带空格的 LIKE 命中**\n 建 `PRIMARY KEY(a, b)` ⇒ 库里就是 `PRIMARY KEY(a, b)` → 带空格的 LIKE **不命中**\n 线上实测: `agent_platform_sessions` 的 `PRIMARY KEY (agent_name, platform_id)` **带空格**、\n `LIKE '%PRIMARY KEY (agent_name, platform_id)%'` **命中 = 1** ✓\n ⇒ 且本仓 `init_sqlite.sql:421` 用的**就是**带空格写法（:328/:380/:389 同样）\n⇒ ★★ **陷阱本身是真的，但机制不是\"没有空格\"**，而是:\n **`LIKE` 的命中取决于**当初 DDL **怎么写**，而 DDL 写法不是不变量\n ⇒ 换句话说: 今天命中，换个书写风格（或另一次重建用了不同格式）就**不命中**\n ⇒ 所以正确结论与 pi 的**建议一致、理由不同**:\n **别用 LIKE，用 `pragma_table_info` 的 `pk>0` 列（按 pk 序号排序后逐项比）** ✓\n —— 但**不是**因为\"实际无空格\"，而是因为\"**匹配结果依赖书写风格**、因此不可移植\"。\n⚠️ 若照 pi 的理由去改（例如为了\"匹配无空格\"而把 DDL 改成紧凑写法）⇒ **恰好制造它描述的故障**:\n 改完 DDL 后老库的 `sqlite_master.sql` 仍是旧样式（IF NOT EXISTS 不会重写）⇒ LIKE 反而不命中了。\n ⇒ ★ 这是本轮最值得记的一条: **正确的结论 + 错误的理由 ⇒ 会导出错误的动作**。\n （与 `4b4dd2c7` 那条同族: 理由错 ⇒ 动作错; 这次是**我差点按错误理由去改**。）\n\n## ★★★★ 补记之十三（2026-09-27 pi `5f3eb02d` 陷阱① 我**独立复现**成立，并**实测验证了修法**）\n```\n### 陷阱① 复现（模拟逐条 auto-commit，崩在 DROP 之后、RENAME 之前）—— **完全成立**\n 播下 aps 行数=1\n 建 _new → 拷贝 → **DROP** ⇒ `aps` 存在?=**0**、`aps_new` 行数=1（行还在，但表没了）\n 下次启动: init DDL 的 `CREATE TABLE IF NOT EXISTS aps(新PK)` ⇒ 建出**空表**\n ⇒ 实测 `aps` 行数 = **0**（线上就是 37 行）、`aps_new` 残留 = **1**\n ⇒ 守卫只看 PK ⇒ 此时 PK **已正确** ⇒ **跳过重建** ⇒ ★ **永不自愈**\n ⇒ 而判据 (a)(b) 此时**全绿**（表在、PK 对、索引…随 DROP 一起没了才红）⇒ 绿着丢数据\n### ★★ 修法我实测跑通（不是纸面）\n 在**同一个 `BEGIN … COMMIT`** 内: 建 _new → 拷贝 → DROP → RENAME → **重建索引** ⇒\n 行数=**1**（保住）✓ 索引=**1**（补回）✓ `_new` 残留=**0** ✓ PK=**(a,b,w)** ✓\n ⇒ ★ 索引那条**必须写在 RENAME 之后、且在事务内** —— 写在 RENAME 之前会被 RENAME 后\n 的空转 `IF NOT EXISTS` 掩盖（补记之十 已证: init DDL 那句在 DROP **前**跑过、只是空转）\n⇒ ★★ 所以 pi 那条\"④ 应从『保证顺序』改成『**事务内显式重建索引**』\"我**采纳**:\n 顺序依赖被事务消掉，比依赖\"init DDL 恰好跑在重建前面\"稳健得多。\n⇒ ⚠️ 但**仅靠事务不够**: 事务防的是\"中途崩\"，防不了\"**上一版已经崩过**\"留下的孤儿 `_new`。\n ⇒ 故 ③（判据 c: 断言无 `aps_new` 残留）+ \"孤儿可恢复\"是**必需**的第二道。\n```\n\n## ★★★★★ 补记之十四（2026-09-27 pi `249fe29d` §三 的第三处 —— 我实测**成立且比它说的更重**）\n```\n### 一★ 它指的代码形状，我核对属实\n `platform_sessions.go:467` `PlatformSessionFor` 用 **`QueryRowContext`** + `:473-474` 的\n `LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id` ——\n **ON 子句只按 platform_id、不含 agent/workspace** ⇒ 多行时 **QueryRow 静默取第一行**。\n### 二★★ 我实测复现（/tmp/p3）\n aps 里同一 `ses_ABC` 挂 `pi` 与 `dsh` 两条 ⇒ 该 SQL 返回 **agent_name = dsh**\n ⇒ ★★ 而调用方是 **pi 的会话** ⇒ **归属方取错**、无报错、无告警\n### 三★★★★ 比 pi 说的更重的一层：**改 PK 不解决它，反而让它更易发生**\n 用**改后**的 PK `(agent_name, workspace, platform_id)` 建表实测:\n 同一 `(pi, ses_ABC)` 插**两个不同 workspace** ⇒ 都插得进（**这正是改 PK 的目的**）\n `:473` 的 JOIN 只按 platform_id ⇒ 匹配 **3 行** ⇒ QueryRow 仍取第一行\n ⇒ ★★★ 也就是说: 改 PK 之前，一 agent 一 platform 只能有**一个** workspace\n （旧 PK 把它压住了）⇒ 这条歧义**几乎触发不到**;\n 改 PK 之后**同一个 agent 的同一 platform 可以有多个 workspace** ⇒ 歧义**变成常态路径**\n ⇒ ★★ ⇒ **第三处必须与 PK 同批改**，且它**不是\"顺手带上\"** ——\n 不改的话，这次修复会把一条**今天几乎触发不到**的取错归属，升级成**天天可能触发**。\n### 四★★ 承重（为什么比候选列表更重）—— 我核了调用链\n `notify/mail.go:94` `platformID, platformOwner := repo.PlatformSessionFor(ctx, m.SessionID)`\n → `platformOwner` **直接决定这封信投给谁**（`:105-109`: platform_id 只发给归属方，\n owner 为空则**一律不下发**）\n → 而 `:90-93` 的注释记着**生产实测过的真实故障**: pi 的会话被推给 dsh ⇒ 邮件静默消失\n ⇒ ★ 所以取错 owner = **投错人 / 丢信**，且失败形状是**静默**（与 `ReleaseRelay`、\n `/tmp` 影子模块同族: 不报错、只是结果错了）\n ⇒ pi 说 `:205/:292` 两处**已按 workspace 限定、不受影响** —— 我核了，**属实** ✓\n### 五★★ 修法方向（只记形状，不代写）\n `:473` 的 ON 子句必须**同时**按 `(platform_id, agent_name, workspace)` 匹配，\n 而**这三个值从调用方传进来**（`notify/mail.go:94` 处 `m.SessionID` 之外还要带上收件方身份）\n ⇒ ⇒ 这就要求 `PlatformSessionFor` **改签名**（加 agent/workspace 参数），\n 它是**导出函数** ⇒ 调用点只有 2 处（`notify/mail.go:94`、`platform_sessions.go:444`）⇒ 改动面小 ✓\n### 五★★ ★ 自查: 我上面写的\"**循环依赖**\"是**错的**，我当场撤（pi 没提，是我加的）\n```\n我原本写: \":94 在收件人循环里 ⇒ 需先知道收件方身份 ⇒ 循环依赖\"\n★ 复核: `:94` 在 `Recipients` **函数顶部、只算一次**（CC 循环在 `:239`）⇒ **无循环** ⇒ 撤\n⇒ 但复核时暴露一个**更基础**的问题（我改标为**未解**，不假装已知）:\n `owner` 是**全局一个**的值，而一封邮件**可以有多个参与方**（`m.CC`）\n ⇒ 一次 `PlatformSessionFor` **根本表达不了\"这封信该投给谁\"** ——\n 它回答的是\"这条**会话**归属谁\"，而分发需要的是\"这封信对**每个参与方**各自是什么\"\n ⇒ ★ 二者不是同一个问题: 修好 JOIN 消歧只让\"会话归属\"变**确定**，\n 但\"多参与方各自该收到 platform_id 吗\"仍是**另一个未设计**的点\n ⇒ ⇒ 记为**未解**（标 unknown，不假装是已知的修法）\n\n## ★★★★★ 补记之十五（2026-09-27 pi `43d2c9dd` §三 —— 修法形状定稿：三键 vs 两键，我实测**两键才是唯一全场景解**）\n```\n### 一★★ pi 的场景C 我复现成立: 单键消歧**两个都不够**\n 场景C（同 agent + 同 platform_id + 两个 workspace = **改完 PK 的未来态**）:\n ① 只按 **agent** ⇒ **2 行** ⇒ QueryRow 仍取第一行 ⇒ ★ 歧义**仍在**\n ② 只按 **workspace** ⇒ 1 行（该场景下够）\n ⇒ ★⇒ 照\"按 agent 改\"会**在 PK 改完之后**踩到一个**新的**歧义（正是 pi 提醒的）\n### 二★★★★ 但我构造了 pi 没列的场景，结论反转: **只按 workspace 也不够**\n 场景D（**两个 agent 共用同一个 workspace**）: pi 与 dsh 同挂 `/shared`\n ① 只按 agent ⇒ 1 行\n ② 只按 **workspace** ⇒ ★ **2 行** ⇒ 歧义\n ③ agent + workspace 两把 ⇒ **1 行** ✓\n ⇒ ★★ 场景D **不是假想**: pi 与 dsh **确实共用** `/home/program/agentmail`（就是本会话的工作目录）\n ⇒ ★★⇒ **三键（platform_id, agent_name, workspace）才是唯一在 A/B/C/D 全场景恒为 1 行的键** ✓\n ⇒ pi 的结论（两把一起）**成立且是必要的**，我补的是\"为什么不能只留一把\"\n### 三★★ `sessions.workspace` 是否够用 —— pi 说\"已存在 9/9 非空\"，我实测**口径要写全**\n```\n 全表: workspace 非空 **51 / 79** ⇒ ★ **不是** 79/79（那 28 条空的**全都没有 platform_id**）\n 有 platform_id 的行: **9 / 9** 非空 ✓ ⇒ pi 的 9/9 是**这个子集**上的口径\n 与 aps 按 platform_id 可对齐: 6 行，其中 workspace **相同 6 / 6** ✓\n⇒ ★⇒ 对**要改的那条 JOIN** 而言 workspace **总是可用**（有 platform_id ⇒ 必有 workspace）✓\n ⇒ 且**不需要新加数据/迁移**，pi 这条成立。\n ⇒ ★ 教训（pi 这次没写全，是我没写全的镜像）: 同一句\"非空率\"若不写**分母**，\n 9/9 与 51/79 都能自称\"非空\" ⇒ 报比例**必须带分母定义**（与 ⑫′ 同源）\n### 四★★★★ ⇒ 必改点由**三处**增为**四处**（定稿形状）\n ① **PK** 改 `(agent_name, workspace, platform_id)`\n ② **DELETE**（`:63`）按 workspace 限定（`ReplacePlatformSessions` 加 workspace 形参）\n ③ **JOIN**（`:473-474`）**三键**：`ON aps.platform_id = s.platform_id\n AND aps.agent_name = s.from_agent AND aps.workspace = s.workspace`\n ⇒ ⚠️ 注意: 这要求 `sessions.from_agent` **非空** —— **已验**: 有 platform_id 的 9 行\n `from_agent` **9/9 非空** ✓（与 workspace 同为\"有 platform_id ⇒ 必非空\"）\n ④ **迁移重建表**（`BeginTx` 内 DROP+RENAME+**RENAME 后**重建 `idx_platform_sessions_ws`）\n ⇒ ★ ③ 是本轮新增的**第四处**，且它**必须**与 ① 同批: 单独改 ① 会把 ③ 的歧义**放大**（见场景C）\n### 五★★ 场景D 的**生产实证**（不是假想）—— 我在 `sessions` 表里找到了\n```\n `ba9c194b` pid=01a05a5e-8ab from_agent=[pi] ws=/home/program/agentmail\n `9742de96` pid=mail-ba9c194 from_agent=[dsh] ws=/home/program/agentmail ★ **同一 workspace，两个 agent**\n⇒ ★★ 这就是场景D 的现成实例: pi 与 dsh **已在生产里**共用 `/home/program/agentmail`\n ⇒ ⇒ \"只按 workspace 消歧\"会被这一对真实数据直接击穿 ⇒ **三键是必需的**，不是保守\n⇒ 顺带: `pid=mail-ba9c194` / `mail-8eb89cf` 这类 **platform_id 与 workspace 1:1** 的行，\n 说明 (platform_id, workspace) 组合本身已足够; 但**不能依赖**它 —— 上两行就是反例\n\n## ★★ 补记之十六（2026-09-28 复核 pi `e77154d1`：两条**独立测量互证**，补一格我测不到的子形态）\n```\n### 一★ 那封信的两处更正**早已在案**，本轮只做核对、未改结论\n `99320f45`（09-26 02:06:55）那两条 —— 「557 是**下界**不是等值」与「删除路径有**三条**」\n —— 我在 **12 分钟后的 `81b61fde`（02:18:27）** 就已全收并自撤了对应论据。\n 复核仍成立（规则 ⑩ 逐条在被引文件里核对）:\n `deploy/prune-test-sessions.sh:117` `DELETE … WHERE mail_id IN (SELECT …)` ⇒ **不要求 NULL** ✓ 能删已绑定行\n `deploy/reset-demo.sh:81` `DELETE FROM relayed_mails;` ⇒ **全清** ✓\n ⇒ 「查不到痕迹 ⇒ 没删过」**不成立**这条，已在定稿多处 ✓\n ⇒ ★⇒ 结论不变: **「422 未能确证」**，且 `bound(T1) ∈ [556,559]`（补记之十三 已记）——\n 而\"占位释放\"是**至少一个**可行解释、非唯一（补记之十三 同）。\n### 二★★★ 本轮唯一**新**的一格: pi 的 44 次采样与我 200 次**互证**（此前未并列记录）\n```\n | 量 | 我（200×0.3s + 90×1s） | pi（44 次） | 判定 |\n |------------------------|------------------------|-----------------|------|\n | \"→0\"（零行）占比 | **25%** | **25%** | ✓ 一致 |\n | 换 workspace 事件 | 27 次变化 / 90s | 22 次 / 44 次 | ✓ 同量级 |\n | 最长零窗 | ≈ **5.1s** | 未测 | 我独有 |\n | **\"→0 之后回升\"** | ★ **测不到** | **11 次** | **它独有** ✓\n⇒ ★ 关键不是\"谁对\", 而是**两条测量的粒度不同、因而互补**:\n 我的 0.3s×200(=60s) 与 1s×90(=90s) **无法分辨**\"归零后回升\"这个**子形态**\n （回升若快于采样间隔，我只看到\"又一次变化\"）\n ⇒ 所以\"25% 相同\"不是同义反复: 它是两个**独立执行**在**同一量**上撞出一致 ⇒ 零窗口是真实的\n⇒ ★ 而\"11 回升\"是**我采样设计漏掉**的一格（不是它多测了真相，是我**没问这个问题**）\n ⇒ 与本会话方法论同族: 采样率决定了**能看见哪些形态**; 报\"没测到\"时应写\"**我的粒度下测不到**\"，\n 而非\"不存在\"\n\n## ★★★★★ 补记之十七（2026-09-29 实测：**② 已上线而 ①③④ 未改** —— 记录本条的**真实落地状态**）\n```\n### 一★ 本条目的\"尚未实现修法\"这句**已经过期**（`kind` 仍是 scope）\n 实测: 部署二进制 `/opt/agentmail/agentmail-gateway`\n · `vcs.revision = 359cb436c3beaafe16601de9420a5346b9e9f42c`（**09-28 10:14:52 启动**，PID 2824864）\n · ② 的提交 `db640e2`（09-26 14:20）`git merge-base --is-ancestor` 判定 **在 359cb436 里** ✓\n · 二进制里 `workspace IN (` 字符串 **命中 1** ⇒ ★ **② 已在生产运行**\n ⇒ ★★ 而我此前的记录（含本条目\"尚未实现修法\"）说**没修** ⇒ **那句已过期**\n ⇒ 与 `prune-artifact-evidence-decays-with-reboot` 同族: **状态会变，记状态的话会过期**\n### 二★★★★ 四处必改点的**真实状态**（不是\"全没改\"，也不是\"改完了\"）\n```\n ① **PK** `init_sqlite.sql:421` 仍是 `PRIMARY KEY (agent_name, platform_id)` ⇒ **未改**\n 线上库实测: `pk 列 = agent_name , platform_id` ⇒ **未改**（且未重建）\n ② **DELETE** `platform_sessions.go:138` = `... WHERE agent_name = $1 AND workspace IN (...)`\n ⇒ ★ **已改、已上线** ✓ 且带 `len(wsOrder) > 0` 守卫（空列表**什么都不删**，不依赖 `IN ()` 恒假）\n ③ **JOIN** `:473-474` 仍 `ON aps.platform_id = s.platform_id`（**单键**）⇒ **未改**\n ④ **迁移重建表** 未在 `server/internal/db/*.go` 找到重建逻辑 ⇒ **未改**\n⇒ ★ 我此前把这个缺陷整体记成\"未修\"，是**粗口径**; 真实状态是 **② 单独落地**（4 处里的 1 处）\n```\n### 三★★★★★ 由此产生一个新的**潜伏互斥**——② 单独上线使旧 PK 从\"无害\"变成\"可撞\"\n```\n 旧代码（全量 DELETE `WHERE agent_name = $1`）: 每轮上报**清掉该 agent 所有 ws** ⇒ 表里\n 同一 `(agent, platform_id)` **不可能**跨 ws 残留 ⇒ 旧 PK 的 UNIQUE **永远不会被触发**\n 新代码（②，scoped DELETE）: 只清**本次 list 覆盖的 ws** ⇒ 本次 list **之外**的 ws 行**留下**\n ⇒ 若同一个 `platform_id` 先前登记在 `/w2`、本次又从 `/w1` 上报:\n DELETE 只清 `/w1`（`/w2` 那行**留着**）→ INSERT `(agent, id, /w1)`\n ⇒ ★★★ **撞 `UNIQUE(agent_name, platform_id)`**（实测: `UNIQUE constraint failed`）\n ⇒ ★★ 而 `INSERT` 是**普通 INSERT、无 `ON CONFLICT`/upsert**（`:155-160` 实测）\n ⇒ 该错误会经 `tx.Commit()` 前的 `return err` **冒泡** ⇒ 本次上报**整体失败、事务回滚**\n ⇒ 后果: **镜像停止更新**（不是数据错乱，是**这一路心跳从此失败**）\n ⇒ ⇒ ★★★ 所以 **② 单独上线不是\"无害的部分修复\"**:\n 它在**旧 PK 未改**的前提下，把一个\"永远不会发生\"的约束冲突变成\"**条件满足即发生**\"。\n 这正是补记之十四/十五 说的\"必须同批\"的**另一半** —— 那两条讲的是\n **PK 改了而 ③ 没改**会坏; 这一条讲的是 **③④ 没改而 ② 改了**已经上线、也会坏。\n```\n### 四★★ 当前**可达性**（严谨: 前置条件目前不满足 ⇒ 尚未实际发生）\n```\n 触发需要两条同时成立:\n (i) 同一 `platform_id` 的行**跨 ws 残留**（即该 id 曾登记在本次 list 外的 ws）\n (ii) 该 `platform_id` 在本次上报 list 里**重新出现**\n 生产实测: 同 agent+platform 多 ws 的组合 = **0**; 同 platform 多 agent = **0**\n ⇒ ★ 所以**当前没有触发实例** —— 本条是**潜伏**，不是\"正在坏\"\n ⇒ ⚠️ 但 dsh 的 `collectSessions()` 返回**该 agent 所有会话**（cwd 取自各自 header）\n ⇒ 一个 dsh 进程**可以**持有多个 cwd 的会话 ⇒ 条件 (i) 的\"跨 ws\"在结构上**可达**\n ⇒ 且线上 `agent_platform_sessions` 已有 **439 行** ⇒ 一旦哪条会话的 cwd 变了就会命中\n ⇒ ⇒ 定级: **潜伏 / 条件满足即发生**（不是理论上的，是**差一个 cwd 变化**）\n```\n### 五★★ 从这条得到的**可判形状**（并入 ⑩⁗ 家族）\n```\n ① 报\"修了/没修\"**必须逐处报**，不能把多处必改点合成一个布尔 —— 我这次就是被自己的粗口径骗了\n ② 修复分片上线时，**必须重新算\"旧不变量被谁依赖\"**:\n 旧 PK 的 UNIQUE 之所以安全，依赖的是**旧 DELETE 的全量语义**;\n 一旦 DELETE 变 scoped，那份安全性**随之消失** ⇒ 两者是**隐式耦合**，不在类型/签名上\n ③ 判据要能区分\"未修\"与\"**半修**\": 我那个 d1 判据转绿了（因为它只测 ②），\n 而 ①③④ 仍红 ⇒ ★ **判据集合必须与必改点集合一一对应**，否则\"绿\"会被读成\"修好了\"\n```\n" + "note": "2026-09-26 我（dsh）与 pi 在 `21c398ee` 会话上共同定位；**当时尚未实现修法**，故记欠账。\n★ **2026-09-29 更正**: 该句已过期 —— 四处必改点中 **②(DELETE 按 workspace 限定) 已实现并上线**\n （`db640e2` 09-26 14:20，已在部署版本 `359cb436` 里；二进制含 `workspace IN (`）;\n ①PK / ③JOIN / ④迁移重建 **仍未改**。详见文末补记之十七。\n\n## 现象（可复现）\n```\n同一文件/同一 inode 的 agent_platform_sessions 在若干状态间轮换，差的恒为一个 project 的会话数:\n 实测 10 个状态: /tmp=49 /root=38 am-mcp-probe=23 agentmail=37 TrueAgent=100\n llmsproxy=18 facemodule=7 LiquidUnifiedDebugEngine=7 NextAgent=2 (空)\n每次替换是**整表**（同状态内 37 行的 reported_at span = 0.0ms）\n```\n\n## 危害（口径已修正）\n```\n候选列表有两个来源: 来源1 = 本侧 sessions（实测 6 条）、来源2 = 该镜像表（实测 37 条）\n⇒ 镜像被别人擦掉时，该 workspace 的候选从 ~43 掉到 ~6（掉 37 条）—— **不是归零**\n （我先前写成 37→0，是漏了来源1；数字口径缺口径，已更正）\n```\n\n## 三个曾被提出、但已被推翻的根因（留作反面材料）\n```\n① 「读域 vs 擦除域不等，且 [] 是 truthy」——只解释 5 个 0 会话 project（实测 45 次里 9 次空），\n 非主因（非空替换占 36/45 = 80%）\n② 「PK 允许并集 ⇒ 擦除在语义上不必要」——**错**。整表替换是**有意设计**且有测试钉着:\n `server/internal/repo/platform_sessions_test.go:219` `TestReplacePlatformSessionsIsFullReplace`\n ＋ 函数文档 :44-46 明写要防「平台删了会话却留在镜像 ⇒ 选了 404」\n ⇒ 擦除**必要**，错的是**范围**（应 per-source replace，即「擦的域 == 读的域」）\n③ 「今天不撞 PK 是因为 session.id 全局唯一」——**因给错了**。实测: 同一 platform_id 换 workspace\n **也不撞**（err=nil）⇒ 真正的原因是两处**代码结构**:\n · 跨调用: `DELETE WHERE agent_name=$1` 先清该 agent 全部行（:63）\n · 同调用内: `seen` map 去重（:70）\n 与 id 是否唯一无关 ⇒ 「数据性质 vs 约束」那个框架本身对，载体是这两处代码。\n```\n\n## 为什么这条值得进登记（而不是只留在信里）\n```\n它是一个**已定性的、带顺序约束的**修法前提: 不是「顺手改一下」，而是\n「先改 PK、再改 DELETE，否则新的写法会从间歇擦除变成**永不自愈的静默停滞**」——\n而后者没有报错、没有日志、桥也不读响应（三重静默），下一个人只会看到「补全里少了会话」。\n★ 该断言的形状（而非点名三笔）已在 debt_registry_test.go 里确立，故新增条目不触碰既有断言。\n```\n\n\n## ★★ 补记（2026-09-26 我实测，三条）\n```\n① `:395` 的歧义**今天就可达，且与 PK 改动无关**: 造两个 agent（opencode/homeagent）上报**同一**\n platform_id（workspace 可以不同、也可以相同）⇒ 该 JOIN 出 **2 行**，\n PlatformSessionFor 返回 owner=**homeagent**，而那条会话是 **opencode** 接管的 ⇒ **取错归属**。\n ⇒ 所以它不是\"改 PK 的副作用\"，是**既存缺陷**（只是今天生产数据里跨 agent 的 platform_id 交集=0，\n 所以没显形 —— 又一个\"当前干净是数据性质、非约束\"）。\n② pi 建议的修法「JOIN 加 workspace」**不完整**:\n 场景A 跨 agent + **不同** workspace ⇒ 1 行 ✓ 修好\n 场景B 跨 agent + **相同** workspace ⇒ **2 行** ✗ 仍歧义（我实测）\n③ 正确的消歧键是 **agent 身份**，不是 workspace: `JOIN ... AND aps.agent_name = s.from_agent`\n ⇒ 1 行 ✓。而 `sessions.from_agent` 由 `AdoptPlatformSession → CreateSession(ctx, nil, agentName, …)`\n 写入（repo.go:260 的第 2 个形参）⇒ **接管路径上结构性地非空**（生产库实测: 接管会话里\n from_agent<>'' = 9 条、=0 条 ⇒ 无空值）。\n⇒ ★ 结论: 这条欠账的伴随项**不止** PK + DELETE + JOIN-加-workspace，\n 而是「**PK 加 workspace（保 (agent,ws,pid) 唯一）+ DELETE 加 workspace + :395 的 JOIN 按 agent 消歧**」\n 三处**必须同批**改；漏掉第三处 ⇒ 出现\"取错归属 ⇒ 邮件静默消失\"（比候选少一条更重）。\n```\n\n\n## ★★ 补记之二（2026-09-26 我实测：③ 的键写全 + ④ 迁移静默失效）\n```\n③ 的键必须写**两把**: 我原写「按 agent 消歧」（`aps.agent_name = s.from_agent`）——\n ★ pi 造出场景C 反驳，我实测**成立**:\n 场景A 跨 agent + 不同 ws ⇒ 三键皆 1 行 ✓\n 场景B 跨 agent + 同 ws ⇒ 按 ws 2 行 ✗ / 按 agent 1 行 ✓ / 两把 1 行 ✓\n 场景C 同 agent + 同 id + 两 ws（**未来态**，PK 加 ws 后合法）⇒ 按 agent **2 行** ✗ / 两把 1 行 ✓\n （我造这张两行的表: 今天插第二行报 `UNIQUE ... (agent_name, platform_id)` 1555 ⇒ 场景C 今天不可达）\n ⇒ 结论订正: 正确键 = `aps.agent_name = s.from_agent AND aps.workspace = s.workspace`，\n 且 `sessions.workspace` **列已存在**（sqliteAddColumns 补的），生产实测: 有 platform_id 的会话 9 条\n ⇒ workspace 非空 **9/9**、与 aps 一致 **6/6**（另 3 条镜像无此 id）⇒ 第三把键**不需要新加数据**。\n ★ 另: 我一度提出用 `ORDER BY (aps.agent_name = s.from_agent) DESC LIMIT 1` 替代\"谓词入 ON\"，\n 实测**更差**: 场景E（本侧由 e2 接管、镜像同名 id 只剩 e1 那行）下 ORDER BY 取到 **e1**（错），\n 而谓词入 ON 得 NULL ⇒ 退回 `from_agent`=e2（对，与文档 :388-390「镜像没有则退回 from_agent」一致）。\n ⇒ 所以 pi 的「谓词入 ON」形态是**对的**，我的排序键想法**撤回**。\n\n④ ★★ 改 PK 这一步在**已部署库上静默不生效**（本回合最重的发现，实测四环）:\n ① `CREATE TABLE IF NOT EXISTS`（init_sqlite.sql:407 / init.sql:371）对**已存在**的表**整条跳过**\n ② `migrate.go:33-40` 每次启动逐条重跑 init DDL（`cmd/server/main.go:39/48`）；\n `addMissingColumns`(:365) 只补列、不碰约束 ⇒ 补不了 PK\n ③ 实测复现: 按旧 PK 建库 → 重跑含新 PK 的 DDL ⇒ **rc=0、无报错**，\n `sqlite_master` 里 PK **仍是旧的** → 再插「同 id 不同 ws」第二行 ⇒ **仍报 1555**\n ④ 而测试库走 `t.TempDir()` + `Migrate` ⇒ **每次全新建表** ⇒ 新 PK 生效 ⇒ **测试全绿**；\n 且全仓**无任何** schema/PK 断言（`sqlite_master`/`table_info` 查询 grep=0）\n ⇒ ★★ 于是「改完 DDL、测试全绿、生产没变」是**完全静默**的:\n 生产上 ②DELETE 加 workspace 会删对、③JOIN 双键会写对，但 ①PK 没变 ⇒\n 同 id 跨 ws 的 INSERT 仍撞 1555 + 无 ON CONFLICT + `defer tx.Rollback()` ⇒\n **整个事务回滚** ⇒ 心跳持续「成功」而镜像**永不再更新**\n —— 比现在的间歇擦除更糟（旧内容看起来正常，且三重静默都不响）。\n ⇒ 治法: 迁移必须是**显式重建表**（建新表含新 PK → INSERT SELECT 拷贝 → DROP 旧 → RENAME），\n 并配一条**断言实际 PK 的判据**（查 sqlite_master / PG information_schema）——\n 因为今天没有任何判据能发现「PK 没换成」。\n```\n\n## ★★ 补记之三（2026-09-26 我实测：④ 的两个伴随项 —— 索引 + 判据的落点）\n```\n(i) 重建表会丢具名索引（pi `b9c7308c` 提出，我独立复现）:\n 重建序列 新表→INSERT SELECT→DROP→RENAME ⇒ 功能对（PK 真换了）**但**:\n 重建前: sqlite_autoindex_aps_1, **idx_platform_sessions_ws**\n 重建后: sqlite_autoindex_aps_1 ← 具名的**没了**（RENAME 不带回）\n 该索引正是本条的基石之一（\"设计本来就是 per-workspace\"）:\n `init_sqlite.sql:424 CREATE INDEX IF NOT EXISTS idx_platform_sessions_ws\n ON agent_platform_sessions(agent_name, workspace);`（PG 侧 :383 同名）\n ⇒ 补救有现成条件: migrate **每次启动逐条重跑整份 init DDL**，而这条 `CREATE INDEX IF NOT EXISTS`\n 与建表同批 ⇒ 只要**重建发生在这批 DDL 之前**，索引当场补回；若在之后，则要等**下次启动**。\n 我实测两个顺序: 重建在 DDL **之后** ⇒ 本次启动内索引缺失（窗口 = 进程余生）；\n 重建在 DDL **之前** ⇒ 索引正常。\n ⇒ ④ 的措辞必须包含「重建具名索引（或保证与 `CREATE INDEX` 的先后）」——\n 又一个**顺序依赖**（与本身 :63/:79 的 PK-先于-DELETE 同族）。\n(ii) 判据长在哪里才有效（pi 提出，我复核）:\n · 常规测试（`setupTestDB` → `t.TempDir()` + `Migrate` = **全新建库**）里断言 PK ⇒ **必然绿** ⇒ 抓不到生产\n · 只有「**旧库 → Migrate → 断言实际 PK**」这种**迁移路径**测试才抓得到（pi 实测: 旧 PK 库 ⇒ 断言红）\n · 更便宜的补充: **启动自检** —— 生产启动时查 `sqlite_master`，PK 不含 workspace 而代码期望它含则**拒启/告警**\n （不需要测试基础设施，且**生产上会响**，而测试永远不覆盖已部署库）\n ⇒ 所以 ④ 的判据应是**两条并列**: (a) 迁移路径断言实际 PK；(b) 断言 `idx_platform_sessions_ws` 存在。\n (b) 今天就能建、不需要新机制。\n```\n\n## ★★ 补记之四（2026-09-26 我实测：危害的机制是\"抵达次序\"，不是\"心跳频率\"，并补语义约束）\n```\n★ 订正一处流传的因果（pi `c790a69c` 提出\"每个 project 心跳频率不同\"，我实测**否证**）:\n ① 各状态**复现间隔全部 = 30.01s**（= `index.js:1243 setInterval(beat,30000)`）\n ⇒ 若某 project 心跳更频繁，其复现间隔应**更短** —— 实测九种状态**无一例外**都是 30.01s\n ② **相位固定**: 三轮 30s 窗口内，抵达次序与相对偏移**逐轮重合**\n （(无行)→/tmp→/root→am-mcp-probe→…→agentmail，每轮同序）\n ③ 驻留时长**相差 30 倍**（agentmail 中位 10.86s vs facemodule 0.30s），而复现间隔**全等**\n ⇒ ★ 真机制 = 各上报者**周期相同**、相位错开、在 ~15s 内**挤成一串**抵达，\n 之后 ~6–15s **静默** ⇒ **最后一个抵达者独占静默间隙**（last-writer-holds）\n ⇒ 某 workspace 的**可观测占比由\"抵达次序\"决定**，不由频率决定。\n ⇒ ★ 这让危害**更重而非更轻**: 次序固定 ⇒ 是**稳定偏置**（agentmail 长采样 = 候选为 0 占 **63.9%**），\n 不像随机间歇那样会被平均掉 ⇒ 与\"间歇擦除\"的印象一致，但它是**稳定偏置**。\n （附: `/tmp/am-mcp-probe` 不是我们的调试动作 → 它是 `opencode.db` 里 **23 条 09-19 的会话**\n —— 标题含\"创建 /tmp/am-mcp-probe 控制文件\"，属**他人早先探针遗留**。）\n\n★ 修法 A 落地时**必须同时定住三条语义**（`[]` 今天把 ① 与 ② 混在一起）:\n ① \"**本目录**没有会话\" ⇒ 允许，载荷 `[]` ⇒ 只清**自己那个 workspace**\n ② \"**本 agent** 没有会话\" ⇒ **今天没有任何上报者该有权说**（若要说得显式声明代表全体）\n ③ \"**我看不到**（list 失败）\" ⇒ 必须继续走\"**省略该字段**\"，**不得**降级成 `[]`\n ★ ③ 这一条不可省: 桥侧 `index.js:1144-1156` 现在是\"异常 ⇒ 返回 undefined ⇒ 省略字段\"（正确），\n 一旦改成 `[]`，\"一次 list 失败\"就会把该 workspace 的 37 行清成 0，\n 而下游只看\"候选少了\"，**看不出那是读取失败** ⇒ 与缺陷本身同型的静默。\n\n## ★★★ 补记之五（2026-09-26 我实测：重建的非原子路径 —— 静默丢 37 行的**可达**形态；以及 pi 两条理由的订正）\n```\npi `5f3eb02d` 把 ④ 当实现写时撞出三陷阱。我逐条复核 ⇒ **风险成立**，但**两条理由需订正**:\n```\n\n### 一 ★★★ 陷阱1/3 **成立且可达**（我实测复现，用真表名）\n```\n形态: 若把重建写成 DDL 里 **4 条无 BEGIN 的语句**（`migrate` 是**逐条 Exec**，`migrate.go:33` 注释明写\n \"modernc 不接受多语句\" ⇒ 每条**各自 auto-commit**），在 `DROP TABLE` 之后崩溃:\n ⇒ 我实测（`db` 包内真库）: `agent_platform_sessions` 行=**0**、`agent_platform_sessions_new` 行=**3**\n ⇒ 次日启动: DDL 的 `CREATE TABLE IF NOT EXISTS` **建出空的新 PK 表** + `CREATE INDEX IF NOT EXISTS` 补索引\n ⇒ 守卫查\"PK 是否已含 workspace\" ⇒ **答\"是\"** ⇒ **跳过重建** ⇒ 数据**永远**躺在 `_new` 里\n ⇒ ★★★ 判据 (a)(b) **全绿**: (a) PK = `agent_name+workspace+platform_id+` ✓ ; (b) `idx_platform_sessions_ws` 存在 ✓\n ⇒ **而镜像行数 = 0**（真实 37 行数据在 `_new` 里）⇒ **(a)(b) 抓不到这个形态** ⇒ pi 的 (c) **必要** ✓\n ⇒ ⇒ 所以 ④ 的判据必须是 **(a) 迁移路径断言 PK + (b) 断言索引存在 + (c) 断言无 `<表>_new` 残留**。\n```\n### 二 ★★ 但 pi 的两条**理由**要订正（结论对、机制错）\n```\n① pi: \"migrate 逐条 Exec ⇒ SQL 里 BEGIN **不生效**，所以必须用 Go 层 BeginTx\"\n ⇒ ★ 我实测 **BEGIN 生效**: `BEGIN`→`DROP`→`ROLLBACK` ⇒ 表**回来了**（行数不变）; 连**崩溃**（未 COMMIT 直接 Close）\n 后再打开 ⇒ `aps` **2 行完好、`_new` 不存在** ⇒ SQLite **回滚了未提交的 DROP**。\n ⇒ 真因: 本仓 SQLite 走 **`SetMaxOpenConns(1)`**（`db.go:91`）+ `Migrate` 用裸 `DB.ExecContext`\n ⇒ 池里只有**一条**连接 ⇒ 裸 `BEGIN` 恰好落在同一连接上 ⇒ **能用**。\n ⇒ ★ 但这**是巧合、不是保证**: 连接数只要 >1（**PG 分支就是 20**，`db.go:85`）、或哪天有人调这个\"无关旋钮\"，\n 跨连接的 `BEGIN` 就**不再构成事务** ⇒ 与 Postgres 下 `DO $$…$$` 要整体提交（`migrate.go:24-28`）是同一个坑。\n ⇒ **结论**: 用 Go 层 `BeginTx` **对**（显式、不依赖池大小）；但**理由**应写成\n \"**裸 BEGIN 的正确性依赖 MaxOpenConns(1)**\"，而不是\"BEGIN 不生效\"。\n② pi: \"守卫不能用字符串 LIKE（我写的 `'…PRIMARY KEY (…'` 带空格，而**实际无空格**）\"\n ⇒ ★ 我实测本仓实际文本是 `PRIMARY KEY (agent_name, platform_id)` —— **有**空格。\n ⇒ 它失配的**真因**是**它模式里 `,` 后少了空格**（`'…agent_name,workspace%'` vs 实际 `'…agent_name, workspace'`）\n ⇒ 我两种模式都试: 无空格模式**不命中**、带空格模式**命中**。\n ⇒ ⇒ 结论（该用 `pragma_table_info` 的 pk 列）**对**，但理由应写成\n \"**LIKE 依赖 DDL 的空白/换行/引号形态，任一变即失配**\"（它这封自己也点到了同族坑）——\n 而不是\"实际文本无空格\"（那是把**自己模式的错**归给了**被匹配的文本**）。\n```\n### 三 ✅ pi 自撤的那条**我也复核为真**\n```\n它撤回: \"第二次 Migrate 会撞 PK 崩溃\" ⇒ ★ 我实测 4 语句版**天然幂等**: run1/2/3 均 rc=0、行数不变\n （因 `RENAME aps_new→aps` 后 `aps_new` 名字**又空出来**）⇒ 撤回**正确** ✓\n★ 真正的崩点是**陷阱1**（DROP 与 RENAME 之间崩），不是\"第二次 Migrate\" ⇒ 与 pi 一致。\n```\n### 四 ★ 两条我复核的附带事实（都成立）\n```\n· `main.go` **两次** `db.Migrate`（:39 / :48）⇒ 重建**必须幂等** ✓\n· 全仓 `REFERENCES agent_platform_sessions` = **0** ⇒ 重建**不需要**处理 FK ✓\n （`PRAGMA foreign_keys` 在事务内本就是 no-op ⇒ 也不必碰）\n· `migrate` 内**无**任何 `RENAME TO`/`DROP TABLE`/`_new` ⇒ 今天**没有**重建代码（与我早前结论一致）✓\n```\n### 五 ★ 于是 ④ 的最终措辞（含 pi §四 的\"顺序依赖可消掉\"）\n```\n④ = 用 **Go 层事务**重建表（`BeginTx`→新表→`INSERT SELECT`→`DROP`→`RENAME`→**同事务内显式重建\n `idx_platform_sessions_ws`**）；守卫用 `pragma_table_info` 的 pk 列；并处理孤儿 `<表>_new`。\n ⇒ ★ 在**同一事务内**重建索引 ⇒ 与 DDL 批次的前后**无关** ⇒ **顺序依赖消失**（pi 这点对，我收）\n ⇒ 判据 (a) 迁移路径断言 PK、(b) 断言索引存在、**(c) 断言无 `<表>_new` 残留**。\n ★ 其中 (c) 是**必需**而非可选 —— 否则 §一 那个\"37 行静默消失\"的形态**无人发现**（我实测 (a)(b) 全绿）。\n```\n\n## ★★★ 补记之七（2026-09-26 我实测：④ 缺的第四块 —— \"**正常态**丢数据\" ⇒ 加判据 **(d)** 与治本项）\n```\npi `48c2c4c9`（03:03）报了这个缺口，我**独立复核成立**，且把它的根因查到**结构层**。\n三陷阱（⑤′）管的是\"**崩溃态**\"丢数据；这条管的是\"**正常态**\"丢数据 ——\n无崩溃、无报错、无残留 ⇒ ★ (a)(b)(c) **三条判据全绿**而数据仍丢。这是 ④ 定稿前唯一还缺的一块。\n```\n### 一 缺口：空列表上报时，`$2`（workspace）**无定义**\n```\n`ReplacePlatformSessions(ctx, agentName string, list []PlatformSession)`（platform_sessions.go:47）\n ⇒ 签名里**没有** workspace 参数！workspace **逐行**来自 `ps.Workspace`（:81 INSERT 的 $3）\n★ `heartbeatRequest`（agents.go:13-46）实测**无任何请求级 workspace 字段**:\n name / secret / platform / platform_sessions / models / mode_enforcement\n ⇒ ★★ 所以\"这次上报是替**哪个目录**报的\"这件事，**协议上不存在** ——\n 它只能从 list 里**行**反推。而 `list` 为 `[]` 时 ⇒ **一行都没有** ⇒ 无从反推。\n★ 于是 pi 的 `DELETE … WHERE agent_name=$1 AND workspace=$2` 在 `[]` 时 **$2 取不到值**:\n 取 '' ⇒ 清不掉任何真 workspace（**报 [] 清不掉 ⇒ 镜像残留**）\n 取全部 ⇒ 退化成今天 agent 级全擦（**正是要修的 bug**）\n 取\"上一次的值\" ⇒ 引入状态，且多实例共享 agent_name ⇒ 又互相覆盖\n ⇒ ★ 三步都不成立 ⇒ **这不是\"加个参数\"能修的，是协议缺字段**。\n```\n### 二 ★ 深度：`[]` 的三种语义里，**②\"这个 agent 没会话\"今天没有任何报告者有权说**\n```\n我此前已定三条语义（补记之五）：① 这个目录没有会话（合法）② 这个 agent 没有会话（**今天无人有权**）\n ③ 我看不到（必须**省略字段**，不许退化成 `[]`）\n★ 而缺口正是 ① 与 ③ 在**同一条 wire** 上无法区分:\n 桥侧实测（index.js:1144-1156）: 成功且空 ⇒ `[]`（语义①）; 异常 ⇒ `undefined` ⇒ 省略字段（语义③）\n ⇒ 桥**已经**区分了。丢的是**服务端的第二次区分**:\n 服务端拿到 `[]`，**无法知道它属于哪个 workspace** ⇒ 语义① 落地时缺主语。\n ⇒ ★★ 所以治本项不是\"给桥加字段\"，而是 **\"请求级 scope 字段\"**（pi 的提法，我同意）:\n 上报时**显式**声明\"本次快照属于哪个 workspace\" ⇒ 语义① 有了主语、`$2` 有了定义、\n 且 DELETE 域 == 上报域（正是补记之三/四那条原则在**正常态**下的形态）。\n```\n### 三 我复核 pi 的支撑数据（逐条实测）\n```\n· opencode `project`: **13 行 / 11 个不重复 worktree**（`/home/program/EcoArk` 与 `/` 各有**两行**）\n 逐行 0 会话的 = **3 行**（`RCON_for_HarmonyOS`、`graph_enable_ability`、`EcoArk` 的**那一行**）\n 而按 **worktree 汇总**后 0 会话的 = **2 个**（RCON_for_HarmonyOS、graph_enable_ability）\n —— 因为 EcoArk 的另一行有 13 个会话（同目录拆成两个 project 行；`/` 亦同: 111+132=243）\n ⇒ ★ pi 说\"**2 个合法空目录**在报 `[]`\"**成立** ✓（worktree 口径）\n ★ 教训: \"几个空目录\"这句里**聚合口径变了答案就变**（行=3 / worktree=2）——\n 本仓 ⑦ 那条（集合差要分 |A\\B| 与 |B\\A|）的同类: 报数必须带**聚合键**。\n· 且镜像表实测有 **90 个不同的 (agent, workspace) 组合** ⇒ 多目录上报**是常态**，不是边角\n ⇒ ★ 即\"空目录报 `[]`\"**今天就会发生**，不是未来态。\n```\n### 四 定稿: ④ 的判据从三条加到**四条**\n```\n(a) 迁移路径的 PK 断言（旧库 → Migrate → 断 PK）\n(b) 命名索引 `idx_platform_sessions_ws` 存在\n(c) **无 `
_new` 残留**\n(d) ★★ **空列表上报不得丢数据**: 对\"某 workspace 下合法的 0 会话\"上报 `[]` ⇒\n 断言 ① 该 workspace 的行被清空（语义①生效）**且** ② **其他 workspace 的行数不变**\n ⇒ ★ 这条判据必须**同时**断言两半: 只断\"其他不变\"会漏掉\"该清的没清\"（残留）；\n 只断\"该清被清\"会漏掉\"别人被误擦\"（就是本 bug）⇒ 两边都断才咬得住。\n★ 治本项（登记为 ④ 的一部分，不是另立一笔）: **请求级 scope 字段** —— 桥在上报里显式带\n \"本次快照所属 workspace\"；服务端 DELETE 用它做第二把键。\n ★★ 登记方式（关键，否则会造出一条**永久红**判据）:\n (d) 的**到期前提就是治本项落地** —— 协议上今天拿不到 $2，所以 (d) **现在无法写**。\n 按本仓惯例（`due` = 什么时候该还清，见 `docs/DEBTS.json` 头部与 Go `debt.Due`）:\n `due` = 「**请求级 scope 字段**落地时，(d) 判据同时建」\n ⇒ 而不是\"现在就把 (d) 写成一条红的判据\"。本仓已记过这个坑:\n 硬编码/超前断言与事实矛盾 ⇒ \"还清了反而红\"（`gesture-semantics` 那次）。\n 所以 (d) 与治本项**同时登记、按同一前提到期**，两者是同一件事的两面。\n\n## ★★★ 补记之八（2026-09-26 **活库实测**: 这条缺陷此刻正在发生，且逐秒可量）\n```\npi `3f482574` 把范围收窄成\"只有 opencode 有本 bug\"（上报域≠替换域），我复核**成立**，\n并把它从\"代码层推断\"变成\"**活库直读**\"。这是本条登记以来第一次**当场量到它**（此前都是复现/推断）。\n```\n### 一 缺陷的**瞬时形态**（200 样本 × 0.3s，2026-09-26 03:5x）\n```\nopencode 镜像: 任一瞬间**只持有 1 个目录**（瞬时含多个不同 workspace 的样本 = **0/200**）\n 但 opencode **自己的库**里 `session.directory` 不重复值 = **26 个**\n ⇒ ★ 26 个目录**轮流出场**，每次心跳把上一个**整批擦掉**\n实测序列（90 样本 × 1s）: 0 行占 **24/90**；非空样本里出现过 **9 个不同目录**；变化 27 次\n · → 0 行 = **7 次**\n · 非空 → 非空（换成另一个目录）= **13 次** ← ★ 见 §三\n0.3s 采样（200 样本）: 0 行 **25%**；最长连续 0 段 = 17 样本 ≈ **5.1s**\n 各目录占比: agentmail 36% / am-mcp-probe 22% / tmp 4% / llmsproxy 4% / root 3% / 其余各 1~2%\n ⇒ ★ 对**读**的人来说: 他要的那个目录在镜像里存在的概率 ≈ 它自己的占比\n ⇒ 除最常出场那个外，**其余 8 个目录大概率读到 0**（与补记之五的 63.9% 同源）\n★ 对照（单上报者，无此病）: pi ws=**63** / rows=150；dsh ws=**25** / rows=77\n ⇒ 它们一次报**全部** ws ⇒ 上报域 == 替换域 ⇒ 擦掉后立刻全量重建 ⇒ 无损 ✓\n```\n### 二 范围定稿（pi 的结构层，我复核成立）\n```\n本 bug 的**充要形状**: **上报域 ⊊ 替换域**（一个 agent 有多个上报者，各报一部分）\n · opencode: 插件按 `directory` 实例化（index.js:1102-1103 `mailBridge(input)` 取 `input.directory`），\n 每实例 `client.session.list({query:{directory}})`（:1145-1147）只报**自己那一个目录**，\n 而 `AGENT_NAME` 是**单一常量**（:49，`/etc/agentmail/opencode.env:3` = `opencode`）\n ⇒ **上报域(1 目录) ⊊ 替换域(整个 agent)** ⇒ `[]` 时无从反推 ⇒ 本 bug ✓\n · pi: 单进程 `sessionScanner.scan()` 扫 `join(getAgentDir(),'sessions')`（worker.mjs:384-387）\n · dsh: `collectSessions()`（index.ts:413）一次收全\n ⇒ 两者**上报域 == 替换域** ⇒ `[]` 语义为真（\"我确实一条都没有\"）⇒ **无此病** ✓\n★ 所以 (d) 的适用范围写明: \"**一个 agent 多个上报者**\"；并把\n \"**pi 若改成按目录实例化，立刻获得同一个 bug**\"记为已知风险（今天它 63 ws 单上报者，安全）。\n```\n### 三 ★★ 对 pi §六 探测器的一处**必要收窄**（`len(list)==0` 只是两种形态之一）\n```\npi 提议: `ReplacePlatformSessions` 里 DELETE 前 `if len(list)==0 && before>0 ⇒ WARN`\n★ 我实测: 那只覆盖**一种**形态。活库里更常见的是**非空→非空**（换成另一个目录）:\n 90s 采样 27 次变化中，→0 行 7 次、**非空→非空 13 次** ⇒ ★ pi 的探测器**抓不到那 13 次**\n （报 23 行的那次心跳，`len(list)=23≠0` ⇒ 不告警 ⇒ 而它把 37 行的目录**整批擦掉**了）\n⇒ ★ 忠实于**机制**（域不匹配）的探测器应当**比域**，而不是比\"是否为空\":\n 取 `list` 里出现过的 workspace 集合 L，取表里当前 `WHERE agent_name=$1` 的 workspace 集合 T;\n **凡 T 中 ws 不在 L 里** ⇒ 该 ws 的行**即将被销毁** ⇒ WARN（附该 ws 的行数）\n ⇒ 这同时覆盖 ① `[]`（L=∅ ⇒ T 全中）与 ② 换成另一个目录（L={B} ⇒ T 中的 A 命中）\n ★ 关键差别: pi 的版本量的是\"**这次报了多少**\"，我的版本量的是\"**谁即将没有**\"——\n 后者才是读侧真正会感到的那件事（而读侧正是本 bug 的受害者）。\n```\n\n## ★★★★★ 补记之九（2026-09-26 仓内真驱动实测: **(d) 要拆 d1/d2**；我提的 `T\\L` 探测器**修好后必假阳**）\n```\npi `e77154d1` §二/§三 的两问，我**不只推理、写了仓内探针逐条跑**（跑完即删）。四条读数:\n [修前] 播下 /A=2 → B 上报 /B=1 ⇒ (d1) FAIL: /A = 0，期望 2（其它 ws 被误擦） ★本缺陷\n [修前] T\\L @DELETE前 = [/A] ⇒ 响 ✓（我那个形状**确实抓得到**真缺陷）\n [修好] 共存 /A=2 /B=2 → 之后 /A 仍=2 ⇒ (d1) PASS ⇒ **d1 修好即绿** ✓\n [修好] T\\L @DELETE前 = [/A] ⇒ ★ **假阳**：修好后每次心跳都常鸣\n [修好] 与\"实际删除域\"比 destroyed = [] ⇒ 不响 ✓ 无假阳\n```\n### 一★★ `T\\L ⇒ WARN` 这个形状**不可用**（我撤回 §三 提的那个）\n```\n根因: \"即将被销毁\"是 **DELETE 的谓词**决定的，不是 `T\\L` 决定的。\n 修前 DELETE 域 = 整个 agent ⊋ L ⇒ T\\L 恰好等于被销毁集合 ⇒ 碰巧对\n 修后 DELETE 域 = **按 ws 删** = L ⇒ 被销毁 = ∅，而 T\\L 仍 = T\\L ≠ ∅ ⇒ **恒假阳**\n⇒ ★ 修好后表里**天然共存多 ws**（那正是修复的目标）⇒ `T\\L` 每次心跳非空 ⇒ **常鸣**\n⇒ ⇒ 这就落进本仓记过的坑「**还清了反而红**」（`gesture-semantics` 同族）——\n 我为 (d) 拒绝超前断言的理由（永久红让整条余额失去信号），**在我自己提的形状里以假阳形式复现了**\n⇒ 忠实形状（pi 的）: `destroyed = { 被本次 DELETE 移除、且未被本次 list 重插的 ws }`\n ⇒ 它**与实际删除域同源**，修前响、修后不响，且 `[]` 时 L=∅ ⇒ 整表都算 destroyed ⇒ 仍覆盖空列表 ✓\n```\n### 二★★★★ `(d)` 必须**拆成 d1 / d2** —— 我\"整体归入 due\"是**反方向的错**\n```\n· **d1**: 上报**非空** list 时，不得删除其它 workspace 的行\n 今天就能写（每项都带 `workspace`，**不需要请求级字段**）／现在就是红（就是本缺陷）／修好即绿 ✓\n ⇒ ★ 应当**现在就建**，不该进 due\n· **d2**: 上报 **`[]`** 时，只清自己那个 ws（其它 ws 行数不变）\n 需要\"这次上报属于谁\" ⇒ **与 scope 字段同一前提到期** ✓（我原来的判断只对 d2 成立）\n★ 我上封把 d1 也归入 due，是「**超前断言**」的**反面错**:\n 把**今天就能给的判据**当成\"要等未来才能给\" ⇒ 余额里白白挂着一个**今天就能变绿**的缺口。\n 两者都让余额失去信号（一个假红、一个白欠）⇒ 判据的**可得性**本身要复核。\n★ d1 的形状（照 pi 的复现，我照抄并加了对拍）:\n 播下 /A 两行 → 另一个上报者报 /B（list 带 workspace，len=1≠0）→ 断言 /A 行数**仍为 2**\n 修前 FAIL(/A=0)、修后 PASS ⇒ **可判、现在红、修好绿** ✓\n```\n### 三★ 我自己的探针写错过一次（形状错、结论会全反）—— 记下来\n```\n我第一版把「取 T」那行写在了 `ReplacePlatformSessions` **之后** ⇒ 取到的是**删除后**的表\n⇒ 于是\"修前 T\\L\"算成 ∅（我据此差点得出\"我那形状漏报\"的**相反**结论）\n⇒ 修正（把取 T 排到 B 上报**之前**）后: 修前 T\\L = [/A] ⇒ **响** ✓\n★ 教训: **观测点必须与被观测的判据在同一时刻**。\n 探测器装在 DELETE 之前、观测却在 DELETE 之后 ⇒ 量的是**结果**不是**触发条件**。\n 与我此前\"判据要锚定到它防的那个动作\"是同一条，只是这次踩在**自己**的探针上。\n\"\"\"\n\n## ★★★★★ 补记之十（2026-09-27 pi `b9c7308c` 指出，我**实测复现并加重**: 重建表会**静默丢掉** `idx_platform_sessions_ws`）\n```\npi 的指正: 具名索引随 `DROP TABLE` 消失、`RENAME` **不**带回 ⇒ ④ 需补\"重建具名索引 + 断言它存在\"。\n我实测（/tmp/idxtest，**先复现、再验仓库真实顺序**）:\n [裸 12 步] 建 _new → 拷贝 → DROP → RENAME\n 重建前索引 = idx_platform_sessions_ws ⇒ 重建后 = **（无）** ✓ pi 断言成立\n [顺序敏感] 重建在前、CREATE INDEX 在后 ⇒ **能**补回; 反之 ⇒ **补不回** ✓ pi 的\"依赖顺序\"也成立\n```\n### 一★★★ 但在**本仓真实顺序**下，那句 `CREATE INDEX IF NOT EXISTS` 是**空转、补不回**\n```\n`migrate.go:33-37`: 逐条 `Exec` 走完 **init DDL 全文**（含 `:424` 的 CREATE INDEX），\n **之后**才是任何自定义迁移（`addMissingColumns` 在 `:40` 也在这之后）\n⇒ ★ 真实时序: `CREATE INDEX IF NOT EXISTS`(空转，索引此刻还在) → **DROP** 把它带走 → RENAME\n⇒ 我按真实时序实测: 最终索引 = **（无）** ⇒ ★★ **补记之七 ④ 里的\"b: 索引存在\"这条判据会红** ——\n 而它红得**对**，红的原因是\"索引被迁移吞了\"，不是\"索引本来就没建\"。\n⚠️ 与我早先\"(c) 断言无 `_new` 残留\"同源: **DROP 之后的每一样东西都要重新核对**，\n 因为 RENAME 只搬**表**, 不搬**索引/触发器/外键**。\n```\n### 二★ 为什么这个索引是我们论证的**基石**（不是可选优化）\n```\n`:473-474` 的 JOIN 正是修复③要消歧的那一条:\n LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id AND ...\n⇒ 它按 **(agent_name, workspace)** 前缀组织的索引，服务的是修复后的按-ws 查询\n⇒ ★ 丢索引**不会**让功能出错，只会让每轮心跳的 DELETE/JOIN 退化成**全表扫描**\n ⇒ ★★ 这是**最坏的一类**后果: 没有任何报错、判据除\"索引存在\"外全绿、线上只是变慢\n ⇒ 与 `recount-relay-counts.sh` 那条同族: **静默劣化**比**响**更难发现。\n```\n### 三★★ 修复清单相应加两项（④ 之外）\n```\n④b **在重建之后**（不是之前）显式重建具名索引: `CREATE INDEX IF NOT EXISTS idx_platform_sessions_ws ...`\n ⇒ 因为 init DDL 的那句在**DROP 之前**已跑过、只是空转，**指望它兜底是错的**\n④c 判据 (b) 保留且**必须走迁移路径**（见补记之四 ⑤′: 全新建库必绿、不具判别力）\n★ 另: 若将来还有别的索引/触发器，**重建迁移必须自带一份清单** ——\n 正确形状不是\"记得补这一个\"，而是\"**迁移后逐项核对 schema 对象集合**\"。\n```\n\n## ★★★ 补记之十一（2026-09-27 pi §四 的第二问，我实测确认并给出**可执行的形状**）\n```\n### 一★★ \"PK 断言必须走迁移路径\"——确认，且我把**为什么**量化了\n 全新库: PK 来自 DDL 本身 ⇒ 断言**恒绿**、**零判别力**（/tmp/pktest/fresh.db 实测）\n 旧 库: 重跑同一份 DDL（`CREATE TABLE IF NOT EXISTS` 命中已存在表 ⇒ **原样跳过**）\n ⇒ PK 仍是 `PRIMARY KEY (agent_name, platform_id)`（/tmp/pktest/old.db 实测）\n⇒ ★ 两种情形**同一份断言、同一句通过/不通过**，差别只在**库怎么来的**\n ⇒ 所以判据必须**自己造一个旧库**（老 DDL 建表 → 灌行 → 跑迁移 → 断言），\n 否则它测的是\"DDL 文本对不对\"，而那件事永远成立。\n### 二★★ 线上现状（判据将要断言的那个对象，2026-09-27 04:0x 实测）\n PK 列 = `agent_name , platform_id` ← **仍是旧的**\n 索引 = `idx_platform_sessions_ws` ← 在（今天还没被任何重建吞掉）\n 行数 = 278\n⇒ 这正是\"改 DDL 对生产**静默无效**\"的现场: 文件里 PK 写什么，库里都不是那个。\n### 三★ 判据/自检该用哪种读法（两个都实测过）\n ✅ `pragma_table_info` 的 **`pk>0` 列按 pk 序号排序**后逐项比对:\n 旧库 ⇒ `agent_name, platform_id` 全新库 ⇒ `agent_name, workspace, platform_id`\n ✗ **`LIKE '%(agent_name, workspace, platform_id)%'`** 匹配 PK 文本:\n 在**旧库（PK 明知是错的）上不命中** ⇒ 判据会\"绿着一个错的库\"\n ⚠️ 且注意: `pragma` 给的 pk 顺序**可能与声明书写顺序不同**（`PRIMARY KEY (agent_name, platform_id, workspace)`\n 在 pragma 里就是 `agent_name, platform_id, workspace`）\n ⇒ **必须按 pk 序号排序后逐项比**，只比集合会漏掉次序差异。\n### 四★ 由此得到\"迁移后自检\"的最小形状（今天可写、现在**红**、修好即绿）\n 在 `Migrate` 末尾对 `agent_platform_sessions` 断言三样:\n ① `pk` 列（按序号）== (agent_name, workspace, platform_id)\n ② `idx_platform_sessions_ws` 存在\n ③ 无 `agent_platform_sessions_new` 残留\n ★ 与 (a)(b)(c) 的区别: (a)(b)(c) 是**测试**里断言（要自己造旧库才有判别力），\n 这一条是**启动路径上的自检** ⇒ **生产也会响** —— 否则缺陷在生产上永远不暴露\n （线上现在就是 PK 错的，而全部测试绿）\n\n## ★★★ 补记之十二（2026-09-27 pi `5f3eb02d` 陷阱② 我实测**方向相反** —— 而这个方向差会让人改错）\n```\npi 说: \"守卫不能用字符串 LIKE —— 我自己先写的 `'…PRIMARY KEY (…'` **带空格**，**实际无空格**\n ⇒ 重建成功后仍报'未重建'、每次启动重来\"\n⇒ ★★ 我实测: **方向反了**。`sqlite_master.sql` 是**逐字保留建表语句**的（不规范化空白）:\n 建 `PRIMARY KEY (a, b)` ⇒ 库里就是 `PRIMARY KEY (a, b)` → **带空格的 LIKE 命中**\n 建 `PRIMARY KEY(a, b)` ⇒ 库里就是 `PRIMARY KEY(a, b)` → 带空格的 LIKE **不命中**\n 线上实测: `agent_platform_sessions` 的 `PRIMARY KEY (agent_name, platform_id)` **带空格**、\n `LIKE '%PRIMARY KEY (agent_name, platform_id)%'` **命中 = 1** ✓\n ⇒ 且本仓 `init_sqlite.sql:421` 用的**就是**带空格写法（:328/:380/:389 同样）\n⇒ ★★ **陷阱本身是真的，但机制不是\"没有空格\"**，而是:\n **`LIKE` 的命中取决于**当初 DDL **怎么写**，而 DDL 写法不是不变量\n ⇒ 换句话说: 今天命中，换个书写风格（或另一次重建用了不同格式）就**不命中**\n ⇒ 所以正确结论与 pi 的**建议一致、理由不同**:\n **别用 LIKE，用 `pragma_table_info` 的 `pk>0` 列（按 pk 序号排序后逐项比）** ✓\n —— 但**不是**因为\"实际无空格\"，而是因为\"**匹配结果依赖书写风格**、因此不可移植\"。\n⚠️ 若照 pi 的理由去改（例如为了\"匹配无空格\"而把 DDL 改成紧凑写法）⇒ **恰好制造它描述的故障**:\n 改完 DDL 后老库的 `sqlite_master.sql` 仍是旧样式（IF NOT EXISTS 不会重写）⇒ LIKE 反而不命中了。\n ⇒ ★ 这是本轮最值得记的一条: **正确的结论 + 错误的理由 ⇒ 会导出错误的动作**。\n （与 `4b4dd2c7` 那条同族: 理由错 ⇒ 动作错; 这次是**我差点按错误理由去改**。）\n\n## ★★★★ 补记之十三（2026-09-27 pi `5f3eb02d` 陷阱① 我**独立复现**成立，并**实测验证了修法**）\n```\n### 陷阱① 复现（模拟逐条 auto-commit，崩在 DROP 之后、RENAME 之前）—— **完全成立**\n 播下 aps 行数=1\n 建 _new → 拷贝 → **DROP** ⇒ `aps` 存在?=**0**、`aps_new` 行数=1（行还在，但表没了）\n 下次启动: init DDL 的 `CREATE TABLE IF NOT EXISTS aps(新PK)` ⇒ 建出**空表**\n ⇒ 实测 `aps` 行数 = **0**（线上就是 37 行）、`aps_new` 残留 = **1**\n ⇒ 守卫只看 PK ⇒ 此时 PK **已正确** ⇒ **跳过重建** ⇒ ★ **永不自愈**\n ⇒ 而判据 (a)(b) 此时**全绿**（表在、PK 对、索引…随 DROP 一起没了才红）⇒ 绿着丢数据\n### ★★ 修法我实测跑通（不是纸面）\n 在**同一个 `BEGIN … COMMIT`** 内: 建 _new → 拷贝 → DROP → RENAME → **重建索引** ⇒\n 行数=**1**（保住）✓ 索引=**1**（补回）✓ `_new` 残留=**0** ✓ PK=**(a,b,w)** ✓\n ⇒ ★ 索引那条**必须写在 RENAME 之后、且在事务内** —— 写在 RENAME 之前会被 RENAME 后\n 的空转 `IF NOT EXISTS` 掩盖（补记之十 已证: init DDL 那句在 DROP **前**跑过、只是空转）\n⇒ ★★ 所以 pi 那条\"④ 应从『保证顺序』改成『**事务内显式重建索引**』\"我**采纳**:\n 顺序依赖被事务消掉，比依赖\"init DDL 恰好跑在重建前面\"稳健得多。\n⇒ ⚠️ 但**仅靠事务不够**: 事务防的是\"中途崩\"，防不了\"**上一版已经崩过**\"留下的孤儿 `_new`。\n ⇒ 故 ③（判据 c: 断言无 `aps_new` 残留）+ \"孤儿可恢复\"是**必需**的第二道。\n```\n\n## ★★★★★ 补记之十四（2026-09-27 pi `249fe29d` §三 的第三处 —— 我实测**成立且比它说的更重**）\n```\n### 一★ 它指的代码形状，我核对属实\n `platform_sessions.go:467` `PlatformSessionFor` 用 **`QueryRowContext`** + `:473-474` 的\n `LEFT JOIN agent_platform_sessions aps ON aps.platform_id = s.platform_id` ——\n **ON 子句只按 platform_id、不含 agent/workspace** ⇒ 多行时 **QueryRow 静默取第一行**。\n### 二★★ 我实测复现（/tmp/p3）\n aps 里同一 `ses_ABC` 挂 `pi` 与 `dsh` 两条 ⇒ 该 SQL 返回 **agent_name = dsh**\n ⇒ ★★ 而调用方是 **pi 的会话** ⇒ **归属方取错**、无报错、无告警\n### 三★★★★ 比 pi 说的更重的一层：**改 PK 不解决它，反而让它更易发生**\n 用**改后**的 PK `(agent_name, workspace, platform_id)` 建表实测:\n 同一 `(pi, ses_ABC)` 插**两个不同 workspace** ⇒ 都插得进（**这正是改 PK 的目的**）\n `:473` 的 JOIN 只按 platform_id ⇒ 匹配 **3 行** ⇒ QueryRow 仍取第一行\n ⇒ ★★★ 也就是说: 改 PK 之前，一 agent 一 platform 只能有**一个** workspace\n （旧 PK 把它压住了）⇒ 这条歧义**几乎触发不到**;\n 改 PK 之后**同一个 agent 的同一 platform 可以有多个 workspace** ⇒ 歧义**变成常态路径**\n ⇒ ★★ ⇒ **第三处必须与 PK 同批改**，且它**不是\"顺手带上\"** ——\n 不改的话，这次修复会把一条**今天几乎触发不到**的取错归属，升级成**天天可能触发**。\n### 四★★ 承重（为什么比候选列表更重）—— 我核了调用链\n `notify/mail.go:94` `platformID, platformOwner := repo.PlatformSessionFor(ctx, m.SessionID)`\n → `platformOwner` **直接决定这封信投给谁**（`:105-109`: platform_id 只发给归属方，\n owner 为空则**一律不下发**）\n → 而 `:90-93` 的注释记着**生产实测过的真实故障**: pi 的会话被推给 dsh ⇒ 邮件静默消失\n ⇒ ★ 所以取错 owner = **投错人 / 丢信**，且失败形状是**静默**（与 `ReleaseRelay`、\n `/tmp` 影子模块同族: 不报错、只是结果错了）\n ⇒ pi 说 `:205/:292` 两处**已按 workspace 限定、不受影响** —— 我核了，**属实** ✓\n### 五★★ 修法方向（只记形状，不代写）\n `:473` 的 ON 子句必须**同时**按 `(platform_id, agent_name, workspace)` 匹配，\n 而**这三个值从调用方传进来**（`notify/mail.go:94` 处 `m.SessionID` 之外还要带上收件方身份）\n ⇒ ⇒ 这就要求 `PlatformSessionFor` **改签名**（加 agent/workspace 参数），\n 它是**导出函数** ⇒ 调用点只有 2 处（`notify/mail.go:94`、`platform_sessions.go:444`）⇒ 改动面小 ✓\n### 五★★ ★ 自查: 我上面写的\"**循环依赖**\"是**错的**，我当场撤（pi 没提，是我加的）\n```\n我原本写: \":94 在收件人循环里 ⇒ 需先知道收件方身份 ⇒ 循环依赖\"\n★ 复核: `:94` 在 `Recipients` **函数顶部、只算一次**（CC 循环在 `:239`）⇒ **无循环** ⇒ 撤\n⇒ 但复核时暴露一个**更基础**的问题（我改标为**未解**，不假装已知）:\n `owner` 是**全局一个**的值，而一封邮件**可以有多个参与方**（`m.CC`）\n ⇒ 一次 `PlatformSessionFor` **根本表达不了\"这封信该投给谁\"** ——\n 它回答的是\"这条**会话**归属谁\"，而分发需要的是\"这封信对**每个参与方**各自是什么\"\n ⇒ ★ 二者不是同一个问题: 修好 JOIN 消歧只让\"会话归属\"变**确定**，\n 但\"多参与方各自该收到 platform_id 吗\"仍是**另一个未设计**的点\n ⇒ ⇒ 记为**未解**（标 unknown，不假装是已知的修法）\n\n## ★★★★★ 补记之十五（2026-09-27 pi `43d2c9dd` §三 —— 修法形状定稿：三键 vs 两键，我实测**两键才是唯一全场景解**）\n```\n### 一★★ pi 的场景C 我复现成立: 单键消歧**两个都不够**\n 场景C（同 agent + 同 platform_id + 两个 workspace = **改完 PK 的未来态**）:\n ① 只按 **agent** ⇒ **2 行** ⇒ QueryRow 仍取第一行 ⇒ ★ 歧义**仍在**\n ② 只按 **workspace** ⇒ 1 行（该场景下够）\n ⇒ ★⇒ 照\"按 agent 改\"会**在 PK 改完之后**踩到一个**新的**歧义（正是 pi 提醒的）\n### 二★★★★ 但我构造了 pi 没列的场景，结论反转: **只按 workspace 也不够**\n 场景D（**两个 agent 共用同一个 workspace**）: pi 与 dsh 同挂 `/shared`\n ① 只按 agent ⇒ 1 行\n ② 只按 **workspace** ⇒ ★ **2 行** ⇒ 歧义\n ③ agent + workspace 两把 ⇒ **1 行** ✓\n ⇒ ★★ 场景D **不是假想**: pi 与 dsh **确实共用** `/home/program/agentmail`（就是本会话的工作目录）\n ⇒ ★★⇒ **三键（platform_id, agent_name, workspace）才是唯一在 A/B/C/D 全场景恒为 1 行的键** ✓\n ⇒ pi 的结论（两把一起）**成立且是必要的**，我补的是\"为什么不能只留一把\"\n### 三★★ `sessions.workspace` 是否够用 —— pi 说\"已存在 9/9 非空\"，我实测**口径要写全**\n```\n 全表: workspace 非空 **51 / 79** ⇒ ★ **不是** 79/79（那 28 条空的**全都没有 platform_id**）\n 有 platform_id 的行: **9 / 9** 非空 ✓ ⇒ pi 的 9/9 是**这个子集**上的口径\n 与 aps 按 platform_id 可对齐: 6 行，其中 workspace **相同 6 / 6** ✓\n⇒ ★⇒ 对**要改的那条 JOIN** 而言 workspace **总是可用**（有 platform_id ⇒ 必有 workspace）✓\n ⇒ 且**不需要新加数据/迁移**，pi 这条成立。\n ⇒ ★ 教训（pi 这次没写全，是我没写全的镜像）: 同一句\"非空率\"若不写**分母**，\n 9/9 与 51/79 都能自称\"非空\" ⇒ 报比例**必须带分母定义**（与 ⑫′ 同源）\n### 四★★★★ ⇒ 必改点由**三处**增为**四处**（定稿形状）\n ① **PK** 改 `(agent_name, workspace, platform_id)`\n ② **DELETE**（`:63`）按 workspace 限定（`ReplacePlatformSessions` 加 workspace 形参）\n ③ **JOIN**（`:473-474`）**三键**：`ON aps.platform_id = s.platform_id\n AND aps.agent_name = s.from_agent AND aps.workspace = s.workspace`\n ⇒ ⚠️ 注意: 这要求 `sessions.from_agent` **非空** —— **已验**: 有 platform_id 的 9 行\n `from_agent` **9/9 非空** ✓（与 workspace 同为\"有 platform_id ⇒ 必非空\"）\n ④ **迁移重建表**（`BeginTx` 内 DROP+RENAME+**RENAME 后**重建 `idx_platform_sessions_ws`）\n ⇒ ★ ③ 是本轮新增的**第四处**，且它**必须**与 ① 同批: 单独改 ① 会把 ③ 的歧义**放大**（见场景C）\n### 五★★ 场景D 的**生产实证**（不是假想）—— 我在 `sessions` 表里找到了\n```\n `ba9c194b` pid=01a05a5e-8ab from_agent=[pi] ws=/home/program/agentmail\n `9742de96` pid=mail-ba9c194 from_agent=[dsh] ws=/home/program/agentmail ★ **同一 workspace，两个 agent**\n⇒ ★★ 这就是场景D 的现成实例: pi 与 dsh **已在生产里**共用 `/home/program/agentmail`\n ⇒ ⇒ \"只按 workspace 消歧\"会被这一对真实数据直接击穿 ⇒ **三键是必需的**，不是保守\n⇒ 顺带: `pid=mail-ba9c194` / `mail-8eb89cf` 这类 **platform_id 与 workspace 1:1** 的行，\n 说明 (platform_id, workspace) 组合本身已足够; 但**不能依赖**它 —— 上两行就是反例\n\n## ★★ 补记之十六（2026-09-28 复核 pi `e77154d1`：两条**独立测量互证**，补一格我测不到的子形态）\n```\n### 一★ 那封信的两处更正**早已在案**，本轮只做核对、未改结论\n `99320f45`（09-26 02:06:55）那两条 —— 「557 是**下界**不是等值」与「删除路径有**三条**」\n —— 我在 **12 分钟后的 `81b61fde`（02:18:27）** 就已全收并自撤了对应论据。\n 复核仍成立（规则 ⑩ 逐条在被引文件里核对）:\n `deploy/prune-test-sessions.sh:117` `DELETE … WHERE mail_id IN (SELECT …)` ⇒ **不要求 NULL** ✓ 能删已绑定行\n `deploy/reset-demo.sh:81` `DELETE FROM relayed_mails;` ⇒ **全清** ✓\n ⇒ 「查不到痕迹 ⇒ 没删过」**不成立**这条，已在定稿多处 ✓\n ⇒ ★⇒ 结论不变: **「422 未能确证」**，且 `bound(T1) ∈ [556,559]`（补记之十三 已记）——\n 而\"占位释放\"是**至少一个**可行解释、非唯一（补记之十三 同）。\n### 二★★★ 本轮唯一**新**的一格: pi 的 44 次采样与我 200 次**互证**（此前未并列记录）\n```\n | 量 | 我（200×0.3s + 90×1s） | pi（44 次） | 判定 |\n |------------------------|------------------------|-----------------|------|\n | \"→0\"（零行）占比 | **25%** | **25%** | ✓ 一致 |\n | 换 workspace 事件 | 27 次变化 / 90s | 22 次 / 44 次 | ✓ 同量级 |\n | 最长零窗 | ≈ **5.1s** | 未测 | 我独有 |\n | **\"→0 之后回升\"** | ★ **测不到** | **11 次** | **它独有** ✓\n⇒ ★ 关键不是\"谁对\", 而是**两条测量的粒度不同、因而互补**:\n 我的 0.3s×200(=60s) 与 1s×90(=90s) **无法分辨**\"归零后回升\"这个**子形态**\n （回升若快于采样间隔，我只看到\"又一次变化\"）\n ⇒ 所以\"25% 相同\"不是同义反复: 它是两个**独立执行**在**同一量**上撞出一致 ⇒ 零窗口是真实的\n⇒ ★ 而\"11 回升\"是**我采样设计漏掉**的一格（不是它多测了真相，是我**没问这个问题**）\n ⇒ 与本会话方法论同族: 采样率决定了**能看见哪些形态**; 报\"没测到\"时应写\"**我的粒度下测不到**\"，\n 而非\"不存在\"\n\n## ★★★★★ 补记之十七（2026-09-29 实测：**② 已上线而 ①③④ 未改** —— 记录本条的**真实落地状态**）\n```\n### 一★ 本条目的\"尚未实现修法\"这句**已经过期**（`kind` 仍是 scope）\n 实测: 部署二进制 `/opt/agentmail/agentmail-gateway`\n · `vcs.revision = 359cb436c3beaafe16601de9420a5346b9e9f42c`（**09-28 10:14:52 启动**，PID 2824864）\n · ② 的提交 `db640e2`（09-26 14:20）`git merge-base --is-ancestor` 判定 **在 359cb436 里** ✓\n · 二进制里 `workspace IN (` 字符串 **命中 1** ⇒ ★ **② 已在生产运行**\n ⇒ ★★ 而我此前的记录（含本条目\"尚未实现修法\"）说**没修** ⇒ **那句已过期**\n ⇒ 与 `prune-artifact-evidence-decays-with-reboot` 同族: **状态会变，记状态的话会过期**\n### 二★★★★ 四处必改点的**真实状态**（不是\"全没改\"，也不是\"改完了\"）\n```\n ① **PK** `init_sqlite.sql:421` 仍是 `PRIMARY KEY (agent_name, platform_id)` ⇒ **未改**\n 线上库实测: `pk 列 = agent_name , platform_id` ⇒ **未改**（且未重建）\n ② **DELETE** `platform_sessions.go:138` = `... WHERE agent_name = $1 AND workspace IN (...)`\n ⇒ ★ **已改、已上线** ✓ 且带 `len(wsOrder) > 0` 守卫（空列表**什么都不删**，不依赖 `IN ()` 恒假）\n ③ **JOIN** `:473-474` 仍 `ON aps.platform_id = s.platform_id`（**单键**）⇒ **未改**\n ④ **迁移重建表** 未在 `server/internal/db/*.go` 找到重建逻辑 ⇒ **未改**\n⇒ ★ 我此前把这个缺陷整体记成\"未修\"，是**粗口径**; 真实状态是 **② 单独落地**（4 处里的 1 处）\n```\n### 三★★★★★ 由此产生一个新的**潜伏互斥**——② 单独上线使旧 PK 从\"无害\"变成\"可撞\"\n```\n 旧代码（全量 DELETE `WHERE agent_name = $1`）: 每轮上报**清掉该 agent 所有 ws** ⇒ 表里\n 同一 `(agent, platform_id)` **不可能**跨 ws 残留 ⇒ 旧 PK 的 UNIQUE **永远不会被触发**\n 新代码（②，scoped DELETE）: 只清**本次 list 覆盖的 ws** ⇒ 本次 list **之外**的 ws 行**留下**\n ⇒ 若同一个 `platform_id` 先前登记在 `/w2`、本次又从 `/w1` 上报:\n DELETE 只清 `/w1`（`/w2` 那行**留着**）→ INSERT `(agent, id, /w1)`\n ⇒ ★★★ **撞 `UNIQUE(agent_name, platform_id)`**（实测: `UNIQUE constraint failed`）\n ⇒ ★★ 而 `INSERT` 是**普通 INSERT、无 `ON CONFLICT`/upsert**（`:155-160` 实测）\n ⇒ 该错误会经 `tx.Commit()` 前的 `return err` **冒泡** ⇒ 本次上报**整体失败、事务回滚**\n ⇒ 后果: **镜像停止更新**（不是数据错乱，是**这一路心跳从此失败**）\n ⇒ ⇒ ★★★ 所以 **② 单独上线不是\"无害的部分修复\"**:\n 它在**旧 PK 未改**的前提下，把一个\"永远不会发生\"的约束冲突变成\"**条件满足即发生**\"。\n 这正是补记之十四/十五 说的\"必须同批\"的**另一半** —— 那两条讲的是\n **PK 改了而 ③ 没改**会坏; 这一条讲的是 **③④ 没改而 ② 改了**已经上线、也会坏。\n```\n### 四★★ 当前**可达性**（严谨: 前置条件目前不满足 ⇒ 尚未实际发生）\n```\n 触发需要两条同时成立:\n (i) 同一 `platform_id` 的行**跨 ws 残留**（即该 id 曾登记在本次 list 外的 ws）\n (ii) 该 `platform_id` 在本次上报 list 里**重新出现**\n 生产实测: 同 agent+platform 多 ws 的组合 = **0**; 同 platform 多 agent = **0**\n ⇒ ★ 所以**当前没有触发实例** —— 本条是**潜伏**，不是\"正在坏\"\n ⇒ ⚠️ 但 dsh 的 `collectSessions()` 返回**该 agent 所有会话**（cwd 取自各自 header）\n ⇒ 一个 dsh 进程**可以**持有多个 cwd 的会话 ⇒ 条件 (i) 的\"跨 ws\"在结构上**可达**\n ⇒ 且线上 `agent_platform_sessions` 已有 **439 行** ⇒ 一旦哪条会话的 cwd 变了就会命中\n ⇒ ⇒ 定级: **潜伏 / 条件满足即发生**（不是理论上的，是**差一个 cwd 变化**）\n```\n### 五★★ 从这条得到的**可判形状**（并入 ⑩⁗ 家族）\n```\n ① 报\"修了/没修\"**必须逐处报**，不能把多处必改点合成一个布尔 —— 我这次就是被自己的粗口径骗了\n ② 修复分片上线时，**必须重新算\"旧不变量被谁依赖\"**:\n 旧 PK 的 UNIQUE 之所以安全，依赖的是**旧 DELETE 的全量语义**;\n 一旦 DELETE 变 scoped，那份安全性**随之消失** ⇒ 两者是**隐式耦合**，不在类型/签名上\n ③ 判据要能区分\"未修\"与\"**半修**\": 我那个 d1 判据转绿了（因为它只测 ②），\n 而 ①③④ 仍红 ⇒ ★ **判据集合必须与必改点集合一一对应**，否则\"绿\"会被读成\"修好了\"\n```\n\n### 六★★★★ 忠实模拟（线上真 schema 导出副本）+ 严重性**再升一档: 不自愈**\n```\n 用 `sqlite3 \"file:/opt/agentmail/data/agentmail.db?mode=ro\" \".backup\"` 导出**真 schema** 副本\n （PK = `(agent_name, platform_id)`、含 `idx_platform_sessions_ws`、439 行）后模拟:\n 初始: `('dsh','sess-A','/w2')`\n 本轮上报 list = [{id:sess-A, ws:**/w1**}]（即该会话 **cwd 变了**）:\n ② DELETE ... WHERE agent_name='dsh' AND workspace IN ('/w1') ⇒ 删 0 行,**/w2 那行留下**\n INSERT ('dsh','sess-A','/w1') ⇒ ★ `UNIQUE constraint failed: agent_platform_sessions.agent_name, ...platform_id`\n ⇒ ★★★ **不自愈**: 再跑一轮（cwd 仍是 /w1）⇒ DELETE 域仍只含 /w1 ⇒ **又撞同一个错**\n ⇒ 因为陈旧行在 `/w2`，而 DELETE **永远**清不到它 ⇒ **每一轮心跳都失败 ⇒ 永久失败**\n ⇒ 出路只有三条: 该 agent 来一次**含 /w2** 的上报（即 cwd 改回去）、\n 人工/脚本清那一行、或**修好 ①**（新 PK 允许同 (agent,platform) 多 ws ⇒ 不再互斥）\n⇒ ★ 所以严重性是\"**静默且永久**\": 不报错给用户、镜像**冻结**在那个 agent 的最后一版,\n 而 `push_tokens`/候选列表这些依赖镜像的读取会**一直看到旧数据**\n ⇒ 与 `ReleaseRelay`（无痕删除）、`/tmp` 影子模块（rc=0 混入）同族: **不响的坏**\n```\n### 七★ 触发前提（把\"差一个 cwd 变化\"说得更准）\n```\n 需要: 某 `platform_id` 的旧行在 `ws=X`（**本轮 list 不含 X**），而同一 id 本轮在 `ws=Y≠X` 被上报\n ⇒ ★ 现实中就是 **\"会话的 cwd 变了\"**（`collectSessions` 用 `header.cwd` 作为 workspace）\n ⇒ 而\"改工作目录/重开会话/迁移项目目录\"是**常见操作**，不是异常路径\n ⇒ 生产实测当前 0 例（同 agent+platform 多 ws = 0）⇒ 尚未发生，但**门槛只是一个 cwd 变更**\n```\n" }, { "id": "recount-labels-must-match-predicates",