@ckanner/flywheel 0.31.0 → 0.31.1

package/docs/plans/2026-11-07-session-lifecycle.md

@@ -0,0 +1,337 @@
+# 按任务、角色与运行事实管理会话
+
+2026-11-07。原始设计方案（PR #30 仅修改文档），取代“每次 Execute／Review 调用
+必须全新会话”的设计原则。本文保留提出方案时的基线分析和完整分期。
+**实施补注：**P1/P2 正常终态续接与已保存回执恢复已实现；P3 配套公开 lifecycle v1、durable ACK、supervisor journal 与精确只读恢复已接通；P4 具备角色策略、有界质量重建与固定源码／独立 oracle 的三组对照工具。当前字段、调用安全与能力差异以[设计](../design.md)、[配置](../zh-CN/configuration.md)及[恢复指南](../zh-CN/session-recovery.md)为准。真实账号质量、缓存及性能实验仍未取得有效结果，离线通过不替代该证据。下文保留原提案的版本基线与分期分析。
+English: [Session lifecycle proposal](2026-11-07-session-lifecycle.en.md)。
+
+## 1. 决策
+
+**会话归属于明确的任务、工作范围和角色；普通返修优先延续该角色的上下文，
+重新建立上下文由实际兼容性、可恢复性、上下文质量和运行事实决定。**
+
+- 一个 packet 的 Executor 通常延续自己的 thread，处理 L1 失败、Review 退回和同范围的补充工作。
+- Reviewer 使用与 Executor 隔离的上下文。同范围复审可以延续 Reviewer 自己的 thread，仍重新检查完整当前候选。
+- Plan 按同一规划目标、Judge 按同一里程碑管理连续性；明确第二意见使用独立上下文。
+- 新任务、无关 packet、不同角色不共用 thread。历史不可恢复、范围不兼容或上下文质量恶化时，用权威材料重建。
+- Go 根据版本化策略和可核对事实决定 create／resume／rebuild／wait，不增加一个负责调度的父模型。
+- 会话历史、单次调用、worker 进程是不同生命周期。延续历史不要求进程常驻，也不改变清理、预算、验收和交付要求。
+
+这是一项有待验证收益的工程选择，不是“续用总比新建好”的性能结论。
+历史 fresh 规则保留在历史文档中作背景，不再作为当前架构不变量。
+
+## 2. 当前实现与依据
+
+检查基线为 Flywheel [`80deeed4`][fw-base]（PR #29 合并后），以及
+`dsh-subagent-codex-pro@0.8.0` 的 [`04ecdb67`][plugin-base]。
+下表描述该固定版本；后续实施必须重新核对依赖和公开接口。
+
+| 项目 | 基线事实 | 对方案的约束 |
+|---|---|---|
+| 调度 | Go 顺序运行 packet；每次 Execute／Review 新会话，重试保留工作区与反馈 | 现有任务不是由一个常驻父 Agent 调度原生 Teams；会话改造不顺带引入并行调度 |
+| Kimi Plan | 明确启用 `resident-session` 且身份匹配时可恢复 | 已证明进程可每次结束而历史继续；不能把该能力外推成所有阶段已支持 |
+| Codex Pro 插件 | machine API 支持 `ephemeral`、`persistent` 和显式 `threadId` | 普通完成后的续用已有公开基础，不必换回旧 Codex CLI |
+| Flywheel bridge／driver | 写死 ephemeral；拒绝非空 SessionID；回执要求无请求 thread ID 且配置来源为 `thread/start` | 必须同时修改请求、状态、回执校验和调用路径，只改一个开关不成立 |
+| DSH worker | 当前 Flywheel 没有接通历史恢复 | 默认 Flash Execute／GPT Review 仍是重要的后续实施范围 |
+| machine 早期事件 | 公开选项只有 signal、env 和文本 onProgress，结构化运行标识在最终回执交付 | 第一阶段不能承诺任意时点崩溃后都能找回新建 thread |
+
+来源：[Flywheel 设计与现状][fw-design]、[bridge][fw-bridge]、[driver][fw-driver]、
+[插件 machine API][plugin-machine]、[machine 实现][plugin-machine-src]。
+
+### 为什么继续使用 machine
+
+`machine` 是插件供确定性编排器调用的程序接口，不是一台临时机器，也不是一种会话类型。
+Flywheel 可以直接请求一次 Codex harness 运行并取得配置、结果、清理与用量回执。
+它不要求先创建 DSH 父模型再让模型调用 `subagent_codex`（[插件实际注册的工具名][plugin-readme]）。
+当初的选择依据是已核对的 DSH rc.5 SDK 与插件接口限制；这不是对未来所有 DSH 版本的断言。
+见[原接入计划](2026-11-03-codex-pro-default.md)与[验证记录](../validation/2026-11-03-codex-pro-default.md)。
+
+| 维度 | 选择 | 含义 |
+|---|---|---|
+| 调用接口 | machine API | Go 调用插件、消费机器可校验回执 |
+| 上下文 | 新 thread／resume 指定 thread | 本次是否继承该角色以前的交互历史 |
+| 历史保存 | ephemeral／persistent | 插件是否请求保留可恢复的 Codex 历史；不等于整个文件系统零写入 |
+| 进程 | 每次启动并收尾／长期运行 | 进程存活时间，独立于历史保存 |
+
+因此可以每次运行都新建 worker/app-server、完成后确认清理，同时通过 persistent history
+和显式 thread ID 延续上下文。也可以建立一个全新的独立 Reviewer thread，并保存其历史供复审。
+官方 [App Server 文档][oa-app-server]与 [Codex SDK 文档][oa-sdk]均将新建和继续已有 thread
+作为显式操作；它们说明能力，不决定 Flywheel 的调度策略。
+
+## 3. 上下文的归属与默认策略
+
+以下为目标策略。首个调用建立该范围自己的上下文，后续调用必须先通过 §4 的资格检查。
+后端未实现相应能力时，继续使用现有可用方式并记录原因，不静默换模型或渠道。
+
+| 角色 | 会话范围 | 通常续用 | 通常重建或另开 |
+|---|---|---|---|
+| Plan | 同一任务内连续的规划目标 | 契约格式修正、同目标修订、verification-gap 的规划反馈 | 新目标、关键前提不兼容、原上下文不可用 |
+| Execute | task + packet + executor | L1 修复、Review return、补普通测试／报告、同范围实现迭代 | 无关 packet、目标实质改变、上下文失控或无法恢复 |
+| Review | Full 的 packet 评审；Quick 的完整单 packet 需求最终评审 | 同范围修复后的复审、verdict 格式修正 | 新评审范围、刻意独立第二意见、执行者历史污染、越权修改候选 |
+| Judge | milestone + judge role；第二意见单独归属 | 同里程碑修复后的再次终验 | 新里程碑、明确第二意见、判断范围不兼容 |
+| Verify | 无模型会话 | 重新运行确定性检查 | 不适用 |
+| Intake／Garden | 一次明确的建议任务 | 该建议的补充与修订 | 不相关任务；不属于第一阶段实施 |
+
+Reviewer／Judge 不能继承 Executor 的对话、私有推理或工具轨迹来代替独立检查。
+它们消费当前契约、权威 diff、合法报告、适用验证证据及自己此前的 findings。
+每次复审都要检查全部当前范围、修复引入的新问题、既有问题的关闭或重开；
+Quick 最终 Review 每次都覆盖所有需求，不能只勾销上次提出的几个问题。
+
+“另请一个独立意见”是可选评估或明确工作流要求，不因会话续用自动新增。
+Quick 首次成功路径仍为 **Execute + 独立最终 Review 两次阶段调用**；
+Full 的集成验证和 Judge 仍按现行工作流执行。会话策略不决定 Quick／Full 资格。
+
+## 4. Go 如何决定下一次调用
+
+决策前先检查停止意图、运行 lease、预算和尝试上限。用户 stop 后不会因 thread 仍存在而自动续跑；
+只有明确恢复入口启动后才重新判断。会话变化、Quick → Full、换进程均不重置计数。
+
+### 4.1 续用资格
+
+正常 resume 同时要求：
+
+1. thread 的任务、packet／milestone 和角色归属正确；没有另一活动 turn 或冲突的工作区写入者。
+2. 上次调用的派发、终态与清理事实足够明确；没有尚待核对的执行结果或副作用。
+3. 持久历史与明确 thread ID 可用，当前后端的公开恢复能力已被适配并验证。
+4. 工作区来源、契约修订、有效运行绑定符合版本化兼容策略；每次仍重新提供当前权威材料。
+5. 未触发上下文／停滞阈值或显式重置；仍有原任务的预算和尝试额度。
+
+无法满足历史条件不必废弃工作区。若前次运行及清理已确认安全，可建立新上下文；
+若结果或清理未知，则必须先核对，**fresh 也不能绕过这个阻断**。
+
+```mermaid
+flowchart TD
+  A["授权、lease 与预算检查通过"] --> B{"存在未确认的运行或清理？"}
+  B -->|是| C["核对事实或停止"]
+  B -->|否| D{"同角色范围且可恢复？"}
+  D -->|是| E["续用角色 thread"]
+  D -->|否| F["权威交接后新建上下文"]
+  E --> G["运行并持久化回执"]
+  F --> G
+  G --> H["验证当前候选"]
+  H -->|需返修且仍获授权| A
+  H -->|证据齐全| I["按工作流继续交付"]
+```
+
+图只表示会话选择与返修关系；工作流的 Plan、Review、Judge、预算和完成门禁仍由现有状态机控制。
+
+### 4.2 兼容性不等于所有字段永远不变
+
+必须区分三个身份：**会话归属**、**本次 attempt**、**被验证的候选与契约**。
+修复代码会改变候选，这是续用的正常用途。候选变化使相应旧证据失效，不自动销毁会话。
+同目标契约修订也可以带着权威差异延续上下文；不能把 Spec hash 改变直接等同于必须 fresh。
+
+| 变化 | 处理原则 |
+|---|---|
+| task、角色、无关 packet／milestone | 新建相应范围的上下文，不能认领别人的 thread |
+| 候选实现、测试、done-report | 记录调用前后身份，按现行规则失效并重做相关验证；可以续用上下文 |
+| 契约修订 | 记录旧／新 fingerprint 和结构化修订依据；同目标的兼容修订可续用，未知或实质换目标则重建／重规划 |
+| cwd | 先解析绝对物理路径；路径别名不是新任务。真实工作区迁移须明确核对归属与内容，不自动沿用 |
+| provider、账号渠道或角色权限边界 | 核对有效绑定与既有授权；不允许借 resume 混用账号、未经授权扩大权限或增加付费后备 |
+| model、effort、有效工具／权限配置 | 按后端支持的逐 turn／resume override 和证据判断，不能一概 fresh 或无条件续用；首版未验证的组合保守重建或拒绝 |
+| 插件、协议、harness 版本 | 用已验证能力表判断；升级不默认证明历史兼容 |
+
+Go 不靠自由文本“看起来还是同一目标”做语义裁决。Plan／用户提供的修订必须沿用现有授权与契约校验，
+实施时定义可机械核对的兼容变化集合和版本；无法核对的变化明确走重建或现有规划／人工路径。
+从后端得到的“请求已接受”与“实际配置已确认”也要分开记录，不能提高证据强度。
+
+### 4.3 按失败类型选择动作
+
+| 事件 | 会话动作 | 必须保留的约束 |
+|---|---|---|
+| L1 发现实现错误，执行回执和清理正常 | 向原 Executor 发送失败证据继续修复 | 新候选重新验收，沿用总尝试和预算 |
+| Review return | 原 Executor 修复，独立 Reviewer 复审 | 复审覆盖完整当前范围，不能沿用旧 pass |
+| 报告／verdict 格式错误，底层运行已可靠结束 | 同角色续用修正输出 | 区分报告错误与不可信的底层回执；仍受原重试上限约束 |
+| verification-gap | 进入现有 Plan 修订路径，再判定各角色兼容性 | Quick 先持久化升级；受影响证据失效 |
+| AUTH、QUOTA、RATE_LIMIT | 按既有错误策略暂停／退避／授权后恢复 | 换 thread 不解决认证或额度，不自动换付费渠道 |
+| 明确未派发的启动失败 | 可重试已知意图 | 记录本次尝试；不能把未知派发伪装成未派发 |
+| 历史不存在／no-rollout，且确认新 turn 未发送、清理完成 | 显式重建并交接 | 不静默冷启动；原任务计数不重置 |
+| 上下文超限、污染或重复失败无进展 | 有界压缩、重建或现有升级出口 | 只使用已公开并验证的能力；不无限刷新 thread 逃避停止 |
+| 中途断连、终态回执丢失、cleanup 未确认 | wait／reconcile／停止 | 不能直接 resume，也不能新开写入者重放 |
+| 人工或外部任务修改工作区 | 核对来源与候选，失效相关证据 | 保留文件；新 thread 不能代替冲突处理 |
+
+上下文长度、连续返修数和停滞检测使用有界、可配置且可记录的策略。
+第一阶段复用现有尝试／空转／预算上限，不宣称某个轮数或百分比普遍最优。
+后端内部压缩不等于 Flywheel 已能请求、控制或证明压缩结果。
+
+## 5. 状态与协议的目标契约
+
+以下是**拟议的数据职责**，不是当前 schema 或可直接复制的配置字段。
+实施先更新 `templates/state.schema.json` 及相关配置／协议定义，再由 `internal/state`
+完成兼容加载和 CAS 写入。worker、模型、skills、桌面 UI 均不直接写 state。
+
+| 记录 | 需要保存的事实 |
+|---|---|
+| 会话归属 | task、packet／milestone、role、canonical worktree、生成代次、策略版本 |
+| 恢复绑定 | harness／协议版本、provider／channel、非秘密账号配置引用、model、请求 effort、有效权限／工具配置、兼容策略版本 |
+| 历史句柄 | 后端 opaque thread ID、persistent 属性、可恢复性证据、最近确认检查点、retired/rebuild 原因 |
+| 单次调用 | 引擎 invocation ID、requestId、后端 runId／turnId、attempt、派发意图和时间、终态回执引用及摘要 |
+| 运行事实 | 派发已知程度、结果已知程度、cleanup 确认、lease／活动调用所有者；这些事实不能合成一个 success 布尔值 |
+| 候选与契约 | 调用前后身份、契约版本、修订依据、对应验证／裁决证据；旧证据按原规则归档 |
+| 用量入账 | 本次可归属增量、complete/partial/unknown、已入账回执标识，防止重放重计 |
+
+账号标识只保存非秘密引用，不能存凭证。后端 thread ID 作为 opaque handle，不解析其格式推断任务归属。
+`requestId` 是关联标识，当前插件不承诺幂等或去重；PID 也不是所有权或清理证明。
+
+分别记录请求的历史保存模式、适配器能够确认的事实和实际恢复结果。thread ID 本身不证明持久化或可恢复；
+`0.8.0` 终态回执没有直接回显 `threadMode` 或 `resumable:true`，不能自行补成后端确认值。
+第一阶段依据原始请求、锁定适配器的核对和终态事实选择恢复候选，实际恢复仍须 `thread/resume` 接受。
+
+Go 先保存派发意图，再启动 worker；完整回执通过校验并原子保存后，CAS 更新状态和入账。
+回执文件是调用证据，不是第二套状态机：只有 Go 可以在持有 lease 时根据匹配的 invocation、
+内容摘要和版本补记状态。已经入账的回执不能重复计量；不能仅凭磁盘存在 done-report 推断运行结束。
+worker 只承载版本化请求／回执，不负责决定复用、换模型或重试。
+
+同一 thread 同一时刻最多一个活动 turn；同一可写工作区也只能有一个活动写入者。
+当前任务 run lease 仍有效。未来并行必须增加明确的 packet 工作区和 thread 所有权，
+不能把“thread 忙”解释为另开 thread 后继续同时写同一工作区。
+
+## 6. 正常续用与崩溃恢复分开交付
+
+### 6.1 第一阶段能保证什么
+
+Codex Pro 首次调用请求 persistent history；正常取得并持久化完整终态回执后，
+下一次符合资格的返修显式传该角色的 thread ID。仍可每次启动独立进程并完整收尾。
+插件 `0.8.0` 已提供这条正常路径，Flywheel 需要接通它。[插件接口][plugin-machine-src]
+
+第一阶段只把**已可靠持久化回执的正常调用**作为可续用检查点。
+新建 thread 后、终态回执前崩溃，可能尚未保存 thread ID；即使 ID 已知，也可能没有可恢复 rollout。
+插件源码记录了其验证版本中“空 thread 不能恢复”的情况，不能将创建成功当成可恢复完成。
+见[thread start/resume 实现][plugin-wire]。
+
+文本 `onProgress` 不能充当恢复协议：它没有版本化结构和持久化确认，回调异常也不会可靠阻止执行，
+thread 文本出现的时机还早于完整配置核对。不要从日志解析 ID 后声称解决了崩溃窗口。
+
+### 6.2 中断核对所需的公开能力
+
+完整的中断核对需要插件新增公开、版本化的 typed lifecycle／recovery 契约，至少涵盖：
+
+1. 配置核对后的 `thread-ready`：明确 request/run/thread 关联、持久属性与证据。
+2. 发送新 turn 前等待 Go 保存检查点的程序确认；这是协议确认，不是新增用户审批。
+3. 区分 turn 派发意图、请求可能已发送、后端已接受和 terminal；终态仍带独立 cleanup 事实。
+4. 对已知运行的只读核对入口，说明哪些 turn／进程／结果事实能被重新确认、哪些仍未知。
+
+这些是拟议接口，不是 `0.8.0` 已有 API。即使有 early checkpoint，发送请求与持久化确认之间
+仍可能有不确定窗口；没有后端幂等执行契约就不承诺 exactly-once。
+正确行为是核对事实、保留 unknown、阻止盲目重放。
+
+| 中断位置 | 恢复要求 |
+|---|---|
+| 首轮已创建 thread，最终回执尚未持久化 | 保留工作区；先核对进程与结果，不承诺找回未知 thread |
+| 已知 thread 的新 turn 发出后断连 | 不能因知道 thread ID 就重复派发；先确认前一 turn 的事实 |
+| 完整回执已落盘，state／计量未完成 | 幂等补记已确认回执，不重新调用模型 |
+| 只有报告文件，最终回执丢失 | 报告不证明终态、清理、配置或使用量；核对前保持未知 |
+| resume 在新 turn 前明确拒绝且清理已确认 | 按有界策略重建并交接，保存失败原因与原计数 |
+| guardian 以后可能清理，当前尚无确认 | 当前调用不能报告成功或开始冲突写入；等待可核对证据 |
+
+沿用并扩展现有[未知清理停止规则][fw-cleanup]。跨机器恢复还依赖历史存储和环境可用性；
+只把 thread ID 写到任务目录，不会自动复制另一台机器上的 Codex 历史。
+
+## 7. 返修输入、重建交接与计量
+
+续用时仍发送简洁的本轮权威输入：目标与约束引用、契约修订、当前候选／diff、
+新的验证失败和评审 findings、已确认进展及本轮交付要求。历史不能覆盖这些事实，
+不能只写“接着做”并假定模型记得当前状态。稳定契约与易变反馈继续分离，避免无意义地重复整段历史。
+
+重建从 Spec、packet、磁盘成果、合法报告、验证结果和结构化反馈恢复。
+交接记录包含被替代 thread／attempt 的引用与重建原因，不复制 Executor 私有推理给 Reviewer。
+总结是导航材料，权威代码和验证仍需读取；不回滚已有成果，不重复已确认完成的外部动作。
+
+usage 按可归属的本次 run 增量入账，不能把 resume 返回的 thread 累计值每次当成新消耗。
+缺少可信基线或明细时保留 unknown/partial；美元成本未上报仍为 unknown，订阅调用不记成免费。
+预算包含所有历史 attempts、失败、重建和升级，遵守现有 soft／hard budget 语义。
+插件已有的 run delta／thread totals 字段也必须经过桥接协议校验。[用量回执][plugin-machine]
+
+运行观察至少展示角色／范围、create/resume/rebuild/wait、原因、最近调用状态和用量完整度。
+DSH 父会话的任务视图关联仍只代表该任务的控制面，不表示 worker transcript 已自动合并进父会话。
+历史保存、归档、保留期限与进程清理分别处理；关闭进程不删除工作区、交付或审计材料。
+具体历史保留策略应在实现时明确，不能默认将所有任务历史无限保存，也不承诺自动出现在某个桌面列表。
+
+## 8. 实施拆分
+
+| 阶段 | 可交付范围 | 完成边界 |
+|---|---|---|
+| P0：本 PR | 修改设计原则、记录现状与目标、双语指南链接、验证计划 | 仅设计评审；无源码、schema、包版本或发行变化 |
+| P1：Codex Pro 正常续用 | Go 会话记录／策略、版本化 worker 请求、persistent/threadId、start/resume 回执校验、正常返修与取消测试 | 在已启用的 Codex Pro 角色上按范围续用；只有已持久化的正常终态可作检查点 |
+| P2：其他后端与角色覆盖 | 核对并实现 DSH 默认 Execute／Review，以及 Kimi Execute、Plan／Judge 的范围连续性 | 能力逐项验证；接通 hard 不代表默认 Flash 路径已经完成 |
+| P3：中断核对 | 与插件公开 typed lifecycle、持久化确认与 recovery 契约配套 | 故障注入证明不盲目重放；不能只解析日志补 ID |
+| P4：上下文质量与效果调优 | 验证过的压缩／重建策略、真实任务对照评估、可观察原因 | 按质量与实测结果调整，不预设缓存率或节省比例 |
+
+P2、P3 可在 P1 契约稳定后分别推进。P1 先覆盖现有 Codex Pro hard Execute；
+若用户已经把 Review／Judge 显式配置为 Codex Pro，同一适配器应按独立角色句柄处理。
+不会为展示复审续用而自动把默认 DSH GPT Review 改为 Codex Pro。
+
+P1 至少涉及下列代码职责；具体字段和协议版本在实施 PR 中定稿：
+
+- `internal/state/`、`templates/state.schema.json`：会话／attempt 身份、回执补记、旧状态迁移。
+- `internal/machine/steps_execute.go`、`steps_verdict.go`、`steps_plan.go`：统一资格选择、反馈、停止与预算；不在各阶段复制另一套重试器。
+- `internal/drivers/`：请求与结果承载 thread/run/turn，分别校验 start/resume 的实际证据。
+- `plugins/dsh/src/codex-pro-bridge.js` 及 worker 协议：放行明确的持久／恢复字段，校验归属，保留清理和用量完整度。
+- 配置 schema／inspect／doctor／双语文档：明确后端能力与有效策略；预检不能通过调用模型证明历史可恢复。
+- 控制面和 skills：实施后说明状态和恢复入口；skills 仍只调用 Go，不自己挑 thread 或循环返修。
+
+生产目标是：已验证后端的新任务按上述范围策略正常续用，fresh 保留为合理选择和明确后备。
+先在能力白名单和显式试用中验证，再更新默认；每次启用都要有版本化状态和可核对的能力。
+既有任务缺少句柄时首次新建，不扫描用户历史、不猜“最近一次 thread”；
+旧任务的预算、attempt、停止与工作流语义继续保留。未知策略版本或损坏记录明确拒绝加载。
+
+不把现有 Plan `resident-session` 布尔值直接改成所有阶段的通用开关，也不改变用户显式的旧设置。
+新策略配置必须说明上下文选择与历史保存的区别；本设计不提供尚不能运行的 CLI 参数或配置示例。
+暂未支持的后端继续当前 fresh 行为，记录能力原因，不能伪装成成功 resume。
+
+## 9. 验收与效果评估
+
+### 行为验收
+
+| 场景 | 应能证明的结果 |
+|---|---|
+| Quick 首次通过 | 仍只有 Execute、独立最终 Review 两次阶段调用；全部原验证和交付门禁执行 |
+| Execute → return → repair → Review | Executor 两次使用同一角色 thread，Reviewer 可使用另一独立 thread；四次调用有各自 attempt/run/turn，旧证据不直接沿用 |
+| L1 红灯／格式错误 | 向正确角色回传明确反馈，既有尝试和预算仍有界；不混淆报告错误与回执不可信 |
+| Reviewer 复审 | 覆盖全部当前范围和新回归；关闭／重开旧 findings；Quick 所有需求重新形成裁决 |
+| 同目标契约修订／实质换目标 | 前者可按可核对兼容策略续用，后者重建；两者都失效并重验受影响证据 |
+| 新 packet／角色／第二意见 | 不复用错误范围的上下文；无执行者 transcript 泄入独立评审 |
+| 配置／路径变化 | 验证支持与不支持的 override；规范化路径；请求接受与实际生效证据不混淆 |
+| thread 不存在／忙／未有 rollout | 未派发且清理确认才允许有界重建；忙时不启动第二写入者 |
+| 中断／坏帧／清理未知 | 阻断 resume 和 fresh replay；保留工作区与真实未知状态 |
+| 回执已持久化但 CAS／入账中断 | 补记一次且仅一次，不再调用模型、不重复计算累计 usage |
+| 取消与显式 stop | 完整收尾；打开视图或 thread 可恢复不自动续跑 |
+| 旧任务与不支持的后端 | 兼容读取、保留预算与成果、明确新建原因，不扫描认领历史 |
+
+实施 PR 按仓库规则运行对应 Go 质量／覆盖率门禁、Node 与跨进程 bridge 检查；
+验证真实子进程、Git 候选、故障窗口和公开协议行为，不用测试镜像实现。
+离线检查与真实 Codex／Kimi／DSH 账号和 Mac 生命周期验收分开记录。
+本设计 PR 只核对文档、相对链接、来源、现状／提案边界和独立审阅，不声称上述实现测试已执行。
+
+### 效果评估
+
+对相同任务、模型、effort、权限、契约和独立验收，至少比较：
+
+1. 当前每次 fresh。
+2. Executor 同 packet 续用，Reviewer 每次新建独立上下文。
+3. Executor 与 Reviewer 各自在自己的范围内续用。
+
+覆盖首次成功、L1 修复、Review 退回、长上下文、停止恢复和配置变化；
+用多次配对试验记录质量／遗漏与回归、修复轮数、重复发现、耗时、input/output/cache 用量、
+重建原因和恢复失败率。未知用量保持未知；保存原始条件与结果，不预先宣称提升百分比。
+优先保证独立验收质量与运行正确性，再判断是否减少重复研究和成本。
+评估所需额外检查属于实验，不变成 Quick 默认多一个模型阶段。
+
+## 10. 参考资料
+
+- Flywheel [固定源码基线][fw-base]、[设计][fw-design]、[bridge][fw-bridge]、[driver][fw-driver]、[清理规则][fw-cleanup]。
+- Codex Pro [固定源码基线][plugin-base]、[machine 文档][plugin-machine]、[machine 实现][plugin-machine-src]、[thread 实现][plugin-wire]。
+- OpenAI [App Server][oa-app-server]、[Codex SDK][oa-sdk]。官方页面会继续更新；实现必须以锁定插件和实际 Codex 版本验证，不能拿新文档证明旧接口已经具备能力。
+
+[fw-base]: https://github.com/ckanner/flywheel/commit/80deeed4b62682585f82073e7bf9ce831728d6f7
+[fw-design]: https://github.com/ckanner/flywheel/blob/80deeed4b62682585f82073e7bf9ce831728d6f7/docs/design.md
+[fw-bridge]: https://github.com/ckanner/flywheel/blob/80deeed4b62682585f82073e7bf9ce831728d6f7/plugins/dsh/src/codex-pro-bridge.js
+[fw-driver]: https://github.com/ckanner/flywheel/blob/80deeed4b62682585f82073e7bf9ce831728d6f7/internal/drivers/codex_pro.go
+[fw-cleanup]: https://github.com/ckanner/flywheel/blob/80deeed4b62682585f82073e7bf9ce831728d6f7/internal/machine/cleanup.go
+[plugin-base]: https://github.com/ckanner/dsh-subagent-codex-pro/commit/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e
+[plugin-readme]: https://github.com/ckanner/dsh-subagent-codex-pro/blob/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e/README.md
+[plugin-machine]: https://github.com/ckanner/dsh-subagent-codex-pro/blob/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e/docs/machine.md
+[plugin-machine-src]: https://github.com/ckanner/dsh-subagent-codex-pro/blob/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e/src/machine.ts
+[plugin-wire]: https://github.com/ckanner/dsh-subagent-codex-pro/blob/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e/src/wire.ts
+[oa-app-server]: https://learn.chatgpt.com/docs/app-server
+[oa-sdk]: https://learn.chatgpt.com/docs/codex-sdk

package/docs/plans/2026-11-08-flow-console.md

@@ -0,0 +1,271 @@
+# Flywheel 流程控制台交互设计与实施方案
+
+2026-11-08。状态为已确认设计、完整控制台源码与故障验证进行中。基线为 Flywheel 0.29.1、`1087b686fa308284b6b68f238129f6779e0ba113`。用户本轮选择先审阅交互设计与实施方案。界面示例使用虚构任务，交互只修改原型草稿。
+
+## 1. 产品结构
+
+保留 DSH 原生「Flywheel」会话视图，位于「统计」之后。内部提供「运行画布」「配置」「运行对比」三个页面。通过 DSH 公开全局面板入口提供项目和配置入口，全局面板注册方式在实施前用当前桌面版本验证。
+
+顶部始终显示仓库链接、项目路径、当前分支、任务集成分支、worktree、DSH 来源会话、task ID、run ID、配置版本、数据更新时间。路径较长时折叠显示，并可复制完整值。
+
+- 全局入口先展示全局设置、已明确登记的项目和最近运行。
+- 会话入口根据确切的 launch/start 回执选择对应任务。一个会话关联多个任务时保留列表，并标记当前选择。
+- 终端运行进入已登记项目的运行列表，用户可主动将该运行关联到当前 DSH 会话。
+- 未关联任务时显示「准备新任务」「打开已有任务」「查看全局配置」。准备任务的交互复用 `/flywheel-task` 或 `/flywheel-new`。
+
+身份分为四层。项目承载仓库和配置，任务承载 spec/packets，运行承载配置快照和一次执行，Provider session 承载某一角色的模型历史。DSH 来源会话单独显示，避免与 Provider session 混用。
+
+## 2. 画布与阶段
+
+画布采用从左到右的阶段图。调度节点向上下分出任务，各任务的执行、测试、Review 和提交步骤在当前画布中向右展开。展开时保留主流程与其他任务，后续聚合和交付节点自动右移；再次点击可收起。前置任务的结果通过依赖边汇合。节点使用稳定 ID，刷新更新状态时保留位置、平移和选中项。
+
+画布支持空白处拖动、触控板横移、左右移动按钮，以及按阶段定位和定位当前节点。节点保持可读尺寸，长流程在画布内部横向浏览，窄屏仍保留左右流向。节点详情位于画布下方，避免压缩流程的横向空间。
+
+Full 的总览结构如下。
+
+```mermaid
+flowchart LR
+  A[需求与获准范围] --> B[Plan 与任务拆分]
+  B --> C[调度与依赖]
+  C --> D[任务分支]
+  D --> E[集成与聚合]
+  E --> F[L2 / L3 与 Judge 终验]
+  F --> G[远端 PR 与检查]
+  G --> H[远端 Merge]
+  H --> I[发布 · 可选交付目标]
+```
+
+每个任务分支展开为「资格／依赖 → Execute → L1／适用缺陷抽检 → Review → 单元提交与集成」。Review 退回的边返回该任务的 Execute，并标记第几次返修。Review 复审读取自己的历史。verification-gap 的边返回 Plan 修订契约。聚合视图展示各单元进入集成候选的结果及冲突。
+
+| 用户看到的阶段 | 0.29.1 的实际归属 | 模型配置位置 |
+|---|---|---|
+| 需求准备、初始拆分 | 宿主 skill 研究并生成契约 | 显示来源 DSH 会话模型 |
+| Plan 与契约修订 | Go 的 Plan Loop | `loops.plan` |
+| 调度 | Go 依赖与资格判断，当前顺序执行 | 确定性阶段 |
+| 执行 | packet 选择 route | `routes.default/frontend/hard` 或显式自定义 route |
+| 测试 | L1/L2/L3 及缺陷抽检 | 展示命令、结果、候选和退出事实 |
+| Review | 每个 packet 的独立评审 | `loops.review` |
+| 集成与聚合 | 单元 Git 提交、worktree 集成、里程碑 gate | 确定性阶段 |
+| 最终裁决 | Full 的 Judge 和可选第二意见 | `loops.judge`、`judge-panel` |
+| PR / Merge | 待接入的远端交付追踪 | 仓库授权与远端状态 |
+| 发布 | 可选目标，绑定版本、候选和环境 | 发布流水线与实际产物回执 |
+
+原型会把 Plan 和拆分画成相邻节点，以展示产物流向。真实状态由宿主准备回执、Plan 调用及契约验证投影得到。缺少独立阶段证据时展示「阶段内活动」或「待取证」，避免根据后续成功推断前面每一步的时间。
+
+### Full、ultraWork 与 Auto
+
+`ultraWork` 是本方案建议采用的 Quick 产品名称，后端继续使用 `quick`。Auto 保持 Go 按契约资格选择 Quick 或 Full。选择器同时展示请求模式、生效模式和判定理由。
+
+ultraWork 的画布为「准备并冻结契约 → 单任务 Execute → 必需验证 → 独立最终 Review → Git 交付 → 可选远端 PR/Merge」。Plan/Judge 显示「本流程不适用」及理由。Quick 升级 Full 时保留原运行、预算、尝试和证据，画布展开新阶段。已运行的 Full 保持其持久化策略，切换入口提供创建新运行草稿。
+
+## 3. 状态与细节
+
+### DSH 视觉规范对齐
+
+2026-11-08 复核 DSH 当前 UI 规范、对齐与间距说明，并参考宿主 Button、SegmentedTabs 和主题别名。控制台沿用宿主字体，信息正文采用 13px/20px，辅助信息采用 12px/18px，页面标题采用 18px/28px，区块标题采用 14px/22px。feature 字重最高 500。
+
+普通操作使用 H36/R12，紧凑工具使用 H28/R8，输入与选择器使用 R12，独立任务节点和配置卡使用 R20。选中、悬停、焦点和禁用状态保持相同尺寸。主按钮采用宿主主色的深浅对比，次操作用中性描边或 ghost。运行状态用小面积色点和文字表示，选中节点使用业务色细线与浅底。
+
+降低重复边框和表单噪声，将阶段定位改为轻量导航。节点中的 Provider / 模型保留可读字号，统一行距与左边线。节点详情顶部集中放置运行、重跑和接管操作，下方以紧凑页签切换证据与会话。图上的端口按固定节点尺寸居中连接，展开后保留可见返修回边。
+
+生产实现消费 `--dsw-alias-*` 和宿主圆角变量。设计稿以同角色的亮暗色值预览这些效果。圆角支持时沿用 `superellipse(1.5)`，状态圆点保持圆形。触屏操作区域至少 44px，窄屏表单与详情纵向排列，横向画布保持独立平移空间。
+
+来源为 [DSH UI 规范](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-client-ui-ux/SKILL.md)、[间距](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-client-ui-ux/references/spacing.md)、[对齐](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/skills/dsh-client-ui-ux/references/alignment.md)及[圆角规范](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/ui-radius.md)。
+
+本轮检查覆盖设计稿的桌面亮暗画布、深色配置页面、390px 容器的导航／表单、任务展开和节点操作。页面宽度实测无外部横向溢出，节点为 200×160px、字重 500，配置操作按钮为 36px。重跑、停止、未确认核对、人工继续、会话接管和配置草稿交互通过本地检查。以上是设计稿验证，生产插件接入后仍需真实 DSH 页面验收。
+
+| 呈现 | 含义与操作 |
+|---|---|
+| 灰色圆点「待开始」 | 展示前置条件 |
+| 蓝色进度图标「进行中」 | 展示角色、attempt、运行时间和 session |
+| 绿色勾「已完成」 | 可查看绑定当前候选的验收与交付证据 |
+| 橙色回转箭头「返修／重试中」 | 显示原因、失败类别及下一步 |
+| 红色错误图标「失败」 | 显示错误来源、退出码及处理入口 |
+| 紫色暂停图标「待人工／结果未确认」 | 展示需要的证据、停止状态和核对入口 |
+| 灰色短横「不适用」 | 显示跳过原因 |
+| 整体低饱和「快照已过期」 | 保留最后已知内容与更新时间 |
+
+颜色始终配文字和图标。远端 PR 状态与引擎任务状态分别展示。引擎完成后，远端检查失败仍会保持在交付阶段。终止、取消、失败与完成各自独立。
+
+画布下方的节点详情面板提供「概况」「配置」「证据」「Session」「历史」页签。窄屏将详情字段纵向排列。任务详情列出需求、依赖、route、worktree、branch、candidate SHA、尝试数、L1/L2/L3、Review findings、返修记录、错误码、日志片段及 PR 链接。只显示当前候选有效证据，旧证据进入历史。
+
+刷新策略建议为可见且运行中的画布每 2 秒进行一次有界只读查询。停止运行后每 10 秒刷新，隐藏时暂停。一次只保留一个查询，指数退避最多 30 秒，并显示最后更新时间。宿主会话切换后丢弃旧身份的迟到响应。轮询是本次拟议增强，需更新现有设计中「不周期轮询」的描述和对应测试。
+
+## 4. 配置先行
+
+配置页面提供「全局配置」「项目配置」「本次运行快照」。前两项可编辑，运行快照只读。每次保存均显示目标文件、SHA-256、完整差异和生效时机。
+
+当前优先级是任务目录配置 → 项目配置 → 全局配置 → 内嵌模板，选择一份完整文件。项目首次配置从当前有效配置生成完整草稿。UI 显示实际选中的文件；项目文件存在时，提示全局编辑对该项目的覆盖关系。未来若引入逐字段继承，需另行修改配置契约。
+
+「使用本版本默认配置」导入完整内嵌模板并给出差异。「保存项目配置」写入明确项目根下的 `flywheel.config.json`。「应用到全局」写入当前全局配置路径。两个保存按钮分别说明影响范围，原型只预览保存结果。
+
+每个模型 loop 配置资源渠道、Harness、模型、推理等级、会话策略和权限。用一个可读的渠道选择器生成一致的 harness/provider/channel 组合，高级区保留真实字段和 Provider 名称。模型候选以本机后端能力为准，同时允许填写明确模型 ID 并校验。
+
+| 资源入口 | Harness / Provider | 模型初始值 | 默认阶段 |
+|---|---|---|---|
+| ChatGPT · DSH | `dsh` / `chatgpt` | `gpt-6.1-sol`、`gpt-6-astra` | Review、Judge |
+| ChatGPT · Codex Pro | `codex-pro` / 原生订阅 | `gpt-6.1-sol` | hard Execute |
+| Kimi Code | `kimi` / 原生订阅 | `kimi-code/k3.1-pro` | Plan、frontend、Garden |
+| DeepSeek Account | `dsh` / `deepseek-account` | `deepseek-flash` | default Execute、Intake |
+| Claude Code Pro | `claude-code-pro` / 选定账号渠道 | 先用 CLI 别名 `sonnet`，也可选明确模型 | 用户指定的 loop／route |
+
+当前 Claude 适配器精确要求 0.4.0，桌面单独安装的 0.3.1 应显示「需要匹配适配器」，并引导正常安装流程。协议导入成功、账号已授权、模型实际可调用分别提供证据状态。
+
+全局区还包含预算、重试上限、超时、worktree、测试命令入口、默认流程、会话质量重建阈值和调度草稿。测试命令归任务契约维护，配置页面链接到对应契约编辑与校验流程。
+
+0.29.1 权限仅支持顶层 `permissions.mode`，取值为 `role-based` 或 `full-access`。按 loop 的权限覆盖需要新增 schema、解析和所有驱动的接纳验证。首版先展示每个阶段的有效权限及全局选择，逐阶段权限编辑在后续接口就绪时启用。账号密钥输入继续交给 Provider 的正常登录入口。
+
+保存流程为读取完整草稿 → schema/语义校验 → 展示差异与目标 → 用原内容摘要进行并发检查 → 同文件系统原子写入 → 重读实际配置。项目内的符号链接、路径别名、并发编辑和写入失败必须有明确结果。新增通用配置写接口复用现有迁移代码的路径和原子写入机制。
+
+运行期间保存草稿，界面标记「下次新运行生效」。涉及当前任务时，先等待或停止已有调用并核对 pending 回执，再允许激活新配置。未消费结果的旧绑定继续用于恢复验证。运行快照始终展示本次实际使用的配置摘要。
+
+## 5. Session 策略与跳转
+
+用以下四项取代单个「会话恢复」布尔字段。
+
+- 历史策略显示「同任务同角色续接 scoped」或「每次新会话 fresh」。
+- 隔离范围显示 task、packet／milestone、role。独立任务和不同角色始终隔离。
+- 本次动作显示新建、续接、重建或核对回执，附原因、generation、invocation ID。
+- 运行事实显示派发、终态、清理、历史可用性及只读 recovery 能力。
+
+Intake/Garden 标记为当前通用角色续接策略之外。支持续接与本次实际续接成功分别显示。每次 worker 进程重启时，Provider session 仍可在资格匹配后沿用。
+
+点击「查看会话」优先使用 Provider 已验证的只读历史入口。DSH SDK 会话通过公开导航 API 和准确 session ID 打开，若当前桌面 profile 无法读取对应历史则显示原因和日志入口。实现前核对 DSH 的实际公开导航及存储兼容能力，避免拼接猜测的 URL。
+
+终端入口显示 cwd、后端 home/profile、session ID、可执行程序版本和一条可复制的命令。本机帮助已确认以下原生形态，具体权限、home/profile、session 所在目录仍须由适配器验证。
+
+```sh
+cd -- '/absolute/worktree' && codex resume 'exact-thread-id'
+cd -- '/absolute/worktree' && kimi --session 'exact-session-id'
+cd -- '/absolute/worktree' && claude --resume 'exact-session-id'
+```
+
+最终按钮建议生成带任务租约检查的 Flywheel 包装命令，再通过 argv 启动原生 CLI。它是待新增接口。进入前检查当前 writer、后端恢复能力、持久化句柄和清理事实。运行中提供「查看历史」，需要交互写入时走「暂停并接管」。人工接管期间锁住引擎继续，归还时重新检查工作区、验收与权限。未知派发／结果时保持阻断。复制按钮仅负责复制，运行命令前还须重新检查租约以处理时间差。
+
+## 6. 串行与并行
+
+### 节点级交互执行
+
+节点详情的主操作随状态变化。鼠标选择、键盘选择和任务列表入口调用同一个受管操作。
+
+| 节点情况 | 主要操作 | Go 接纳条件与结果 |
+|---|---|---|
+| 待开始且前置已满足 | 运行此节点 | 获得任务租约，核对候选与配置，只执行获准的该阶段 |
+| 待开始但前置未满足 | 查看前置条件／运行所需前置 | 返回阻塞节点；明确选择后由引擎推进前置，不把未完成节点置为通过 |
+| 失败且调用已结束、清理已确认 | 重跑此节点 | 新 attempt，按有效策略续接对应角色历史，沿用预算和累计失败次数 |
+| 自动重试耗尽 | 人工继续一次 | 展示失败摘要与继续理由，记录一次有界人工授权；额度/权限不足时仍需先处理 |
+| 正在运行 | 查看输出／请求停止 | 确认进程收尾后才转入可重跑或接管状态 |
+| 结果未确认 | 核对上次结果 | 查原调用证据，完成核对后再提供安全的继续动作 |
+| 已完成 | 重新执行 | 显示将失效的下游测试/Review/交付证据，接受新候选后重新验收 |
+| 人工接管中 | 验证修改并交回流程 | 重读候选和契约，失效旧证据，进入必需验证与独立 Review |
+
+可接纳的待开始／普通失败节点支持一次点击发出操作，按钮显示待确认状态。成功响应后刷新节点。双击、刷新、重连、重复请求通过 operation ID 和任务身份去重。超时不自动再次派发。
+
+运行某节点与继续整个流程是两个按钮。单节点运行结束后显示「阶段已完成，流程等待继续」，由用户选择继续。执行器内部仍可完成其有界 Execute/L1 循环，界面提前显示这一操作包含的范围。
+
+现有 `run --only` 和 control start/stop 可复用其引擎逻辑。需要新增版本化节点命令，将 node ID、expected revision、candidate SHA、operation ID、单节点／流程范围和人工继续原因提交给 Go。所有作用域判断、前置门禁、证据失效和 attempt 更新由引擎完成。
+
+「进入会话自己发 prompt」使用前节的受管接管流程。用户可以在 Provider 桌面或 CLI 内修改成果，交回时 Go 重新验证。接管记录包含角色、原 session、worktree、起始候选、归还候选和授权范围；人工修改不能直接形成 Review pass。
+
+发布、push、PR 和 Merge 节点的重跑先核对原目标及外部结果。例如 npm 包已经存在时核对原 tarball integrity，PR 已合并时读取实际 merge commit。已确认完成的外部操作显示其回执，部分完成的操作从缺失步骤继续。每个发布节点绑定版本、源码、候选与目标环境，并使用该交付范围的已有授权。
+
+默认串行沿用现有引擎。并行模式的拟议配置包括最大并发、依赖、文件范围冲突、Provider 配额、预算和集成队列。独立就绪任务可并行，依赖未满足的任务保留等待原因。相互冲突的写入任务进入串行队列，每个并行执行单元使用独立 worktree。
+
+调度仍由单一 Go 状态写入者统一接纳结果并 CAS 保存。重启必须找回所有在飞调用，停止必须覆盖所有子进程组。集成和最终候选验收串行执行，避免两个完成结果覆盖彼此。界面通过 capabilities 展示并行可用性，0.29.1 上只能预览并行方案。
+
+拖动节点仅改变画布位置。改依赖、重排执行顺序、换模型属于运行方案编辑，需校验与明确激活。运行中的模式切换安排在所有受影响调用达到可信终态之后。
+
+## 7. 自动关联与 CLI 发现
+
+已存在的 `flywheelTask` projection 消费本会话 command/tool/PTC 的确切参数和回执。保留其 fork 隔离和结果未确认保护，扩展为多个任务的关联列表。
+
+skill 被提及只显示「准备中」。真正的任务定位来自准备回执里的物理 taskDir/cwd，以及之后的 launch 回执。计划新增 preparation 类型回执，让 `/flywheel-new` 准备出的任务也能打开画布。
+
+CLI 入口增加受管运行索引，记录 repoRoot、taskDir、cwd、branch、run ID 和最近控制操作 ID。索引提供候选列表，活跃状态仍向 Go 查询。索引按用户私有目录保存，通过原子更新协调并发登记，并处理失效目录。发现范围限于已登记项目，避免搜索整个磁盘的 `state.json`。
+
+项目、任务、运行、Provider session 使用稳定身份。分支只作为标签与归属信息，同分支可有多个任务，同一任务也可有多个 worktree。显式关联用于把终端运行接到 DSH 会话；模型文本里的路径和裸 skill 名称不自动建立运行关系。
+
+## 8. 成本、延迟与质量
+
+运行对比按任务／契约版本、工作流、模型、thinking、权限和 session 策略分组。显示样本数、成功／失败／未完成数、首次验收率、返修次数、回归与遗漏、端到端时延及各调用时延。
+
+用量保留 complete/partial/unknown，成本展示已知金额和缺失调用数。订阅调用缺少价格时显示「费用未报告」。P4 配对报告可导入并链接独立 oracle。只有条件相同的配对任务支持收益对比，原型使用「待采集」占位。引擎账本中的迟到 correction 按同一 invocation 对账后统计。
+
+## 9. 数据和接口拆分
+
+UI 通过 Go 的 JSON 接口读取状态和操作任务。新增只读投影统一计算节点、边、状态和能力，避免 React 根据多个字段自行重建状态机。沿用当前接口兼容旧客户端，新投影带独立 schema 版本。
+
+| 数据 | 当前来源 | 拟议补充 |
+|---|---|---|
+| 运行和任务 | `control status` 的 state/packets/milestones | run ID、阶段 projection、稳定节点 ID、current candidate |
+| 工作区 | packet.worktree/base-ref/commit | repo 身份、integration branch、当前 HEAD |
+| 模型和策略 | `control config` 的 bindings/session | 文件摘要、编辑 schema、能力目录、运行配置快照 |
+| session | state.sessions 与紧凑 sessions 投影 | 受控目标信息、查看／接管能力、租约 |
+| 失败和测试 | evidence/history/last-feedback/retry-history | 有界报告索引、候选有效性和原始证据链接 |
+| 成本与延迟 | metrics、budget、P4 reports | 有界分页、去重聚合和对比条件 |
+| PR | 当前由宿主／用户完成远端交付 | repo + PR number + head SHA + checks/review/merge 状态与更新时间 |
+
+PR 关联以当前运行的提交和分支为依据，远端 HEAD 变化时失效旧检查。首版提供打开仓库／PR 和只读刷新，后续开 PR、push、merge 操作遵循用户已有授权和仓库规则。引擎的本地 worktree merge 与 GitHub PR merge 分开呈现。
+
+建议修改点为 `plugins/dsh/src/client.js`、`client.module.css`、新增 canvas/config/session 组件、`task-association.js`、`index.js`、`control.js`，以及 `internal/cli` 的只读 projection、`internal/config` 的受管保存、`internal/diagnostic` 的能力解析。并行、session 接管和远端写操作分别作为后续引擎变更。实际协议改动同步 `PROTOCOL.md`、schema、中文与英文用户指南。
+
+## 10. 分期和验收
+
+| 顺序 | 交付内容 | 必须看到的验收结果 |
+|---|---|---|
+| A 配置 | 全局／项目编辑、阶段映射、正确 session 展示、内置默认导入 | 保存后 CLI 与 UI 解析一致；覆盖、校验、并发修改和失败恢复通过 |
+| B 画布与节点执行 | Full/ultraWork、任务钻取、颜色状态、单节点运行/重跑、有界人工继续 | 与 Go 状态逐项一致；前置门禁、双击去重、返修、Quick 升级和 unknown 保护可复现 |
+| C 关联与观测 | 多任务关联、CLI 登记、刷新、PR 只读跟踪、指标对比 | 跨会话/fork/分支切换与迟到响应隔离；远端 HEAD 绑定正确 |
+| D 会话入口 | 只读查看、后端验证、受管终端接管 | 每条跳转到准确会话；活跃 writer 和 unknown 下拒绝接管 |
+| E 并行和远端操作 | 调度器、独立 worktree、集成队列、授权 PR/Merge | 并发结果 CAS、预算、取消、重启与 Git 冲突回归通过 |
+
+交互评审应逐一走通「全局配置编辑」「项目覆盖」「从 DSH 准备并启动」「从 CLI 登记」「待开始节点单独运行」「执行测试失败后重跑」「自动重试耗尽后人工继续」「Review 退回」「结果未确认」「打开 Provider 历史并接管」「验证后交回」「ultraWork 升级」「PR 检查变化」「发布部分成功后继续」十四条路径。
+
+UI 验收覆盖 390px 和桌面宽度、亮暗主题、键盘、长路径、上百任务、错误重试和会话切换。Go 变更运行 quality-gate，插件运行 Node 与真实桥接，发行复用同一组六包进行安装验证。真实账号续接与桌面导航另列实机验收。
+
+## 11. 原型审阅重点
+
+交互原型提供总画布与任务子画布、配置作用域和映射编辑、Full/ultraWork、串行／并行草稿、返修／未确认示例、Provider 会话详情以及待采集的对比页面。配置保存反馈明确表示本地设计草稿。
+
+建议先确认画布层级与节点详情是否符合日常操作，再确认全局／项目配置的作用域，最后确定并行调度和接管入口的优先级。首版实施以 A、B 为一组，C–E 按接口依赖继续交付。
+
+## 当前实现记录
+
+本轮源码已接通横向 packet 画布、可见活跃任务轮询、真实节点证据／会话记录、scoped 展示和全局／项目配置编辑。新项目配置从内嵌版本默认值建立完整文件。节点操作复用 Go 的 Plan/Execute/Review/Verify 单环，并用 revision 与任务租约防止重复／过期派发。
+
+首版只包含受管阶段操作和全局配置。用户随后要求继续完整目标；以下续作属于未发行开发代码，首版门禁结果不自动覆盖新增代码。
+
+### 首版验证记录
+
+- Go 完整 quality-gate 逐函数覆盖率 100%，七个核心包的 race 检查通过。
+- 插件主套件 199 项和旧版宿主 8 项通过，DSH／Codex Pro／Claude Code Pro 离线桥接通过。
+- 根目录 npm 141 项通过，开发候选六包的安装套件 10 项通过，包含实际安装后的配置读取／保存和版本冲突拒绝。
+- 浏览器装载真实构建客户端，通过隔离 mock-driver 任务和真实 Go 控制接口验证了横向展开、单阶段执行、配置保存、人工继续一次及阶段完成后的暂停。人工重试计数从 3 增至 4，累计失败保留。
+- 检查亮暗主题和 390px 容器；窄容器表单单列，画布保留独立横移。正式 DSH 桌面升级与真实 Provider 推理留作发行后的实机验收。
+- 首轮暴露的测试退出时序均保留了失败记录。注册表超时夹具改用单进程 shell 预先登记 PID 和信号处理，Go race 子进程移除仅用于检测器退出的等待。Guardian 测试在原期限内等待 Darwin 临时 EPERM 消退，仅以 ESRCH 证明进程组结束。SDK 正常关闭增加到有界 2 秒，并用延迟落盘场景验证。
+
+
+### 完整目标续作（进行中）
+
+- 已实现 `permissions.bindings` 的按 loop／route 权限覆盖、加载期 schema 校验与实际 driver／diagnostic 解析；未覆盖阶段沿用全局策略。
+- CLI 与受管启动登记独立 run ID，记录启动／退出、配置／契约摘要、工作流和操作种类。索引不扫描磁盘、不作为任务存活判断。`control runs` 返回登记列表。
+- `control metrics` 先按 invocation 与 receipt 链核对迟到 correction，再按运行／角色／Provider／模型汇总。已知 Token、费用、时延与各自缺失计数并列显示；没有据此宣称模型质量或因果收益。
+- 已完成节点可通过有原因的 Execute 人工继续重开，旧证据与提交回执进入历史，后续节点和里程碑验收失效；累计用量和失败次数保留。
+- `control history` 只读准确 session 的最近摘要绑定回执。`control session`／`flywheel session` 提供 packet 会话的受管接管、原 thread 交互、核对原调用及验证交回。`state.handoff` 阻止普通自动运行；人工调用仍经预算和原适配器。交回重新跑 L1 和独立 Review，保存 human-takeover 候选证据，正常 Git 交付仍由引擎执行。
+- 接管命令经私有控制文件、内容摘要和 revision 传递，prompt 不进入 argv。路径别名测试发现 /var 与 /private/var 差异，现按物理任务根核对。
+- 针对新增功能的引擎、配置、指标和 UI 测试已陆续通过；逐函数完整门禁尚未关闭。期间完整 Go 测试全部通过（machine 包约 583 秒），覆盖率门禁报告新增分支未覆盖；在门禁运行期间继续修改源码会使部分行号归属失真，最终门禁必须在冻结源码后重跑。
+- 仍需完成：多任务关联历史／全局入口、真实并行调度与集成、PR／Merge 远端状态及授权操作、项目／分支身份补全、完整回归和实际桌面验收。当前没有发布、提交或更新真实桌面安装。
+
+- 并行调度首轮实现：`scheduler.mode/max-parallel/providers`，packet 的 `schedule.after/writes`；旧契约默认串行，声明依赖必须指向较早单元、写入范围必须是规范相对路径。Execute/L1 在独立 worktree 并发，协调器集中 CAS 和计费，hard 预算在确认计费前不释放模型调用槽。Review 与集成串行，合成候选重新验收。
+- 新增并行的真实 Git 集成测试和 race 测试已通过（两执行器重叠、第二单元 Review 看见第一单元产物、六次调用累计 1080 token、独立 scoped 会话、渠道限制、hard 预算仅派发一次、取消等待全部已启动工作返回）。并行故障分支的 100% 覆盖门禁仍在补齐，尚未用于真实模型或桌面安装。
+
+
+### 2026-11-09 验收进展
+
+主线已扩展为规划／拆分、调度、任务、集成、终验、PR、Merge。模型绑定记录来自运行快照／实际调用；Plan 的校验结果有独立回执。新增完整节点读取与大画布摘要、多个任务关联、按 run 对账、人工退出接管、分支／HEAD 归属、PR 远端查询与授权写入。Go 节点操作记录终态和失败原因。
+
+新增会话存储 v2 栅栏，并用冻结的 0.29.1 schema 证明旧引擎拒绝它。正常协议和旧 v1 读取保持兼容。CLI 测试索引统一放在临时目录，避免污染真实用户运行列表。
+
+旧 CLI 的三条时限失败保留在 `/tmp/flywheel-console-cli-tests3.log`。单独复查时，取消用例恢复通过，两个完整流程接近 10 秒边界。PATH 优先命中 Codex 自带 Git shell 包装器；20 次只读测量中位耗时约 13.5 ms，系统 Git 约 7.4 ms。使用系统 Git 的完整流程追踪为 4.54 秒，131 条 Git 命令自身累计约 0.47 秒。之后固定系统 Git 与 Node 24 工具链，既有用例时限不变。包级测试总等待窗口设为 30 分钟，以容纳增长后的全量套件；业务命令和取消时限没有放宽。
+
+整套回归另发现空节点详情空值访问和提前取消返回类型，均已修复。并行重试耗尽会在集成前继续原有 Plan 升级流程。最终门禁、候选安装与桌面视觉验收尚未关闭；任何历史首版通过均不替代本轮最终结果。