work-ally 0.2.0-alpha.1

package/docs/issues/README.md

@@ -0,0 +1,10 @@
+# Issues
+
+`docs/issues/` 用来放问题调查、事故分析和问题演进材料。
+
+从现在开始，这里分成两层：
+
+- `pending/`：还没真正修完、后续仍要继续推进落地的问题
+- `resolved/`：已经完成收口，保留作问题演进痕迹和历史证据
+
+当前应优先关注 `pending/`。只有当实现、验证和文档都收口后，才应把对应材料移入 `resolved/`。

package/docs/issues/pending/ANALYSIS-ally-premature-recovery-notice-and-task-state-semantics-2026-03-18.md

@@ -0,0 +1,295 @@
+# 分析报告：Ally 首轮误发 recovery notice 与“任务状态”语义偏厚问题
+
+更新时间：2026-03-18  
+状态：待修复 / 待收口  
+作者：Codex
+
+## 1. 这份报告回答什么
+
+这份文档回答两个直接相关的问题：
+
+1. 为什么 `Ally` 在 2026-03-18 14:40 左右，刚启动后收到第一条消息，就立刻向用户发出：
+   `【系统消息】 当前任务状态暂未确认，正在继续核对这一轮结果。`
+2. `work-ally` 当前是否引入了一层不必要的“任务状态”用户语义；如果是，它和官方 Codex App Server 推荐的原语之间到底是什么关系。
+
+这不是单纯排查一句文案，也不是单纯排查一个竞态 bug。
+
+这次问题同时暴露了两层缺口：
+
+- 一层是实现缺口：bridge 在 turn 刚启动后的极短窗口内，过早把一次暂态对账失败升级成了 recovery notice。
+- 一层是产品语义缺口：bridge 仍在用“任务状态”这类本地二次解释去面向用户表达协议事实，这与“克制中间层、尽量贴近官方 App Server 原语”的方向存在张力。
+
+## 2. 背景问题
+
+用户当前对 `work-ally` 的核心诉求很明确：
+
+- 只做非常克制的中间层。
+- 重点负责“人 <-> Codex”之间消息往返的稳定转交。
+- 允许保留少量必要中间能力，例如自动审批、补拉最终结果、必要重发提示。
+- 不希望 bridge 变成一套自作主张的任务引擎，也不希望引入一层难以和官方文档对齐的厚语义。
+
+在这个背景下，`Ally` 启动后第一句就收到“当前任务状态暂未确认”，会让人自然质疑两件事：
+
+1. 这是不是一个真实故障。
+2. bridge 是否已经越过“协议事实转发器 + 最小编排器”的边界，开始替用户解释一套自己的“任务状态”。
+
+## 3. 官方原语与我们当前说法的关系
+
+先把官方模型说清楚。
+
+根据 OpenAI 官方 `Codex App Server` 文档与《Unlocking the Codex harness》一文，客户端真正需要围绕的是这些原语：
+
+- `thread`
+- `turn`
+- `item`
+- `thread.status`
+- `turn.status`
+- server-initiated request（例如 approval）
+
+官方对 conversation primitives 的定义是：
+
+- `item` 是原子输入输出单元，具有 `item/started`、可选 `item/*/delta`、`item/completed` 生命周期。
+- `turn` 是由用户输入触发的一次 agent 工作单元。
+- `thread` 是可持久化的会话容器，持有多个 turn。
+
+官方还明确说明：
+
+- `thread/read(includeTurns=true)` 可以读取线程与 turn 历史。
+- `thread.status` 是 runtime status，类型是 `notLoaded`、`idle`、`systemError`、`active`；如果是 `active`，可能带 `activeFlags`，例如 `waitingOnApproval`。
+- `turn/completed` 才携带 turn 的最终状态，终态是 `completed`、`interrupted`、`failed`。
+- 审批这类 server request 会暂停 turn，直到客户端回复。
+
+重要的是：
+
+> 官方协议里没有一个独立命名、独立建模的“任务状态（task state）”原语。
+
+因此，bridge 当前面向用户说的“当前任务状态暂未确认”，并不是官方 App Server 原生状态；它只是我们拿 `thread.status`、`turn` 终态对账结果、以及本地 recovery 判断，二次翻译出来的一句中文。
+
+这件事本身不一定绝对错误，但它说明我们当前前台语义已经不再是“直接贴协议事实”，而是“在协议事实之上加了一层本地产品解释”。
+
+## 4. 现场证据
+
+### 4.1 事件时间与对象
+
+- 助理：`Ally`
+- 办公桌：`/Users/allenfeng/.work-ally/assistants/Ally`
+- 会话：`feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8`
+- 本地时间：2026-03-18 14:40 左右（Asia/Shanghai）
+- 对应日志时间：`2026-03-18T06:40Z`
+
+### 4.2 bridge 日志事实链
+
+`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/bridge-2026-03-18.log`
+
+关键事实如下：
+
+1. `06:40:33Z`，bridge 收到用户消息：`你还在吗？好久不见，最近这个项目有什么新的进展？`
+2. `06:40:37.186Z`，turn 正常启动。
+3. `06:40:37.712Z`，仅约 0.5 秒后，bridge 记录：
+   `runtime turn reconciliation failed: idle thread without completed turn event (...)`
+4. 同一时刻，receiver 进入 `turn_recovery_attempt`。
+5. 紧接着，bridge 向前台发送了一条系统消息；这条消息对应的文案就是：
+   `当前任务状态暂未确认，正在继续核对这一轮结果。`
+6. 但 `06:41:07.638Z`，真正的 `runtime.turn_completed_event` 到达，状态是 `completed`。
+7. `06:41:08.134Z`，bridge 记录 `receiver.turn_recovered`。
+8. `06:41:09.478Z`，最终回复成功送达前台。
+
+这条事实链说明：
+
+- 这轮 turn 并没有真正失败。
+- 前台收到 recovery notice 时，bridge 只是“本地暂未对账成功”，不是 Codex App Server 已经宣告 turn 失败。
+- 这句系统消息不是来自官方 turn 终态，而是来自 bridge 本地 recovery 分支。
+
+### 4.3 持久化 turn 记录事实
+
+`/Users/allenfeng/.work-ally/assistants/Ally/.system/runtime/sessions/feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8/turns/2026-03-18T06-40-37-186Z-019cffac-bf45-7c13-93d3-c574ac4bdc88.json`
+
+该文件最终记录的是：
+
+- `status: completed`
+- `completedAt: 2026-03-18T06:41:08.136Z`
+
+也就是说，持久化真相明确表明：
+
+> turn 最终完成了。
+
+因此，14:40 用户看到的那句系统消息，描述的不是 turn 的真实最终状态，而是 bridge 在 recovery 过程中的一个过早、过度外显的中间判断。
+
+### 4.4 代码层证据
+
+相关代码位置：
+
+- `bridge/src/runtime-client.ts`
+- `bridge/src/receiver.ts`
+- `bridge/src/translator.ts`
+
+当前实现链路如下：
+
+1. `runtime-client.ts` 在 `pollTurnFinalState()` 中，如果 thread 已经进入 `idle`，但本地还没有拿到 `completedEventResult`，就会抛出：
+   `runtime turn reconciliation failed: idle thread without completed turn event (...)`
+2. `receiver.ts` 捕获到这类错误后，会进入 `turn_recovery_attempt`。
+3. 在 recovery attempt 开始时，receiver 会主动往前台发一条 `progress_update`。
+4. 这条 `progress_update` 的文本定义在 `translator.ts`，固定就是：
+   `当前任务状态暂未确认，正在继续核对这一轮结果。`
+
+所以这条系统消息的触发条件，不是官方协议里出现了某个“task state = unknown”，而是：
+
+> 我们自己的 runtime-client 在某个时间窗内，没有拿到足够的终态证据，于是本地转入 recovery path，并主动向用户暴露了一条自己翻译出来的状态文案。
+
+## 5. 我的思考
+
+### 5.1 这次 bug 真正是什么
+
+这次 bug 不是 transport 真断了，也不是 Codex 真告诉用户“任务状态不明”。
+
+它本质上是：
+
+- turn 刚启动。
+- bridge 很快看到 thread 落到 `idle`。
+- 但 `turn/completed` 事件还没来，或还没被本地拿到。
+- bridge 过早把这一瞬间解释成“终态待恢复”。
+- 于是前台先收到一条恢复型系统消息。
+- 几十秒后，turn 其实又正常完成并送达了。
+
+所以从第一性原理看，这是一种**过早 recovery 可见化**问题。
+
+更准确地说：
+
+> 本地对账机制本来是为了提升可靠性，但它在一个很短的正常时序抖动窗口里，被过早上升成了用户可见语义。
+
+### 5.2 “任务状态”是不是必要概念
+
+我的判断是分两层。
+
+第一层，内部实现层：
+
+- 需要有最小 execution / delivery / recovery 状态。
+- 需要有 ledger。
+- 需要区分 `pending_recovery`、`delivery_unavailable`、`recovery_required` 等内部事实。
+
+这层是必要的，因为它支撑稳定补偿、补读、补发，不应轻易删除。
+
+第二层，用户语义层：
+
+- “任务状态”这个说法不属于官方协议原语。
+- 它会把 bridge 自己的对账不确定性，包装成“Codex 的任务状态”。
+- 这容易让用户误以为自己看到的是一条权威协议事实。
+
+这层我认为不必要，至少不应该成为默认用户词汇。
+
+更克制的做法应该是：
+
+- 内部继续保留 recovery / ledger。
+- 前台尽量只暴露协议事实本身，或者只暴露最小动作提示。
+
+### 5.3 前台到底应该暴露什么
+
+我认为前台可以分成三类信息。
+
+第一类：用户必须立刻行动的。
+
+- 等审批
+- 等补充输入
+- 明确需要重发上一条消息
+
+这类应该保留，而且可以直接对齐官方 `waitingOnApproval` 等事实。
+
+第二类：最终失败且无法自动补偿的。
+
+- 例如补拉失败，bridge 无法证明这轮是否已完成，只能要求用户重发
+
+这类也应保留。
+
+第三类：bridge 自己正在内部补对账的短暂过程。
+
+- 例如这次 14:40 这种，最终几十秒后自己恢复并补齐了结果
+
+这类默认不应前台外显，至少不应立刻外显。
+
+如果真的必须外显，也应尽量贴近协议与实现事实，比如：
+
+- `reconciling latest turn result`
+- `recovering final turn result`
+
+而不是说成“当前任务状态暂未确认”。
+
+因为后者已经是一层偏厚的解释。
+
+## 6. 最终合理的修改建议
+
+下面的建议分成“必须改”和“应该收口”两层。
+
+### 6.1 必须改：修掉这次首轮误发 recovery notice 的 bug
+
+目标不是删 recovery，而是避免它在正常短时序抖动窗口里过早前台可见。
+
+建议：
+
+1. 保留内部 `pending_recovery` / `recoverTurnResult` / ledger。
+2. 收紧 fresh turn 启动后的 recovery 触发条件，不要在 turn 刚启动后的极短窗口里，仅凭一次 `idle + 无 completedEventResult` 就立刻发前台 notice。
+3. 优先等待更可靠的 turn 终态证据，再决定是否对用户可见。
+4. 将“开始 recovery”与“需要前台提示”拆成两个阶段：
+   - 内部先 recovery
+   - 只有超出短暂窗口仍未收敛，才考虑用户可见化
+
+这样改动不会损害稳定性骨架，反而会减少误报。
+
+### 6.2 应该收口：去掉默认用户语汇里的“任务状态”
+
+建议默认不再用：
+
+- `当前任务状态暂未确认`
+- `当前任务状态待确认`
+
+原因很简单：
+
+- 它们不是官方协议原语。
+- 它们混淆了 bridge 内部对账状态与 Codex 的 thread / turn 事实。
+- 它们让中间层看起来像“任务裁判”，而不是“协议事实转发器 + 最小编排器”。
+
+### 6.3 应该保留：内部稳定性机制不要因为收薄语义而被误删
+
+本次收口不应动这些底层能力：
+
+- `thread/read(includeTurns=true)` 的 pull-primary 对账
+- inbound / turn / delivery ledger
+- `delivery_unavailable` 后续补发
+- waiting approval / waiting user input 承接
+- `recovery_required` 时的明确用户兜底
+
+原因是：
+
+> 我们要收薄的是“用户语义层”，不是“可靠性交付层”。
+
+### 6.4 推荐的前台暴露原则
+
+后续用户可见语义建议统一按下面原则约束：
+
+1. 能直接对应官方协议事实的，优先直接对应，不额外翻译厚化。
+2. 不需要用户行动的短暂内部恢复过程，默认静默。
+3. 只有以下两类事情值得主动打断用户：
+   - 需要用户立刻动作
+   - 已确认无法自动恢复，需要用户补救
+4. 若确实要暴露中间恢复过程，使用贴协议、贴实现事实的表述，不使用“任务状态”这种二次抽象。
+
+## 7. 一句话结论
+
+这次 14:40 的问题，表层是一个 recovery notice 误触发 bug；深层是 bridge 仍保留了一层偏厚的“任务状态”前台语义。
+
+合理的修正方向不是削掉内部稳定性机制，而是：
+
+> 保留最小 recovery / ledger 骨架，修掉误触发，把默认前台语言从“任务状态”收回到更克制、更贴官方 App Server 原语的表达。
+
+## 8. 相关材料
+
+仓库内相关材料：
+
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+- `docs/issues/resolved/ANALYSIS-runtime-turn-delivery-and-recovery-2026-03-14.md`
+- `docs/issues/resolved/ANALYSIS-codex-app-server-transport-disconnect-semantics-2026-03-14.md`
+
+外部参考：
+
+- OpenAI Developers: `Codex App Server`
+- OpenAI Engineering: `Unlocking the Codex harness: how we built the App Server`