work-ally 0.2.0-alpha.1

package/docs/completed/SPEC-faithful-bridge-core-thinning.md

@@ -0,0 +1,1071 @@
+# SPEC: 忠实中间层收边界与核心瘦身重构
+
+更新时间：2026-03-20  
+状态：Completed  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md`
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-runtime-connection-and-turn-recovery-semantics.md`
+- `README.md`
+- OpenAI Codex App Server docs: `https://developers.openai.com/codex/app-server`
+- OpenAI blog: `https://openai.com/index/unlocking-the-codex-harness/`
+
+## 1. Summary
+
+这份 spec 要解决的不是“再做一轮稳定性 patch”，而是把 `work-ally` 的中间层重新收回到一个更忠实、更克制的边界：
+
+> `work-ally` 的 bridge 默认应是 **Feishu <-> Codex App Server 的稳定双向桥梁 + 最小必要补偿层**，而不是自带一整套会话任务脑的本地系统。
+
+过去几轮实现里，`work-ally` 为了解决真实稳定性问题，逐步长出了 `turn ledger`、`pending_recovery`、`superseded`、`supervisor`、`work_session ownership` 等能力。这些能力里有些是稳定桥梁必须的，有些则已经超出“忠实中间层”边界，开始混入更厚的产品系统语义。
+
+本次 spec 的目标是在**不降低当前产品稳定性**的前提下，做一次结构性重构：
+
+1. 明确什么是 bridge 核心，什么只是外围产品层
+2. 保留真正必要的稳定性骨架
+3. 收掉 bridge 自己创造的过厚会话语义
+4. 把已经失控的大文件拆回清楚模块，让边界在代码结构上真正可见
+5. 让后续代码、测试、文档都围绕同一条“忠实中间层”边界继续演进
+
+这不是“删功能式瘦身”，而是一次**守住底线的减法重构 + 模块化重构**。
+
+## 2. 背景
+
+结合官方 Codex App Server 文档和当前实现，可以先确认三件事：
+
+1. 官方已经给出了稳定、UI-friendly 的协议面：双向 JSON-RPC、默认 `stdio`、线程状态、turn 控制、审批 / user-input 请求、`thread/read` 等事实源。
+2. `work-ally` 不需要再造一个任务引擎；它首先应该忠实承接官方协议原语，再做最小必要的交付补偿。
+3. 但“上游 runtime 稳定”并不自动等于“Feishu 消息链路天然不会丢、不重、不乱序”；桥层仍需要一定的最小补偿机制。
+
+当前项目里已经形成一个较清楚的共识：
+
+- 中间层最本质的职责，就是两次稳定转交
+  - 从 Feishu 到 Codex
+  - 从 Codex 到 Feishu
+- 默认不要把 bridge 做成第二个脑
+- 只有当用户必须行动，或系统必须诚实告知无法继续时，中间层才应该显式出声
+
+问题在于，当前代码结构里“必要补偿”与“额外产品系统层”已经混在一起：
+
+- 有些能力确实是桥必须承担的，例如 final reply 补发
+- 有些能力已经进入更厚的本地语义，例如丰富的 turn lifecycle ledger
+- 还有些能力并不是 bridge 核心，而是围绕 desk / multi-surface / ops 的外围产品层
+
+结果是：
+
+- 代码量显著变厚
+- 核心边界不再一眼清楚
+- 若核心逻辑长期集中在 900 ~ 2400 行级别的大文件里，边界会继续被文件体积掩盖
+- 后续每次加功能都更容易继续往 bridge 里塞语义
+
+## 3. 问题定义
+
+当前系统的核心问题不是“有几个模块写大了”，而是边界漂移。
+
+### 3.1 bridge 核心与外围产品层混在一起
+
+当前 `bridge/src/` 里混合了至少四类东西：
+
+1. 协议转接
+2. 最小交付补偿
+3. 会话控制与恢复语义
+4. 多表面 / desk / ops / archive 等外围产品能力
+
+这会直接导致一个认知问题：
+
+> 工程上无法一眼回答“哪些模块属于忠实中间层核心，哪些只是顺手堆进去的产品层”。
+
+### 3.2 会话真相模型长得过厚
+
+当前实现不是只维护最小的 `conversation -> thread` 绑定，而是额外维护：
+
+- inbound acceptance ledger
+- turn execution ledger
+- `pending_recovery`
+- `recovery_required`
+- `superseded`
+- delivery ledger
+
+这里面有一部分对稳定性有帮助，但整体已经超过“最小 bridge state”的合理范围，开始变成桥自己维护的一套 turn 生命周期系统。
+
+### 3.3 恢复语义和交付补偿没有彻底分层
+
+“确认最终态”和“补发最终结果”是两类不同问题：
+
+- 最终态确认：用官方事实源确认 Codex 到底结束在哪个状态
+- 渠道交付补偿：Codex 已完成，但 Feishu 没稳定收到
+
+当前实现里，这两类语义都被包进较厚的 recovery / ledger 逻辑里，增加了维护负担，也放大了桥层自创状态的数量。
+
+### 3.4 生命周期编排已经超出桥核心
+
+当前还存在：
+
+- `supervisor`
+- `assistant-autosave`
+- desk Git checkpoint
+- `work_session` / handoff
+- archive / conversation view
+- routine / scheduler
+
+这些能力对整体产品可能有价值，但它们并不都属于“Feishu <-> Codex 忠实中间层核心”。
+
+如果继续把它们和 bridge 核心绑在一起，后续重构很难做减法。
+
+### 3.5 模块边界没有在文件结构上体现
+
+当前几个核心文件已经明显超过健康规模：
+
+- `bridge/src/receiver.ts` 已超过 2400 行
+- `bridge/src/runtime-client.ts` 已超过 1700 行
+- `bridge/src/session-store.ts` 已超过 900 行
+
+这不是单纯的审美问题，而是工程边界问题：
+
+- 文件一旦过大，真正的核心与外围分支会被混在一起
+- review、回归分析、定向删除和责任归属都会越来越困难
+- 即便产品边界已经想清楚，如果代码结构没有同步模块化，后续仍然会反复长回去
+
+## 4. 目标
+
+本次重构必须达成下面 8 个目标：
+
+1. 明确 `work-ally` 中间层的金字塔结构，区分核心桥梁层与外围产品层。
+2. 让 bridge 核心重新回到“协议转接 + 最小补偿”的边界。
+3. 把当前过厚的会话真相模型收缩到最小可证稳定集。
+4. 把“最终态确认”与“渠道补发”收口成更清楚的两层机制，不再扩张 recovery 语义。
+5. 保证现有用户主路径、审批、user-input、最终结果、失败兜底、结果补发这些稳定性底线不回退。
+6. 让 `supervisor` / handoff / archive / routines` 等外围能力不再污染 bridge 核心判断路径。
+7. 把超大文件拆回模块化结构，让代码文件规模重新回到可维护范围。
+8. 给后续工程一个清晰规则：新增需求必须先判断属于 bridge 核心、最小补偿层，还是外围产品层，不能再默认往 bridge 里堆。
+
+## 5. 非目标
+
+本次明确不做：
+
+1. 不否认现有稳定性治理的价值，更不是回到“纯转发、完全不补偿”的薄弱实现。
+2. 不把 handoff、archive、routine、desk 生命周期这些能力一刀切删除。
+3. 不重做 Feishu 通道产品面。
+4. 不改变官方 Codex App Server 作为一等集成方式的方向。
+5. 不在本期引入新的重型编排系统、消息队列或第二套 runtime host。
+6. 不为了瘦身而接受“结果偶尔丢失 / 用户必须自己重试一切”的稳定性退步。
+
+## 6. 核心原则
+
+### 6.1 协议优先，不自创第二套真相
+
+官方 App Server 已经提供线程状态、turn 控制、审批请求和 `thread/read` 等事实源。bridge 默认应优先依赖这些协议事实，而不是额外创造更厚的任务语义。
+
+### 6.2 交付诚实，但只做最小补偿
+
+中间层必须诚实面对“结果已产生但渠道未送达”这类问题，因此允许存在最小 delivery ledger 与 redelivery；但不应围绕它继续长出复杂任务状态体系。
+
+### 6.3 最小 durable state 原则
+
+只保留桥层稳定运行真正需要的最小持久状态；任何新增 durable state 都必须能回答：
+
+1. 如果没有它，会失去什么稳定性底线？
+2. 它是不是官方协议已提供、无需重复维护？
+3. 它是不是其实属于外围产品层，而不是 bridge 核心？
+
+### 6.4 外围能力可以存在，但不得反向定义 bridge 核心
+
+handoff、archive、autosave、scheduler 等能力即便继续存在，也只能建立在核心桥梁合同之上，不能反过来决定 bridge 的主路径语义。
+
+### 6.5 减法重构必须可证明不降稳定性
+
+这次不是“边删边赌”。每一步收边界都要有自动化验证、兼容路径和明确 DoD，先证明没掉底线，再继续瘦身。
+
+### 6.6 边界必须体现在文件结构上
+
+如果核心边界已经想清楚，但代码仍堆在 900 行、1700 行、2000 行单文件里，说明重构并没有真正完成。
+
+本专题默认采用下面的工程纪律：
+
+1. 实现代码文件超过 `300` 行时，必须先反思是否需要拆分模块
+2. 新增或重构后的实现代码文件，原则上不应超过 `600` 行；若必须超过，应有明确理由
+3. 达到 `1000+` 行的实现代码文件视为明确重构信号，不得继续无节制增长
+4. 已经达到 `1700 ~ 2400` 行级别的核心文件，必须纳入本次专题的拆分目标
+
+## 7. 金字塔结构与模块判断
+
+本次之后，`work-ally` 中间层应按下面四层理解。
+
+### 7.1 第 1 层：协议与传输适配层
+
+定义：忠实承接 Feishu 与 Codex App Server 协议。
+
+职责：
+
+- Feishu inbound normalize / outbound send
+- Codex App Server child-process / JSON-RPC binding
+- `thread/start` / `thread/resume` / `turn/start` / `turn/steer` / `turn/interrupt`
+- approval / user-input 请求与回写
+
+代表模块：
+
+- `bridge/src/channels/feishu/*`
+- `bridge/src/runtime-client.ts`
+- `bridge/src/router.ts`
+- `bridge/src/runtime-user-input.ts`
+
+判断：**绝对核心，必须保留。**
+
+### 7.2 第 2 层：最小交付补偿层
+
+定义：为了守住“不丢、不重、能补发”的底线而存在的最小状态与机制。
+
+职责：
+
+- inbound 去重
+- final state pull-primary 确认
+- final reply delivery ledger
+- delivery unavailable 后的 bounded redelivery
+- 渠道权限 / 未发布 / 频控等 non-fatal delivery issue 识别
+
+代表模块：
+
+- `SessionStore` 中与 inbound receipt、final delivery 直接相关的最小子集
+- `bridge/src/channel-delivery.ts`
+- `Receiver.redeliverPendingFinalReplies()`
+
+判断：**属于 bridge 核心，但必须严格做薄。**
+
+### 7.3 第 3 层：最小会话控制层
+
+定义：为了把普通文本正确路由到当前 thread / turn，而不得不保留的最小会话控制。
+
+职责：
+
+- `conversation -> threadId` 绑定
+- 当前 active turn 的最小跟踪
+- 当前是否存在“已对用户可见”的 pending approval / pending user-input
+- 普通文本是 `turn/start` 还是 `turn/steer`
+
+这层**不应**再承担：
+
+- 丰富的 turn execution lifecycle
+- `pending_recovery` / `recovery_required` 作为核心产品对象
+- 大量 `superseded` 语义扩展
+
+判断：**核心需要，但当前实现过厚，必须收缩。**
+
+### 7.4 第 4 层：外围产品与运维层
+
+定义：与 desk、multi-surface、ops、长期资产有关，但并非 Feishu <-> Codex 基线桥梁必需。
+
+包括：
+
+- `supervisor`
+- `assistant-autosave`
+- desk Git checkpoint
+- `work-session-store` / `handoff-service`
+- `archive-store` / `conversation-view-store`
+- `scheduler` / `routine` / `memory-digest`
+
+判断：**可以继续存在，但不再算 bridge 核心；后续要与核心桥梁解耦。**
+
+## 8. 产品定义与用户路径
+
+### 8.1 一句话产品定义
+
+重构后，`work-ally` 的 bridge 应表现为：
+
+> 默认把 Feishu 用户输入忠实送进 Codex，把 Codex 的真实进度、审批请求和最终结果稳定带回 Feishu；只有在交付无法自动补偿时，才最小化地出声。
+
+### 8.2 输入路径
+
+V1 只保留三类输入解释：
+
+1. slash 控制命令：bridge 本地消费
+2. 对已可见 approval / user-input 的直接回答：bridge 作为协议 request/response 客户端回写给 runtime
+3. 其他普通自然语言：默认发给 Codex
+
+默认规则：
+
+- 无 active turn：`turn/start`
+- 有 active turn 且无线程级显式阻塞：`turn/steer`
+- 当前存在已对用户可见的 pending approval / user-input：提示先处理该 request，不新造本地忙状态
+
+### 8.3 输出路径
+
+V1 只保留下面几类用户可见输出：
+
+- reaction ack
+- 真实 runtime commentary / progress
+- approval request
+- user-input request
+- final reply
+- completion without reply 的最小结束提示
+- 无法自动补偿时的明确失败 / 重发说明
+- 上一轮结果补发提示
+
+### 8.4 失败与恢复路径
+
+桥层只承认两类补偿：
+
+1. **最终态确认补偿**
+   - 优先用官方 `thread/read(includeTurns=true)` 确认 turn 终态
+2. **渠道交付补偿**
+   - 若最终结果已落成但 Feishu 未稳定送达，则记为 pending delivery 并在后续时机补发
+
+桥层不再把 recovery 扩张成一套更厚的任务语义世界。
+
+## 9. 机制设计
+
+这次重构不接受“先抽象一套新模型，旧东西以后再说”的写法。
+
+必须直接回答三件事：
+
+1. bridge 核心到底保留什么
+2. 哪些现有状态 / 代码只是过渡兼容，最终要删
+3. 新主路径以后只能依赖哪些事实
+
+### 9.1 核心保留面
+
+本次之后，bridge core 只保留下面 6 类能力。
+
+#### A. 协议与传输适配
+
+保留：
+
+- Feishu inbound normalize / outbound send
+- Codex App Server child-process + JSON-RPC binding
+- `thread/start` / `thread/resume` / `turn/start` / `turn/steer` / `turn/interrupt`
+- approval / user-input request 与 response 回写
+
+#### B. inbound 去重与接单事实
+
+保留：
+
+- 每条 inbound message 的 receipt claim
+- 最小 `received -> processing -> completed` 去重合同
+- 允许判断“这条消息是否已经被接单、是否允许重入”
+
+这层是稳定桥梁的底线，不裁。
+
+#### C. conversation 到 thread 的最小绑定
+
+保留：
+
+- `conversationKey -> threadId`
+- `activeTurnId`
+- `lastMessageId`
+- `lastTurnId`
+- 少量 recent preview 字段（仅用于 status / debug，不得反向定义主路径）
+
+这层负责正常路由，不负责解释厚任务状态。
+
+#### D. 已可见的人类阻塞门
+
+保留：
+
+- visible approval gate
+- visible user-input gate
+
+硬约束：
+
+- 只有 request 已稳定送达给用户，才允许进入 blocking 语义
+- blocking truth 只由“visible human gate”表达，不再由 turn ledger execution status 表达
+
+#### E. 已持久化的最终结果 + 送达补偿
+
+保留：
+
+- pull-primary 最终态确认
+- 已持久化 final turn result
+- final delivery ledger
+- bounded redelivery
+- non-fatal channel delivery issue 识别
+
+这是 bridge 诚实交付的底线，不裁。
+
+#### F. stale output suppression
+
+保留行为，不保留厚语义扩张。
+
+说明：
+
+- 旧 turn 一旦被新消息推进，旧输出仍必须被抑制
+- 这是防串话正确性保护，不是可选体验增强
+- 但它不再扩张成桥层总任务状态世界
+
+### 9.2 核心 durable object 收口
+
+重构后的 bridge core，以“最小但够用”为准，核心 durable object 收口为下面 5 类。
+
+#### A. InboundReceiptClaim
+
+职责：表达一条 inbound message 是否已被 bridge 接单、是否仍在处理中。
+
+最小字段：
+
+- `conversationKey`
+- `messageId`
+- `status = processing | completed`
+- `createdAt`
+- `updatedAt`
+
+#### B. ConversationBinding
+
+职责：表达当前 conversation 应路由到哪条 thread，以及当前 active turn 是谁。
+
+最小字段：
+
+- `conversationKey`
+- `threadId`
+- `activeTurnId`
+- `lastMessageId`
+- `lastTurnId`
+- `updatedAt`
+
+#### C. VisibleHumanGate
+
+职责：表达“当前是否存在一个已经送达到用户、必须先由用户回答的 gate”。
+
+最小字段：
+
+- `conversationKey`
+- `kind = approval | user_input`
+- `requestId`
+- `turnId`
+- `visible = true`
+- `updatedAt`
+
+说明：
+
+- 核心只认 visible gate
+- hidden / unsent request 不是 blocking truth
+
+#### D. PersistedTurnResult
+
+职责：表达某个 turn 的终态结果已经被 bridge 确认并持久化，可用于后续补发。
+
+最小字段：
+
+- `conversationKey`
+- `threadId`
+- `turnId`
+- `status = completed | failed | interrupted`
+- `reply`
+- `error`
+- `persistedAt`
+
+说明：
+
+- 这是 redelivery 的真相源
+- 不再要求它同时承载丰富 execution lifecycle
+
+#### E. FinalDeliveryRecord
+
+职责：表达 `PersistedTurnResult` 是否已经稳定送达到渠道。
+
+最小字段：
+
+- `conversationKey`
+- `threadId`
+- `turnId`
+- `deliveryStatus = pending | delivered | delivery_unavailable`
+- `updatedAt`
+
+说明：
+
+- payload 本体不在这里重复存储
+- payload 以 `PersistedTurnResult` 为准，避免双重真相
+
+### 9.3 当前实现里明确保留、明确删除的东西
+
+这次专题不能只写“收薄”，必须明确到现有代码层。
+
+#### 9.3.1 明确保留
+
+保留下面这些现有能力或等价能力：
+
+- `noteInboundReceipt` / `completeInboundReceipt` 这类 receipt 去重能力
+- `bindThread` / `activeTurnId` 这类 conversation binding 能力
+- `recordApproval(..., { visible })` / `markApprovalVisible(...)`
+- `notePendingUserInput(..., { visible })` / `markPendingUserInputVisible(...)`
+- `recordTurn(...)` 作为最终结果持久化入口，或语义等价入口
+- `recordOutboundDelivery(...)` / `markOutboundDelivered(...)`
+- `redeliverPendingFinalReplies()` 与上一轮结果补发能力
+- stale output suppression 的最终行为
+
+#### 9.3.2 停止作为主路径判断依据
+
+下面这些语义，从本专题开始不得再作为 bridge 主路径判断真相：
+
+- `pending_recovery`
+- `recovery_required`
+- `waiting_approval` / `waiting_user_input` 作为 blocking truth
+- `superseded` 作为普通路由和会话控制真相
+- heartbeat 里基于 `turn-ledger.executionStatus` 的判断
+
+允许它们在迁移期短暂存在于兼容层，但新主路径不得继续新增依赖。
+
+#### 9.3.3 最终应删除的代码 / 接口
+
+当新主路径切换完成并通过验证后，下面这些旧厚接口应直接删除，而不是长期保留：
+
+- `SessionStore.markTurnWaitingApproval()`
+- `SessionStore.markTurnWaitingUserInput()`
+- `SessionStore.markTurnPendingRecovery()`
+- `SessionStore.markTurnRecoveryRequired()`
+- 任何仅为了驱动上述状态而存在的主路径分支
+- `Receiver` 中以 `turn-ledger.executionStatus` 为主依据的 routing / heartbeat / waiting 判断
+- 用户面与文档里仍在解释这些内部状态的文案
+
+说明：
+
+- `markTurnSuppressed()` 是否保留，不以“名字是否还在”为判断标准
+- 如果 stale suppression 仍需要一个极简内部标记，就保留极简标记
+- 但要删除它作为“厚生命周期状态”的扩张用法
+
+### 9.4 新主路径合同
+
+#### A. inbound
+
+1. Feishu inbound normalize
+2. receipt claim
+3. slash / pending-response / plain-text 分类
+4. reaction ack
+
+#### B. route to runtime
+
+1. 读 `ConversationBinding`
+2. 无 thread：`thread/start` + `turn/start`
+3. 有 active turn 且无 visible gate：`turn/steer`
+4. 无 active turn 但已有 thread：`thread/resume` + `turn/start`
+
+#### C. blocking truth
+
+1. 若存在 visible approval gate：普通文本不转发，提示先处理审批
+2. 若存在 visible user-input gate：普通文本不转发，提示先回答当前问题
+3. 若 request 尚未真正送达到用户：不得进入 blocking
+
+#### D. final result
+
+1. 终态仍以 `thread/read(includeTurns=true)` 为 authoritative final-state check
+2. 一旦确认终态，写入 `PersistedTurnResult`
+3. 随后写入 / 更新 `FinalDeliveryRecord`
+4. 渠道发送成功：`delivered`
+5. 渠道发送失败但属 non-fatal：`delivery_unavailable`
+6. 启动时或下一条 inbound 到来时做 bounded redelivery
+
+### 9.5 recovery、stale、delivery 的新边界
+
+#### A. recovery
+
+recovery 保留为内部机制，但不再保留为 bridge 主路径状态世界。
+
+允许保留的只有：
+
+- 静默 bounded final-state reconcile
+- reconcile 失败后的事实型兜底
+
+不再允许：
+
+- recovery 过程本身成为默认用户提示面
+- recovery 状态成为 routing truth
+- 围绕 recovery 继续增加 durable lifecycle enum
+
+#### B. stale suppression
+
+stale suppression 必须保留，但边界改为：
+
+- 它只负责“不要把旧输出串给用户”
+- 它可以留下 archive 事实或极简 suppression 标记
+- 它不再承担桥层通用生命周期建模职责
+
+#### C. delivery
+
+delivery 是 bridge 核心补偿语义，继续保留并强化：
+
+- 终态已确认 != 用户已收到
+- delivery ledger 是核心对象，不是外围调试信息
+- 只要结果已经持久化，就必须允许后续补发
+
+### 9.6 外围能力与 bridge core 的边界
+
+这次专题的目标不是把外围能力全部杀掉，而是切断它们反向定义 core 的权力。
+
+#### A. supervisor
+
+- 只负责进程托管
+- 不再定义 turn / session / waiting / recovery 语义
+- foreground 模式必须独立成立
+
+#### B. work-session / handoff
+
+- 只服务显式 multi-surface 场景
+- 普通 Feishu 单路聊天主路径不得以它为前提
+- 不得因为它的存在，让默认消息路由变复杂
+
+#### C. archive / conversation view
+
+- 只做 sidecar fact sink
+- 不得主导 routing、blocking、recovery、delivery 真相
+
+#### D. routine / scheduler / digest
+
+- 视为独立产品能力
+- 不得把自己的状态模型注入普通聊天主路径
+
+### 9.7 工程模块化与文件规模治理
+
+这次专题明确把“模块化”视为实现的一部分，而不是代码整理 bonus。
+
+#### A. 文件规模纪律
+
+- `300` 行是强制反思阈值：超过后必须判断是否拆分
+- `600` 行是默认上限：新增或重构后的实现代码文件原则上不应超过
+- `1000+` 行是明确重构信号：不得当成常态接受
+- `1700 ~ 2400` 行级别文件必须优先拆分，不允许继续堆功能
+
+说明：
+
+- 这里指项目实现代码，不含生成文件、fixture 快照或第三方代码
+- 目标不是机械切文件，而是让模块边界和产品边界对齐
+
+#### B. 当前必须纳入拆分目标的热点文件
+
+- `bridge/src/receiver.ts`
+- `bridge/src/runtime-client.ts`
+- `bridge/src/session-store.ts`
+
+#### C. 拆分原则
+
+- 按职责拆，不按随机行数硬切
+- 核心桥梁路径与外围能力优先分离
+- routing、visible gate、delivery compensation、runtime transport、sidecar observability 等职责要能落到不同模块
+- 拆分后若只是把同一团语义换成更多文件名，不算完成
+
+## 10. 重构范围与阶段
+
+### Phase 1：冻结边界，补齐护栏
+
+用户价值：先把“绝不能退”的主链路写死，避免边做边赌。
+
+交付：
+
+- 明确 core / peripheral 边界
+- 补 characterization tests，锁定当前必须保留行为
+- 补“只认 visible gate”“只认 persisted result + delivery ledger”的测试护栏
+
+完成标准：
+
+- 团队可以明确回答：哪些是 bridge core，哪些不是
+- 当前主路径的正确性底线已被测试覆盖
+
+### Phase 2：切换主路径到精简真相
+
+用户价值：bridge 更忠实、更薄，普通消息和结果交付更少受本地厚状态干扰。
+
+交付：
+
+- `Receiver` / `router` / `translator` 主路径改为只依赖：
+  - receipt claim
+  - conversation binding
+  - visible human gate
+  - persisted turn result
+  - final delivery ledger
+- 主路径不再依赖 `pending_recovery` / `recovery_required` / `waiting_*` / `superseded` 这些厚 enum
+- recovery 改成静默 reconcile + terminal fallback
+- heartbeat 不再依赖厚 ledger 状态
+- 开始拆分 `receiver.ts`、`runtime-client.ts`、`session-store.ts` 等超大文件，把边界真正落到模块结构
+
+完成标准：
+
+- 用户主路径仍稳定
+- 主路径代码已不再读取厚状态作为核心真相
+
+### Phase 3：删旧状态、删旧代码、删旧测试
+
+用户价值：不是“逻辑上变薄”，而是代码和维护面真的变薄。
+
+交付：
+
+- 删除已不再需要的 turn lifecycle enum 与写接口
+- 删除只服务旧厚状态的分支、文案、测试
+- 删除已经不再被核心主路径依赖的兼容逻辑
+- 删除本次确认无用的巨型文件内部耦合层与搬运代码
+- 文档同步切到新边界，不再保留旧心智
+
+硬要求：
+
+- 这一阶段不是可选“以后再清理”
+- 只要新主路径已经稳定，就必须把确认无用的旧代码一起删掉
+
+## 10.5 小步快跑实施策略
+
+这次专题是重构，不接受“大爆炸式改完再统一验证”的落地方式。
+
+默认实施方法必须是：
+
+- 一次只改一类主语义或一类模块职责
+- 每一步结束后立刻验证
+- 验证不过，不进入下一步
+- 每一步都应可单独提交、单独回滚、单独验收
+
+### 10.5.1 稳定性定义
+
+对本专题，`稳定性` 指下面这些用户面底线在整个重构过程中始终成立：
+
+1. 普通消息必须稳定进入 Codex。
+2. approval / user-input 不能丢、不能错拦、不能误解。
+3. final reply 不能因为重构而丢失。
+4. 私聊 / 群聊 / conversation thread 不能串。
+5. 旧 turn 的迟到输出不能串到新消息。
+6. 用户不能因为重构体感成“消息被吞了”或“机器人没反应”。
+
+### 10.5.2 切片原则
+
+每一个实施切片都必须满足：
+
+1. 目标单一：一次只解决一个主题，例如“只拆文件”或“只切 blocking truth”。
+2. 改动可控：尽量避免同一步同时改语义、改文件结构、改文案、改测试基线。
+3. 风险可回退：改动失败时可以直接回滚，不会把 bridge 留在半坏状态。
+4. 验证闭环：该步完成后，必须有对应自动化和必要 smoke 支撑。
+
+### 10.5.3 推荐实施切片
+
+#### Step 0：补护栏，不改产品语义
+
+目标：先锁定当前必须保留的行为，防止后续减法误伤主链路。
+
+只做：
+
+- 补 characterization tests
+- 补 bridge core 主路径基线测试
+- 补当前超大文件拆分前的 smoke 护栏
+
+不做：
+
+- 不改 routing 语义
+- 不改 recovery 语义
+- 不删旧代码
+
+完成后必须验证：
+
+- unit tests
+- 必要的 integration / shell tests
+- 最小聊天 smoke
+
+#### Step 1：先拆文件，不改行为
+
+目标：优先把超大文件里的纯 helper / 纯职责模块拆出去，但保持行为等价。
+
+只做：
+
+- 从 `receiver.ts`、`runtime-client.ts`、`session-store.ts` 中拆纯职责模块
+- 例如 delivery、visible gate、runtime transport、stale suppression、status formatting 等
+
+不做：
+
+- 不改变主路径判断条件
+- 不改变用户面语义
+- 不借机删状态模型
+
+完成后必须验证：
+
+- 行为回归零变化
+- 现有测试全绿
+
+#### Step 2：把 visible human gate 收成唯一 blocking truth
+
+目标：普通 follow-up 是否被拦截，只由 visible approval / visible user-input 决定。
+
+只做：
+
+- 切 routing / waiting 判断
+- 停止让 `waiting_*` ledger 状态主导 blocking truth
+
+允许保留：
+
+- 旧厚状态继续兼容写入
+- 旧结构继续保留短期读取
+
+完成后必须验证：
+
+- 普通 follow-up
+- approval 阻塞与回复
+- user-input 阻塞与回复
+
+#### Step 3：把 final result 真相收口到 persisted result + delivery ledger
+
+目标：终态确认与结果补发只围绕 authoritative final-state check、persisted result、delivery ledger 运转。
+
+只做：
+
+- final result truth 收口
+- redelivery 主路径收口
+- 停止让 recovery 厚状态主导 final result 判断
+
+完成后必须验证：
+
+- completed / failed / interrupted
+- delivery unavailable -> redelivery
+- completion without reply
+
+#### Step 4：把 stale suppression 从厚状态降回正确性保护
+
+目标：保留防串话能力，但不再让 `superseded` 主导通用生命周期。
+
+只做：
+
+- 收缩 stale suppression 语义
+- 保留必要的极简 suppression marker 或 sidecar fact
+
+完成后必须验证：
+
+- 旧 turn 迟到结果不会串给新消息
+- 新消息仍可稳定启动或 steer
+
+#### Step 5：外围能力降耦
+
+目标：让 `supervisor`、`work-session`、`handoff`、`archive`、`routine` 不再污染 bridge core 主路径。
+
+只做：
+
+- 降低外围能力对默认聊天主路径的耦合
+- 确认 foreground 模式可独立成立
+
+完成后必须验证：
+
+- foreground 主链路
+- 托管模式主链路
+- 相关外围能力未破坏默认聊天路径
+
+#### Step 6：删旧代码并收口文档
+
+目标：在前面几步都稳定后，再真正删除已无用的厚状态接口、旧分支、旧测试、旧文案。
+
+只做：
+
+- 删已确认无用代码
+- 删旧测试 / 旧文案
+- 回写 README / DASHBOARD / 相关 spec
+
+硬约束：
+
+- 这一阶段不能提前做
+- 但一旦进入，也不能再以“以后可能有用”为理由长期保留遗产代码
+
+### 10.5.4 每一步的最小执行模板
+
+后续实际推进时，每一步都按同一模板执行：
+
+1. 先声明这一步只改什么，不改什么。
+2. 实现后立刻跑对应自动化。
+3. 必要时补最小真人 smoke。
+4. 验证通过后再进入下一步。
+5. 若失败，就在这一步内修完或回退，不把问题带进下一步。
+
+### 10.5.5 交付节奏要求
+
+本专题最终虽然会合成一个“已完成”的专题，但实施过程必须保持：
+
+- 多个小步骤
+- 多次独立验证
+- 多次可回退交付
+
+不允许：
+
+- 一次改几十个文件后再统一验收
+- 文件拆分和语义切换大面积混做
+- 在没有验证闭环的前提下连续推进多个步骤
+
+## 11. 稳定性保障与删代码原则
+
+### 11.1 不可退化的 9 条底线
+
+1. 同一条 inbound message 不得触发多个有效 turn。
+2. 普通自然语言默认仍可进入 Codex，而不是被 bridge 吞掉。
+3. 只有 visible human gate 才能阻塞普通 follow-up。
+4. approval / user-input 仍可正确送达、回答并回写 runtime。
+5. final result 一旦已从官方事实源确认，就不能因为单次渠道失败而永久丢失。
+6. stale output 仍必须被稳定抑制，不能串到新一轮对话里。
+7. 只有显式 `/stop` 语义，才能稳定翻译为“当前任务已停止”。
+8. foreground 模式必须成立；supervisor 只是托管增强，不是语义前提。
+9. handoff / archive / routine 等外围能力即便保留，也不能破坏聊天主路径。
+
+### 11.2 迁移策略
+
+1. 先补护栏，再改主路径。
+2. 迁移期允许读取旧 `SessionStore` / turn ledger 结构。
+3. 从 Phase 2 开始，新主路径只允许写入和读取精简真相。
+4. 旧厚状态只可用于兼容读取或短期回放，不得继续成为新分支前提。
+5. Phase 3 一旦完成验证，必须删除已无用的旧接口、旧测试、旧文案。
+
+### 11.3 删代码原则
+
+这次专题明确遵守下面 3 条：
+
+1. 不因为“以后可能用得上”而保留已确认无用的状态与分支。
+2. 不允许长期存在“双真相模型”：新模型负责主路径，旧模型只是临时兼容，必须有删除节点。
+3. 文档、测试、代码必须一起删旧；不能代码删了，文档还写旧心智，或反过来。
+
+### 11.4 测试策略
+
+自动化至少覆盖：
+
+- inbound 去重
+- `turn/start` / `turn/steer` 主路径
+- visible approval / user-input gate
+- final-state pull-primary
+- delivery unavailable -> redelivery
+- stale output suppression
+- foreground 无 supervisor 主路径
+- supervisor 仅做进程托管，不影响主语义
+- 拆分后的模块边界 smoke，不因文件重组破坏现有主链路
+
+### 11.5 文档策略
+
+需要同步回写：
+
+- `README.md`
+- `DASHBOARD.md`
+- 相关 planning / implementation spec
+- 必要的 manual acceptance 文档
+
+文档口径必须统一成一句话：
+
+> bridge core = 协议转接 + 最小路由状态 + visible human gate + final delivery compensation。
+
+## 12. DoD / 验收标准
+
+### 12.1 结构 DoD
+
+1. 工程上可以明确区分 bridge core 与外围产品层。
+2. bridge core 主路径只依赖精简真相对象，而不是厚 turn lifecycle 状态。
+3. `pending_recovery` / `recovery_required` / `waiting_*` / `superseded` 不再是主路径判断前提。
+4. `supervisor`、`handoff`、`archive`、`routine` 不再污染核心主路径判断。
+5. 本次纳入治理的超大实现文件已完成模块化拆分，或至少已有明确的阶段性交付切口，不再继续无边界膨胀。
+
+### 12.2 行为 DoD
+
+1. 普通消息默认仍可正确进入 Codex。
+2. active turn 中的普通 follow-up 默认仍按协议进入 `turn/steer`。
+3. approval / user-input 请求仍能正确形成 visible gate 并被用户回答。
+4. final reply 仍以 authoritative final-state check + delivery ledger 收口。
+5. 渠道单次失败后，仍能稳定补发上一轮结果。
+6. stale output 仍会被抑制，不会把旧 turn 的结果串给新消息。
+
+### 12.3 删除 DoD
+
+1. 已确认无用的厚状态接口与分支已删除，而不是只停止使用。
+2. 只服务旧厚状态的测试、文案和说明已同步删除或改写。
+3. 仓库里不存在“主路径靠新模型，解释仍靠旧模型”的双口径残留。
+4. 已确认只是历史堆积、没有继续保留价值的超大文件内部耦合层与搬运代码已同步清掉。
+
+### 12.4 模块化 DoD
+
+1. 重构后的核心实现文件规模符合新的工程纪律：超过 `300` 行有明确拆分判断，超过 `600` 行有明确理由。
+2. `1700+` / `2000+` 行级别的核心文件不再继续原地膨胀，至少已有明确拆分成果。
+3. 模块命名与职责能直接映射到 bridge core / peripheral 的产品边界。
+
+### 12.5 稳定性 DoD
+
+1. 核心自动化测试全部通过。
+2. `bash tests/shell/assistant.sh`、相关 integration / unit tests、以及必要的 runtime/bridge 路径验证通过。
+3. foreground 模式与托管模式都能跑通聊天主链路。
+4. 不出现“因为瘦身而丢 reply / 丢 approval / 丢 user input / 错吞消息”的回归。
+
+### 12.6 文档 DoD
+
+1. README 与相关 spec 已回到新的核心边界口径。
+2. dashboard 上能明确看出该专题的状态与后续阶段。
+3. 后续新增 feature 若继续往 core bridge 塞厚语义，将有明确文档标准可拦截。
+
+## 13. 风险、假设与待决问题
+
+### 13.1 风险
+
+1. 如果精简过头，可能误伤少数异常路径的补偿能力。
+2. 如果删代码顺序不当，可能在短期内造成 handoff / archive / routine 与核心桥梁接口抖动。
+3. 如果 characterization tests 不先补齐，瘦身会重新变成边改边赌。
+
+### 13.2 假设
+
+1. 官方 Codex App Server 协议面已足够支撑忠实桥梁，不需要 bridge 再造第二套任务语义。
+2. 当前真正必须保留的补偿，主要集中在 receipt dedupe、visible gate、pull-primary final-state reconcile、final delivery redelivery。
+3. stale suppression 是正确性保护，应保留；但它不需要继续扩张为厚生命周期状态系统。
+
+### 13.3 待决问题
+
+1. `PersistedTurnResult` 最终是继续复用当前 `TurnRecord` 文件结构，还是收口成更小的专用结构？
+2. `markTurnSuppressed()` 最终是完全删除，还是保留为极简 suppression marker？
+3. `work-session` / handoff 后续是只做桥内外围模块，还是再单独拆专题继续降耦？
+
+## 14. 当前实施结论
+
+### 14.1 当前实施快照（2026-03-19）
+
+最近已按“小步快跑”连续落地并提交这些纯结构化切片：
+
+- `9429b78` `Split session store meta and inbound acceptance helpers`
+- `0ca6974` `Extract receiver support actions`
+- `158af1f` `Extract receiver turn execution orchestration`
+- `a65dfd6` `Extract runtime client request plumbing`
+- `d0ef542` `Extract runtime client turn state helpers`
+- `cdc1955` `Extract runtime turn start flow`
+- `cc692b9` `Extract server routine execution`
+- `e779c84` `Extract server handoff command`
+- `c83893c` `Extract server main entry flow`
+- `e3ede0d` `Extract server routine command`
+- `d39fea0` `Extract runtime app support helpers`
+- `b8c3f4d` `Extract runtime app composition shell`
+- `9eeec02` `Simplify inbound receipt dedupe semantics`
+
+当前已确认的阶段性结果：
+
+- `bridge/src/runtime-client.ts` 已从 `442` 行压到 `331` 行
+- `bridge/src/server.ts` 当前已压到 `16` 行，仅保留 re-export 与 CLI 入口 facade
+- `bridge/src/server-runtime-app.ts` 已稳定承接 `RuntimeApp` 与 app factory 组装逻辑，当前 `243` 行
+- `bridge/src/server-main.ts` 已稳定承接主进程入口，当前 `74` 行
+- `bridge/src/server-runtime-app-support.ts` 已稳定承接 `RuntimeApp` 的 startup / health / notice / redelivery 支撑逻辑，当前 `110` 行
+- `bridge/src/receiver.ts` 已压到 `329` 行，当前主要承担 orchestrator 角色
+- `bridge/src/session-store.ts` 已压到 `369` 行，meta / inbound acceptance 已拆出
+- receipt claim 现仅保留 `claimed / duplicate_processing / duplicate_completed`
+- `superseded` 已不再占据 execution truth；当前已进一步收口为 `suppressed / suppression provenance` 标记
+
+当前新增并已稳定承接职责的模块：
+
+- `bridge/src/runtime-client-request-ops.ts`
+- `bridge/src/runtime-client-turn-state.ts`
+- `bridge/src/server-routine-execution.ts`
+- `bridge/src/server-handoff-command.ts`
+- `bridge/src/server-main.ts`
+- `bridge/src/server-routine-command.ts`
+- `bridge/src/server-runtime-app-support.ts`
+- `bridge/src/server-runtime-app.ts`
+
+当前验证已覆盖并通过的代表性路径：
+
+- `tests/unit/runtime/runtime-client-lifecycle.test.mjs`
+- `tests/unit/runtime/runtime-client-message-phases.test.mjs`
+- `tests/unit/runtime/runtime-client-thread-status.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary-waiting.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/unit/session/session-store.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/integration/routines/routine-flow.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/integration/routines/routine-delivery.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/integration/session/bridge-core-baseline.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/integration/session/runtime-failure-and-recovery.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp node --test tests/integration/session/stability-regression.test.mjs`
+- `env -i PATH=/usr/bin:/bin:/opt/homebrew/bin HOME=$HOME TMPDIR=/tmp bash tests/shell/routines.sh`
+- `tests/shell/codex-handoff.sh`
+
+完成判定：
+
+- 本专题目标已经完成：bridge core 已完成收边界、厚状态口径已退出主路径、关键超大文件已完成阶段性模块化拆分。
+- clean-env Node 回归与 `tests/shell/codex-handoff.sh` 已通过；`tests/shell/assistant.sh` 的剩余卡点已确认是测试收尾阶段的 assistant desk remote push 噪音，不属于本专题改动引入的 bridge 回归。
+- 后续若要处理 `assistant.sh` 的 remote push 卡顿，应作为独立测试/工程问题继续跟进，不再阻塞本专题收口。
+
+对这次专题，执行口径直接定为下面 4 句：
+
+1. **保留**：协议转接、receipt 去重、最小 conversation binding、visible human gate、persisted final result、delivery ledger、bounded redelivery、stale suppression。
+2. **停止依赖**：`pending_recovery`、`recovery_required`、`waiting_*`、`superseded` 这些厚状态作为主路径真相。
+3. **删掉**：确认无用的厚状态接口、分支、文案、测试，不做“留着以后再说”的温和保留。
+4. **守住边界**：bridge core 以后只做稳定桥梁和最小补偿，不再回到“本地任务脑”的方向。
+
+这份 spec 的本质，不是为了“看起来更薄”，而是为了让 `work-ally` 真正回到它最该维护、也最值得长期维护的产品边界。