@ckanner/flywheel 0.28.4 → 0.29.1

package/docs/configuration.md

@@ -14,7 +14,7 @@ Flywheel 在启动时加载一份完整配置，再把模型 profile 展开成
 flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
 ```
 
-输出 `source`、`scope`、物理 `cwd/taskDir` 和按阶段排列的 `bindings`。`scope` 为 task／project／global／embedded。它只解析配置，不物化全局文件，不读取账号 token，不启动模型，也不创建任务状态。省略任务时只从项目及更低层发现配置，不会误读运行命令所在的另一个目录。
+输出 `source`、`scope`、物理 `cwd/taskDir`、`sessions` 策略和按阶段排列的 `bindings`。每个绑定的 `session` 包含所选模式、适配器支持情况、原因以及恒为 false 的 `historyRecoveryTested`。`scope` 为 task／project／global／embedded。它只解析配置，不物化全局文件，不读取账号 token，不启动模型，也不创建任务状态。省略任务时只从项目及更低层发现配置，不会误读运行命令所在的另一个目录。
 
 展示值包含 Flywheel 已确定的 driver 默认：DSH／Codex／Kimi 的空 thinking 为 high，pi／omp／zcode 为 max；Kimi／Codex／Zcode 的空 model 使用各自 driver 常量。pi／omp 未指定模型时仍留空，表示 Flywheel 不能从配置确定它。`residentSession` 只有 Plan＋Kimi＋明确启用时为 true，不把其他阶段忽略的请求显示为已生效。
 
@@ -32,7 +32,7 @@ flywheel config migrate --preset subscriptions --cwd /repo --apply --json
 flywheel config inspect --cwd /repo --json
 ```
 
-第一条只预览。`--apply` 明确应用到当前实际命中的任务／项目／全局文件，并先备份原始字节。没有文件时写全局配置，不创建意外的项目覆盖。可以用 `--expect-sha256` 绑定之前预览的摘要；文件已经变化时拒绝陈旧应用。预算、worktree、验证、重试、价格和用户说明等非模型设置保留，Plan 明确设置的 `resident-session:false` 也保留。配置损坏、额外自定义路由／阶段或不支持的文件身份会明确阻断，不猜测替代。
+第一条只预览。`--apply` 明确应用到当前实际命中的任务／项目／全局文件，并先备份原始字节。没有文件时写全局配置，不创建意外的项目覆盖。可以用 `--expect-sha256` 绑定之前预览的摘要；文件已经变化时拒绝陈旧应用。预算、worktree、验证、重试、价格和用户说明等非模型设置保留，Plan 明确设置的 `resident-session:false` 以及现有 `sessions` 策略或其缺省状态也保留；模型迁移不会让旧文件自动启用 scoped。配置损坏、额外自定义路由／阶段或不支持的文件身份会明确阻断，不猜测替代。
 
 迁移写入完整的阶段模型、thinking 和渠道，去掉被替换绑定的旧 profile 引用，清除所选渠道的旧 fallback／模型映射，使旧付费渠道不再自动可达；未引用的自定义 profiles／channels 仍保留。包括 0.28.2 留下的 API channel，也可以作为未引用配置保留，但不会成为账号路由的自动后备。默认关闭第二意见，并明确报告旧多模态路由被停用。默认分配仍是 Kimi K3.1 Pro high 负责 Plan／frontend／Garden，DeepSeek Flash high 负责普通执行、low 负责 Intake，GPT-6.1 Sol high 负责 hard／Review，GPT-6 Astra high 负责 Judge。hard 通过 Codex Pro 插件，Review／Judge 通过 DSH ChatGPT provider。Kimi 缺省模型为 `kimi-code/k3.1-pro`；显式写入的自选模型不会被仅修改 driver 缺省值覆盖。档位依据与尚未完成的对照评估见[推理等级与账号选择](model-policy.md)。
 
@@ -52,11 +52,180 @@ flywheel config inspect --cwd /repo --json
 
 完全权限不会关闭 Flywheel 的任务边界、冻结验收、验证和候选身份检查。评审职责仍是评价已有候选，修改候选或验收条件不能取得有效通过。需要受限权限时显式使用 `role-based`；工作区隔离本身不是 OS 沙箱。
 
+### 会话策略、历史复用与调用安全
+
+```json
+{"sessions":{"mode":"scoped","policy-version":1}}
+```
+
+新安装的两份配置模板显式选择 `scoped`。已有配置没有 `sessions` 时归一为
+`fresh`／版本 1，升级不会改写原文件。显式声明时两个字段均必填；未知模式、未来版本、
+null、错拼字段和不完整对象在模型启动前拒绝。字段信源为
+[会话策略 schema](../templates/session-policy.schema.json)。
+
+`sessions.mode` 控制历史复用，不关闭调用安全记录。Codex Pro、Claude Code Pro、DSH 和 Kimi 的主任务
+Plan／Execute／Review／Judge 调用在两种模式下都先记录调用意图，再保存可信终态回执。
+`fresh` 不复用通用的角色历史，保持后端原有的新调用方式，并保留既有 Kimi Plan
+`resident-session` 行为；`scoped` 在身份兼容且终态满足条件时延续同角色历史。
+其他适配器及 mock 仍使用原有调用路径；Intake／Garden 不在本轮角色会话策略内。
+
+| 角色 | 历史作用域与责任 |
+|---|---|
+| Plan | 同任务、同里程碑；只修订获准的任务契约 |
+| Execute | 同任务、同 packet；普通返修可以延续执行者历史 |
+| Review | 同任务、同 packet 和评审职责；与执行者隔离，复审仍检查完整当前候选 |
+| Judge／第二意见 | 同任务、同里程碑，各自独立；不能共享主判和第二意见历史 |
+
+Quick 最终 Review 与 Full 单元 Review 的完成要求不同，不能互用旧历史或裁决。
+Quick 的正常首次成功路径仍只有 Execute 和最终 Review 两次阶段调用。Go 负责所有
+会话选择、恢复、重建和计量；技能、模型与桌面控制面不扫描后端历史来猜测会话。
+
+Plan 显式 `resident-session:false` 在 scoped 下仍关闭该角色的历史复用；省略该字段
+不等于明确关闭。`resident-session:true` 是既有 Kimi Plan 选项，不是跨 harness 开关，
+Codex Pro 仍拒绝它；为 Codex Pro 选择 scoped 应使用 `sessions`。
+
+复用身份包含实际任务／工作目录、角色／作用域、harness、provider、channel、model、
+thinking、权限及后端运行配置引用。home/profile、worker 和命令引用取实际子进程所用
+配置，注入凭据只记录名称集合，不保存值。profile 改名而实际绑定不变不使历史失效；
+后端、账号渠道、模型、权限或工作目录变化则重新建立合适的历史。Spec 目标、非目标、
+需求身份及 packet 的目标、正文、边界或需求映射发生变化也不复用旧任务语义。
+里程碑级 Plan、Judge 和第二意见还核对里程碑标题以及所属 packet 的身份和这些目标字段。
+兼容的验收修订可以保留已消费的历史，但每次重新提交当前契约和证据。
+
+这些非秘密引用不证明账号主体或所指文件的内容。配置、账号授权或可执行文件在相同
+路径被原位替换时，当前策略不保证发现变化；不会读取凭据值来比对账号。实际配置
+接受和权限事实仍以本次适配器回执能够证明的内容为限。
+
+已完成但尚未消费的回执采用更严格的规则：Review／Judge 必须匹配原契约、候选与验证
+证据，不能用重新验证的记录替换原证据。Plan 获准修改契约时，仍绑定完整调用后候选及
+持久化的原始前后保护证据。评审或规划越界改动不能在重启后变成有效结果。
+
+`state.sessions` 保存每个作用域的代次、动作／原因和最新调用事实；每个作用域只保留
+一个原子替换的 `.sessions` 回执槽，原始回执不进入 Git。恢复先核对已保存的调用意图、
+回执摘要和身份，再消费同一结果，不重复发模型请求或重复计费。预算限制新的派发，
+不会把消费已有可信回执算作新调用。历史审计事实通过指标保留。
+
+单槽上限只适用于 Flywheel 恢复回执。后端原生 thread／Session 历史依其自身规则
+保留；Flywheel 不会因重建角色历史或结束 worker 而自动删除旧历史。
+
+派发、结果或清理有任何一项未知时，原调用阻止继续执行；换成 fresh、改变适配器或
+重启不能绕过。子进程退出只解决进程事实，不证明模型结果已知。`resume-candidate`
+只是允许适配器尝试正常续接，不是历史已持久化或任意崩溃后都可恢复的证明。
+Codex Pro 0.9.0 与 Claude Code Pro 0.4.0 的主任务调用使用外层 worker v3，
+接通公开 typed lifecycle、等待 Go 持久化后返回的 ACK，以及不发送新 turn 的只读
+recovery。Codex 可以在配置核对后的 `thread-ready` 阻止新 turn；Claude 原生 init
+发生在 prompt 已派发之后，不能提供同等的派发前配置证明。两个后端都保留未知窗口，
+不会从 PID 消失或报告存在推断任务完成。详见[中断核对](session-recovery.md)。
+
+`status` 及 `control status` 展示角色、作用域、代次、动作／原因、最新调用状态、
+派发／结果／清理、是否复用历史与用量状态。紧凑投影不读取回执内容或历史正文，也不
+修改账本；无会话记录的旧任务不被推断为已具备恢复资格。
+
+### 按角色选择与上下文质量
+
+`sessions.roles` 可对 `plan`、`execute`、`review`、`judge`、`judge-panel` 分别
+选择 `fresh` 或 `scoped`；省略的角色继承 `mode`。显式 `roles.plan:"fresh"`
+也关闭旧 Kimi Plan 的历史捷径；显式 `resident-session:false` 继续阻止 Plan 复用。
+Intake／Garden 不接受角色覆盖。示例只改变历史策略，不改变模型与渠道：
+
+```json
+{
+  "sessions": {
+    "mode": "scoped",
+    "policy-version": 1,
+    "roles": {"review": "fresh"},
+    "quality": {
+      "max-confirmed-turns": 0,
+      "max-unproductive-turns": 0,
+      "max-run-input-tokens": 0
+    }
+  }
+}
+```
+
+质量阈值均默认为 `0`（关闭），不会凭未测得的收益改变旧行为。设为正整数后：
+
+| 字段 | 机械可核对的重建依据 |
+|---|---|
+| `max-confirmed-turns` | 当前角色历史代次内已确认派发并安全结束的调用次数达到上限 |
+| `max-unproductive-turns` | Execute 连续调用前后的权威候选 fingerprint 未变达到上限；这只证明候选没变，不替代语义质量判断 |
+| `max-run-input-tokens` | 最近一次 complete 用量回执的单次 run input 达到上限；它是工作量观测，不是原生 context window 的测量 |
+
+只有上一次结果已消费、已入账、派发／终态／清理均确认且历史原本可续用，质量策略
+才允许重建。未派发失败不增加已确认 turn 数；回执重放按 invocation ID 去重。
+partial／unknown 用量不补零，也不能单凭缺失用量触发输入阈值。原预算、失败次数、
+停滞限制、工作区成果和独立验收继续保留。重建只交接本角色的代次／调用引用、原因
+与当前权威材料，不复制另一角色的私有历史，不新增模型压缩调用。
+
+`state.sessions.records[*].quality` 与对应指标记录已确认 turn 数、候选未变化次数、
+最近输入观测及完整度、代次重建次数和原因。阈值范围由同一 schema 限制；无依据的
+未来字段或不合法值在启动前失败。如何对真实任务进行三策略配对评估、选择阈值以及
+保留未确认结果，见[会话效果评估](session-evaluation.md)。
+
+### 工作流策略与恢复
+
+工作流决定运行哪些阶段；模型 profiles、loops、routes 和 `permissions.mode` 仍决定
+各阶段使用什么后端与权限。**工作流写在 Spec 的 YAML frontmatter，不写进
+`flywheel.config.json`。** 统一 `flywheel-task` 入口默认 Auto，准备阶段保存真实的
+代码依据、资格事实与风险，再交 Go 校验。下面仅示意字段，内容须替换为当前任务事实：
+
+```yaml
+workflow:
+  version: 1
+  mode: auto
+  reason: "缺陷已定位，沿用现有实现模式及回归验收"
+  scope-clear: true
+  implementation-known: true
+  verification-complete: true
+  review-sufficient: true
+  evidence:
+    - "已检查实际实现、调用方与可复现该缺陷的回归测试"
+  risks: []
+  not-applicable:
+    L2: "没有跨模块协议变化，调用边界由 L1 回归覆盖"
+    L3: "没有独立 UI 或外部服务路径，行为由本地函数契约验证"
+```
+
+`version` 与 `mode` 必填，其他字段缺省不会产生 Quick 资格。Quick 要求一个里程碑、
+一个 packet、四项事实标志均为 true、非空 reason/evidence、无 risks、每条 Spec
+需求被 packet 引用且有非空 verification、至少一条 L1，以及缺失 L2/L3 的不适用理由。
+Go 根据可核验结构与声明选择，不能把一个模型的“低风险”标签当成语义证明；
+新风险仍可在执行或最终评审时升级。存在风险或资格不足时采用 Full。
+
+```sh
+flywheel control launch --task-dir /repo/docs/task --cwd /repo --mode auto
+flywheel control start --task-dir /repo/docs/task --cwd /repo --mode full
+flywheel run /repo/docs/task --mode full
+flywheel control status --task-dir /repo/docs/task --cwd /repo
+```
+
+`launch` 默认请求 Auto；`start`／`run` 省略 `--mode` 时沿用契约或状态的选择。
+只读 status、stop 不接受模式切换。旧契约或旧状态没有工作流字段时保留 Full。
+已保存的策略在恢复时继续使用，Auto 不重新分类，Full 不降回 Quick；Quick 发现
+新风险、验收缺口或显式选择 Full 时，由引擎先保存升级检查点，再继续完整流程。
+未知工作流版本明确报错。不要手改 state 或重新建任务来重置预算与证据。
+
+`state.workflow` 保存 requested、effective、reason、evidence、risks、版本、选择时间、
+`stages.plan/judge` 适用性及 upgrades。Plan／Judge 不适用不表示验收通过。
+工作流与完成要求进入证据身份，旧 Quick 最终 Review 不能充当升级后 Full 的 Judge。
+新任务可在 packet 的 `done-report-format` 声明 `workflow-risks: []`，让执行者报告
+具体新风险；模型和 skill 不直接修改模式或状态。
+
+Quick 复用现有 Execute 与 Review 绑定，不自动改变 thinking、账户、后备渠道或
+全访问设置。全部必需验证仍运行，适用 L2/L3 必须在实际候选中、最终 Review 前完成。
+完整最终 Review 逐项核对需求，正常首次成功只调用 Execute 与最终 Review 两个阶段。
+字段信源为 [Spec schema](../templates/spec.schema.json) 与
+[state schema](../templates/state.schema.json)，运行流程见[工作流指南](workflow.md)。
+
+### 可选 Claude Code Pro
+
+新增 `harness:claude-code-pro` 与未绑定的 `claude-sonnet` profile，可用于任意已配置 loop 或 Execute route。模型、thinking、optional peer 安装、full-access-only 权限及正常续接边界见 [Claude Code Pro 指南](claude-code-pro.md)。`provider` 仍只用于 DSH 原生 adapter；默认阶段分配不变。
+
 ## 2. 四个概念各负责什么
 
 | 字段 | 含义 | 示例 |
 |---|---|---|
-| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`；`codex` 为显式旧 CLI 路径 |
+| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`、`claude-code-pro`；`codex` 为显式旧 CLI 路径 |
 | `provider` | DSH SDK 已注册的 LLM adapter ID；仅 DSH 使用 | `deepseek-account`、`chatgpt` |
 | `channel` | 配置中的凭证／后备／计量渠道名称 | `deepseek-account-sdk`、`chatgpt-sdk`、`kimi-subscription` |
 | `profile` | 当前 Flywheel 配置内的一组模型字段引用 | `flash`、`gpt-review`、`kimi` |
@@ -95,13 +264,30 @@ DSH 桌面在登录后且没有任何 provider API key 时，可以自动选择
 }
 ```
 
-完整 profiles 模板使用 `profiles.codex-pro`，hard 路由引用它。插件依赖 `dsh-subagent-codex-pro@0.8.0` 由 npm 安装；worker 直接导入其公开 `dsh-subagent-codex-pro/machine` API，内部仍使用 Codex app-server 和用户已有登录。它不是 DSH LLM provider，也不需要父模型调用 `subagent_codex_pro`。缺少插件或回执不符会失败，不自动回退 `codex exec`。
+完整 profiles 模板使用 `profiles.codex-pro`，hard 路由引用它。插件精确消费
+`dsh-subagent-codex-pro@0.9.0` 的公开 `dsh-subagent-codex-pro/machine` API。
+当前候选将已审查源码生成的真实公开包一并打入插件，不能据此推断 0.9.0 已在 registry
+发行。内部仍使用 Codex app-server 和用户已有登录，不需要父模型二次委派；缺包、
+版本或回执不符会失败，不自动回退 `codex exec`。Claude 另为精确 `0.4.0` optional peer，
+未选择该后端时无需安装。
 
-已有配置不自动改写。要从旧路径迁移，在 `config inspect` 显示的有效文件中修改 inline harness 或其 profile，保留所选 model／thinking／channel，然后重启引擎。保留 `harness: "codex"` 则明确继续使用旧 CLI。`codex-pro` 必须提供 model 和 channel，不沿用旧 Codex driver 的隐式模型；`resident-session: true` 会在加载时拒绝。执行／评审每次创建 ephemeral 新会话，thinking 省略时为 high。
+已有配置不自动改写。要从旧路径迁移，在 `config inspect` 显示的有效文件中修改 inline harness 或其 profile，保留所选 model／thinking／channel，然后重启引擎。保留 `harness: "codex"` 则明确继续使用旧 CLI。`codex-pro` 必须提供 model 和 channel，不沿用旧 Codex driver 的隐式模型；`resident-session: true` 会在加载时拒绝。thinking 省略时为 high。
+
+主任务在 fresh 与 scoped 两种模式下均使用外层 worker 协议 3：前者选 ephemeral，
+后者选 persistent 并在续用时提供精确 thread ID；派发前需完成对应生命周期检查点
+与 Go 持久化 ACK。公开 machine 请求／终态回执仍为协议 1，typed lifecycle 另有
+版本化契约，不能混为一个版本。旧外层 v1/v2 入口继续服务低层兼容调用；没有自动获得
+主任务的持久化恢复保证。任何 resume 必须匹配原 thread，busy 或失败文本不能证明
+安全冷启动。具体事件与只读恢复条件见[中断核对](session-recovery.md)。
 
 `FLYWHEEL_CODEX_PRO_WORKER` 可显式指定 worker；通常由 npm 启动器解析同版本依赖。`FLYWHEEL_CODEX_BIN` 指定插件内部的 Codex 程序，默认 PATH 中的 `codex`；`CODEX_HOME` 可选择既有配置与登录目录。自定义环境需对启动引擎的进程可见，安装器不会复制凭证。
 
-插件在运行前确认模型、cwd、approval 和沙箱模式；Flywheel 在完整结果返回后检查实际策略及进程终态。在 role-based 的 workspace-write 模式，允许工作区及 Codex 标准临时目录；额外的工作区外 writable roots、网络启用或不能确认的策略不能进入成功验收。显式 full-access 则核对 `danger-full-access`／`dangerFullAccess` 完全权限回执，不将其误报为受限沙箱。**该完整策略检查发生在运行后，不能阻止自定义 Codex 配置已允许的访问。** 要求完整策略在任务前被拒绝的环境，应等待上游公开 pre-turn guard；doctor 会持续提示这一边界。
+Codex 主任务先通过公开 `thread-ready` 核对实际模型、cwd、approval 和完整沙箱策略，
+Go 保存检查点并 ACK 后才允许新 turn。role-based 的 workspace-write 允许工作区与
+Codex 标准临时目录；额外 writable roots、网络启用或无法确认的策略在派发前拒绝。
+full-access 核对 `danger-full-access`／`dangerFullAccess`，不将其称为受限沙箱。
+终态仍重新验证配置和清理事实。低层 v1/v2 兼容调用没有 Go 的派发前 ACK；外部管理
+策略与原生拒绝在所有模式下仍然生效。
 
 指标的 `codex-pro-receipt` 保存完整 machine receipt，包含请求、实际配置、thread/turn、进程、清理、usage 和失败事实。effort 的 `accepted: true` 不等于服务器证明了实际推理强度，`effectiveEffort` 保留 null。仅 `usage.status: "complete"` 的本次增量进入已知预算；partial/unknown 原样留在回执并计入未知调用。插件不提供实际美元成本，原始 cost 保持 unknown；Flywheel 只有在用户显式配置 pricing 且 usage 完整时才能另行估算，估算不等于订阅账单。
 
@@ -158,14 +344,16 @@ flywheel template flywheel.profiles.example.json
 | 阶段省略某字段 | 继承所引用 profile 的字段 |
 | 阶段显式写 `model`／`channel`／`thinking` 等 | 只覆盖该阶段，不修改共享 profile 或其他阶段 |
 | `thinking: ""` | 使用对应 harness 的现有默认 effort，不重新继承 profile |
-| `resident-session: false` | 明确关闭该阶段的恢复请求；不会丢失为缺省值 |
+| Plan `resident-session: false` | 明确关闭 Plan 历史复用；加载、profile 展开和配置导出均保留其显式存在 |
 | `judge-panel: null` | 关闭第二意见，保持默认行为 |
 | profile 定义缺 `harness/model/channel`，或这些字段为空／null／纯空白 | 加载失败 |
 | profile 不存在、未知字段、错拼阶段名、不支持的 harness | 加载失败，不静默回落 |
 | profile 再引用另一个 profile | 不支持继承链；加载失败 |
 | `_note`、`_note_*` | 允许配置对象中的说明文字，不进入执行绑定 |
 
-`resident-session` 是阶段策略，不能放进 profile。当前只有 Kimi 的 Plan 可恢复历史，且必须匹配实际 harness/model/channel/cwd/thinking/permissionMode；profile 名改了而实际值没变，不影响身份。其他执行、评审和 SDK 调用仍是新会话。
+`resident-session` 是既有阶段选项，不能放进 profile。它继续控制旧 Kimi Plan 行为，
+其显式 false 在 scoped 下也保持 Plan 退出；其他角色的历史复用由顶层 `sessions`
+控制。恢复的是历史，不是要求一个模型进程永久存活。
 
 旧内联绑定保留原有缺省行为，不强制迁移。`env-key: null`、`retry.jitter: 0`、`worktree.enabled: false` 等已有合法零值继续支持。显式切换 harness 或 channel 时，要一起核对继承的 provider；必要时用 `provider: ""` 清除显式值，再按新 channel 解析，不能保留另一个 adapter 的 ID。
 
@@ -183,15 +371,30 @@ flywheel doctor --cwd /repo --task-dir /repo/docs/task --json
 flywheel doctor --cwd /repo --task-dir /repo/docs/task --probe --json
 ```
 
-没有任务时检查全部配置绑定。有任务时校验 Spec/packet，仅把 Plan、Review、Judge、已启用的第二意见和实际 packet 路由列为必需；其他绑定显示 skipped。任务尚未生成 packet 时检查默认执行路由并提示规划后复查。mock driver 跳过真实工具检查，不冒充模型已验证。
+没有任务时检查全部配置绑定。有任务时校验 Spec/packet，并使用与引擎相同的策略解析器：
+新任务按 Spec 判断，已有任务按持久化选择，旧状态保留 Full。Full 要求 Plan、Review、
+Judge、已启用的第二意见和实际 packet 路由；合格 Quick 只要求 Review 与实际执行路由，
+Plan／Judge／第二意见显示 skipped。工作流状态损坏会阻止 SDK 探测，不重分类或改状态。
+任务尚未生成 packet 时检查默认执行路由并提示规划后复查。mock driver 跳过真实工具检查，不冒充模型已验证。
+
+doctor 不接收运行时的 `--mode` 覆盖，只反映 Spec／已保存状态；启动时另传模式后，
+仍以 Go 实际选定并保存的策略为准。配置查看列出所有绑定，不表示每条绑定都必然被调用。
 
-预检可提前运行，正式 `run`／`control start` 仍需至少一个已准备并审阅的合法 packet；没有 packet 的 warn 不表示引擎已经能从空任务开始。绑定中的 permissionMode 表示阶段要求，实际实施能力还取决于 harness，尤其 Kimi CLI 不能据此宣称拥有 OS 沙箱。
+预检可提前运行，正式 `run`／`control launch|start` 仍需至少一个已准备、范围获授权的合法 packet；没有 packet 的 warn 不表示引擎已经能从空任务开始。绑定中的 permissionMode 表示阶段要求，实际实施能力还取决于 harness，尤其 Kimi CLI 不能据此宣称拥有 OS 沙箱。
 
 本地检查确认命令可用、版本响应可靠，以及声明的环境变量存在且非空，不显示变量值。`--probe` 才启动 DSH worker 验证 adapter 接受配置、cwd、完整沙箱、approval policy 和 SDK 正常关闭。相同 provider、channel、model、effort、cwd 和权限的探测去重；不同账号别名或读写权限不能相互代替。整体验证预算 40 秒，另留进程清理窗口。
 
 DSH 的 `ready.reasoningEffort` 是 SDK 接受配置之后的 worker 回显，不是模型服务独立证明的实际推理强度。没有模型请求的检查不能证明更高档位提高质量；GPT、Kimi 和 Flash 也不共用同一套档位枚举，详见[推理等级说明](model-policy.md)。
 
-Codex Pro 本地检查额外实际导入公开 machine API，核对精确 0.8.0／协议 1、Node >=22.18.0 以及 Codex 命令版本；同一 worker 只查一次。`--probe` 不为此路径发送任务，实际模型、effort 与完整权限保持 unknown；它不会把成功导入插件当成账号、沙箱或推理能力已经验证。
+Codex Pro 本地检查额外实际导入公开 machine API，核对精确 0.9.0／协议 1、typed
+lifecycle／recovery 导出、Node >=22.18.0 与 Codex 命令版本；同一 worker 只查一次。
+绑定的 `durableJournal`、`readOnlyRecovery`、`threadReadyBeforeDispatch` 表示锁定
+适配器的静态能力；Claude 最后一项为 false。`historyRecoveryTested` 保持 false。
+`--probe` 不发送模型任务，不把导入成功解释为账号、权限或某段历史恢复已经验证。
+
+`sessions.policy` 检查只确认配置模式及版本；每个适用真实绑定的 `.session` 检查
+显示所选模式、原因和适配器支持，历史恢复仍为 unknown。Doctor 不尝试恢复用户
+历史，不发送测试 turn，也不把 worker 包导入成功当作持久化确认。
 
 | 状态 | 解释 |
 |---|---|

package/docs/en/claude-code-pro.md

@@ -0,0 +1,145 @@
+# Optional Claude Code Pro backend
+
+[中文](../claude-code-pro.md) · [Configuration](configuration.md)
+
+Select `harness: "claude-code-pro"` to call the public machine API of
+[`dsh-subagent-claude-code-pro`](https://github.com/ckanner/dsh-subagent-claude-code-pro).
+The plugin runs the user's installed Claude Code CLI, with its native tool loop
+and login environment. Go retains scheduling, role sessions, verification,
+budgets, and delivery.
+
+**Source and release boundary:** the integration requires plugin **0.4.0,
+machine protocol 1**. Version 0.3.1 only exposes the DSH tool interface and lacks
+the required machine receipt. The companion source version does not establish
+an npm publication. Flywheel source remains version 0.28.5; the new source does
+not update an already installed artifact. No default stage or route selects Claude.
+
+## 1. Prepare the optional dependency
+
+Use Node.js 22.18.0 or later on macOS or Linux, with the user's installed and
+authenticated `claude` CLI accessible to the process starting the engine.
+Flywheel does not copy credentials or sign in on the user's behalf.
+
+Flywheel ships `flywheel-claude-code-pro-worker` and declares the exact plugin as
+an **optional peer**. Other backends work without it. To select Claude, install
+`dsh-subagent-claude-code-pro@0.4.0` in the same Node dependency tree or global npm
+prefix as Flywheel. Installing it only in a DSH desktop profile does not establish
+that the independent worker can resolve it.
+
+After publication, install that exact release. Before publication, run
+`npm pack --ignore-scripts` in the reviewed plugin checkout and install the actual
+resulting `.tgz` into the same prefix, alongside a newly built Flywheel candidate.
+Do not relabel 0.3.1 or substitute it for the missing machine interface. This
+source-candidate validation does not promote npm latest.
+
+| Variable | Purpose |
+|---|---|
+| `FLYWHEEL_CLAUDE_CODE_PRO_WORKER` | Explicit worker override; npm normally resolves the matching worker |
+| `FLYWHEEL_CLAUDE_BIN` | Claude CLI command or absolute path; defaults to `claude` |
+| `CLAUDE_CONFIG_DIR` | Optional native configuration/login directory, interpreted by Claude |
+
+Go forwards only its base environment allowlist and credentials explicitly
+selected by the channel. A subscription channel with no env-key does not inherit
+an ambient Anthropic API key. Supported explicit credentials are passed through
+the machine runtime. The bridge does not serialize environment credential values
+into requests or diagnostics; text returned by the CLI is preserved as received.
+
+## 2. Define a profile, then choose its stages
+
+The complete [profile template](../../templates/flywheel.profiles.example.json)
+includes an unreferenced `claude-sonnet` profile. This fragment belongs in your
+existing complete configuration; it is not a replacement file:
+
+```json
+{
+  "profiles": {
+    "claude-sonnet": {
+      "harness": "claude-code-pro",
+      "model": "sonnet",
+      "channel": "claude-subscription",
+      "thinking": "high"
+    }
+  },
+  "channels": {
+    "claude-subscription": { "env-key": null }
+  },
+  "permissions": { "mode": "full-access" },
+  "sessions": { "mode": "scoped", "policy-version": 1 }
+}
+```
+
+Use native `sonnet`, `opus`, or `haiku` aliases, or a full model ID available to
+your account. Full IDs must match the observed CLI initialization value; the
+three aliases must resolve to the corresponding family. Flywheel does not pin a
+changing model catalog. Supported request efforts are low, medium, high, xhigh,
+and max, with high as the default. A particular CLI or model can still reject a
+choice; Flywheel never silently substitutes another model or effort. Where the
+CLI cannot attest effective reasoning effort, only the requested value is recorded.
+
+When you decide the use case, reference the profile from the selected
+`loops.plan/review/judge/intake/garden` or Execute `routes.*` binding, for example
+`{"profile":"claude-sonnet"}`. This is a configuration capability, not a new default
+allocation. Clear any explicit inherited `provider`: that field identifies a DSH
+native LLM adapter. Neither `subagent_claude_code` nor `claude-code-pro` belongs
+there as a substitute for the harness field.
+When switching from Kimi Plan, remove its `resident-session` field to use
+`sessions.mode`. Claude rejects `resident-session:true`; an explicit Plan
+`resident-session:false` still disables scoped history reuse, preserving that
+existing opt-out.
+
+Restart the engine after changing the configuration. Inspect the effective file
+and expanded bindings:
+
+```sh
+flywheel config inspect --cwd /repo --json
+flywheel doctor --cwd /repo --json
+flywheel-claude-code-pro-worker --doctor
+```
+
+An unused profile does not require the optional adapter. A selected binding makes
+doctor check the worker, exact public API, and local CLI. These commands do not
+make model requests or prove account availability, quota, or live inference.
+
+## 3. Permissions and role history
+
+The initial adapter requires explicit `permissions.mode:full-access`, mapped to
+native `bypassPermissions` and noninteractive invocation. Native plan/acceptEdits
+approval policies are not OS read-only/workspace-write sandboxes; role-based
+requests therefore fail before dispatch. Reviewer and planner responsibilities,
+contract boundaries, and before/after candidate guards remain enforced by Go.
+
+Main-task Plan, Execute, Review, and Judge use the existing fresh/scoped policy.
+Scoped repairs resume only a confirmed session owned by the same task, scope,
+and role. Review never shares the executor's session; a second opinion is also
+independent. Resume supplies the exact session ID, without discovering the latest
+history or silently starting a fresh task after a failed resume. Intake and Garden
+can select the backend, but remain independent advisory calls without the main
+task's role-session ledger.
+
+Success requires a complete valid stream, correlated request/session/configuration,
+normal physical process exit, and confirmed cleanup. Disconnects, cancellation,
+timeouts, malformed frames, duplicate terminal results, abnormal exit, and unknown
+cleanup never qualify. Dependency and input failures proven to occur before
+machine invocation are not-dispatched with known zero consumption, so fixing the
+environment can permit a later attempt. After invocation, a missing trustworthy
+outcome must stop replay even if cleanup is confirmed.
+
+Before dispatching Claude, an independent supervisor owns a durable journal and native guardian. Go persists and acknowledges intent/possible checkpoints before prompt submission. Worker loss cancels unacknowledged steps and initiates native cleanup; complete terminal receipts are durable before notification. Public `recoverMachine` reads only that invocation and never starts the CLI or resubmits a prompt.
+
+Claude init arrives after the prompt. There is no fabricated pre-dispatch thread-ready or native turn-accepted event; actual model, cwd, and permission checks still apply at terminal admission. Supervisor loss, corruption, or missing original candidate proof can leave execution blocked. See [recovery and context quality](session-recovery.md). Real-account quality, cache, and performance require separate paired evidence.
+
+## 4. Usage and subscription cost
+
+CLI input_tokens excludes cache. For complete reports, Flywheel adds cache read
+and cache creation to input, then adds output to calculate total tokens. Missing
+counters remain partial/unknown instead of becoming zero. Each resumed invocation
+is accounted once, without rebilling historical totals.
+
+The raw receipt retains CLI total_cost_usd as reportedCostUSD, an API-equivalent
+estimate rather than a subscription bill. costUSD stays null and costStatus stays
+unknown. Existing soft/hard budget behavior remains in effect.
+
+An explicit user `pricing` table can separately produce an estimate in metrics
+and budgets. The estimator subtracts cache read/creation from inclusive input
+before pricing disjoint buckets, avoiding duplicate charges. This estimate does
+not use reportedCostUSD, rewrite the raw receipt, or establish a subscription bill.