docs(debt): 补记 platform-mirror 那条的第三处必改点 —— :395 的 JOIN 歧义（既存，非 PK 副作用）

pi（`249fe29d`）指出改 PK 的下游影响面，我实测复核并**修正其归因**:

① `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 就有两行。
   实测: opencode 与 homeagent 上报同一 platform_id ⇒ JOIN 出 **2 行**，
   PlatformSessionFor 返回 owner=homeagent 而该会话是 opencode 接管的 ⇒ **取错归属**。

★ 归因修正: 这是**既存缺陷**，**不是**"改 PK 的副作用" ——
   它与 workspace 无关（PK 今天已允许跨 agent 同名），且生产数据里跨 agent 的
   platform_id 交集 = 0 所以未显形（又一个"当前干净是数据性质、非约束"）。

② pi 建议的修法「JOIN 加 workspace」**不完整**（实测两场景）:
     跨 agent + 不同 workspace ⇒ 1 行 ✓
     跨 agent + **相同** workspace ⇒ **2 行** ✗ 仍歧义

③ 正确消歧键是 **agent 身份**: JOIN ... AND aps.agent_name = s.from_agent ⇒ 1 行 ✓
   而 sessions.from_agent 由 AdoptPlatformSession → CreateSession(ctx, nil, agentName, …)
   写入（repo.go:260 第 2 个形参）⇒ 接管路径结构性非空（生产库: 无空值）。

⇒ 伴随项从「PK + DELETE」扩为三处**必须同批**改；
   漏掉第三处 ⇒ 取错归属 ⇒ platform_session_id 发给非归属方 ⇒ 邮件静默消失
   （比候选少一条更重，消费者 notify/mail.go:94）。

校验: go test ./internal/repo/ -run Debt ⇒ ok

docs/DEBTS.json

@@ -198,10 +198,10 @@
     {
       "id": "platform-mirror-replace-domain-too-wide",
       "count": 1,
-      "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` 对 `[]` 为真 ⇒ 空清单也走整表替换。",
+      "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` 发给谁（发错 = 收方去自己磁盘找别人的会话文件 ⇒ 抛「平台侧会话已删」⇒ 邮件静默消失）。",
       "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\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"
+      "note": "2026-09-26 我（dsh）与 pi 在 `21c398ee` 会话上共同定位；**尚未实现修法**，故记欠账。\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"
     }
   ]
 }