@ckanner/flywheel 0.28.5 → 0.30.0

package/docs/model-policy.md

@@ -14,7 +14,7 @@
 
 | 当前调用路径 | 已核对的能力 | Flywheel 当前请求 |
 |---|---|---|
-| GPT-6.1 Sol／Codex Pro 0.8.0 | 模型支持 `low/medium/high/xhigh/max`；machine API 原样传递 effort | hard 为 high |
+| GPT-6.1 Sol／Codex Pro 0.9.0 | 模型支持 `low/medium/high/xhigh/max`；machine API 原样传递 effort | hard 为 high |
 | GPT-6.1 Sol、GPT-6 Astra／DSH ChatGPT provider | 模型及已核对的 provider 表均列 `low/medium/high/xhigh/max`；请求写入 `reasoning.effort` | Review、Judge 为 high |
 | Kimi K3.1 Pro／Kimi CLI | 模型原生 `low/high/max`，默认 high，不能关闭 thinking | Plan、frontend、Garden 为 high |
 | DeepSeek Flash／DSH rc.5 | DSH 接受 `off/low/high/max`，默认 high | 普通执行 high，Intake low |
@@ -50,7 +50,7 @@ hard 承担难实现，Judge 在 L2/L3 后独立核对整个里程碑；它们
 - SDK 接受配置或 machine API 接受请求，只证明对应接口接纳，不是效果评测。
 - 服务端实际采用的强度和质量收益，需要独立回执或实际任务测量；当前证据不能补造这些事实。
 
-DSH `initialize` 调用配置校验，但回复只含 serverInfo。Flywheel 的 `ready.reasoningEffort` 是初始化成功后的请求回显，不是模型服务独立返回的 effort 证明。Codex Pro 回执明确区分 `requestedEffort`、`accepted` 和未知的 `effectiveEffort:null`。依据见 [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts)及 [Codex Pro 0.8.0 协议](https://github.com/ckanner/dsh-subagent-codex-pro/blob/04ecdb677735d84f3a0f5dba01a9d9b28c324c0e/docs/machine.md)。无推理 doctor 也不能证明账号余额、真实调用或更高档位的收益。
+DSH `initialize` 调用配置校验，但回复只含 serverInfo。Flywheel 的 `ready.reasoningEffort` 是初始化成功后的请求回显，不是模型服务独立返回的 effort 证明。Codex Pro 回执明确区分 `requestedEffort`、`accepted` 和未知的 `effectiveEffort:null`。依据见 [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts)及 [Codex Pro 0.9.0 协议](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md)。无推理 doctor 也不能证明账号余额、真实调用或更高档位的收益。
 
 ## 5. DeepSeek 默认应使用已充值账号
 
@@ -59,3 +59,7 @@ DSH `initialize` 调用配置校验，但回复只含 serverInfo。Flywheel 的
 桌面能在登录后初始化账号默认模型，但独立 SDK 调用仍需明确 provider/model。Flywheel 固定请求 `deepseek-account`／`deepseek-flash`，既采用指定账号通路，也保持“只用 Flash”的选择。认证失败或额度不足会报告；默认预设没有跨渠道后备。用户显式配置的后备链仍按原有规则执行，本轮不新增后备路径。
 
 **发布与迁移要分开：**0.28.3 将内嵌默认改为账号，0.28.2 仍内嵌 API 默认。安装升级保留已有用户配置，采用新账号预设需升级至 0.28.3 或以后版本，再预览并显式应用迁移。完整账号/API 区别、共享登录条件和迁移步骤见[配置指南](configuration.md#deepseek-账号与-api-key-是两个-provider)。本轮没有修改用户机器上的凭证或正在运行的任务。
+
+## 可选 Claude Code Pro
+
+默认模型策略尚未给 Claude 分配场景。可选 `claude-code-pro` harness 接收明确的原生模型与 low/medium/high/xhigh/max 请求，具体 CLI／账号可能拒绝某项选择；此接入不新增模型排名或 effort 实测结论。配套 0.4.0 公开接口、full-access 边界及用量口径见[接入指南](claude-code-pro.md)。

package/docs/session-evaluation.md

@@ -0,0 +1,120 @@
+# 会话质量策略与配对评估
+
+P4 提供两部分可执行能力：按已确认事实进行有界重建，以及对相同任务运行三种历史策略的配对评估。重建阈值默认关闭；评估程序保存原始条件和结果，不把缺失用量写成零，也不预设质量、缓存率或速度收益。
+
+配置入口见 [配置文档](configuration.md)，中断恢复的生命周期和账本语义见 [恢复文档](session-recovery.md)。实现入口为 [质量策略](../internal/machine/session_quality.go)、[评估器](../scripts/evaluate-sessions.js) 与 [任务集生成器](../scripts/prepare-session-evaluation.js)。
+
+## 有界重建
+
+`sessions.roles` 可分别指定 `plan`、`execute`、`review`、`judge` 和 `judge-panel` 的 `fresh` / `scoped`，未配置的角色继承 `sessions.mode`。Plan 的显式 `resident-session:false` 仍然禁止续用；显式 `sessions.roles.plan:"fresh"` 也关闭旧 Kimi Plan 的续用入口。
+
+`sessions.quality` 支持以下阈值；`0` 表示关闭，对既有默认行为没有改变。
+
+| 配置 | 触发依据 | 能证明的内容 |
+|---|---|---|
+| `max-confirmed-turns` | 本代已确认、安全归属的 turn 数达到阈值 | 对话被重用的次数；不等同于质量已经下降 |
+| `max-unproductive-turns` | Execute 连续完成后，候选成果 fingerprint 没有变化 | 磁盘候选没有进展；不推断模型思考过程 |
+| `max-run-input-tokens` | 最近一次完整、可归属的单次运行 input 达到阈值 | 该次输入用量；不等同于原生历史占用或剩余上下文容量 |
+
+只有上一调用已经消费、记账状态已保存、派发与终态确定、清理已确认、候选成果可核对时，才按这些阈值重建。未知派发/终态、未完成的生命周期和未确认清理先进入 P3 的恢复或现有升级路径。partial/unknown usage 不能触发输入用量阈值；但已确认 turn 数和候选无进展仍可独立触发各自阈值。未知用量继续保留，原有 hard budget 可另行阻断后续调用。重复消费同一 invocation 不重复增加计数。
+
+重建记录原因、代数、被替代调用引用，并通过当前 Spec、packet、磁盘成果、合法报告、验证证据和结构化反馈交接。Executor 的私有历史不会复制给 Reviewer。新代重置本代质量计数，但任务 attempts、失败、耗时及预算账本继续保留。这里使用可验证的重建，不调用额外模型做未计量的历史压缩。
+
+## 三种固定策略
+
+评估器使用同一固定 Git commit、任务契约、模型、effort、权限、验收与质量阈值。它只改变 Execute / Review 历史策略。
+
+| 报告中的 variant | Execute | Review | Plan / Judge / judge-panel |
+|---|---|---|---|
+| `fresh` | 每次 fresh | 每次 fresh | 显式 fresh |
+| `executor-scoped` | 同 packet 范围 scoped | 每次 fresh | 显式 fresh |
+| `role-scoped` | 同 packet 范围 scoped | Reviewer 自己的评审范围 scoped | 显式 fresh |
+
+`role-scoped` 是设计中的“Executor 和 Reviewer 各自在自己的范围续用”，不表示所有角色共享一个 thread。每个 case 至少运行两次配对重复，每一组含三种策略；运行顺序按 case 和重复编号轮换。每个 trial 使用新的隔离 Git clone，不修改原始仓库，不把前一个 trial 的工作树或历史交给下一个 trial。
+
+## 准备可执行任务集
+
+先准备完整的 Flywheel 配置，显式指定 `routes.default` 和 `loops.review`，以及它们引用的渠道。使用已经能正常运行的账号与后端配置。生成器只读取这份配置，不运行模型，也不读取或复制账号凭据。
+
+```sh
+node scripts/prepare-session-evaluation.js \
+  --config /absolute/path/flywheel.config.json \
+  --output /absolute/path/new-session-corpus \
+  --repetitions 2
+```
+
+生成器输出新的本地 Git 仓库、精确 commit 和 `manifest.json`。它为所有 trial 统一关闭额外 worktree 创建，因为评估器本身已经逐 trial 隔离；并把冻结检查 `eval/` 加入保护范围。原配置文件不被覆盖。
+
+生成的配置变化场景使用 `medium` / `high`。所选模型必须接受这两个值；不同 effort 枚举的后端应在运行前把 manifest 的 `configure` 步骤改为该后端明确支持的另一个值。三种策略使用同一份修改后的 manifest，不在某一个 trial 中临时猜测或替换。
+
+内置任务是一个可独立验收的真实代码修改：实现纯函数 `compactRanges`，把安全整数数组变成排序后的最大闭区间，去重、支持负数和空数组，并保持输入数组不变。冻结 L1 检查输出，最终 Review 独立检查输入不变性；进程外的固定 oracle 同时检查两者。模型自己的 done-report 不是评估评分依据。
+
+| 场景 | 实验步骤 | 观测条件 |
+|---|---|---|
+| `first-pass` | 从未实现代码开始正常执行 | 完成任务，且一次 Execute、一次 Review |
+| `l1-repair` | 首次执行后，固定脚本注入错误输出；真实 L1 拒绝，再由引擎修复 | 存在 L1 失败且 Execute 多于一次 |
+| `review-return` | 注入输出仍正确、但原地排序输入的回归；L1 通过，Review 应退回 | 存在 Review return 且 Execute 多于一次 |
+| `long-context` | 在实际 Execute prompt 的 `cache-scope` 中加入稳定参考材料 | 实测单次 input 达到 manifest 阈值；缺失用量记 unknown |
+| `stop-resume` | 在 Review 前由引擎正常暂停，再显式运行 | 已保存 paused 状态后继续执行；这是阶段边界恢复 |
+| `configuration-change` | 首次 Execute 后显式改变同一 binding 的 thinking，再执行 | 观察到有效 binding fingerprint 改变 |
+
+受控注入只修改候选代码；评估器核对注入前后的 Go state、任务契约和配置不变。它不伪造 L1、Review、receipt、metrics 或 state。阶段边界暂停不替代 P3 对活跃 turn 杀进程、ACK 故障窗口和只读恢复的独立测试。
+
+有效配置写在隔离 trial 的候选目录外，通过 `FLYWHEEL_CONFIG` 指定。开始前，评估器在该 clone 中移除会覆盖它的根目录和任务目录配置并提交这个实验基线。因此配置变化不会伪装成模型修改受保护契约。源配置和变更前后 binding 均保留在条件记录中。
+
+## 运行真实后端评估
+
+构建当前 Go CLI，确认所选公开 adapter、原生 CLI 与账号能够执行任务后运行：
+
+```sh
+node scripts/evaluate-sessions.js \
+  --manifest /absolute/path/new-session-corpus/manifest.json \
+  --flywheel /absolute/path/flywheel \
+  --output /absolute/path/new-session-results \
+  --live
+```
+
+`execution:"live"` 必须显式传 `--live`，且不能使用 mock driver。评估器使用提供的模型与权限，不自动切换到其他模型、渠道或更宽权限。输出目录必须不存在，已经保存的结果不会被覆盖。
+
+所有调用仍走真实引擎的预算、停止和恢复规则。manifest 的 `maxCalls` 是额外的观测调用上限：运行中每 50 ms 检查落盘 metrics，达到上限发送取消；已在途调用和 metrics 落盘延迟可能造成超出，因此它不是模型调用前的事务额度预留。`runTimeoutMs` 控制每个步骤，取消后保留最多 30 秒清理时间。强制杀进程、未知派发/终态或未确认清理会停止整个实验，保存已知结果，不自动重发。
+
+## 报告如何解释
+
+`report.json` 包含源 commit/tree、manifest/config/engine/oracle 的 SHA-256、开始结束时间、每个 trial 的固定条件、顺序、策略、原始步骤结果和配对比较。每个 trial 另存 stdout/stderr、状态快照和原始 metrics。独立 oracle 从固定 commit 复制到候选目录外，执行前后核对 hash；候选篡改 oracle 会终止实验。
+
+| 字段 | 含义与边界 |
+|---|---|
+| `quality.pass`、`omissions`、`regressions` | 独立 oracle 的结果；未完成检查保留 null，不拿引擎 completed 代替质量证据 |
+| `repairRounds` | packet attempts 减首次执行的总数；使用真实 Go 状态 |
+| `repeatedFindings` | 规范空白后完全相同的 Review return 原因重复数；不声称语义相同 |
+| `elapsedMs` | 引擎运行步骤耗时；不包含 clone、oracle 与注入开销 |
+| `usage.*.known` | 完整单次 input/output/cacheRead/cacheWrite/totalTokens 的已知合计 |
+| `observedCalls` / `missingCalls` | 各指标实际可计数和缺失的调用数；有缺失时 known 仅为下限 |
+| `cost.knownUSD` | 已知费用合计；缺失费用单列，不把订阅账单当零 |
+| `actions`、`rebuildReasons` | 实际创建、续用、重建次数及其可核对原因 |
+| `recovery` | 续用数、失败或未知续用数、未知终态、未解决调用、只读核对次数 |
+| `scenarioCoverage` | 分别记录已计划、实际观测到、未观测到和 unknown；场景名称不是成功证据 |
+
+P3 的 `record-kind:"reconciliation"` 行按 `reconciles-invocation` 替换原调用的后验事实；不把审计行当成新模型调用，也不重复累加用量或费用。原始审计行仍完整保存。
+
+只有三个策略都完成配对、固定条件相同且实际 role/harness/provider/channel/model 集合一致时，才计算差值。某个用量字段缺失则该差值为 null。报告没有自动生成收益百分比；需要先判断验收质量和场景是否成立，再讨论性能变化。
+
+## 离线门禁与真实证据分开
+
+仓库提供三层不同的证据入口：
+
+1. `node --test npm/test/session-evaluation.test.js` 验证 manifest、隔离、未知用量、配对与停止规则，使用明确标记的 runner 协议 fixture。
+2. 下列命令运行真实 Go CLI → worker 3 → 实际公开 Codex 0.9 包 → 原生 CLI fixture，共 36 个 trial。fixture 只实现原生协议和受控代码工作，不写 Go state/metrics/receipts；真实引擎执行 L1、Review 判定、Git 边界与恢复选择。
+3. `--live` 使用真实后端推理，才能提供模型质量、缓存、耗时与费用方面的实际证据。
+
+```sh
+FLYWHEEL_EVAL_BINARY=/absolute/path/freshly-built-flywheel \
+FLYWHEEL_EVAL_OUTPUT=/absolute/path/new-native-evaluation \
+node scripts/test-session-evaluation.js
+```
+
+仓库根目录的 `npm run test:sessions` 是同一门禁入口，接受相同环境变量。
+
+第二层要求已构建 `plugins/dsh/dist`、已安装实际固定版本 Codex 包；缺少二进制或依赖会失败，不会自动 skip。它在独立目录冻结 worker 和公开包，原生 fixture 只能访问带实验标记的 CODEX_HOME 与任务集，不接触实际账号。用量由 fixture 合成，只验证计量链路，不能作为模型节省数据。
+
+当前实现不以离线通过宣称真实账号或 macOS 生命周期验收已完成。真实环境若拒绝权限或在 thread/start 超时，应保存阻断证据；默认阈值继续关闭，直到配对真实结果支持具体调整。

package/docs/session-recovery.md

@@ -0,0 +1,81 @@
+# 会话中断恢复与上下文质量
+
+本指南描述会话方案 P3/P4 的当前源码实现。P1/P2 的角色历史续用和已保存回执消费继续有效；新能力需要配套的 **Codex Pro 0.9.0** 或 **Claude Code Pro 0.4.0** 公开 machine API。源码、npm 发行、账号可用性和真实任务效果是不同的验收项。
+
+## 1. 谁拥有哪些事实
+
+| 层 | 责任 |
+|---|---|
+| Go 引擎 | 任务状态、角色与范围、调用意图、候选与契约检查、预算、计量、回执消费和交付 |
+| Flywheel worker v3 | 传递有类型的生命周期帧；等待 Go 的持久化 ACK；转发取消；不作业务判断 |
+| 上游 machine API | 独立 supervisor、私有 durable journal、原生进程 guardian、完整原始终态回执、只读 `recoverMachine` |
+| 原生 Codex / Claude | 模型与工具执行、原生历史、实际配置与可观察 usage |
+
+外层 worker 协议为 3，插件请求和回执仍是 machine protocol 1，生命周期单独为 version 1。DSH 和 Kimi 继续使用其已实现的正常历史续用及 Go 回执恢复；不能从这两个新插件的能力推断它们也有同样的 P3 接口。
+
+## 2. 派发前必须有持久化确认
+
+Go 准备任务的 `.sessions/` 父目录并保存调用意图，上游 API 再独占创建本次调用的恢复子目录。子目录以调用 ID 的摘要命名；不在用户的全局模型历史中搜索。
+
+上游按实际可观察边界发送 `thread-ready`、`dispatch-intent`、`dispatch-possible`、`turn-accepted`、`terminal` 和 `cleanup-confirmed`。不同后端可观察到的事件不同，不能自行补齐：
+
+- **Codex** 的 `thread-ready` 在 `turn/start` 之前返回实际 thread/configuration。Go 在确认 ACK 前核对完整权限策略、cwd、模型和身份。任一确认失败会阻止后续 turn。
+- **Claude** 只有提交 prompt 后才返回原生 init。它提供派发前的 intent/possible ACK，但不宣称有 prompt 前的 thread-ready 或真实 turn-accepted；实际配置仍是终态接纳检查。
+
+Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点与状态，再回 ACK。缺失、错误、重复、过早或超时的 ACK 不能释放后续步骤。`persistent:true` 表示请求保留原生历史；不表示空 thread 已有可恢复 rollout。
+
+上游 supervisor 与 worker 的生命周期分离，拥有原生 guardian。worker 断连时，它取消尚未确认的步骤并收束原生进程；终态回执在向 worker 通知终态之前已落盘。通知或最后 ACK 丢失不能把原本成功的完整回执改成“未执行”。
+
+## 3. 恢复只读，不会重发 prompt
+
+重新启动同一任务时，Go 根据原调用保存的 adapter 版本、request/run ID、任务目录与绑定，调用公开 `recoverMachine`。它只读取那个调用的 journal，不启动原生 CLI，不执行 `thread/resume`，不查询其他任务，不重新提交 prompt。
+
+| 恢复返回 | 含义与引擎行为 |
+|---|---|
+| `terminal` | 找到同一调用的完整原始回执；继续核验身份、执行终态、清理、用量与原候选证据 |
+| `pending` | 尚未找到已持久化终态；不证明原进程仍存活，保持阻断 |
+| `unknown` / 损坏 / 错配 | 无法证明该次调用结果，保留证据并阻断；不能换 fresh、换后端或删账本来重放 |
+
+只读查询可以重复。原生机器、历史文件或 journal 不可用时，不承诺跨机器恢复。supervisor 自身也被终止时可能只剩 pending；本实现没有 exactly-once 执行保证。
+
+### 回执成功仍须有原候选证据
+
+`cleanup-confirmed` 到达时，Go 在 ACK 前保存该次执行结束后的候选摘要、原角色 guard，以及 Execute 的报告。恢复得到成功回执后，必须同时有这份原调用的证据，才能应用业务结果。重启后重新拍摄的工作区、重新跑过的验收不能替代原检查点。
+
+若 supervisor 保存了回执，但 Go 尚未来得及记录原候选，则可恢复可信用量，业务仍保持阻断。只有物理事实证明未派发、清理完成且候选与原 guard 完全未变的拒绝，才允许按已知未执行处理。独立 Review/Judge 的原契约与候选检查继续适用。
+
+## 4. 计量与预算
+
+已消费的调用不再次计数，不重发模型请求。原调用曾因丢失回执计为 unknown、后又找回可信 usage 时，Go 按同一调用记一条可审计 correction；保留原 provider、原日桶和 lifetime 归属。已过保留窗口的日桶不会因为恢复而重新出现。
+
+状态采用 CAS，receipt、状态和 metrics 都在成功前持久化。metric 已追加但状态 CAS 失败时，重试不会追加第二份相同调用；已存在行也必须再次确认文件与目录已同步，不能将“可读”当作持久化完成。
+
+未知仍不是零。恢复中的质量重建、Quick → Full、角色模式变化和新 worker 都不重置预算、尝试次数或未知调用阻断。预算只约束新的派发，不妨碍消费已经执行完成且证据齐全的结果。
+
+## 5. 可解释的上下文重建
+
+`sessions.roles` 可分别选择 Plan、Execute、Review、Judge 的 fresh/scoped；未覆盖的角色沿用总模式。具体配置见[会话策略](configuration.md#会话策略历史复用与调用安全)。
+
+可选 `sessions.quality` 接受三个有界指标：
+
+| 字段 | 观测事实 |
+|---|---|
+| `max-confirmed-turns` | 当前角色历史已确认且去重后的调用次数 |
+| `max-unproductive-turns` | Execute 连续完成调用但候选摘要未变化的次数 |
+| `max-run-input-tokens` | 最近一次可完整归属的实际输入 token 数；不是猜测的上下文窗口大小 |
+
+所有阈值默认关闭。只有原调用已安全终止、计量并消费后，阈值才可让下一次调用重建。unknown 或待消费结果优先处理，不能借重建绕过。
+
+重建保留明确原因与 generation，并用当前 Spec、packet、工作区、合法报告、验证与结构化反馈交接。它不读取另一个角色的私有 transcript，不以“压缩成功”伪造模型事实，也不另发未计量的模型压缩调用。Review 即使续用自己历史，仍须检查完整当前候选。
+
+## 6. P4 对照评估与证据边界
+
+仓库提供固定源码与独立 oracle 的评估工具，比较 fresh、仅 Execute scoped、各角色 scoped。覆盖一次成功、L1 返修、Review return、长上下文、停止恢复、配置改变；轮换策略顺序并要求重复运行。工具记录完成质量、漏项、回归、返修轮数、重复 findings、耗时、已知/未知 token 与缓存、重建原因和恢复失败。场景是否发生由实际状态证据判断，不靠名称。
+
+离线 native fixture 经过真实 Go、worker v3 和公开插件接口，验证评估工具及安全边界；它不是实际模型质量、缓存率或节省比例。真实账号的对照结果需要可用的原生 CLI、账号、权限与模型环境。未获得该结果前不自动启用阈值，不改变任何默认模型或 loop。操作步骤与实验产物说明见[配置指南](configuration.md)及 `scripts/prepare-session-evaluation.js`、`scripts/evaluate-sessions.js` 的帮助。
+
+## 7. 保存和排障
+
+上游恢复目录与文件使用私有权限、独占创建、身份/摘要检查和原子持久化；已存在目录不会触发二次执行。它们属于任务审计证据，可能含模型输出与诊断。按任务一起保存、备份和控制访问，不复制凭证，也不因安装升级而删除未知调用的证据。
+
+当前没有自动删除这些恢复证据的保留计时器。确认任务完成或由人解决未知结果之后，才能按项目的任务归档流程处理；删除 journal 不是解除阻断的恢复方法。`control status`/doctor 是查看入口，模型与 skills 不修改 `state.json`。需要恢复时仍从原任务目录使用正常 Go 启动入口，由引擎核对并决定下一步。

package/docs/workflow.md

@@ -10,9 +10,44 @@ Codex Pro 插件 machine API；源码存在不代表 npm `latest` 已更新，
 Flywheel 将通过验收的 packet 合入任务分支；整个需求通过终验和远端检查后，
 再由人或已获授权的宿主 Agent 合并 PR 到 `main`。
 
+## 0. 常规入口：描述目标并启动
+
+包含自适应工作流的同版本 CLI／DSH 插件提供统一入口：
+
+```text
+/flywheel-task 修复已定位的问题，补齐回归测试并完成验证。mode=auto
+```
+
+宿主使用当前对话研究代码、复用或建立任务 worktree，准备 Spec、packet、验收与
+工作流事实，保存契约后调用 `flywheel_launch`。Go 校验资格并启动，DSH 将这个
+具体任务关联到当前会话的 Flywheel 视图；通常无需复制路径或反复确认已授权范围。
+`flywheel control launch --help` 可确认新接口是否存在；旧发行中的基础命令不代表
+已经具备此入口。
+
+| 选择 | 引擎选择与闭环 |
+|---|---|
+| Auto（默认） | 根据已研究并记录的事实选择 Quick；资格不足或存在风险则 Full |
+| Quick | 一个里程碑、一个 packet，执行、全部必需验证、独立最终 Review、Git 交付 |
+| Full | Plan、逐 packet 执行与评审、集成 L2/L3、Judge |
+
+Quick 不按文件数量判断风险。范围与实现模式必须明确、全部需求有验收映射、
+独立最终评审可以完整判断，缺失 L2/L3 要有不适用理由。鉴权、支付、迁移、并发、
+权限或未决设计等使用 Full；显式 Quick 也不能绕过资格。最终 Review 发现验收
+缺口或新风险时，Go 保存升级并继续 Full，保留预算、工作区和历史。
+
+正常首次成功的 Quick 只有 Execute 与最终 Review 两次阶段 Agent 调用，宿主
+准备、模型内部轮次和重试另计。必需测试、覆盖率、适用 L2/L3 与缺陷注入仍保留，
+而且都必须验证最终 Review 读取的同一候选。Plan／Judge 记录为“不适用”及原因，
+不能显示假通过。
+
+只想先看方案时用 `/flywheel-new <需求>`；已准备或要恢复任务时用
+`/flywheel-run <真实任务目录>`。用户已有的工作区、实施与交付授权继续沿用，
+明确提出“先给我看方案”时才停在审阅。下面逐节展开准备、启动与交付的检查点，
+不要求自动入口逐项等待用户点击。
+
 ## 1. 选择准备阶段的模型
 
-`flywheel-new` 使用当前 DSH 对话的模型。`loops.plan` 只控制引擎启动后的规划
+`flywheel-task` 与 `flywheel-new` 使用当前 DSH 对话的模型。`loops.plan` 只控制引擎启动后的规划
 和修订，不会替准备阶段切换模型。建议按需求的不确定性选择：
 
 | 准备任务 | DSH Provider / 模型 | 思考等级 |
@@ -95,6 +130,11 @@ Kimi 的语法。依据见 [DSH 技能入口](https://github.com/deepseek-ai/dee
 不要填未经运行的验收结果；环境缺失应标记 unverified。不要手工创建或修改
 `state.json`，它由引擎管理。完整要求见 [flywheel-new](../skills/flywheel-new/SKILL.md)。
 
+自动准备启动使用 `flywheel-task`，其契约在 Spec 的 `workflow` 中记录 mode、
+版本、代码依据、风险与资格判断，字段见[工作流配置](configuration.md#工作流策略与恢复)。
+只有模型写了“low risk”不能取得 Quick；Go 校验结构与声明，执行和最终评审再
+检查实际候选。没有 workflow 字段的旧契约保留 Full。
+
 按已有 Git 授权保存审阅后的契约，仅选择本任务文件：
 
 ```sh
@@ -144,38 +184,46 @@ flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 ```
 
+新统一入口可将 start 换成 `control launch ... --mode auto`；它消费已经准备的
+契约，默认请求 Auto。`start`／前台 `run` 可带 `--mode auto|quick|full`，省略时
+保留契约或持久化策略。旧状态不会因新增 --mode 而静默跳过原来的 Full 阶段，
+恢复也不会重新分类或从 Full 降为 Quick。
+
 预检不发送模型推理，不能证明账号额度或真实模型调用已经通过。启动会实际调用
-所选模型。另选 DSH 的 Flywheel 视图时，把准备阶段给出的 `task_dir` 填入
-“任务资料目录”；“项目目录”可留空，前提是 DSH 当前工作目录已经是同一个
-`repo_dir`。当前源码通过公开 `workingDirectory.get(session)` 读取它；显式路径
-优先，不从任务名或历史对话猜路径。仅在 shell 中 `cd` 不会改变 DSH 的会话目录，
-未切换会话工作目录时应填入真实 `repo_dir`。不要混用原 checkout 的账本和新 worktree。
-技能调用不会自动选择视图中的任务，视图也不自动发现或启动任务。
-
-每个 packet 的实现、L1 与独立 Review 通过后，引擎提交并快进合入任务分支。
-所有 packet 完成后仍需里程碑 L2/L3 与 Judge；单元合并不代表整个需求已通过。
+所选模型。DSH `flywheel_launch` 与 `flywheel_control` start 将明确的 `taskDir`
+和 `cwd` 关联到发起会话的 Flywheel 视图；单纯 shell 调 CLI 不会创建桌面会话关联。
+终端启动或另开已有任务时，仍可手动填“任务资料目录”和“项目目录”。后者仅在
+会话当前目录已经是同一 `repo_dir` 时可留空。插件通过公开
+`workingDirectory.get(session)` 读取目录；不扫描或猜测。仅在 shell 中 `cd`
+不会改变 DSH 的会话目录，不要混用原 checkout 的账本和新 worktree。
+
+Full 的每个 packet 经实现、L1 与独立 Review 通过后，引擎提交并快进合入任务分支，
+全部 packet 完成后仍需集成 L2/L3 与 Judge。Quick 在实际 packet 候选中先执行
+所有适用 L2/L3，再作覆盖全部需求的一次最终 Review，然后持久化同一候选。
+两种流程都必须核对 `state.status` 与交付证据；单元合并不等于整个需求完成。
 合并冲突或验证失败时保留产物并处理记录，不强制清理。停止与恢复见
 [入门教程](getting-started.md#7-启动观察停止与恢复)。
 
-若报告 `cleanup-unconfirmed` 或 `process cleanup is unconfirmed`，引擎会将本次
-运行升级为 `escalated` 并停止自动执行，保留工作区和审计记录。先核对本次调用
-拥有的 worker、guardian 和 app-server 是否已退出，再按恢复流程继续；不能仅
-因外层 worker 已退出或已等待几秒，就假定内部进程不会再修改工作区。
+若派发、结果或清理未知，引擎停止自动执行并保留工作区和调用记录。先核对本次调用
+拥有的 worker、guardian 和 app-server；外层退出或等待几秒不证明内部进程已停止，
+子进程退出也不证明模型结果已知。Go 仅消费匹配原始身份与证据的可信终态回执，不能
+通过切 fresh、换目录、换后端或重置 state 绕过未知调用。没有可核对回执的中断仍阻断。
 
 ### 5.1 Skills 入口与各 Loop 的工作目录
 
 内置 skills 将任务 worktree 约定作为准备、启动、恢复和单环入口的检查步骤。
-`flywheel-new` 在生成契约前创建或复用任务 worktree；`flywheel-run` 以及单环
+`flywheel-task`／`flywheel-new` 在生成契约前创建或复用任务 worktree；`flywheel-run` 以及单环
 skills 从实际任务目录解析同一 worktree 根，再调用 CLI。默认不从 `main`、
 `master` 或 detached HEAD 启动开发；已有明确工作区选择与授权不重复询问。
 恢复复用原任务路径及引擎保存的 packet 状态，不为恢复另建一份任务或复制 state。
 
 | 阶段／入口 | 实际工作目录 | 谁负责选择或创建 |
 |---|---|---|
-| `flywheel-new` 准备契约 | 任务集成 worktree | 宿主 Agent 按 skill 创建或复用 |
-| Plan | 任务集成 worktree，修订任务契约 | 引擎使用启动时的根目录 |
+| `flywheel-task`／`flywheel-new` 准备契约 | 任务集成 worktree | 宿主 Agent 按 skill 创建或复用 |
+| Full Plan／升级后修订 | 任务集成 worktree，修订任务契约 | 引擎使用启动时的根目录 |
 | Execute、L1、Review | 当前 packet 候选工作区；正常模式为 packet worktree | 引擎创建、记录并复用 packet worktree |
-| L2/L3、Judge | 任务集成 worktree | 引擎验证已集成的需求与里程碑 |
+| Quick 适用 L2/L3 | 同一 packet 候选工作区，先于最终 Review | 引擎不能使用尚未集成修改的旧 checkout |
+| Full L2/L3、Judge | 任务集成 worktree | 引擎验证已集成的需求与里程碑 |
 | Intake、Garden | 所选任务所属 worktree | 入口解析目录，Go 写建议结果 |
 | Status、Stop | 对应原任务路径与根目录 | 直接查询或停止，不要求为此新建 worktree、切分支或提交 |
 
@@ -189,8 +237,32 @@ Plan／Execute 请求 `workspace-write`，Review／Judge 以及 DSH／Codex（
 各 Loop 不会各自新建一份 worktree。任务 worktree 贯穿整个需求，
 packet worktree 贯穿该单元的执行、验收与评审；完成交付才由引擎处理本地合并
 与清理。恢复入口仍是 `flywheel-run`，没有另一个独立的 resume skill。
-`flywheel-verify` 只运行确定性验收：指定 packet 时只检查该单元 L1；未指定时
-检查未完成单元 L1 与当前里程碑 L2/L3。它不调用 Review／Judge，也不创建 worktree。
+
+Go 按已配置策略和冻结依赖调度 packet，不依赖一个持续存活的父模型会话监督。`sessions.mode=scoped`
+允许同 packet 的 Executor 返修续用，以及独立 Reviewer 在同范围复审时续用自己的
+历史；每次复审仍完整检查当前候选、契约和适用需求，不能只关闭上轮 findings。
+Plan 按同任务／里程碑续用，Judge 与第二意见各自隔离；显式 Plan
+`resident-session:false` 继续生效。团队通信和依赖图并行调度不在本期范围。
+
+新配置模板显式启用 scoped，旧文件未声明时保留 fresh。fresh 不启用通用的角色历史
+复用，保留旧 Kimi Plan resident 选项；两种模式都为 Codex Pro／Claude Code Pro／DSH／Kimi 主任务
+调用保存安全记录。其他适配器、mock 及 Intake／Garden 保留原路径。历史复用不减少
+任何验证要求，也不增加 Quick 首次成功的两次固定阶段调用。具体契约见
+[会话配置](configuration.md#会话策略历史复用与调用安全)。
+
+恢复保存的回执时沿用原调用的候选、契约和保护证据；不得重新执行抽检或验收来替换
+待消费回执所绑定的证据。Go 对已完成结果的消费不重发模型请求或重复计费；预算限制
+新的派发。Codex／Claude 的 P3 通过公开 typed lifecycle、Go 持久化 ACK 与原调用
+journal 只读核对恢复；成功回执还必须绑定原调用结束时保存的候选与角色证据。
+P4 提供按角色的 fresh/scoped、有界质量重建及三组对照评估；阈值默认关闭，真实模型
+效果另验，详见[中断恢复与上下文质量](session-recovery.md)和[对照评估](session-evaluation.md)。
+
+`flywheel-verify` 只运行确定性验收：Full 保留指定 packet 的 L1／当前里程碑
+L2/L3 语义；Quick 还会在实际候选上收齐适用 L2/L3。它不调用 Review／Judge，
+不创建 worktree，也不交付任务。Quick 的 `--only review` 是最终 Review；若发现
+验收缺口或资格失效，Go 当即保存单向 Full 升级，下一次完整 run 才进入 Full。
+`--only plan` 则要求 Full，确需规划时显式 `--mode full` 由引擎升级。
+`--only execute` 始终只是 Execute／L1 子环，不等于完整 Quick。
 
 Skill 的启动检查由宿主 Agent 遵守，CLI／GUI 直接调用不会自动执行这些 skill
 正文，也不会自动创建外层任务分支。直接使用控制接口时仍须显式选择正确的
@@ -232,3 +304,7 @@ required checks、审阅要求和授权，再按仓库策略启用；Agent 的 p
 [Astra 模型与 effort](https://developers.openai.com/api/docs/models/gpt-6-astra)、
 [Kimi 模型配置](https://www.kimi.com/code/docs/en/kimi-code/models)、
 [Flywheel 设计](design.md)。
+
+## 控制台交互交付
+
+新的[流程控制台](flow-console.md)提供阶段操作、接管、声明式并行与明确授权的 PR／Merge 入口。普通 run 的本地完成不自动授权远端写入；已有 Draft PR 会在推送后重新核对，Merge 后的发布另按真实 merge commit 验收。

package/npm/install.js

@@ -227,7 +227,7 @@ function launcherContent({ cli, prefix, dshBin, environment = process.env }) {
   return lines.join("\n");
 }
 
-async function writeLauncher({ directory, previous, cli, prefix, worker, codexProWorker, adapter, dshBin, environment }) {
+async function writeLauncher({ directory, previous, cli, prefix, worker, codexProWorker, claudeCodeProWorker, adapter, dshBin, environment }) {
   await fsp.mkdir(directory, { recursive: true });
   const launcher = path.join(directory, "npm-launcher");
   const content = launcherContent({ cli, prefix, dshBin, environment });
@@ -240,7 +240,7 @@ async function writeLauncher({ directory, previous, cli, prefix, worker, codexPr
     }
   } catch (error) { if (error.code !== "ENOENT") throw error; }
   await atomicWrite(launcher, content, 0o755);
-  const receipt = { protocol: 1, owner: OWNER, version: meta.version, prefix, cli, worker, codexProWorker, adapter,
+  const receipt = { protocol: 1, owner: OWNER, version: meta.version, prefix, cli, worker, codexProWorker, claudeCodeProWorker, adapter,
     node: process.execPath, launcher: { path: launcher, sha256: digest(content) } };
   await atomicWrite(path.join(directory, "installation.json"), JSON.stringify(receipt, null, 2) + "\n", 0o600);
   return receipt;
@@ -315,12 +315,12 @@ async function install(options, { environment = process.env, cwd = process.cwd()
       const installedRequire = createRequire(path.join(installedRoot, "package.json"));
       const runtime = installedRequire("./bin/runtime.js");
       report.paths = { cli: path.join(installedRoot, "bin", "flywheel.js"), native: runtime.loadNativePath(), worker: runtime.loadWorkerPath(),
-        codexProWorker: runtime.loadCodexProWorkerPath() };
+        codexProWorker: runtime.loadCodexProWorkerPath(), claudeCodeProWorker: runtime.loadClaudeCodeProWorkerPath() };
       const probe = await run(process.execPath, [report.paths.codexProWorker, '--doctor']);
       requireSuccess(probe, 'installed Codex Pro dependency');
       const adapter = parseDocument(probe, 'installed Codex Pro dependency');
       if (adapter.protocol !== 1 || adapter.type !== 'doctor' || adapter.package !== 'dsh-subagent-codex-pro' ||
-          adapter.version !== '0.8.0' || adapter.machineProtocol !== 1 || adapter.available !== true || adapter.inferenceTested !== false) {
+          adapter.version !== '0.9.0' || adapter.machineProtocol !== 1 || adapter.available !== true || adapter.inferenceTested !== false) {
         throw new Error('installed Codex Pro dependency did not verify the exact public machine API');
       }
       report.adapter = { package: adapter.package, version: adapter.version, protocol: adapter.machineProtocol, inferenceTested: false };
@@ -358,7 +358,7 @@ async function install(options, { environment = process.env, cwd = process.cwd()
     const dshBin = findExecutable(requestedDsh, environment);
     await step("desktop-launcher", async item => {
       const receipt = await writeLauncher({ directory, previous, cli: report.paths.cli, prefix, worker: report.paths.worker,
-        codexProWorker: report.paths.codexProWorker, adapter: report.adapter, dshBin, environment });
+        codexProWorker: report.paths.codexProWorker, claudeCodeProWorker: report.paths.claudeCodeProWorker, adapter: report.adapter, dshBin, environment });
       report.paths.launcher = receipt.launcher.path;
       item.path = receipt.launcher.path;
     });

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.28.5",
+  "version": "0.30.0",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
     "flywheel-dsh-worker": "bin/flywheel-dsh-worker.js",
-    "flywheel-codex-pro-worker": "bin/flywheel-codex-pro-worker.js"
+    "flywheel-codex-pro-worker": "bin/flywheel-codex-pro-worker.js",
+    "flywheel-claude-code-pro-worker": "bin/flywheel-claude-code-pro-worker.js"
   },
   "os": [
     "darwin",
@@ -33,17 +34,25 @@
     "docs/configuration.md",
     "docs/model-policy.md",
     "docs/workflow.md",
+    "docs/flow-console.md",
     "docs/en/getting-started.md",
     "docs/en/configuration.md",
     "docs/en/model-policy.md",
     "docs/en/workflow.md",
-    "docs/examples/create-first-task.sh"
+    "docs/en/flow-console.md",
+    "docs/examples/create-first-task.sh",
+    "docs/claude-code-pro.md",
+    "docs/en/claude-code-pro.md",
+    "docs/session-recovery.md",
+    "docs/en/session-recovery.md",
+    "docs/session-evaluation.md",
+    "docs/en/session-evaluation.md"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.28.5",
-    "@ckanner/flywheel-darwin-amd64": "0.28.5",
-    "@ckanner/flywheel-linux-arm64": "0.28.5",
-    "@ckanner/flywheel-linux-amd64": "0.28.5"
+    "@ckanner/flywheel-darwin-arm64": "0.30.0",
+    "@ckanner/flywheel-darwin-amd64": "0.30.0",
+    "@ckanner/flywheel-linux-arm64": "0.30.0",
+    "@ckanner/flywheel-linux-amd64": "0.30.0"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
@@ -51,9 +60,10 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.28.5 dist-npm"
+    "build:npm": "bash scripts/build-npm.sh 0.30.0 dist-npm",
+    "test:sessions": "node scripts/test-session-evaluation.js"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.28.5"
+    "@ckanner/dsh-plugin-flywheel": "0.30.0"
   }
 }