work-ally 0.2.0-alpha.1

package/docs/issues/resolved/ANALYSIS-premature-terminalization-on-fresh-thread-poll-and-object-error-leak-2026-03-16.md

@@ -0,0 +1,348 @@
+# 分析报告：fresh thread 过早终态判定与 `[object Object]` 错误外泄
+
+更新时间：2026-03-16  
+状态：已修复并补门禁（2026-03-17）  
+作者：Codex
+
+## 1. 这份报告回答什么
+
+这份报告不把 `Ally 22:43 只回了 [object Object]` 当成一个孤立的文案事故，而是把它上提为一个更值得警惕的问题：
+
+> bridge 目前会把某些“暂时还没观测清楚 turn 终态”的运行态，过早升级成“本轮已经失败”，然后把这个本地判断直接外显给用户。
+
+这份文档要回答的是：
+
+1. 这次 `[object Object]` 现场到底发生了什么。
+2. 它为什么不是一个单纯的字符串格式化问题。
+3. 它暴露的是哪一条 turn 终态判定链路的设计缺陷。
+4. 它和之前“阻塞态对用户可见但无可操作实体”的问题，是否属于同一类上位问题。
+5. 后续应该按什么原则收口，避免继续东打一块补丁、西打一块补丁。
+
+## 2. 结论先说
+
+结论很明确：
+
+- 这是一条真实 bug，不是飞书显示问题。
+- 用户消息已经进入 bridge，也已经成功启动了新的 thread 和 turn。
+- bridge 在 fresh thread 刚创建后，过早执行了 `thread/read(includeTurns=true)` 轮询。
+- runtime 返回的是一个结构化暂态错误：thread 还没 materialize，当前还不支持 `includeTurns`。
+- `runtime-client` 把这个结构化错误错误地转换成了 `Error(String(error))`，于是用户看到了字面量 `[object Object]`。
+- 更深层的问题不在于字符串丑，而在于 bridge 把一次“暂态观测失败”误判成了“turn 已失败”，并且在真正的 `turn/completed` 后续到来前，就已经把错误结果发给了用户。
+
+一句话收口：
+
+> **当前 turn 终态链路把“没有可靠读到终态”错误地等价成了“终态就是失败”。**
+
+## 3. 事件背景
+
+### 3.1 排查对象
+
+- 助理：`Ally`
+- 办公桌：`/Users/allenfeng/.work-ally/assistants/Ally`
+- 会话：`feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8`
+- 关注时间：2026-03-16 22:43 左右（Asia/Shanghai，对应 `2026-03-16T14:43Z`）
+- 对应 thread：`019cf719-de8c-79e2-9a60-10603069b15e`
+- 对应 turn：`019cf719-e00e-7663-a831-2b29124a876f`
+
+### 3.2 用户可见现象
+
+用户发出一条正常需求消息后，只收到一条回复：
+
+`[object Object]`
+
+这不是“回复内容不完整”，而是系统直接把内部错误对象以错误形式暴露给了用户。
+
+## 4. 证据链
+
+### 4.1 archive 原材料
+
+- `/Users/allenfeng/.work-ally/assistants/Ally/.system/archive/2026/03/16/feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8.ndjson`
+
+关键记录：
+
+1. 用户消息在 `2026-03-16T14:43:13.248Z` 进入 archive。
+2. `2026-03-16T14:43:14.105Z` 记录 `system_event: turn_failed`，其中 `error` 已经是 `[object Object]`。
+3. `2026-03-16T14:43:14.690Z` 记录 `error_reply`，正文就是 `[object Object]`。
+
+这说明：
+
+- `[object Object]` 是 bridge 真正发给飞书用户的内容；
+- 不是日志里才有，用户前台确实看到了。
+
+### 4.2 bridge / timeline 日志
+
+- bridge：`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/bridge-2026-03-16.log`
+- timeline：`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/timeline-2026-03-16.log`
+
+关键顺序如下：
+
+1. `14:43:13.638Z`：bridge 收到用户消息。
+2. `14:43:14.054Z`：thread 创建成功。
+3. `14:43:14.064Z`：turn 创建成功。
+4. `14:43:14.068Z`：bridge 立刻发起 `thread/read`。
+5. `14:43:14.102Z`：runtime 返回错误：
+
+   `thread ... is not materialized yet; includeTurns is unavailable before first user message`
+
+6. 同一时刻：`runtime.turn_final_state_poll_failed` 被记录为 `Error: [object Object]`。
+7. 随后：`receiver.turn_failed`，bridge 把这轮直接判成失败。
+8. `14:45:25.752Z`：两分钟后，runtime 其实发来了 `turn_completed_event`，状态是 `completed`。
+
+这条时间线说明：
+
+- turn 并没有在 `14:43:14` 真正失败；
+- bridge 是在真正终态到来之前，提前宣判了失败；
+- 这不是“Codex 没工作”，而是 bridge 自己把暂态错误转成了用户可见终态。
+
+## 5. 直接原因
+
+这次事故的直接原因有两层。
+
+### 5.1 第一层：错误归一化坏了
+
+`bridge/src/runtime-client.ts` 当前在 `pollTurnFinalState()` 的异常路径中使用：
+
+- `new Error(String(error))`
+
+对应位置：
+
+- `/Users/allenfeng/Development/Repositories/work-ally/bridge/src/runtime-client.ts:686`
+
+当 runtime 返回的是 JSON-RPC 结构化错误对象时，`String(error)` 会得到 `[object Object]`，于是：
+
+- 日志里的错误变成 `[object Object]`
+- 用户看到的错误也变成 `[object Object]`
+
+### 5.2 第二层：暂态观测失败被误判成终态失败
+
+更严重的问题在同一段逻辑里：
+
+- `pollTurnFinalState()` 只要遇到“非 recoverable”读错误，就会 `rejectTurnResult()`；
+- `receiver` 捕获到 reject 后，会沿 `turn_failed -> error_reply` 这条路径向用户回错；
+- 但这次错误并不是 turn 真失败，而只是 fresh thread 尚未 materialize 时 `thread/read(includeTurns=true)` 暂时不可用。
+
+也就是说，系统当前把：
+
+- “现在还不能可靠读取 turn 历史”
+
+错误地升级成了：
+
+- “这一轮 turn 已经失败”
+
+## 6. 5 Why 根因分析
+
+### Why 1：为什么用户看到了 `[object Object]`？
+
+因为 runtime 返回了结构化错误对象，而 bridge 用 `String(error)` 包装它，最终把对象字符串化成了 `[object Object]`。
+
+### Why 2：为什么这个对象字符串最终会暴露给用户？
+
+因为这次错误没有被当成“观测层暂态错误”，而是被当成了“turn failure”，随后 receiver 直接走了 `error_reply` 用户出口。
+
+### Why 3：为什么一次 `thread/read` 失败会被当成 turn failure？
+
+因为当前终态轮询模型里，`pollTurnFinalState()` 承担了双重职责：
+
+1. 读取 runtime 已存储事实；
+2. 本地裁定 turn 是否结束。
+
+一旦读取事实这一步失败，当前实现会直接把它理解成“终态判定已经失败”。
+
+### Why 4：为什么 fresh thread 上会出现这种读取失败？
+
+因为 `turn/start` 成功后，bridge 立即执行 `thread/read(includeTurns=true)`；但 fresh thread 在 materialize 之前，并不总是支持带 `includeTurns` 的读取。这说明 bridge 当前默认假设：
+
+> turn 刚启动后，thread 的完整可读视图一定已经就绪。
+
+这个假设并不成立。
+
+### Why 5：为什么这种暂态会升级成用户可见事故？
+
+因为当前状态机缺少一个关键分层：
+
+- “尚未可靠观测到终态”
+- “已可靠确认终态失败”
+
+这两种状态在实现里被混成了一类。于是任何不在 recoverable 正则名单里的读错误，都会过早地落到用户侧终态。
+
+### 根因收口
+
+根因不是一个字符串处理小失误，而是：
+
+> **turn 终态状态机没有把“观测失败”与“业务终态失败”分层，导致 bridge 用本地读取异常覆盖了 runtime 的真实 turn 事实。**
+
+## 7. 这次事故反映的上位设计问题
+
+这次 `[object Object]` 事故暴露的不是单点 patch 位，而是 turn 终态链路上至少三条设计问题。
+
+### 7.1 问题一：终态判定过早绑定在观测链路上
+
+当前实现里：
+
+- `turn/start` 后立刻开启 `pollTurnFinalState()`；
+- poll 既负责“看事实”，又负责“下结论”；
+- 一旦 `thread/read` 报错，系统很容易直接走失败出口。
+
+这意味着：
+
+> 终态不是由 runtime 的 durable fact 驱动，而是被本地观测成功与否牵着走。
+
+这在设计上过于激进。
+
+### 7.2 问题二：event truth 和 poll truth 的优先级没有收干净
+
+当前代码里，`turn/completed` 事件已经被接住，并存在 `completedEventResult` 中；但 `pollTurnFinalState()` 仍可能在更早时刻先 reject 整个 turn。
+
+一旦 reject 发生：
+
+- turn state 被 finalize；
+- 后续真正到来的 `turn/completed` 即使存在，也已经来不及正常兑现给用户。
+
+也就是说，当前系统虽然在做 pull-primary，但还残留着：
+
+> “只要本地某一步观察不顺，就先把这轮打死”
+
+的旧思路。
+
+### 7.3 问题三：用户出口没有经过“是否已确认终态”的把关
+
+用户最终看到的 `error_reply`，本质上应只来自两类情况：
+
+1. runtime 已明确给出失败终态；
+2. bridge 已经过完整补偿、对账和等待后，仍能确认无法恢复。
+
+但这次现场中：
+
+- runtime 尚未给出终态；
+- bridge 也没有完整进入补偿 / 继续拉取 / 等待 completed event 的流程；
+- 用户却已经收到了失败消息。
+
+这说明当前用户出口缺少“终态已确认”这一层门禁。
+
+## 8. 和之前 pending 问题的关系
+
+它和下面两份 pending 报告不是同一个具体 bug，但属于同一个上位问题家族：
+
+- `docs/issues/resolved/ANALYSIS-approval-waiting-visible-but-approval-artifact-missing-2026-03-16.md`
+- `docs/issues/resolved/ANALYSIS-blocking-state-visible-without-user-actionable-artifact-2026-03-16.md`
+
+共同点是：
+
+> bridge 把“不完整的内部信号”过早升级成了“用户面前已经成立的事实”。
+
+前两份文档里，不完整的内部信号是：
+
+- `waitingOnApproval`
+- `waitingOnUserInput`
+
+这份文档里，不完整的内部信号是：
+
+- fresh thread 上一次暂态 `thread/read` 失败
+
+三者的共性问题都是：
+
+- 内部信号还不足以支撑对用户下结论；
+- 但 bridge 已经先替用户做了结论化翻译；
+- 结果导致用户看到错误状态，甚至后续真实结果被吞掉。
+
+## 9. 修复原则
+
+后续修复不应只停在“把 `[object Object]` 改得更好看”，而应按下面几条硬原则推进。
+
+### 9.1 原则一：观测失败不等于 turn failure
+
+任何 `thread/read` / transport / materialization 暂态错误，都只能先落在：
+
+- 观测暂不可用
+- 继续等待
+- 继续拉取
+- 等待 `turn/completed`
+
+除非 runtime 已明确给出 turn failed，或 bridge 已经过完整恢复窗口仍确认不可恢复，否则不能直接对用户宣称失败。
+
+### 9.2 原则二：fresh thread 需要显式 materialization 窗口
+
+`turn/start` 成功后，不应假设 `thread/read(includeTurns=true)` 立即可用。
+
+要么：
+
+- 对 “not materialized yet / includeTurns unavailable” 定义专门的 retryable 暂态；
+
+要么：
+
+- 在 fresh thread 的早期阶段先读轻量状态，再延后拉取 turns。
+
+但无论采用哪种实现，结论都一样：
+
+> fresh thread 初期的可读性，不能被当成稳定前提。
+
+### 9.3 原则三：用户可见错误必须建立在“终态已确认”之上
+
+以后用户出口的错误文案必须满足一条门槛：
+
+- 这是 runtime 的真实终态；
+- 或这是 bridge 经过恢复和对账后仍然确认的不可恢复状态。
+
+不能再把中间层自己的内部读取异常直接回显给用户。
+
+### 9.4 原则四：turn/completed 和 persisted turn fact 才是终态真相
+
+在架构上，最终应坚持：
+
+- `turn/completed`
+- `thread/read` 读到的 persisted turn status
+
+这两类 durable fact 才能决定 turn 的用户终态。
+
+轮询失败、暂态协议错误、短时 materialization 窗口，都只应影响“还要不要继续等 / 继续拉”，不应直接决定“用户该看到什么终态”。
+
+### 9.5 原则五：错误归一化要先于状态机判断
+
+任何 runtime 结构化错误都必须先规范化成：
+
+- `code`
+- `message`
+- `retryable / transient / terminal`
+
+然后再进入状态机。
+
+如果连错误都还没被正确归类，就直接参与 turn 终态裁决，后续还会继续冒出别的“对象字符串化”或“误分类”事故。
+
+## 10. 建议测试门禁
+
+这次事故同时说明，自测仍缺少一组针对“fresh thread 初期终态判定”的用例。后续至少应补下列场景：
+
+1. `turn/start` 成功后首次 `thread/read(includeTurns=true)` 返回 `not materialized yet`。
+2. 上述错误是结构化 JSON-RPC object，而不是 `Error` 实例。
+3. 同一轮 turn 在暂态读错误后，随后正常收到 `turn/completed`。
+4. 暂态读错误期间，不得向用户发送 `error_reply`。
+5. 用户前台绝不能看到 `[object Object]`。
+6. archive 不得过早记录 `turn_failed`。
+7. 如果后来 turn 真 completed，结果必须能继续对账并交付。
+8. 如果最终确实失败，用户看到的也必须是规范化后的可解释错误，而不是对象字符串。
+
+## 11. 后续落地方向
+
+这份报告当前只做问题收敛，不直接给 patch 细节，但后续实现应优先围绕下面三块推进：
+
+1. `runtime-client` 的错误归一化：结构化 JSON-RPC error 不能再走 `String(error)`。
+2. `pollTurnFinalState()` 的状态机重收：fresh thread materialization 暂态不能直接 reject turn。
+3. `receiver` 的用户出口门禁：只有在 turn 终态已确认时，才允许向用户发送失败终态。
+
+## 12. 一句话结论
+
+`[object Object]` 不是一次偶发字符串事故，而是 turn 终态架构里“把观测异常误当业务终态”的一次明确暴露；如果不按状态机分层去修，后面还会以别的文案继续冒出来。
+
+## 10. 实现收口（2026-03-17）
+
+本问题已按“观测失败 != 终态失败”收口：
+
+1. `runtime-client` 新增结构化 JSON-RPC 错误归一化，不再把对象错误透传成 `[object Object]`。
+2. `thread ... is not materialized yet; includeTurns is unavailable before first user message` 已纳入 recoverable transient。
+3. `pollTurnFinalState()` 对这类 fresh-thread materialization read failure 继续轮询，不再过早 `rejectTurnResult()`。
+4. `receiver` 的错误落日志与对用户文案也改为统一的错误提取逻辑，避免对象串化外泄。
+5. 对应门禁已补到 `tests/unit/runtime/runtime-client-pull-primary.test.mjs`：
+   - `runTurn treats fresh-thread materialization error as transient and never leaks object formatting`
+
+因此，这个问题现在已经从“pending 分析”进入“resolved behavior + regression guard”。
+