work-ally 0.2.0-alpha.1

package/docs/issues/resolved/ANALYSIS-codex-app-server-transport-disconnect-semantics-2026-03-14.md

@@ -0,0 +1,606 @@
+# 分析报告：Codex App Server 断开语义、中间层可靠性边界与 pull-primary 主设计
+
+更新时间：2026-03-15  
+状态：分析完成 / 已归档（主结论已吸收进 runtime recovery 专项）  
+作者：Codex
+
+> 归档说明：这份分析继续保留在 `docs/issues/` 作为问题演进痕迹。与当前实现直接相关、仍需推进的最小闭环，以 `docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md` 为准；其中 runtime abstraction 相关延展已移出本专项，统一以后续独立 spec 为准。
+
+## 0. 给架构师先看
+
+### 0.1 这是什么文档
+
+这是一份面向架构评审的分析报告，讨论 `work-ally` 作为 Feishu 与官方 `Codex app-server` 之间的中间层，为什么会在 runtime transport 抖动时暴露用户可见的不确定性，以及应如何从设计上治理。
+
+它不是代码修复说明，也不是某一次单点 bug 的 patch 设计，而是对中间层可靠性模型的重新定义。
+
+### 0.2 背景一句话
+
+当前系统一旦与 `Codex app-server` 的实时连接发生抖动，就可能无法稳定判断：
+
+- 人类发出的消息是否已经真正进入 Codex thread
+- Codex 已完成的回复是否已经成功回给 Feishu 用户
+- 哪些结果需要补发，哪些结果绝不能重复发
+
+### 0.3 核心判断
+
+这类问题的本质不是“socket 偶尔会断”，而是：
+
+> 中间层把产品正确性建立在一条实时连接的连续观察能力上；连接一抖动，系统就失去对会话事实与交付事实的确定性。
+
+### 0.4 最终建议
+
+主设计应升级为：
+
+> **pull-primary, push-assisted, ledger-backed**
+
+含义是：
+
+- 最终答复和恢复补偿，以主动拉取 Codex 已存储 thread/turn 事实为准
+- 实时推送只承担体验增强和阻塞性交互承接
+- 中间层自己维护 durable ledger，区分执行状态、交付状态和确认状态
+
+### 0.5 架构决策点
+
+如果只让读者记住四件事，应记住：
+
+1. `Codex App Server 已断开` 表示 transport connection 断了，不等于 thread 死亡。
+2. 官方协议同时支持“事件订阅”和“读取已存储 thread”，因此主动拉取补偿是成立的。
+3. 真正的一等问题不是 websocket 还是 stdio，而是有没有 reconciliation 和 delivery ledger。
+4. `stdio` 值得评估，但即使改成 `stdio`，也不能替代 pull-primary 主模型。
+
+### 0.6 术语表
+
+- `transport`：bridge 与 `Codex app-server` 之间的通信通道，当前仓库使用本机 websocket；官方还支持 stdio。
+- `thread`：Codex 侧的一条会话上下文，不等于一个操作系统进程。
+- `turn`：thread 中的一轮请求-处理-完成过程。
+- `item`：turn 内更细粒度的输出或请求单元，例如 agent message、plan、approval request 等。
+- `pull-primary`：最终真相以主动读取已存储 thread/turn 状态为准，而不是以实时事件流为准。
+- `push-assisted`：保留最小化实时事件通道，只承接审批、用户输入等阻塞性交互和必要状态变化。
+- `ledger-backed`：中间层维护 durable ledger，用来判断哪些消息已执行、已交付、需补发、不可重放。
+
+## 1. 文档定位
+
+这份报告是第一份事故报告的上位分析，不再只回答“`Codex App Server 已断开` 到底是什么意思”，而是把整条论证链走完：
+
+1. 这里的“断开”在官方协议和当前实现里到底是什么。
+2. 为什么同机进程之间仍然会发生这类断连。
+3. 为什么这不自动等于 thread 死亡或 turn 失败。
+4. 为什么 `work-ally` 不能把产品正确性建立在一条实时连接上。
+5. 基于官方协议与当前产品诉求，什么才是更合理的主设计。
+
+这份报告与前一份文档的关系是：
+
+- 第一份报告：聚焦 2026-03-14 21:47 的真实 incident、证据链、根因与现有缺口。  
+  文件：`docs/issues/resolved/ANALYSIS-runtime-turn-delivery-and-recovery-2026-03-14.md`
+- 本报告：从 incident 提升到架构层，回答“这类问题在设计上应如何被治理”。
+
+本报告不提交任何代码实现，只给架构判断、协议边界和建议方向。
+
+## 2. 先给最终建议
+
+先写结论，避免读者在细节里迷路。
+
+### 2.1 最终建议
+
+`work-ally` 应把与 `Codex app-server` 的桥接主设计升级为：
+
+> **pull-primary, push-assisted, ledger-backed**
+
+具体含义是：
+
+1. **最终答复与会话正确性以主动拉取为准。**
+2. **实时推送只承担体验增强和阻塞性交互承接，不再承担正确性职责。**
+3. **中间层必须维护自己的 durable ledger，区分执行状态、交付状态与确认状态。**
+
+### 2.2 为什么这才是主设计
+
+因为用户真正需要的不是“实时流永不断”，而是：
+
+- 飞书里的消息不要漏
+- 不要重复发
+- AI 已经完成的回复，即使 transport 抖动后也能补回来
+- 人类已经发给 AI 的消息，不要因为桥接层抖动而神秘消失或重复进入 thread
+
+只要系统仍然把正确性压在一条实时连接上，那么无论底层用 websocket 还是 stdio，本质上都还不够稳。
+
+### 2.3 对 transport 的重新定位
+
+在这个新模型下：
+
+- `stdio` / `websocket` 仍然重要，但它们的重要性从“正确性基石”降为“transport 稳定性与实现复杂度取舍”。
+- 如果只看本机部署，`stdio` 大概率比当前 websocket 更稳。
+- 但就算改成 `stdio`，如果没有 pull-based reconciliation 和 delivery ledger，这类问题仍然只能“少一点”，不能“从设计上收口”。
+
+## 3. 核心问题定义
+
+本报告要回答的核心问题，不是“某个 socket 为什么关了”这么窄，而是下面四个更底层的问题：
+
+1. “`Codex App Server 已断开 / 连接已恢复`”在协议上是什么意思。
+2. 它是否意味着 thread 或 turn 已经挂掉。
+3. 既然底层 thread 有自己的存储与状态，我们是否可以在实时链路不稳时，主动读取并完成补发。
+4. 如果可以，那中间层的主设计是否应该从“等着推”转向“以拉为准”。
+
+用户对产品的真实诉求可以压缩成一句话：
+
+> 作为飞书与 Codex 之间的中间层，系统必须忠实地把 thread 的对话事实反映给人类，而不是把 transport 抖动放大成用户语义不确定。
+
+## 4. 官方协议给出的事实边界
+
+这部分只讲 OpenAI 官方 `Codex App Server` 文档中可直接得到的事实。
+
+### 4.1 app-server 支持两种 transport
+
+官方文档明确写明：
+
+- `stdio`（`--listen stdio://`）是默认 transport，使用 JSONL。
+- `websocket`（`--listen ws://IP:PORT`）是 experimental transport。  
+- 在 websocket 模式下，server 使用 bounded queues；当 ingress 满时，会拒绝新请求并返回 `Server overloaded; retry later.`，客户端应做指数退避重试。 citeturn1view0
+
+这件事的含义非常明确：
+
+1. 当前仓库用 websocket 不是唯一选择。  
+2. 官方自己也没有把 websocket 定义成默认稳定基线。  
+3. transport 本身就是一个有容量、排队与重试语义的工程层，而不是“天然可靠消息总线”。 citeturn1view0
+
+### 4.2 initialize 是 per-connection 握手
+
+官方文档明确写明：
+
+- 每打开一条 transport connection，都必须先发一次 `initialize`。  
+- 然后发 `initialized`。  
+- 在这条连接上，如果未完成初始化就发送其他请求，server 会拒绝。  
+- 同一条连接重复 `initialize` 会返回 `Already initialized`。 citeturn2view0
+
+因此，“连接已恢复”的协议含义不是“旧连接回来了”，而是：
+
+> 建立了一条新的 transport connection，并在这条新连接上重新完成了 app-server 协议握手。 citeturn2view0
+
+### 4.3 thread/start 与 thread/read 是两种不同能力
+
+官方文档明确区分了：
+
+- `thread/start`：创建新 thread，并自动让当前连接订阅该 thread 的 turn/item 事件。  
+- `thread/resume`：继续已有 thread。  
+- `thread/read`：读取已存储 thread，不恢复订阅、不把 thread load 到内存、也不发 `thread/started`。  
+- `thread/read(includeTurns=true)` 可以返回 turn 历史。  
+- 返回的 `thread` 对象带 runtime `status`。 citeturn2view0turn2view1
+
+这意味着协议天然支持两种访问模式：
+
+1. **在线订阅模式**：等 server 往当前连接推事件。  
+2. **存量读取模式**：客户端按需主动读取 thread 当前已存储的事实。 citeturn2view0turn2view1
+
+### 4.4 thread 的 runtime status 独立于 transport connection
+
+官方文档说明：`thread/read` 返回的 `thread.status` 可能是：
+
+- `notLoaded`
+- `idle`
+- `systemError`
+- `active`，并可带 `activeFlags`，例如 `waitingOnApproval`。 citeturn2view1turn2view4
+
+文档还给出：
+
+- `thread/loaded/list` 返回当前内存中已加载的 thread ids。  
+- `thread/unsubscribe` 只是取消当前连接对某个 thread 的订阅；如果这是最后一个 subscriber，server 才会 unload thread，并发 `thread/closed`。 citeturn2view5turn2view7
+
+因此，transport connection、thread 是否 loaded、thread 是否 active / idle，是三个相关但不等价的概念。socket 断开并不自动等于 thread 死亡。 citeturn2view1turn2view5turn2view7
+
+### 4.5 turn/item 的权威终态来源
+
+官方文档明确写明：
+
+- `turn/start` 响应会立即返回初始 `turn`，其中已经包含 `turn.id`，初始状态为 `inProgress`。  
+- `turn/completed` 是 turn 的终态通知，`turn.status` 可为 `completed`、`interrupted` 或 `failed`。  
+- `item/completed` 提供 item 的 final state，并且官方明确要求把它视为 authoritative state。  
+- `item/agentMessage/delta`、`plan` 增量等属于流式过程。 citeturn3view0turn2view2turn2view3
+
+因此一个成熟的中间层不应只依赖流式 delta，而应围绕：
+
+- `thread.id`
+- `turn.id`
+- `item.id`
+- `turn/completed`
+- `item/completed`
+
+构造自己的 durable delivery model。 citeturn3view0turn2view2turn2view3
+
+### 4.6 审批与用户输入是 server-initiated request 语义
+
+官方文档明确写明：
+
+- 命令审批、文件变更审批由 server 主动向 client 发 JSON-RPC request。  
+- client 响应后，server 通过 `serverRequest/resolved` 确认请求已被回答或被清理。  
+- `tool/requestUserInput`、动态工具调用也遵循类似的 server-initiated request 模型。 citeturn2view3turn2view6turn3view2
+
+这意味着：
+
+- 有些语义适合靠主动拉取补偿，例如 turn 最终回复。  
+- 有些语义天然更依赖在线 request channel，例如审批 prompt、用户输入请求细节。 citeturn2view3turn2view6turn3view2
+
+## 5. 当前仓库的实现模型
+
+这一部分只回答“`work-ally` 现在到底怎么接 app-server”。
+
+### 5.1 app-server 现在是后台独立进程，不是 bridge 子进程
+
+仓库当前通过 shell 层以 `nohup` 方式启动：
+
+- `codex app-server --listen "$CODEX_LISTEN"`
+
+然后 bridge 再根据配置里的 `listenUrl` 去连接该地址。证据位置：
+
+- `internal/modules/runtime/start.sh`
+- `internal/modules/runtime/supervisor.sh`
+- `bridge/src/config.ts`
+- `bridge/src/server.ts`
+
+所以当前运行模型是：
+
+- 一个长期后台 app-server 进程  
+- 一个独立 bridge 进程  
+- 两者通过 loopback websocket transport 通信
+
+这不是“同进程内函数调用”，而是一条真正的本地 socket 会话。
+
+### 5.2 当前 bridge 如何定义“断开”
+
+在 `bridge/src/runtime-client.ts` 里：
+
+- `connect()` 使用 `new WebSocket(this.listenUrl)` 建连。  
+- websocket 一旦 `close`，就进入 `handleSocketClosed('runtime websocket closed')`。  
+- `handleSocketClosed()` 会：
+  - 记录 `connect_closed`
+  - 清掉当前 socket 引用
+  - reject 所有 pending request
+  - reject 所有活动 turn
+  - 若不是手动断开，则安排自动重连
+
+因此当前实现里“已断开”的直接语义是：
+
+> bridge 这边持有的那条 websocket 会话结束了，基于该连接等待中的请求与 turn 跟踪需要进入恢复逻辑。
+
+### 5.3 当前 bridge 如何定义“恢复”
+
+当前实现里，重连成功后会在新 socket 上重新执行 `initialize()`；若此前经历过 reconnect 流程，就发出 `reconnected` 事件。
+
+因此当前实现里的“连接已恢复”只表示：
+
+> 新 transport 已连通，握手已完成，bridge 又可以继续和 app-server 通信了。
+
+它并不自动保证：
+
+- 断线期间漏掉的事件已经重放  
+- 旧 turn 的最终结果已经被正确识别  
+- 飞书侧已经和 Codex thread 自动对齐
+
+## 6. 第一性原理：问题本质不是“断了”，而是“失去确定性”
+
+如果只从第一性原理看，这类问题的本质不是“socket 断了”本身，而是：
+
+> 中间层把会话正确性建立在一条在线 transport 的连续观察能力上；一旦观察中断，系统就失去了对‘已经发生了什么、已经转达了什么、还缺什么’的确定性。
+
+把问题拆开，会发现至少有三层真相：
+
+1. **执行真相**：Codex thread / turn / item 实际发生了什么。  
+2. **交付真相**：这些事实有没有成功传给飞书中的人。  
+3. **确认真相**：飞书里的人发来的消息，有没有真正进入 Codex thread。  
+
+当前问题之所以让用户尴尬，不是因为 transport 抖动本身不可接受，而是因为一旦抖动，系统就无法稳定回答下面这些问题：
+
+- 这轮 turn 到底完成了吗？
+- 已完成的回复到底有没有发到飞书？
+- 飞书里的那条消息到底有没有成功送进 Codex？
+- 如果没有送进，应该补送；如果已经送进，就绝不能重复送。
+
+所以这类问题的深层根因，不是“网络会断”，而是：
+
+> 中间层还没有形成一套不依赖实时连接连续性的 durable truth model。
+
+## 7. 为什么“同一台电脑”仍然会断
+
+用户对这点的直觉疑惑是合理的，但工程上并不矛盾。
+
+### 7.1 同机不等于无连接状态机
+
+只要是：
+
+- 两个独立进程
+- 中间通过 `127.0.0.1:PORT` 上的 websocket 会话通信
+
+那它就是一个有完整生命周期的连接：
+
+- 建连
+- 握手
+- 收发帧
+- close
+- 重连
+
+“在一台机器上”只能减少外部网络因素，不会消灭 transport 自身的生命周期。
+
+### 7.2 当前架构里至少有四类断点
+
+当前模型下，以下任一层都可能导致“connection closed”：
+
+1. app-server 进程退出、重启或主动关闭连接  
+2. bridge/client 侧超时、异常、清理或主动关闭  
+3. runtime supervisor / allocator 重新分配监听地址  
+4. websocket transport 自身的容量、队列与实验性实现边界
+
+因此，单靠一句 `runtime websocket closed` 现象日志，不能负责任地说一定是谁的锅。
+
+### 7.3 断开不自动等于 thread 挂掉
+
+按照官方协议，必须把以下几件事分开判断：
+
+1. app-server 进程是否还活着  
+2. thread 是否仍 loaded  
+3. turn 是否仍在执行或已经终态  
+4. 当前 transport 是否还连着
+
+只有这样，才能避免把“连接断了”误判成“任务没了”。
+
+## 8. 为什么 push-only 模型不再成立
+
+当前桥接更接近一种 push-first 设计：
+
+- transport 在线时，依赖 `turn/*`、`item/*`、approval request 等事件流推进状态
+- 断线后，再用少量 `thread/read` 和本地内存状态做补救
+
+这个模型在“连接持续稳定”时可以工作，但它有两个结构性缺陷。
+
+### 8.1 push-only 把在线事件流误当成唯一真相
+
+一旦某个关键事件没到，系统就容易掉进歧义区：
+
+- turn 没完成
+- 还是完成了但通知没送到
+- 还是已经完成但飞书没投递成功
+- 还是其实结果已经送达，只是本地状态没记录下来
+
+如果没有独立 ledger，系统只能猜。
+
+### 8.2 push-only 让 transport 抖动直接伤害用户语义
+
+用户并不关心 websocket 是不是一度 closed；用户关心的是：
+
+- “我刚才那句话到底有没有送到 AI？”
+- “AI 刚才那轮到底有没有答完？”
+- “如果答完了，为什么飞书里没看到？”
+
+只要系统无法用持久化事实回答这三个问题，产品就仍然是脆弱的。
+
+## 9. 为什么 pull-primary 是值得确立的主设计
+
+这是本报告的主结论。
+
+### 9.1 你们的产品目标不需要实时流承担正确性
+
+用户已经明确表达：产品不以极低延迟为核心目标，晚几秒可接受；真正重要的是不中断、不漏消息、不断言错误。
+
+在这种产品目标下，把“最终答复”主路径改成主动拉取，是非常自然的选择。
+
+### 9.2 官方协议天然支持“主动拉取最终真相”
+
+因为官方已经给出了：
+
+- `turn/start` 返回初始 `turn.id`  
+- `thread/read(includeTurns=true)` 返回历史 turns  
+- `thread.status` 告诉你当前线程是 `active`、`idle`、`notLoaded` 还是 `systemError`  
+- `turn/completed` 和 `item/completed` 给出终态语义
+
+所以中间层完全可以这样工作：
+
+1. 收到飞书用户消息  
+2. 启动 turn，拿到 `turn.id`  
+3. 不把流式 delta 当最终依据  
+4. 轮询 `thread/read(includeTurns=true)` 直到该 turn 进入终态  
+5. 再根据 ledger 决定是否向飞书发送最终答复或失败状态
+
+在这个模型里，实时流断一下不再是致命问题，因为最终真相可以主动读取。
+
+### 9.3 pull-primary 更符合“忠实转达”的中间层定位
+
+如果站在“快递员”这个比喻上看：
+
+- push-only 像是“边走边喊，喊漏了就容易说不清”  
+- pull-primary 像是“最终一定回仓库核对签收单，再决定哪些要补派、哪些已签收不能重派”
+
+对飞书这种异步人类入口来说，后者显然更符合产品责任。
+
+## 10. 为什么不是 pure pull
+
+虽然我建议把主设计切到 pull-primary，但我不建议把整个系统做成完全不依赖推送的 pure pull。
+
+### 10.1 最终答复适合拉
+
+以下内容很适合做成主动拉取驱动：
+
+- turn 是否完成  
+- 最终回复文本  
+- turn 失败 / 中断终态  
+- thread 当前是否仍 active / idle / notLoaded  
+- 某个最终 item 的 authoritative state
+
+这些都属于稳定终态事实。
+
+### 10.2 阻塞性交互不适合纯拉
+
+审批、文件变更审批、`tool/requestUserInput`、动态工具调用这类 server-initiated request，本质上是“server 正在向 client 要一个交互决策”。
+
+目前官方文档并没有提供一个对等的“拉取所有待审批请求详情”的通用 inbox 接口；它提供的是：
+
+- request 通过实时流发出  
+- `thread/status/changed` 可能告诉你正在 `waitingOnApproval` 或 `waitingOnUserInput`  
+- `serverRequest/resolved` 告诉你该请求已被回答或被清理
+
+因此，纯拉模型虽然能知道“线程卡住了”，但不一定能完整还原“该向用户展示什么审批 prompt、有哪些按钮、上下文是什么”。
+
+### 10.3 正确取舍是 push-assisted
+
+所以更合理的设计不是 pure pull，而是：
+
+- **pull-primary**：最终答复、最终状态、恢复对账以主动拉取为准  
+- **push-assisted**：审批、用户输入请求、必要状态变更提示仍通过在线事件通道承接
+
+这样既不会把正确性押在实时流上，也不会把协议原生的交互能力做残。
+
+## 11. 为什么 ledger-backed 是不可跳过的一层
+
+这是比 transport 选择更关键的部分。
+
+### 11.1 没有 ledger，pull 只能“看见”，不能“对账”
+
+主动拉取只能让你看到 Codex 里发生了什么，但它不能自动告诉你：
+
+- 哪条结果已经回给飞书了  
+- 哪条结果虽然完成了，但还没回给飞书  
+- 哪条飞书消息已经成功进入对应 turn 了  
+- 哪条飞书消息只是在 bridge 侧看见了，但从未真正启动 turn
+
+这些都必须由中间层自己持久化。
+
+### 11.2 至少需要两本账
+
+最小可用模型至少要有两本 durable ledger。
+
+#### A. 入站确认账本
+
+把下面这些关系持久化下来：
+
+- `feishu_inbound_message_id`
+- `conversationRef`
+- `threadId`
+- `turnId`
+- `accepted_at`
+- `execution_status`
+
+它回答的问题是：
+
+- 这条飞书消息到底有没有成功进入 Codex thread  
+- 如果没有进入，是否允许恢复后重放  
+- 如果已经绑定到某个 `turnId`，则绝不能重复重放
+
+#### B. 出站交付账本
+
+把下面这些关系持久化下来：
+
+- `threadId`
+- `turnId`
+- `itemId`（如果需要更细粒度）
+- `result_kind`（final reply / failure / interrupted / approval prompt / user-input prompt）
+- `feishu_outbound_message_id`
+- `delivery_status`（pending / delivered / failed / superseded）
+
+它回答的问题是：
+
+- Codex 已经产出的哪条结果还没有回给飞书  
+- 哪条已经回了，不应再补发  
+- 哪条因为飞书投递失败，需要恢复后重试
+
+### 11.3 这才是“忠实转达”的核心
+
+只有把执行状态和交付状态分开，中间层才真正称得上是在“忠实反映 thread”，而不是在“在线转发好运时就成功”。
+
+## 12. transport 在新模型下该怎么重新看
+
+### 12.1 websocket 现在的问题是什么
+
+当前 websocket 模型的问题，不只是它会断，更重要的是：
+
+- 它被产品无意中提升成了正确性的唯一在线入口  
+- 一旦它抖动，系统就失去会话确定性  
+- 用户可见语义被迫跟着 transport 状态抖动
+
+### 12.2 stdio 值得认真评估，但它不再是“唯一主角”
+
+在 pull-primary + ledger-backed 的新模型下，`stdio` 依然值得认真评估，理由有三点：
+
+1. 官方把它定义为默认 transport。  
+2. 它更适合本机单 bridge + 单 app-server 的父子进程模型。  
+3. 它可以减少 loopback socket、端口与 websocket 生命周期的一层复杂度。 citeturn1view0
+
+但这里的关键变化是：
+
+> 即使最终改成 stdio，它也只是让在线通道更稳，而不是替代 reconciliation 和 ledger。
+
+这意味着 transport 讨论被放回了正确位置：
+
+- 它重要  
+- 但它不再是产品正确性的唯一基石
+
+### 12.3 一个务实判断
+
+如果后续架构只允许本机部署、bridge 与 app-server 一一对应，我会建议把 `stdio` 作为优先评估方向；如果保留当前 daemon 化模型或有远程接入诉求，websocket 仍可能有部署便利性。但无论选哪种，都不应再做 push-only。 citeturn1view0turn2view0
+
+## 13. 建议的系统形态
+
+如果把本报告的结论压缩成一个产品级运行模型，它应当长这样：
+
+### 13.1 主路径
+
+1. 飞书来消息。  
+2. bridge 先把入站消息落到入站确认账本。  
+3. bridge 成功启动 turn 后，拿到 `turnId` 并绑定到账本。  
+4. 之后不以实时 delta 为最终真相，而是主动拉取 `thread/read(includeTurns=true)`。  
+5. 一旦确认 turn 终态，先把结果落到出站交付账本，再向飞书发送。  
+6. 若飞书发送失败，账本保留 `pending/failed`，恢复后继续补发。
+
+### 13.2 辅路径
+
+1. 保留最小化的 push 通道接收审批、用户输入请求、必要 status 变化。  
+2. 这些 server-initiated request 仍按在线交互处理。  
+3. 如果连接抖动，至少能根据 `thread.status.activeFlags` 判断线程是否卡在等待人工决策状态。  
+4. 后续若官方补出可枚举的 pending request 读取接口，再评估是否进一步降低对 push 的依赖。 citeturn2view4turn2view6turn3view2
+
+### 13.3 用户语义
+
+在这个系统里，用户看到的文案与行为也应重构：
+
+- 不再把“socket 断开”直接表达成“任务可能没了”  
+- 更准确地表达为“系统正在重新确认这一轮结果”  
+- 若 turn 终态已在 Codex 中落定但未发送到飞书，则自动补发  
+- 只有在无法证明消息已进入 turn、也无法自动恢复时，才要求用户重发
+
+## 14. 回答用户最关心的那个根问题
+
+把整份报告压缩成一句最重要的话：
+
+> 这类问题真正要解决的，不是“让实时连接永远不断”，而是“即使实时连接断了，中间层仍然能靠主动拉取和 durable ledger，把 Codex thread 的事实忠实、去重、可补偿地反映给飞书里的用户”。
+
+换句话说：
+
+- 如果 `work-ally` 继续做成“脆弱的实时转发器”，那它确实站在不稳的基石上。  
+- 如果 `work-ally` 升级成“以主动拉取确认最终真相、以账本保证不漏不重、以最小推送承接阻塞交互的可靠语义层”，那它就是有产品意义的，而且这正是它存在的价值。
+
+## 15. 最终建议清单
+
+最后给出可供架构师直接使用的结论清单。
+
+1. 不再把“实时推送不断”作为产品正确性的前提。  
+2. 把最终答复与恢复补偿主路径切到 `pull-primary`。  
+3. 保留最小化 `push-assisted` 通道，只承接审批、用户输入请求和必要状态变化。  
+4. 明确建设两本 durable ledger：入站确认账本与出站交付账本。  
+5. 把 websocket / stdio 的讨论放回 transport 基线问题，而不是正确性基石问题。  
+6. 若后续部署形态允许，认真评估把本机默认 transport 从 websocket 调整为 stdio。  
+7. 用户文案与恢复语义同步升级，减少“连接断开 = 任务失败”的误导表达。
+
+## 16. 参考材料
+
+### 16.1 官方文档
+
+- OpenAI Developers: `Codex App Server`
+  - `https://developers.openai.com/codex/app-server`
+
+### 16.2 仓库实现证据
+
+- `/Users/allenfeng/Development/Repositories/work-ally/internal/modules/runtime/start.sh`
+- `/Users/allenfeng/Development/Repositories/work-ally/internal/modules/runtime/supervisor.sh`
+- `/Users/allenfeng/Development/Repositories/work-ally/bridge/src/config.ts`
+- `/Users/allenfeng/Development/Repositories/work-ally/bridge/src/server.ts`
+- `/Users/allenfeng/Development/Repositories/work-ally/bridge/src/runtime-client.ts`
+
+### 16.3 前序 incident 报告
+
+- `/Users/allenfeng/Development/Repositories/work-ally/docs/issues/resolved/ANALYSIS-runtime-turn-delivery-and-recovery-2026-03-14.md`