@ckanner/flywheel 0.28.5 → 0.29.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.29.1
+
+- 完成会话 P3 源码：Codex Pro 0.9.0／Claude Code Pro 0.4.0 公开 lifecycle v1、独立 durable journal 与只读 recovery，经 worker v3 接入 Go。派发检查点先 fsync 再 ACK；恢复终态仍绑定原候选和角色 guard，未知不盲目重放。
+- 完成 P4 策略与实验工具：可按角色覆盖 fresh/scoped，按确认轮数、Execute 候选停滞和实测单次输入做有界重建；默认阈值关闭。固定源码与独立 oracle 比较三种策略，覆盖六场景并重复配对；离线 native fixture 不被当作真实模型质量或节省证据。
+- 恢复可归属的迟到 usage 时写独立 correction，保留原调用／provider／日期，不重复计数或复活已过期日桶；metrics 与状态成功前同步文件与目录，持久化失败可安全重试。
+- Codex 0.9.0 以已审查、真实 npm tarball 随 DSH 插件 bundle，保留源码与摘要，安装不依赖未发布 registry 版本。Claude 0.4.0 保持精确 optional peer；默认模型、loop 和账号渠道不变。
+
+- 新增可选 `claude-code-pro` harness：通过 `dsh-subagent-claude-code-pro@0.4.0` 公开 machine v1 运行本地 Claude Code CLI，明确模型／thinking、full-access、fresh／同角色 scoped 续接和原始调用回执。添加可选 profile、worker、无推理 doctor、安装路径和双语指南，暂不改变任何默认 loop／route。0.4.0 是配套源码版本，本条不表示它或 Flywheel 已发布 npm。
+- 修正已跟踪调用的派发前拒绝／取消：确认未启动就保存已知未派发与零消耗，配置修复后可继续；未知结果仍阻断。Intake／Garden 对有结构化事实的未知派发或结果也停止重试，进程清理不被误当作业务完成。
+- 校准显式 pricing 估算：Claude／Codex Pro／DSH 的总输入包含缓存量，估价前拆成不相交桶，避免缓存 token 被按普通输入重复计价；legacy pi 的原分桶语义不变，缺失／矛盾数据继续 unknown。
+- 实现 Auto／Quick／Full：宿主先研究并准备契约，Go 校验资格并持久化策略。Quick 保留 Execute、全部必需验证、独立最终 Review 与同一候选的 Git 交付；合格时 Plan／Judge 记为不适用。旧任务继续 Full，发现风险或验证缺口只允许向 Full 升级，保留预算、工作区和审计历史。
+- 新增 `flywheel-task` 统一准备启动 skill、`flywheel_launch` 模型工具及 `control launch --mode auto|quick|full`。通过 DSH 公开会话投影关联确切任务，覆盖会话重放、fork 隔离与未确认操作；视图显示请求模式、生效策略、阶段适用性和升级原因。
+- 补齐 11 个内嵌 skills 的安装校验、双语工作流／配置／入门指南，以及引擎、控制接口和真实 DSH 发布包的离线回归。模型、账号与权限配置继续沿用现有选择。
+
+- 按任务、范围和角色复用 Codex Pro、DSH 和 Kimi 会话。对已保存的终态回执进行对账，避免重复调用和计量。旧任务配置保持原有默认行为。
+- 修复 macOS 上临时目录别名导致的配对评估误拒，并校正 CLI、DSH 和 worker 测试夹具。Kimi 取消测试使用单进程夹具，避免子进程回收时序干扰断言。
+
 ## 0.28.5
 
 - 将 Flywheel 自定义会话视图排到内置“对话／轨迹／统计”之后，保持内置视图顺序；不修改宿主 DOM，不改变任务、模型和权限行为。六包统一 0.28.5。

package/README.en.md

@@ -4,7 +4,15 @@ English | [简体中文](README.md)
 
 Flywheel turns reviewed software requirements into bounded coding tasks with explicit acceptance criteria. A deterministic Go engine runs Plan, Execute, Review, and verification loops. Models propose plans, implement changes, and review candidates; the engine owns state, retries, budgets, workspaces, verification, local Git delivery, and stopping.
 
-This source targets **0.28.5**, including account defaults, account-error handling, and the current session directory. Check the npm registry before installing; merging source does not update an installed package. The desktop integration covers the checked **DSH Mac 0.2.1-rc.5 and 0.2.2-rc.1** interfaces. Version 0.28.4 declares only these two runtime versions. Check the registry before installing a version. Offline tests do not establish a live user Mac, account, or model pass.
+Current source supports **Auto, Quick, and Full** workflows. `flywheel-task` prepares and launches an authorized goal. A qualified small task uses Execute, all required checks, one independent final Review, and persisted Git delivery; larger or uncertain tasks retain the full loop. Existing tasks remain Full. Workflow selection does not change model bindings, permissions, or delivery authorization.
+
+Session policy supports **fresh/scoped**: new templates explicitly choose scoped, while old configurations default to fresh. Scoped mode can continue compatible history for the same task, role, and scope after a trusted normal terminal outcome; independent re-review still checks the complete current candidate. Both modes journal main-task Codex Pro, Claude Code Pro, DSH, and Kimi calls. Unknown dispatch, outcome, or cleanup blocks execution and cannot be bypassed by switching modes. P3 adds public typed lifecycle events, durable acknowledgements, and read-only Codex/Claude receipt recovery. P4 adds role overrides, bounded quality rebuilds, and paired evaluation tools. Real-account quality, cache, and performance results remain unverified; offline tests cannot establish them. See [Interrupted calls and context quality](docs/en/session-recovery.md). See [Session policy](docs/en/configuration.md#session-policy-history-reuse-and-invocation-safety).
+
+This source targets **0.29.1**, including account defaults, account-error handling, and the current session directory. Check the npm registry before installing; merging source does not update an installed package. The desktop integration covers the checked **DSH Mac 0.2.1-rc.5 and 0.2.2-rc.1** interfaces. Version 0.28.4 declares only these two runtime versions. Check the registry before installing a version. Offline tests do not establish a live user Mac, account, or model pass.
+
+The adaptive workflow and `flywheel-task` require a matching CLI/plugin release containing these changes. Check `flywheel control launch --help`; the older installation commands alone do not establish that this new interface is available.
+
+Current source also supports an optional [Claude Code Pro backend](docs/en/claude-code-pro.md), with explicit models/efforts and scoped role history. No default stage selects it. It requires the companion 0.4.0 machine API and explicit full access; the 0.3.1 desktop tool is not a compatible substitute.
 
 ## Install
 
@@ -22,7 +30,7 @@ Once the version you intend to use is available:
 npx -y @ckanner/flywheel@latest install
 ```
 
-Add `--json` for a structured installation result. The installer selects one exact version for the CLI, platform binary, workers, and DSH plugin; installs the ten bundled skills; preserves existing configuration and modified skills; and records a managed desktop launcher. Binary packages cover macOS and Linux on arm64 and amd64.
+Add `--json` for a structured installation result. The installer selects one exact version for the CLI, platform binary, workers, and DSH plugin; installs that version's bundled skills (eleven in current source); preserves existing configuration and modified skills; and records a managed desktop launcher. Binary packages cover macOS and Linux on arm64 and amd64.
 
 `ok:true` means installation succeeded. `ready:false` means local diagnostics still found a blocker; these values can occur together. The installer does not install or log in to Kimi/Codex or prove model access. Current source defaults reuse the signed-in DeepSeek account in DSH; API-key credentials are needed only for an explicitly selected API provider. Plain `npm install --global @ckanner/flywheel` only installs package files; run `flywheel setup --no-global` afterward to perform explicit user setup.
 
@@ -43,7 +51,7 @@ These bindings are editable starting points, not a model ranking or a performanc
 | Intake, optional | DSH SDK | `deepseek-account` | `deepseek-flash` | `low` |
 | Garden, optional | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
 
-Initial requirement preparation is separate: `flywheel-new` runs in the host's current conversation and uses its selected model. Changing `loops.plan` does not change that conversation. The [workflow guide](docs/en/workflow.md) explains preparation model choices and the later engine loops.
+Initial requirement preparation is separate: `flywheel-task` and the preparation-only `flywheel-new` use the host's current conversation model. Changing `loops.plan` does not change that conversation. Quick reuses the configured Execute route and Review binding; it does not change effort or add a paid fallback. The [workflow guide](docs/en/workflow.md) explains preparation and the later engine loops.
 
 The default configuration has no automatic paid fallback across channels and no second judge. Flash's checked DSH effort values are `off`, `low`, `high`, and `max`; there is no `medium` in that adapter baseline. There is no default multimodal route: the current bridge has a text contract, so a model's vision capability alone does not establish attachment support.
 
@@ -53,7 +61,7 @@ The standard SDK already includes the DeepSeek account provider and account serv
 
 ## Codex Pro uses the actual plugin runtime
 
-The hard route uses `harness: "codex-pro"`. Its worker directly imports the public `dsh-subagent-codex-pro/machine` API from the exact dependency **`dsh-subagent-codex-pro@0.8.0`**, using protocol 1. The plugin runs Codex app-server with the user's existing Codex installation and login. No parent DSH model is required to delegate the task again.
+The hard route uses `harness: "codex-pro"`. Its worker directly imports the public `dsh-subagent-codex-pro/machine` API from the exact dependency **`dsh-subagent-codex-pro@0.9.0`**, using machine protocol 1 and lifecycle version 1. The reviewed source candidate is bundled with Flywheel; [provenance and hashes](plugins/dsh/vendor/README.md) identify its exact bytes. The plugin runs Codex app-server with the user's existing Codex installation and login. No parent DSH model is required to delegate the task again.
 
 `subagent_codex_pro` is an external tool name, not a DSH LLM provider. Native DSH GPT calls use the `chatgpt` provider and have a different execution backend. The older `harness: "codex"` driver remains an explicit compatibility choice; the new route does not silently fall back to `codex exec`.
 
@@ -61,16 +69,28 @@ Existing configuration is preserved during upgrades. To adopt the new route, ins
 
 ## From a requirement to a pull request
 
-Use one task integration branch and worktree for a deliverable. Create it **before** preparing contracts with `flywheel-new`; keep the task directory inside that same worktree. The host or user creates this outer worktree. Flywheel then manages the inner packet workspaces.
+Describe an authorized goal in DSH without filling directory fields first:
 
-In DSH's composer, `/flywheel-new` invokes preparation and `/flywheel-run` invokes the run Skill after review. Kimi CLI uses `/skill:flywheel-new` and `/skill:flywheel-run`. The host loads these Skills and the assistant follows their CLI workflow. No panel fields need filling first.
+```text
+/flywheel-task Fix the identified empty-list behavior, add regression coverage, and deliver the verified change. mode=auto
+```
+
+| Choice | Use | Engine behavior |
+|---|---|---|
+| Auto | Let the engine select from researched contract facts | Quick when eligibility is established; otherwise Full |
+| Quick | One milestone and packet, known implementation, complete checks | Execute, required checks, independent final Review, Git delivery; upgrade on a gap or new risk |
+| Full | Multiple units, unresolved design, significant impact, or explicit choice | Plan, packet Execute/Review, integrated L2/L3, Judge |
+
+Quick retains repository gates, applicable L2/L3, defect sampling, and persistence checks. Its first-success path has two stage-agent calls, excluding host preparation, internal tool turns, and retries. A legacy task remains Full; restarting does not reclassify or downgrade an existing Full task.
+
+Use one task integration branch and worktree for a deliverable. The host creates or deliberately reuses it before preparing contracts and keeps the task directory inside it. Flywheel manages the inner packet workspaces. `/flywheel-task` prepares and launches, `/flywheel-new` prepares a proposal without starting, and `/flywheel-run` starts or resumes an existing task. Kimi uses the `/skill:` prefix for the same skill names. Existing authorizations remain valid; an explicit request to review a proposal first remains a stopping point.
 
 A normal workflow is:
 
-1. Prepare and review the Spec, task packets, frozen acceptance tests, and actual dry-run evidence in the task worktree.
+1. Prepare the Spec, task packets, workflow facts, frozen acceptance tests, and actual dry-run evidence in the task worktree; honor any requested proposal review.
 2. Commit the substantive contract files. Push the task branch and open a task-level Draft PR through the host or GitHub CLI.
-3. Start Flywheel with the task worktree as `cwd` and its own task directory as `taskDir`.
-4. Let the engine run bounded execution, L1 acceptance, and independent review for each packet; then run milestone L2/L3 and Judge.
+3. Launch with the task worktree as `cwd`, its own task directory as `taskDir`, and the requested mode. DSH's `flywheel_launch` associates this concrete task with the initiating session's view.
+4. Let the Go engine select and run Quick or Full, including all applicable checks and independent review against the same candidate.
 5. Push the completed result, verify the current PR head, review it, and merge under the repository's chosen policy.
 
 For example, from an already prepared task worktree:
@@ -78,21 +98,23 @@ For example, from an already prepared task worktree:
 ```sh
 flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --json
 flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
-flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+flywheel control launch --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --mode auto
 flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 ```
 
+`control launch` defaults to Auto and consumes prepared contracts; it does not invent requirements or create the outer task branch. `control start` and foreground `run` preserve the contract/persisted selection when `--mode` is omitted. Their optional mode is `auto|quick|full`; Go still enforces eligibility and one-way upgrade rules. `--only execute` is a partial loop, not Quick or complete delivery.
+
 Packet delivery is a **local Git operation**. After evidence matches the current candidate, the engine commits the packet and fast-forwards it into the branch checked out at `cwd`. With the recommended layout, that is the task integration branch. Flywheel does not itself push, create GitHub PRs, wait for remote CI, merge remote PRs, or publish releases. Those operations belong to the authorized host or user. See [Workflow](docs/en/workflow.md) for commands, directory ownership, and merge timing.
 
 ### Desktop task controls
 
 From `0.28.1`, the native **Flywheel** conversation view appears alongside the built-in views (after Statistics from 0.28.5), preserving DSH's composer, model selector, and right sidebar. Version `0.28.0` uses the old composer popup; upgrade the CLI and desktop plugin together. **Task files directory** selects the prepared `docs/<slug>/`; **Project directory** is its project/integration worktree and may stay blank. From 0.28.3, Flywheel reads DSH's `workingDirectory.get(session)`, following session directory changes. Version 0.28.2 still uses the original header directory: explicitly fill the project path after switching worktrees. Configuration and diagnostics can omit the task; start, refresh, and stop require an existing task directory.
 
-The view retains session-scoped drafts while the host retains the session binding and shows snapshots with their refresh time. It does not discover tasks or poll automatically. An unconfirmed start/stop outcome requires a successful refresh of the same task before further mutations; closing or switching the view does not stop the independent engine. DSH's trajectory keeps its parent-session records, without automatically merging independent worker history. Desktop capabilities and SDK worker policy have separate scopes; see the [plugin guide](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#use-the-desktop-controls).
+DSH tool launch/start associates the exact task with the initiating session. The view shows requested and effective modes, reasons, stage applicability, and upgrades. It does not scan directories to guess tasks or poll tasks started separately in a terminal; manual opening remains supported. An unconfirmed start/stop outcome requires a successful refresh of the original task before further mutations; late responses cannot overwrite a different session or newer binding. Closing the view does not stop the independent engine. DSH's trajectory keeps its parent-session records, without automatically merging worker history. See the [plugin guide](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#use-the-desktop-controls) for association lifetime and runtime boundaries.
 
 ## Verification and operating boundaries
 
-L1 validates a packet; L2/L3 validate integration and user paths at milestone scope. Review examines the actual candidate and acceptance evidence independently of the executor transcript. Candidate or contract changes invalidate prior evidence. Completion requires verified Git delivery and persisted state; an agent's claim that it finished is insufficient.
+L1 validates a packet; L2/L3 validate integration and user paths. Quick runs applicable L2/L3 in the actual packet candidate before its final Review, which covers every requirement and acceptance sufficiency. Full keeps the integrated milestone gates and Judge. Review is independent of the executor transcript. Candidate, contract, verification configuration, and effective workflow policy changes invalidate incompatible evidence. Completion requires verified Git delivery and persisted state; an agent's claim that it finished is insufficient.
 
 Keep these boundaries in mind:
 
@@ -111,6 +133,7 @@ The engine alone writes `state.json`, atomically with revision checks. Do not ed
 |---|---|
 | [Getting started](docs/en/getting-started.md) | Install, configure, diagnose, run a small task, stop, and recover |
 | [Workflow](docs/en/workflow.md) | Preparation models, task and packet worktrees, Draft PRs, completion, and merge policy |
+| [Session lifecycle proposal](docs/en/plans/2026-11-07-session-lifecycle.md) | Original P1–P4 proposal; implemented recovery and quality policy are documented in the current guides |
 | [Configuration](docs/en/configuration.md) | File precedence, profiles, providers, channels, Codex Pro, and diagnostics |
 | [Reasoning effort](docs/en/model-policy.md) | Supported levels, high baseline, evaluation candidates, and account-provider choice |
 | [Chinese documentation](README.md) | Default language and additional implementation detail |

package/README.md

@@ -4,14 +4,26 @@
 
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-当前源码的统一发行目标为 **v0.28.5**，使用 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务默认走 Codex Pro 插件的公开 machine API。0.28.3 包含 DeepSeek 账号默认、账号错误分类与会话当前目录修复；安装前核对 npm registry，源码合并不会更新已安装的包。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
+当前源码支持 **Auto／Quick／Full**：描述目标后由 `flywheel-task` 准备并启动；合格小任务走 Execute、必要验证、一次独立最终 Review 和持久化交付，复杂任务保留完整流程。旧任务继续按 Full 恢复。模式选择不改变已有模型、权限和交付授权。
 
-**本教程适用于 0.28.0 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
+会话策略支持 **fresh／scoped**：新模板显式 scoped，旧配置缺省 fresh。scoped 可在可信
+正常终态后延续同任务、同角色、同作用域的历史；独立复审仍检查完整当前候选。
+Codex Pro、Claude Code Pro、DSH、Kimi 的主任务调用在两种模式下都保存安全记录，未知派发、结果或清理
+会阻止继续执行，不能靠换模式绕过。P3 已接通 Codex／Claude 公开 typed lifecycle、
+持久化 ACK 与只读回执恢复；P4 提供按角色策略、有界质量重建和三组对照评估工具。
+真实账号的质量、缓存与性能结果仍待完成，不能由离线实验推断。详见
+[会话配置](docs/configuration.md#会话策略历史复用与调用安全)及[中断恢复与上下文质量](docs/session-recovery.md)。
+
+当前源码的统一发行目标为 **v0.29.1**，使用 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务默认走 Codex Pro 插件的公开 machine API。0.28.3 包含 DeepSeek 账号默认、账号错误分类与会话当前目录修复；安装前核对 npm registry，源码合并不会更新已安装的包。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
+
+**基础安装命令适用于 0.28.0 及以后的完整 npm 发行版；Auto／Quick／Full 与 `flywheel-task` 需要包含本轮变更的同版本 CLI／插件。** 用 `flywheel control launch --help` 检查新增入口是否存在，并在安装前用 `npm view @ckanner/flywheel version` 核对 registry；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
 
 本轮插件接入测试与实机边界见[验证记录](docs/validation/2026-11-03-codex-pro-default.md)，既有 npm 发行证据见[安装验证](docs/validation/2026-11-01-npm-installation.md)。旧版本的选型、维护机环境与演练记录保存在[历史设计](docs/design-history-v0.24.md)，不代表当前默认值或用户机器状态。
 
 首次使用请按 [Mac 安装与首个任务教程](docs/getting-started.md) 完成安装、配置、无推理检查和小任务验收。本文保留各接口与设计边界的速查。
 
+当前源码另支持可选的 [Claude Code Pro 后端](docs/claude-code-pro.md)：模型与 thinking 可配置，按角色续用已确认会话，尚未分配任何默认 loop。它需要配套插件 0.4.0 的公开 machine API 与显式 full-access；0.3.1 桌面工具不等于已满足此接口。
+
 ## 1. 一条命令安装
 
 已有 **Node.js 22.18.0 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
@@ -20,7 +32,7 @@ Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，
 npx -y @ckanner/flywheel@latest install
 ```
 
-Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制、DSH worker 和 Codex Pro worker（含精确版本的插件依赖）装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
+Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制、DSH worker 和 Codex Pro worker（含精确版本的插件依赖）装到 npm 全局目录，安装该版本的内嵌 skills（当前源码为 11 个），再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
 
 安装完成会显示每个步骤和本地预检结果。`ok:true` 表示软件安装成功；`ready:false` 表示当前配置仍有运行阻断项，例如缺少 Kimi／Codex CLI，二者可以同时出现。安装器不替换现有 DSH，也不安装或代登录 Kimi／Codex。当前源码的 DeepSeek 默认复用 DSH 已登录账号；用户明确选择 API Key 时仍自行配置该凭证。运行真实任务前需完成所选渠道的准备。
 
@@ -46,7 +58,7 @@ npx -y @ckanner/flywheel@latest install --prefix "$HOME/.local"
 dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 ```
 
-这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会复制凭证，也不证明账号可以调用默认表里的所有模型。DSH 桌面能在登录后选择账号默认模型，但该选择不控制独立 SDK 会话；Flywheel 显式请求 `deepseek-account`／`deepseek-flash`，详见[账号与 API 的区别](docs/configuration.md#deepseek-账号与-api-key-是两个-provider)。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider。Flywheel 的 `hard` 路由通过独立 worker 直接导入 `dsh-subagent-codex-pro@0.8.0` 的公开 `./machine` 入口，复用插件运行时；它不创建 DSH 父模型再次委派。插件内部仍运行 Codex app-server，并使用用户已有的 Codex 登录。
+这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会复制凭证，也不证明账号可以调用默认表里的所有模型。DSH 桌面能在登录后选择账号默认模型，但该选择不控制独立 SDK 会话；Flywheel 显式请求 `deepseek-account`／`deepseek-flash`，详见[账号与 API 的区别](docs/configuration.md#deepseek-账号与-api-key-是两个-provider)。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider。Flywheel 的 `hard` 路由通过独立 worker 直接导入 `dsh-subagent-codex-pro@0.9.0` 的公开 `./machine` 入口，复用插件运行时；该精确源码候选随插件 bundle，来源与摘要见 [vendor 记录](plugins/dsh/vendor/README.md)。它不创建 DSH 父模型再次委派。插件内部仍运行 Codex app-server，并使用用户已有的 Codex 登录。
 
 ### worker 入口配置
 
@@ -124,11 +136,27 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 
 ## 4. 创建、运行和观察任务
 
+在 DSH 对话中描述需求即可准备并启动，通常无需手工填写目录：
+
+```text
+/flywheel-task 修复已定位的列表空状态问题，补齐回归测试并完成交付。mode=auto
+```
+
+| 选择 | 何时使用 | 实际行为 |
+|---|---|---|
+| Auto | 让引擎根据已研究的契约事实选择 | 资格充分时 Quick，否则 Full |
+| Quick | 一个里程碑、一个 packet、范围明确且验证充分 | 全部必需验证后作一次独立最终 Review；新风险或验收缺口升级 Full |
+| Full | 多工作单元、设计未定、影响较大或明确要求完整流程 | Plan → Execute／Review → 集成验证／Judge |
+
+Quick 不省略仓库门禁、适用 L2/L3、缺陷注入或 Git 持久化检查。正常成功路径有两次
+阶段 Agent 调用（Execute、最终 Review），不含宿主准备、内部工具轮次与重试。
+旧任务缺少新字段仍为 Full；恢复沿用持久化策略，Full 不因重启自动降为 Quick。
+
 业务仓库建议先建立任务集成分支与独立 worktree；准备契约、Draft PR 和人工合并的完整流程见[从需求准备到 PR 合并](docs/workflow.md)。引擎的单元合并目标是启动 checkout 当前所在分支，GitHub PR 操作由使用者或获授权的宿主执行。
 
 准备阶段由当前 DSH 对话模型生成需求契约，`loops.plan` 只控制引擎启动后的规划／修订。复杂需求建议先用已授权的 `gpt-6-astra`、`high` 生成可审阅草稿；简单明确的任务可沿用 Flash，避免每个 packet 都重复调用昂贵规划模型。
 
-先在目标 Git 仓库准备并审阅 `docs/<slug>/` 中的 Spec、packet 与配置：需求编号、L1/L2/L3 命令、禁止修改的验收路径和失败出口都应明确。DSH 输入框用 `/flywheel-new` 调用准备 Skill，审阅后用 `/flywheel-run`；Kimi CLI 的对应语法是 `/skill:flywheel-new`、`/skill:flywheel-run`。两者都是宿主加载 Skill 后让助手按流程调用 CLI，不是另一个引擎。完整步骤见[工作流](docs/workflow.md)，无需先填面板。
+`flywheel-task` 使用当前对话研究代码，在任务 worktree 准备 `docs/<slug>/` 的 Spec、packet、验收与工作流事实，再调用 Go `control launch`。DSH 通过 `flywheel_launch` 把该具体任务关联到当前会话的视图。只想先看方案时用 `/flywheel-new`；启动或恢复已有任务用 `/flywheel-run`。Kimi 对应使用 `/skill:flywheel-task`、`/skill:flywheel-new` 和 `/skill:flywheel-run`。宿主准备与 Go 调度的分工、授权和目录规则见[工作流](docs/workflow.md)。
 
 从 `0.28.1` 开始，桌面控制面接入顶部原生 **Flywheel** 会话视图（从 0.28.5 起排在内置“统计”之后），保留 DSH 输入区、模型选择器和右侧栏。`0.28.0` 仍是旧底部弹层，需把 CLI 与桌面插件同版升级。“任务资料目录”选择已准备的 `docs/<slug>/`；“项目目录”是任务所在项目／集成 worktree，可留空。从 0.28.3 开始通过 DSH `workingDirectory.get(session)` 读取会话实际目录，跟随目录切换；0.28.2 仍取最初的 header 目录，切换 worktree 后需显式填写项目路径。查看配置或检查接入可不填任务目录；启动、刷新和停止必须选择已有任务。视图展示最近刷新的结果、完整 packet 列表与未知用量，模型配置和诊断按需查看，原始 JSON 默认折叠。也可使用人工命令：
 
@@ -136,9 +164,10 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 /flywheel {"action":"status","taskDir":"/repo/docs/my-task","cwd":"/repo"}
 ```
 
-面板、人工命令和 `flywheel_control` 模型工具复用同一组 Go 接口：
+面板、人工命令、`flywheel_control` 与 `flywheel_launch` 模型工具复用同一组 Go 接口：
 
 ```sh
+flywheel control launch --task-dir /repo/docs/my-task --cwd /repo --mode auto
 flywheel control start --task-dir /repo/docs/my-task --cwd /repo
 flywheel control status --task-dir /repo/docs/my-task --cwd /repo
 flywheel control stop --task-dir /repo/docs/my-task --cwd /repo
@@ -146,16 +175,19 @@ flywheel control config --cwd /repo
 flywheel control doctor --task-dir /repo/docs/my-task --cwd /repo --probe
 ```
 
-`start` 派生独立后台引擎，日志进入任务目录的 `orchestrator.log`；关闭面板或桌面不等于停止任务。`status` 只读。`stop` 向本次运行提交带随机 token 的停止请求，等待本次引擎退出受管调用栈、释放任务 lease 后才保存停止状态；不按文件里的 PID 盲目发送信号。引擎只管理本次拥有的进程组；已观测的 `CleanupError` 仍保留在证据和指标中、阻止交付，需要按错误记录处理，`stopped` 不代表任意逃逸进程已清理。停止等待最长 45 秒，桌面入口预留 60 秒。
+`launch` 对准备好的契约默认请求 Auto；`start`／前台 `run` 未提供 `--mode` 时沿用契约与持久化策略，旧任务保持 Full。三者可显式请求 `auto|quick|full`，资格和升级仍由 Go 决定。CLI 消费契约，不自行调用模型生成任务或创建外层任务分支。
+
+`launch`／`start` 派生独立后台引擎，日志进入任务目录的 `orchestrator.log`；关闭面板或桌面不等于停止任务。`status` 只读。`stop` 向本次运行提交带随机 token 的停止请求，等待本次引擎退出受管调用栈、释放任务 lease 后才保存停止状态；不按文件里的 PID 盲目发送信号。引擎只管理本次拥有的进程组；已观测的 `CleanupError` 仍保留在证据和指标中、阻止交付，需要按错误记录处理，`stopped` 不代表任意逃逸进程已清理。停止等待最长 45 秒，桌面入口预留 60 秒。
 
 控制接口始终返回一个 protocol 1 JSON；`ok` 表示控制操作成功，任务是否完成应看 `state.status`。`config` 返回 `configuration`，`doctor` 返回 `diagnostic`；诊断有阻断项时保留完整报告并返回退出码 1，不能当成空白传输错误。若启动就绪超时，后台引擎可能仍在加载：先刷新状态和查看日志，不要另起重复任务。
 
-视图草稿按 DSH 会话保留，展示的是带刷新时间的快照；不自动发现任务或轮询。启动／停止结果未确认时，先刷新同一任务再恢复操作。原生轨迹保留父会话已有记录，独立 worker 历史不会自动合并。桌面原生能力与 SDK worker 的临时策略属于不同范围，详见[桌面视图与运行边界](plugins/dsh/README.md)。
+DSH 工具的 launch／start 将明确的任务路径关联到发起会话；视图展示请求模式、生效策略、原因、阶段适用性与升级记录。它不扫描目录猜任务，也不轮询终端另行启动的任务；手动打开仍可用。启动／停止结果未确认时，先刷新原任务再恢复操作，迟到响应不能覆盖另一个会话或新绑定。原生轨迹保留父会话已有记录，独立 worker 历史不会自动合并。关联的恢复范围见[桌面视图与运行边界](plugins/dsh/README.md)。
 
 原有前台／单步 CLI 仍可使用；这些命令应在目标仓库根目录运行：
 
 ```sh
 flywheel run docs/my-task
+flywheel run docs/my-task --mode full
 flywheel run docs/my-task --pause-before review
 flywheel run docs/my-task --only execute --packet M01-T01
 flywheel run docs/my-task --only verify --packet M01-T01
@@ -163,7 +195,7 @@ flywheel status docs/my-task
 flywheel stop docs/my-task
 ```
 
-`--only` 与 `--pause-before` 不能同时使用。前台 `run` 的退出码为 0 成功、1 用法／运行错误、3 升级／预算／单步失败、143 中断；控制命令的操作失败返回 1。
+`--only` 与 `--pause-before` 不能同时使用，`--only execute` 不等于 Quick 或完整交付。前台 `run` 的退出码为 0 成功、1 用法／运行错误、3 升级／预算／单步失败、143 中断；控制命令的操作失败返回 1。
 
 ### 已安装的 skills
 
@@ -171,20 +203,20 @@ flywheel stop docs/my-task
 flywheel install-skills
 flywheel install-skills --project /path/to/project
 flywheel skills list
-flywheel skills read flywheel-new
+flywheel skills read flywheel-task
 ```
 
-一条命令安装已包含全部 10 个 skills。默认把 Go 内嵌快照安装到 `~/.agents/skills`，`--project` 改为项目的 `.agents/skills`；上述命令可用于补装、检查或显式安装项目范围的副本。
+一条命令安装包含所选版本的全部 skills，当前源码为 11 个。默认把 Go 内嵌快照安装到 `~/.agents/skills`，`--project` 改为项目的 `.agents/skills`；上述命令可用于补装、检查或显式安装项目范围的副本。
 
 每个快照保存带文件内容 hash 的 `.flywheel-snapshot` 清单。重跑先校验当前树：未改过的自有快照可更新，相同内容跳过；用户修改、新增／删除文件、链接或未标记目录都保留并报告冲突。更新按每个 skill 暂存、rename 替换，失败时回滚，不会因为存在一个标记就覆盖用户内容。旧纯文本标记仅在整棵目录与当前内嵌内容一致时迁移。冲突恢复见[升级教程](docs/getting-started.md#8-升级排错与卸载)；`--force` 只用于源码 `--link` 模式，不能绕过默认快照保护。
 
-安装同时会在全局配置不存在时生成默认配置，已有配置保留。源码开发者才使用 `--link`。skills 只是 CLI 操作按钮，宿主的发现规则和调用语法按其配置使用，不能承担重试或状态机逻辑；安装成功不等于所有宿主已经发现它们。可用按钮涵盖 new、run、plan、exec、review、verify、status、stop、intake、garden。
+安装同时会在全局配置不存在时生成默认配置，已有配置保留。源码开发者才使用 `--link`。skills 是宿主准备／CLI 操作入口，宿主的发现规则和调用语法按其配置使用，不能承担重试或状态机逻辑；安装成功不等于所有宿主已经发现它们。可用入口涵盖 task、new、run、plan、exec、review、verify、status、stop、intake、garden。
 
 ## 5. 什么才算完成
 
 执行者可以一起修改实现、单测和回归测试；冻结验收通过 packet 的 `boundaries.must-not-touch` 或配置的 `protected-test-patterns` 显式保护。100% 覆盖率仍是本项目的门禁，断言是否有效由验收和独立评审共同检查。
 
-L1 在命令前后检查候选身份。验收过程中代码或契约变了，即使命令 exit 0 也不能继续交付。Review 同样必须针对当前候选；最终 L2/L3 与 Judge 还会核对主 checkout 的前后身份。正常完成需要代码实际提交、合并到本地目标 checkout，并确认提交后的 Git tree 与已验证候选一致；commit hook 修改 index 或文件也不能绕过这一步。任务最终完成前再次检查持久化状态，重启不会把上次验收留下的未提交副作用当成交付。
+L1 在命令前后检查候选身份。验收过程中代码或契约变了，即使命令 exit 0 也不能继续交付。Quick 在实际候选上先收齐适用 L2/L3，再作覆盖所有需求的独立最终 Review；Full 仍在集成 checkout 运行里程碑 L2/L3 与 Judge。工作流策略也进入证据身份，模式变化不能复用旧绿灯。正常完成需要代码实际提交、合并到本地目标 checkout，并确认提交后的 Git tree 与已验证候选一致；commit hook 修改 index 或文件也不能绕过这一步。任务最终完成前再次检查持久化状态，重启不会把上次验收留下的未提交副作用当成交付。
 
 Plan 只能直接修改任务目录内的 Spec 和 packet。它若修改外部验收、实现或运行配置，引擎保留现场并停止，不自动提交或丢弃。修订后的契约 fingerprint 会跨重启保存：旧 completed 单元的契约或验证策略改变时重新打开，早先已关闭的里程碑也会被重新调度。同一 run 对一个里程碑最多访问 3 次，再反复重开就升级给人。最终要求所有当前契约单元完成、里程碑关闭。
 
@@ -236,6 +268,7 @@ npm run build:npm
 |---|---|
 | [docs/getting-started.md](docs/getting-started.md) | Mac 安装、首个任务、配置迁移与排错 |
 | [docs/design.md](docs/design.md) | 权威设计、不变量、闭环与边界 |
+| [会话生命周期方案](docs/plans/2026-11-07-session-lifecycle.md) | P1/P2 正常终态续接与回执恢复；P3 公开实时恢复 API、P4 真实实验仍待完成 |
 | [docs/configuration.md](docs/configuration.md) | profiles、阶段覆盖、provider／channel 与预检语义 |
 | [docs/plans/2026-11-03-codex-pro-default.md](docs/plans/2026-11-03-codex-pro-default.md) | 默认插件接入与验收计划 |
 | [docs/plans/2026-11-01-dsh-integration.md](docs/plans/2026-11-01-dsh-integration.md) | 本轮实施和验收记录 |

package/bin/flywheel-claude-code-pro-worker.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
+"use strict";
+
+const { loadClaudeCodeProWorkerPath, runChild } = require("./runtime.js");
+
+async function main() {
+  return runChild(process.execPath, [loadClaudeCodeProWorkerPath(), ...process.argv.slice(2)], {
+    label: "flywheel-claude-code-pro-worker",
+  });
+}
+
+main().then(code => { process.exitCode = code; }).catch(error => {
+  console.error(`flywheel-claude-code-pro-worker: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/flywheel.js

@@ -2,7 +2,7 @@
 // Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
 "use strict";
 
-const { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild } = require("./runtime.js");
+const { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, loadClaudeCodeProWorkerPath, assertSupportedNode, runChild } = require("./runtime.js");
 
 async function main() {
   const args = process.argv.slice(2);
@@ -21,6 +21,9 @@ async function main() {
   if (env.FLYWHEEL_CODEX_PRO_WORKER === undefined) {
     env.FLYWHEEL_CODEX_PRO_WORKER = loadCodexProWorkerPath();
   }
+  if (env.FLYWHEEL_CLAUDE_CODE_PRO_WORKER === undefined) {
+    env.FLYWHEEL_CLAUDE_CODE_PRO_WORKER = loadClaudeCodeProWorkerPath();
+  }
   return runChild(loadNativePath(), args, { env });
 }
 

package/bin/runtime.js

@@ -53,6 +53,12 @@ function loadCodexProWorkerPath() {
     "the matching @ckanner/dsh-plugin-flywheel Codex Pro worker is missing; reinstall @ckanner/flywheel");
 }
 
+function loadClaudeCodeProWorkerPath() {
+  const name = "@ckanner/dsh-plugin-flywheel";
+  return packageEntry(name, "claude-code-pro-worker", ownPackage.dependencies?.[name],
+    "the matching @ckanner/dsh-plugin-flywheel Claude Code Pro worker is missing; reinstall @ckanner/flywheel");
+}
+
 function assertSupportedNode(version = process.versions.node) {
   const match = /^(\d+)\.(\d+)\.(\d+)(?:$|-)/.exec(version);
   if (!match || Number(match[1]) < 22 || (Number(match[1]) === 22 && Number(match[2]) < 18)) {
@@ -97,4 +103,4 @@ function runChild(command, args, { env = process.env, cwd, label = "flywheel" }
   });
 }
 
-module.exports = { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild };
+module.exports = { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, loadClaudeCodeProWorkerPath, assertSupportedNode, runChild };

package/docs/claude-code-pro.md

@@ -0,0 +1,128 @@
+# 可选 Claude Code Pro 后端
+
+[English](en/claude-code-pro.md) · [配置指南](configuration.md)
+
+Flywheel 现在可通过 `harness: "claude-code-pro"` 调用
+[`dsh-subagent-claude-code-pro`](https://github.com/ckanner/dsh-subagent-claude-code-pro)
+的公开 machine API。插件运行用户已安装的 Claude Code CLI，使用该 CLI 的原生工具
+循环与登录环境。Go 仍负责阶段调度、角色会话、验证、预算和交付。
+
+**源码与发行边界：**此接入要求插件 **0.4.0 / machine protocol 1**；0.3.1 只有
+DSH 工具入口，0.3.2 只有旧 machine 契约，均不满足新 lifecycle/recovery 接口。0.4.0 是本次配套源码版本，不能据此推断 npm 已
+发布。Flywheel 当前源码版本仍为 0.28.5，新增代码也不等于旧同版本安装已更新。
+合并、发布及用户安装各有独立状态。现有默认 loop／route 没有切换到 Claude。
+
+## 1. 准备依赖
+
+需要 Node.js 22.18.0 或更高、macOS 或 Linux，以及可被启动引擎的进程找到的
+`claude` CLI。用户按 CLI 自身流程完成登录；Flywheel 不复制登录数据。
+
+Flywheel 包含 `flywheel-claude-code-pro-worker`，把 Claude 插件作为精确版本的
+**optional peer**。没有选择这个后端时无需安装插件，也不会启动 Claude。选择后必须
+让 worker 的 Node 依赖解析能找到 `dsh-subagent-claude-code-pro@0.4.0`。仅在 DSH
+desktop profile 安装插件，不保证独立 worker 能访问该目录。
+
+正式发布后，将该精确版本装到 Flywheel 所在的同一全局 npm prefix 或同一项目依赖树。
+发布前可从已审查的插件源码运行 `npm pack --ignore-scripts`，把产生的真实 `.tgz`
+安装到同一 prefix，再用新构建的 Flywheel 验证。不要用 0.3.1 替代，也不要编辑包版本
+伪装兼容。此开发候选流程不提升 npm latest。
+
+| 环境变量 | 用途 |
+|---|---|
+| `FLYWHEEL_CLAUDE_CODE_PRO_WORKER` | 显式 worker 覆盖；npm 启动器通常自动解析同版本 worker |
+| `FLYWHEEL_CLAUDE_BIN` | Claude CLI 命令或绝对路径，缺省为 `claude` |
+| `CLAUDE_CONFIG_DIR` | 可选的原生 CLI 配置／登录目录，由 Claude 解释 |
+
+Go 只传递白名单基础环境和所选 channel 明确注入的凭证；没有配置 env-key 的订阅
+渠道不自动继承外部 Anthropic API key。显式凭证只通过受支持的环境名进入插件，
+环境凭证值不主动序列化到请求或 diagnostics；CLI 返回的文本按实际结果保留。
+
+## 2. 先定义模型，按需绑定阶段
+
+完整的 [profiles 模板](../templates/flywheel.profiles.example.json) 具有未引用的
+`claude-sonnet`。以下是加入自己现有完整配置的片段，不是替换全部配置的文件：
+
+```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 }
+}
+```
+
+`sonnet`、`opus`、`haiku` 使用 CLI 原生别名，也可写实际账号支持的完整模型 ID。
+完整 ID 必须与 CLI init 观察值一致，三个别名核对对应模型 family；具体版本由 CLI
+目录决定。支持传递 low、medium、high、xhigh、max，省略时 high。能传递档位不代表
+每个模型／CLI 版本都支持它；拒绝会原样保留，不静默更换模型或档位。CLI 没有回显
+有效 effort 时只记录请求值。
+
+未来决定用途时，让所需的 `loops.plan/review/judge/intake/garden` 或 Execute 的
+`routes.*` 引用该 profile。例如，把某个绑定设为 `{"profile":"claude-sonnet"}`。
+这只是配置能力，不是默认阶段分配建议。现有绑定有显式 `provider` 时需同时清掉；
+`provider` 是 DSH 原生 LLM adapter 字段，不能填 `subagent_claude_code` 或
+`claude-code-pro` 来代替 harness。
+从 Kimi Plan 切换时也移除原来的 `resident-session` 字段，让历史策略由
+`sessions.mode` 控制。`resident-session:true` 对 Claude 无效；为保留旧配置的明确
+选择，Plan 的显式 `resident-session:false` 仍会关闭 scoped 历史复用。
+
+新配置在下次启动引擎时生效。检查实际命中的文件和展开结果：
+
+```sh
+flywheel config inspect --cwd /repo --json
+flywheel doctor --cwd /repo --json
+flywheel-claude-code-pro-worker --doctor
+```
+
+未绑定的 profile 不要求安装 Claude；一旦绑定，doctor 会检查 worker、精确插件接口
+和 CLI。上述检查不发模型请求，不能证明账号额度或真实推理已通过。
+
+## 3. 权限与会话
+
+首版要求显式 `permissions.mode:full-access`，映射为 Claude 原生
+`bypassPermissions` 与非交互调用。plan／acceptEdits 等原生审批模式不等于 OS 的
+read-only／workspace-write 沙箱，因此 role-based 请求会在启动前拒绝。
+评审、规划的角色职责及候选前后检查仍有效；完全权限不允许通过修改验收取得 pass。
+
+主任务的 Plan／Execute／Review／Judge 使用现有 fresh/scoped 策略。scoped 普通
+返修只续接同任务、同范围、同角色的已确认历史；Review 与 Execute 分开，第二意见
+也独立。session ID 精确传入原生 resume，不猜最近会话，恢复失败不改为新建重放。
+Intake／Garden 可选此后端，但继续执行独立建议调用，不拥有主任务角色会话账本。
+
+一个可应用的成功结果必须同时具备合法完整流、请求／会话／配置匹配、正常物理退出和清理
+确认。父连接断开、取消、超时、坏帧、重复终态、异常退出或未知清理都不能取得成功。
+确定发生在 machine 调用前的依赖缺失／参数拒绝被记录为未派发与零消耗；修好环境后
+可继续。已经进入调用却没有可信结果时，即使进程已清理，仍须停止而不能自动重放。
+
+插件在派发 Claude 前建立独立 supervisor、durable journal 和 native guardian。
+Go 保存并确认 intent/possible 检查点后才允许提交 prompt。worker 被强制终止时，
+supervisor 取消未确认步骤并收束原生进程，将完整终态落盘；正常调用也等待 guardian
+退出。公开 `recoverMachine` 只读取这次调用，不启动 CLI 或重发 prompt。
+
+Claude 的 init 只能在 prompt 后观察，不提供预派发 thread-ready 或真实 turn-accepted；
+终态仍须检查实际模型、目录与权限。supervisor 自身丢失、journal 损坏或缺少原候选
+检查点时仍可阻断，不能承诺任意崩溃都继续交付。详见[恢复与质量](session-recovery.md)。
+真实账号质量、缓存率和性能收益须另行评估，离线成功不证明这些结果。
+
+## 4. 用量与成本
+
+完整 CLI usage 中 input_tokens 不含缓存；Flywheel 总输入加上 cache read 和 cache
+creation，再加 output 得到总 token。缺失计数保持 partial/unknown，不能补零。
+每次续接只计入该次调用，不把历史累计重复入账。
+
+原始回执保留 CLI 的 `total_cost_usd` 为 `reportedCostUSD`。它是 API 等价估算，
+不是订阅实际账单；`costUSD` 保持 null、`costStatus` 保持 unknown。已有 soft/hard
+预算纪律继续适用。
+
+若用户显式提供 `pricing`，metrics／预算可另记配置价表估算：从包含缓存的总输入中
+扣除 cache read／creation，再对各桶计价，避免重复计算。该估算不读取
+`reportedCostUSD`，也不改写原始回执或变成订阅实际账单。