work-ally 0.2.0-alpha.1

package/docs/issues/resolved/ANALYSIS-self-test-gap-approval-waiting-visible-but-approval-artifact-missing-2026-03-16.md

@@ -0,0 +1,166 @@
+# 反思报告：为什么“等待审批已可见但审批实体缺失”没有在自测中暴露
+
+更新时间：2026-03-16  
+状态：反思完成 / 待补测试门禁  
+作者：Codex
+关联问题：`docs/issues/resolved/ANALYSIS-approval-waiting-visible-but-approval-artifact-missing-2026-03-16.md`
+
+## 1. 这份反思报告回答什么
+
+这份文档不重复讲 bug 本身，而是专门回答一个更关键的问题：
+
+> 为什么这类问题没有在本地自测里被我发现，反而要等到用户在飞书真实对话里才暴露？
+
+目标是把“测试为什么失真”讲清楚，并反推后续测试纪律。
+
+## 2. 先说结论
+
+这次不是“完全没写审批测试”，而是：
+
+- 我写了审批 happy path；
+- 我也测了审批后继续执行；
+- 但我没有把“等待审批状态”和“审批卡已成功交付”拆成两个独立事实去测。
+
+所以现有测试验证的是：
+
+- 有审批请求时，审批卡能不能工作；
+
+却没有验证：
+
+- 只有 thread flag、没有审批实体时，系统是不是还会错误进入 waiting state；
+- 后续自然语言是不是会被误拦截；
+- 没有审批卡时，系统是不是仍错误要求用户审批。
+
+这正是现实现场里发生的事。
+
+## 3. 当时有哪些测试，为什么它们没拦住
+
+当前仓库里，和审批最相关的测试主要是：
+
+- `tests/integration/session/approval-flow.test.mjs`
+- `tests/integration/session/waiting-and-redelivery.test.mjs`
+- `tests/integration/session/control-commands.test.mjs`
+
+这些测试覆盖了：
+
+- 正常审批卡生成；
+- 回复审批卡“同意/拒绝”；
+- `/approve <id>` 命令；
+- 阻塞期间追问会被拦截；
+- 长时间等待审批不应直接失败。
+
+问题在于，这些测试都共享一个默认前提：
+
+> 只要 runtime 进入 `waitingOnApproval`，审批卡实体一定也已经存在。
+
+这个前提在假 runtime 里总是成立，所以整个测试世界里，“等待审批但没有审批卡”这种状态根本不可能出现。
+
+## 4. 5 Why 反思
+
+### Why 1：为什么自测没暴露这个 bug？
+
+因为测试只验证了“审批卡存在时审批是否可用”，没有验证“审批卡缺失时系统是否仍错误阻塞”。
+
+### Why 2：为什么没有覆盖“审批卡缺失”这个场景？
+
+因为我写测试时默认认为：`waitingOnApproval` 和 `approval_requested` 是同一件事的两个侧面，不会分离。
+
+### Why 3：为什么我会做这个默认假设？
+
+因为 `FakeRuntimeClient` 的建模把这两个阶段耦合在一起了：一旦进入审批流程，waiting flag 和审批回调会按顺滑路径一起出现。
+
+也就是说，测试替身本身把一种真实系统里可能分离的时序，错误建模成了“原子成功”。
+
+### Why 4：为什么测试替身会被我建成这样？
+
+因为我当时写测试的视角是“功能流程要能走通”，而不是“状态机边界是否稳固”。
+
+我验证的是：
+
+- 审批后能继续；
+- 拒绝后能失败；
+- 自动审批能放行；
+
+但没有从第一性原理问一句：
+
+- 用户被阻塞前，是否已经真正拿到了可操作对象？
+
+### Why 5：为什么我没有把这个问题上升成测试不变量？
+
+因为我的测试设计仍然太贴实现路径，而不是贴产品事实。
+
+真正应该守的不变量是：
+
+> 用户可见的 `waiting approval` 只能建立在“审批实体已成功交付给用户”之上。
+
+这个不变量之前没有被写进测试，所以实现可以静悄悄地偏掉。
+
+## 5. 为什么要等到飞书里才暴露
+
+因为飞书真实运行态里，审批链路不是一个原子动作，而是至少三段：
+
+1. runtime thread 出现 `waitingOnApproval`
+2. bridge 收到并记录审批请求
+3. bridge 成功把审批卡发到用户前台
+
+而我的本地自测，把这三段压缩成了一个“同步成功”的假世界。
+
+于是：
+
+- 在假世界里，用户一旦被提示等待审批，就一定已经能看到审批卡；
+- 在真实世界里，这三步可能时序错位、漏接、延迟、甚至只到了前两步。
+
+所以问题只会在真实链路里显形。
+
+## 6. 自测设计到底哪里错了
+
+这次反映出的测试设计错误有三层。
+
+### 6.1 错在按 feature 测，而不是按状态不变量测
+
+我测了“审批功能是否可用”，但没测“阻塞态是否有资格成立”。
+
+### 6.2 错在替身建模过于乐观
+
+`FakeRuntimeClient` 默认让 waiting flag 和审批请求同进同出，掩盖了真实系统的时序裂缝。
+
+### 6.3 错在没有对“用户可见事实”做独立断言
+
+测试断言大多围绕：
+
+- 有没有审批卡
+- 能不能 approve
+- 最终 reply 对不对
+
+但没有独立断言：
+
+- 如果没有 `approval_requested`，就绝不能进入真正的 waiting interception。
+
+## 7. 后续必须补的测试门禁
+
+针对这个 issue，后续必须补的不是更多 happy path，而是下面几类 fault-injection case：
+
+1. runtime 先给 `waitingOnApproval`，但审批请求事件缺失。
+2. runtime 先给 `waitingOnApproval`，审批请求晚到。
+3. 用户只看到 `waiting approval` 状态时继续追问，消息应继续转给 Codex 或进入“详情同步中”，不能直接拦截。
+4. 没有审批卡上下文时，用户说“同意”，系统不能误判为用户已完成审批，也不能永远卡死。
+5. session/archive 中不存在 pending approval object 时，`waiting_user_follow_up_intercepted` 不得成立。
+
+## 8. 以后我的测试纪律要怎么改
+
+以后这类问题不能再只测“功能通不通”，必须额外测一层：
+
+> 用户面前成立的事实，是否真的有后端证据和前台实体支撑。
+
+具体到审批链路，就是：
+
+- waiting flag
+- pending approval record
+- approval card 已发送
+- 用户后续消息是否应该被拦截
+
+这四件事必须拆开建模，不能再默认捆绑。
+
+## 9. 一句话反思
+
+这次不是我没测审批，而是我把“审批流程走通”误当成了“审批阻塞模型正确”；以后必须把“用户被阻塞前，是否真的拿到了可操作实体”提升成独立测试不变量。

package/docs/issues/resolved/ANALYSIS-self-test-gap-blocking-state-visible-without-user-actionable-artifact-2026-03-16.md

@@ -0,0 +1,186 @@
+# 反思报告：为什么“阻塞态已可见但用户无可操作实体”没有在自测中暴露
+
+更新时间：2026-03-16  
+状态：反思完成 / 待补测试门禁  
+作者：Codex
+关联问题：`docs/issues/resolved/ANALYSIS-blocking-state-visible-without-user-actionable-artifact-2026-03-16.md`
+
+## 1. 这份反思报告回答什么
+
+这份文档聚焦更上位的问题：
+
+> 为什么我之前已经写了 user input、MCP auto-resolve、waiting state 等测试，但仍然没在本地发现“用户已被阻塞、但根本没有拿到可操作实体”这类问题？
+
+这不是单个审批 bug，而是我测试模型本身的缺口。
+
+## 2. 先说结论
+
+这次自测失效的根本原因是：
+
+- 我的测试是按“功能入口”组织的；
+- 真实事故暴露的是“阻塞资格”问题；
+- 我没有把“阻塞态成立”这件事拆成独立 contract 来测。
+
+因此，现有测试都在验证：
+
+- user input 请求来了后能不能继续；
+- MCP 默认自动放行后能不能跑完；
+- 等待期间能不能恢复；
+
+却没有验证：
+
+- 如果只有 `waitingOnUserInput` / `waitingOnApproval` flag，而没有用户可见实体，bridge 是否仍错误阻塞；
+- auto-resolve 过程中，waiting flag 是否会先于实体 / 收口结果暴露；
+- `pendingUserInputRequestId` 为空时，为什么还能拦截用户追问。
+
+## 3. 当时有哪些测试，为什么它们没拦住
+
+相关测试主要包括：
+
+- `tests/integration/session/user-input-flow.test.mjs`
+- `tests/integration/session/mcp-tool-approval-flow.test.mjs`
+- `tests/integration/session/waiting-and-redelivery.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary.test.mjs`
+
+这些测试验证了：
+
+- user input 请求能发出来并恢复；
+- MCP allowlist 场景可自动放行；
+- 非 allowlist 的 MCP elicitation 会正常提示用户；
+- waitingOnUserInput / waitingOnApproval 长时间存在时不会超时失败。
+
+但它们共同遗漏了一件事：
+
+> 没有任何一条测试故意制造“flag 已出现，但用户可操作实体缺失”的失真态。
+
+所以整个测试世界默认认为：
+
+- 有 waiting flag，就一定有 pending object；
+- 有 pending object，就一定已对用户可见；
+- auto-resolve 也总能在线性时序里完成。
+
+而真实现场恰恰打破了这些假设。
+
+## 4. 5 Why 反思
+
+### Why 1：为什么自测没发现这个家族问题？
+
+因为我测的是“审批链路”“user input 链路”“MCP 链路”能否走通，没有测“阻塞态是否具备成立条件”。
+
+### Why 2：为什么我没测“阻塞资格”而只测“链路走通”？
+
+因为我当时的测试思路仍然是 feature-driven，不是 state-contract-driven。
+
+也就是说，我在问：
+
+- 用户输入来了能不能继续？
+- 自动放行后能不能完成？
+
+而没有问：
+
+- 系统有资格拦截用户后续自然语言吗？
+
+### Why 3：为什么我没有把“阻塞资格”定义成 contract？
+
+因为我默认认为 waiting flag 自身就足够说明“现在轮到用户处理”，没把“用户可操作实体”作为一个独立事实层。
+
+### Why 4：为什么会形成这种默认？
+
+因为假 runtime、session 状态和 channel 发送，在本地测试里基本总是线性一致的：
+
+- status 变了
+- request 也来了
+- prompt 也发了
+- 用户答复后就恢复
+
+这种顺滑路径让我忽略了真实系统里的一个关键事实：
+
+- status 信号
+- pending object
+- channel delivery
+- auto-resolve result
+
+它们并不是天然原子的。
+
+### Why 5：为什么我要等飞书里才意识到这个问题？
+
+因为只有在真实链路里，这几个层次才会自然拉开：
+
+- runtime 可能先给 flag；
+- request 事件可能晚到或漏接；
+- auto-resolve 可能和状态机切换不是同一拍；
+- 用户前台是否真正见到实体，又是第三层事实。
+
+而我之前的测试没有主动把这些层次拆开，所以实验室里永远不可能长出这种 bug。
+
+## 5. 为什么飞书里才暴露
+
+因为飞书现场不是单一模块自娱自乐，而是一个跨层系统：
+
+1. runtime 给 thread status
+2. runtime 或 bridge 生成 request / elicitation object
+3. session store 记录 pending object
+4. channel 发到飞书前台
+5. 用户看到后才能真正执行下一步
+
+现在回看，我之前的测试覆盖大多停留在：
+
+- 第 1 层和第 2 层是否存在；
+- 第 5 层能否在理想前提下完成；
+
+却几乎没测：
+
+- 第 2、3、4 层之间是否一致；
+- 如果 2/3/4 断裂，bridge 是否还错误拦截第 5 层输入。
+
+所以它必须等到真实飞书链路里才爆。
+
+## 6. 我当时的自测模型哪里不合理
+
+### 6.1 把“状态”误当成“用户事实”
+
+我测了 waiting flag，但没测 waiting flag 是否被用户真正兑现成了可操作对象。
+
+### 6.2 把 auto-resolve 误当成线性即时成功
+
+在 MCP 相关测试里，我主要验证 allowlist 是否能自动放行，但没有刻意验证：
+
+- waiting flag 先出现、auto-resolve 结果后到
+- auto-resolve 失败或未落库
+- pending object 为空却仍阻塞
+
+### 6.3 没有跨层对账断言
+
+测试大多盯住 channel.sent 是否包含某类消息，却没有系统性验证：
+
+- runtime flag
+- session pending record
+- archive event
+- channel outbound
+
+这四层是否一致。
+
+## 7. 后续必须补的测试门禁
+
+后续围绕这个上位问题，必须补以下 contract tests：
+
+1. 仅有 `waitingOnApproval` / `waitingOnUserInput` flag，没有 pending object。
+2. pending object 已存在，但 channel 未成功发出。
+3. auto-resolve 规则命中前，waiting flag 先暴露。
+4. session 中 `pendingUserInputRequestId` 为 `null` 时，任何 follow-up 都不得走 waiting interception。
+5. 没有审批卡 / 没有 input prompt 时，用户自然语言必须继续转发给 Codex，或走“阻塞详情待同步”而不是本地卡死。
+6. archive、session、channel 三层必须对账：只要缺一层，就不允许进入真正的 `waiting_user_action`。
+
+## 8. 以后我的测试纪律要怎么改
+
+以后对任何“用户被阻塞”的 feature，都必须先问三个问题：
+
+1. 系统内部为什么认为现在轮到用户操作？
+2. 用户前台到底拿到了什么可执行实体？
+3. 如果实体没拿到，bridge 是否还会错误地拦截用户输入？
+
+这三个问题必须被单独测到，不能只靠 happy path 测试间接覆盖。
+
+## 9. 一句话反思
+
+这次不是某条链路单独漏测，而是我把“waiting flag 成立”误当成了“用户阻塞条件成立”；以后必须把“阻塞资格”本身定义成一等测试对象。

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

@@ -0,0 +1,166 @@
+# 反思报告：为什么“fresh thread 过早终态判定与 `[object Object]` 外泄”没有在自测中暴露
+
+更新时间：2026-03-16  
+状态：反思完成 / 待补测试门禁  
+作者：Codex
+关联问题：`docs/issues/resolved/ANALYSIS-premature-terminalization-on-fresh-thread-poll-and-object-error-leak-2026-03-16.md`
+
+## 1. 这份反思报告回答什么
+
+这份文档专门回答：
+
+> 为什么我已经给 `runtime-client` 写了 pull-primary、transient read failure、late terminal result 等测试，结果 `[object Object]` 这种事故还是只能等飞书里真实对话才暴露？
+
+这次必须反思的，不是“少写了一条 case”这么简单，而是我的 turn 终态测试模型本身还不够完整。
+
+## 2. 先说结论
+
+这次没被自测提前拦住，根因有三条：
+
+- 我测了“通用 transient error”，没测“协议级结构化错误对象”；
+- 我测了“thread/read 暂时断连”，没测“fresh thread 刚启动时尚未 materialize”；
+- 我测了“completed event 与 poll 冲突”，没测“poll 先错误 reject，导致 completed event 来晚后已经救不回来”。
+
+所以现有测试确实覆盖了一部分恢复逻辑，但没有覆盖这次事故真正命中的那块状态空间。
+
+## 3. 当时有哪些测试，为什么它们没拦住
+
+相关测试主要在：
+
+- `tests/unit/runtime/runtime-client-pull-primary.test.mjs`
+- `tests/unit/runtime/runtime-client-lifecycle.test.mjs`
+- `tests/integration/session/runtime-failure-and-recovery.test.mjs`
+
+这些测试已经覆盖了：
+
+- `thread/read` 遇到 `runtime websocket is not connected` 的重试；
+- pull-primary 在 `turn/completed` 不到时仍可从 `thread/read` 恢复；
+- `turn/completed` 与后续 poll 冲突时优先用 authoritative completed result；
+- bounded timeout 后的错误提示。
+
+但它们没有覆盖这次事故的三个关键条件同时成立：
+
+1. 这是一个 fresh thread；
+2. 首次 `thread/read(includeTurns=true)` 返回的是结构化 JSON-RPC object error；
+3. 这个错误既不在 recoverable regex 名单里，又不是 turn 真失败；
+4. runtime 后面仍会给出 `turn/completed`，但因为前面已 reject，后续事实无法再兑现给用户。
+
+少了这组组合，整个测试看起来就像“恢复逻辑已经够用了”。
+
+## 4. 5 Why 反思
+
+### Why 1：为什么自测没暴露这次 `[object Object]`？
+
+因为我没有构造“结构化错误对象 + fresh thread materialization 窗口”这一类场景。
+
+### Why 2：为什么没有构造这类场景？
+
+因为我写 runtime 测试时，主要围绕已知 recoverable 文本错误来测，比如：
+
+- `runtime websocket is not connected`
+
+而不是围绕协议语义来测：
+
+- JSON-RPC error object
+- not materialized yet
+- includeTurns unavailable before first user message
+
+### Why 3：为什么我会更偏向文本错误而不是协议语义？
+
+因为我当时的测试思路还是实现驱动的：
+
+- 代码里正则匹配什么，我就测什么；
+- 代码里已有分支是什么，我就补什么。
+
+这会导致一个问题：
+
+> 测试在证明“当前实现能处理它已经认识的错误”，而不是证明“系统能覆盖完整的协议失效面”。
+
+### Why 4：为什么 fresh thread materialization 这类状态被我漏掉了？
+
+因为我的假设是：
+
+- `turn/start` 成功后，`thread/read(includeTurns=true)` 基本立刻可用。
+
+这个假设在大多数 stub / fake 环境里都成立，所以我没有主动质疑它。
+
+但真实 runtime 明确告诉我们：
+
+- fresh thread 在某个短窗口里，`includeTurns` 可能还不可用。
+
+这说明我之前的测试模型把 thread 生命周期过度理想化了。
+
+### Why 5：为什么最终要等飞书里才看见这个事故？
+
+因为只有真实链路会同时出现这四层组合：
+
+1. 新 thread 刚建好；
+2. poll 立即开始；
+3. 协议返回结构化对象错误；
+4. 后续 turn 其实继续执行并完成。
+
+而本地自测之前从没主动制造过“先误判失败、后真实完成”的窗口，所以系统提前 reject 的问题一直被藏住了。
+
+## 5. 为什么飞书里才暴露
+
+因为飞书现场不是只测 runtime-client 单点，而是把整条链串起来了：
+
+- 用户发消息
+- bridge start thread / turn
+- pollTurnFinalState 立即启动
+- receiver 把 reject 直接翻成用户错误
+- 后面真实的 `turn/completed` 再到来时，已经晚了
+
+在 unit test 里，如果没把这整个序列连起来，只测其中一段，很容易得出“恢复逻辑整体没问题”的错觉。
+
+## 6. 我当时的自测模型哪里不合理
+
+### 6.1 用实现当前认得的错误，代替协议层完整错误面
+
+我测了 regex 已识别的错误，却没测 JSON-RPC object error 的归一化。
+
+### 6.2 把 fresh thread 生命周期理想化了
+
+我默认 `turn/start` 之后就能立即安全 `thread/read(includeTurns=true)`，没有给 materialization 窗口留位置。
+
+### 6.3 没测“过早 reject 后 completed event 迟到”的致命组合
+
+我测了 completed event 与 poll 冲突，但没测：
+
+- poll 先把 turn state finalize 掉；
+- completed event 后到；
+- 结果因为 turn 已被打死，真实完成事实无法再交付。
+
+这恰好就是这次事故的致命点。
+
+### 6.4 没有用户面向断言
+
+之前测试更多断言 runtime 结果对象，而不是最终用户面向输出，所以“用户看到 `[object Object]`”这种问题没有被单独设成红线。
+
+## 7. 后续必须补的测试门禁
+
+针对这个 issue，后续至少必须补：
+
+1. `turn/start` 后首次 `thread/read(includeTurns=true)` 返回 JSON-RPC object error。
+2. 错误内容是 `thread ... is not materialized yet`，并应被判为暂态而不是终态失败。
+3. 结构化错误对象必须被正确归一化，用户绝不能看到 `[object Object]`。
+4. 暂态读错误发生后，系统不得提前记录 `turn_failed`。
+5. 同一轮在暂态错误后 later `turn/completed` 到来时，结果仍应能成功交付。
+6. integration 层必须断言：用户最终看到的是正常 final reply 或明确恢复语义，而不是裸内部错误。
+
+## 8. 以后我的测试纪律要怎么改
+
+以后对 turn 终态相关测试，不能只按“transport 断开 / 超时 / completed conflict”去列，要按 MECE 的终态风险面去列：
+
+- transport 错误
+- protocol 错误
+- thread lifecycle 可见性
+- event vs poll 时序冲突
+- 过早 terminalization
+- 用户出口错误外泄
+
+只有这样，测试才不会一直围着当前实现的小圆圈转。
+
+## 9. 一句话反思
+
+这次不是我没写恢复测试，而是我把“恢复”理解得太像传输层问题，没把 fresh thread 生命周期、协议对象错误和过早终态化当成同一组必须联测的风险面。