@ckanner/flywheel 0.27.3 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.28.0
+
+Codex Pro 默认接入。安装和迁移见 [配置指南](docs/configuration.md#codex-pro-默认与旧配置迁移)；源码、测试、CI 和 registry 发布证据分别记录，不用离线通过代替用户 Mac 实测。
+
+- 新增 `codex-pro` Go driver 与独立 Node worker，直接使用 `dsh-subagent-codex-pro@0.8.0` 的公开 machine API。默认 hard 路由使用此插件；DSH Flash 默认执行、Kimi CLI 规划／前端、DSH 原生 GPT 评审保持原角色。旧 `codex` CLI 仅作为用户显式配置的兼容入口。
+- 完整传递模型、effort、目录、权限、取消与 deadline。每次使用 ephemeral 新会话；结果必须同时满足外层 worker 和插件终态／清理要求，正常 app-server 主动终止不冒充调用方取消。
+- 指标保存完整 `codex-pro-receipt`；usage 只有 complete 才进入已知预算，partial/unknown 与美元未知成本保持可见。effort accepted 不伪造为已证实实际强度，不用账号 channel 冒充实际 provider。
+- npm 自动安装精确插件依赖并解析同版本 worker，保持 hoisted dependency、GUI 启动入口、用户配置与 skills 保护；统一六包版本 0.28.0，Node 最低 22.18.0。
+- 本地 doctor 验证插件公开 API、精确版本、Node 和 Codex 命令，不调用模型。配置错误、缺依赖与版本不符明确失败，不自动改走旧 CLI。
+- worker 意外退出或清理回执缺失时明确记录清理未知；所有模型循环保存升级诊断、保留工作区并停止本次运行，禁止自动重试／降级与 Plan 冷启动，避免 guardian 清理期间出现重叠执行。正常错误且清理已确认时仍可重试。
+- 明确 0.8.0 权限边界：插件在运行前验证模型／cwd／权限模式，完整 sandboxPolicy 由 Flywheel 在运行后核对；事后拒绝交付不能阻止自定义 Codex 配置已允许的访问。需运行前完整策略 guard 的环境仍待上游能力。
+- 更新设计、安装／迁移教程、协议和相关技能按钮，增加协议、计量、生命周期、真实 npm 安装与跨进程回归。
+- 补齐 10 个内置 skills 的任务 worktree、分支与绝对路径约定，区分任务集成目录和 packet 候选目录；恢复复用原任务，状态查询／停止保持可用，PR 合并仍由获授权宿主处理。
+- 新增英文 README、入门／配置／工作流、DSH 插件说明、贡献和发行指南，并将英文用户文档纳入 npm 包。补充 CI 不可用时经维护者授权的手动发行流程，沿用精确源码、同一候选、六包 integrity 与 registry 安装门禁。
+
 ## 0.27.3
 
 当前统一 npm 发行目标。本节记录修复内容，不代表本版门禁、registry 发布、latest 提升或用户 Mac 实机验收已完成。0.27.0／0.27.1 未上传 npm 包；0.27.2 的发行在验证阶段主动取消，未上传包，旧 tag 均保留不移动。

package/README.en.md

@@ -0,0 +1,127 @@
+# Flywheel
+
+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 documentation describes the **0.28.0 implementation**. The desktop integration targets the interfaces checked against **DSH Mac 0.2.1-rc.5**. Source changes and GitHub releases do not establish npm availability: check the registry before installing a version. Offline test results also do not establish that a user's Mac, desktop permissions, account, or selected model works.
+
+## Install
+
+You need **Node.js 22.18.0 or later**, npm, Git with a commit identity, and DSH Mac with its desktop-supplied `dsh` command. The default configuration also needs an authenticated Kimi CLI, a Codex installation and login for the hard route, and configured DeepSeek and ChatGPT providers in the DSH SDK profile. Go is needed for source builds and the Go example, but not for npm binary installation.
+
+First check the published version:
+
+```sh
+npm view @ckanner/flywheel version
+```
+
+Once the version you intend to use is available:
+
+```sh
+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.
+
+`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, configure API credentials, or prove model access. Plain `npm install --global @ckanner/flywheel` only installs package files; run `flywheel setup --no-global` afterward to perform explicit user setup.
+
+Follow [Getting started](docs/en/getting-started.md) for prerequisites, desktop versus SDK setup, a runnable first task, and recovery. Use `--prefix "$HOME/.local"` if you need a user-owned npm prefix.
+
+## Default model routes
+
+These bindings are editable starting points, not a model ranking or a performance guarantee. Availability depends on the actual account, adapter, and model catalog.
+
+| Stage or route | Harness | Provider or channel | Model | Requested thinking |
+|---|---|---|---|---|
+| Plan | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+| Execute: `default` | DSH SDK | `deepseek-official` | `deepseek-flash` | `high` |
+| Execute: `frontend` | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+| Execute: `hard` | Codex Pro machine API | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
+| Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high`, read-only |
+| Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high`, read-only |
+| Intake, optional | DSH SDK | `deepseek-official` | `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.
+
+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.
+
+## 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.
+
+`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`.
+
+Existing configuration is preserved during upgrades. To adopt the new route, inspect the effective configuration and update the hard route or its model profile explicitly. See [Configuration](docs/en/configuration.md#codex-pro-and-migration).
+
+## 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.
+
+A normal workflow is:
+
+1. Prepare and review the Spec, task packets, frozen acceptance tests, and actual dry-run evidence in the task worktree.
+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.
+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:
+
+```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 status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+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.
+
+## 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.
+
+Keep these boundaries in mind:
+
+- **Worktrees isolate Git work, not process permissions.** Packet worktree creation can currently fall back to in-place execution. There is no engine option requiring isolation in every case. Skills check the recommended task location; direct CLI/GUI use does not execute those skill checks.
+- **Permissions depend on the harness.** DSH and Codex paths request explicit permissions. Kimi's current CLI integration does not provide an OS-level read-only or workspace sandbox guarantee.
+- **Codex Pro's complete policy check is after the run.** The plugin checks model, directory, approval, and sandbox mode before a turn. Flywheel validates the full returned policy afterward, allowing the workspace and standard Codex temporary directories. Additional external write roots, enabled network access, or unconfirmed policy prevent acceptance. This check cannot prevent access already allowed by custom Codex configuration.
+- **Cleanup needs evidence.** A worker exiting does not prove that the plugin's separate app-server or guardian processes stopped. An unconfirmed cleanup result escalates and stops the run; inspect and resolve it before resuming.
+- **Unknown usage remains unknown.** Missing usage or monetary cost is not zero. Soft budgets report uncertainty; hard budgets stop when unknown usage makes the limit unverifiable.
+- **Preflight is not a model smoke test.** `doctor --probe` initializes supported SDK sessions without an inference prompt. Codex Pro checks import/version/protocol and local commands, leaving actual model, authorization, and full runtime policy unverified.
+
+The engine alone writes `state.json`, atomically with revision checks. Do not edit it to force progress or delete retained work to make a retry look clean.
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [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 |
+| [Configuration](docs/en/configuration.md) | File precedence, profiles, providers, channels, Codex Pro, and diagnostics |
+| [Chinese documentation](README.md) | Default language and additional implementation detail |
+| [System design](https://github.com/ckanner/flywheel/blob/main/docs/design.md) (Chinese) | Authoritative design and invariants |
+| [DSH plugin](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md) / [protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md) (protocol in Chinese) | Desktop control surface, workers, permissions, and lifecycle |
+| [Release guide](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md) | Candidate artifacts, registry verification, and release recovery |
+| [Contributing](https://github.com/ckanner/flywheel/blob/main/docs/contributing.md) | Development workflow, validation, and contribution boundaries |
+
+The English guides cover current operation. Historical design and validation ledgers remain in their original language. Source and design links are intended for browsing the repository; the npm package contains selected runtime and user documentation rather than the entire repository.
+
+## Development
+
+Read [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md) and the [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md) before changing the engine. Source development needs Go 1.27 or later and Node.js 22.18.0 or later. Relevant local gates include:
+
+```sh
+make quality-gate
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+FLYWHEEL_TEST_NODE_BRIDGE=1 go test ./internal/drivers -run '^Test(DSH|CodexPro)NodeWorkerOfflineBridge$' -count=1
+npm test
+```
+
+These commands cover local code and protocol behavior. Real desktop UI, macOS permissions, account access, and model inference require separate, recorded testing in the intended environment.
+
+## License status
+
+The package currently declares **`UNLICENSED`**. An open-source license has not been selected; these English documents do not change the repository's visibility or licensing status.

package/README.md

@@ -1,24 +1,26 @@
 # Flywheel（飞轮）
 
+[English](README.en.md) · 简体中文
+
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-当前 **v0.27.3 实施版**以 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务可走独立 Codex CLI。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
+当前 **v0.28.0 实施版**以 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务默认走 Codex Pro 插件的公开 machine API。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
 
-**本教程适用于 0.27.3 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
+**本教程适用于 0.28.0 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
 
-测试结果与实机边界见[验证记录](docs/validation/2026-11-01-npm-installation.md)。旧版本的选型、维护机环境与演练记录保存在[历史设计](docs/design-history-v0.24.md)，不代表当前默认值或用户机器状态。
+本轮插件接入测试与实机边界见[验证记录](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) 完成安装、配置、无推理检查和小任务验收。本文保留各接口与设计边界的速查。
 
 ## 1. 一条命令安装
 
-已有 **Node.js 22 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
+已有 **Node.js 22.18.0 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
 
 ```sh
 npx -y @ckanner/flywheel@latest install
 ```
 
-Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制和 DSH worker 装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
+Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制、DSH worker 和 Codex Pro worker（含精确版本的插件依赖）装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
 
 安装完成会显示每个步骤和本地预检结果。`ok:true` 表示软件安装成功；`ready:false` 表示当前配置仍有运行阻断项，例如缺少 Kimi／Codex CLI，二者可以同时出现。安装器不替换现有 DSH，也不安装或代登录 Kimi／Codex，不代配 DeepSeek API 凭证。运行真实任务前需完成所选渠道的准备。
 
@@ -44,7 +46,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 不会自动迁移桌面凭证，也不证明账号可以调用默认表里的所有模型。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider；Flywheel 的 `hard` 路由使用独立 Codex CLI。
+这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会自动迁移桌面凭证，也不证明账号可以调用默认表里的所有模型。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider。Flywheel 的 `hard` 路由通过独立 worker 直接导入 `dsh-subagent-codex-pro@0.8.0` 的公开 `./machine` 入口，复用插件运行时；它不创建 DSH 父模型再次委派。插件内部仍运行 Codex app-server，并使用用户已有的 Codex 登录。
 
 ### worker 入口配置
 
@@ -55,8 +57,11 @@ dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 | `FLYWHEEL_DSH_PROFILE` | `sdk`；必须是 SDK profile，不能是 `desktop` |
 | `DSH_HOME` | 交给 DSH 的自定义配置根；不设置时沿用 DSH 自己的默认行为 |
 | `FLYWHEEL_KIMI_BIN` | PATH 中的 `kimi`；可指定 Kimi CLI 的绝对路径 |
+| `FLYWHEEL_CODEX_PRO_WORKER` | npm 启动器解析同版本包的 Codex Pro worker；独立 Go 二进制默认查找 `flywheel-codex-pro-worker` |
+| `FLYWHEEL_CODEX_BIN` | 插件内部使用的 Codex 可执行路径；默认 `codex` |
+| `CODEX_HOME` | 可选的 Codex 配置／登录目录，交给插件使用；不复制账号凭证 |
 
-Codex CLI 通过 PATH 中的 `codex` 启动。所有选定 CLI、Node 与账户配置必须对**启动 Go 引擎的进程环境**可见。
+旧 `harness: "codex"` 仍是显式兼容路径，使用 PATH 中的 `codex exec`；新默认不会自动退回它。所有选定 CLI、Node 与账户配置必须对**启动 Go 引擎的进程环境**可见。
 
 安装器自动生成 `~/.config/flywheel/npm-launcher` 和 `installation.json`：记录绝对 Node／CLI 路径、已核对的 DSH 入口及安装时可见的工具 PATH。桌面插件未显式配置 `flywheelBinary` 时，读取这份安装记录，校验 launcher 是普通可执行文件且 SHA-256 匹配后使用。**无需手写 GUI 启动脚本或修改 profile 配置。**
 
@@ -87,7 +92,7 @@ flywheel doctor --cwd "$PWD" --probe --json
 | Plan | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high`，匹配身份后可恢复会话 |
 | Execute `default` | DSH SDK | `deepseek-official` | `deepseek-flash` | `high` |
 | Execute `frontend` | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
-| Execute `hard` | Codex CLI | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
+| Execute `hard` | Codex Pro machine API | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
 | Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high`，只读 |
 | Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high`，里程碑终验 |
 | Intake | DSH SDK | `deepseek-official` | `deepseek-flash` | `low` |
@@ -95,7 +100,7 @@ flywheel doctor --cwd "$PWD" --probe --json
 
 这些是可编辑的初始绑定，并非模型排名或性能承诺。DeepSeek 只用 Flash；当前 Mac rc.5 的合法 effort 为 `off/low/high/max`，没有 `medium`。双 judge 默认关闭，也不默认跨渠道付费降级。`multimodal` 暂无默认绑定：当前 bridge 只有文本契约，模型名称或目录里的 vision 标记不能证明附件已正确传递。
 
-Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。DSH/Codex 使用明确的 workspace-write 或 read-only 与禁止扩权策略。具体账号的可用模型、额度和使用授权需要由所选服务确认。
+Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。DSH/Codex 使用明确的 workspace-write 或 read-only 与 never 审批策略。Codex Pro 在运行前核对模型、目录和沙箱模式，Flywheel 在结果返回后检查完整策略；工作区写入允许 Codex 标准临时目录，额外工作区外 roots 或启用网络的策略不能通过交付资格检查。这是事后校验，不能阻止自定义 Codex 配置已允许的访问；要求运行前完整策略阻止的环境需等待上游公开 guard。具体账号的可用模型、额度和使用授权需要由所选服务确认。
 
 usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免费。默认 soft token budget 会报告未知量；hard budget 无法证明未知用量未超额时停止。汇总数字是已知量下限。
 
@@ -103,6 +108,8 @@ usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免
 
 配置按**第一个存在的完整文件**选择，不逐字段合并：任务目录 → 项目根 → 全局 `~/.config/flywheel/flywheel.config.json` → 二进制内嵌模板；`FLYWHEEL_CONFIG` 可指定全局配置路径。已有文件不会因升级自动改写。
 
+从 0.27.x 升级要采用插件路径时，在实际生效配置中将 `routes.hard.harness` 从 `codex` 改为 `codex-pro`；具名 profile 则修改对应定义。保留 `model`、`thinking` 和 `channel`，不要把 `subagent_codex_pro` 填入 provider。安装依赖不自动迁移已有配置，也不会默默替换旧后端。
+
 可用新二进制查看模板，再审阅并迁移自己的配置：
 
 ```sh
@@ -115,6 +122,10 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 
 ## 4. 创建、运行和观察任务
 
+业务仓库建议先建立任务集成分支与独立 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 命令、禁止修改的验收路径和失败出口都应明确。模板可通过 `flywheel template` 查看；可选的 `flywheel-new` skill 用于辅助生成，最终仍由人确认契约。不要把 DSH 面板当成需求生成器。
 
 桌面面板位于会话输入区底部的 **Flywheel** 按钮。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。面板展示实际阶段绑定、检查项、完整 packet 列表与未知用量，原始 JSON 可按需展开。也可使用人工命令：
@@ -196,11 +207,11 @@ DSH 检查包括离线 worker 生命周期、事件与 usage 折叠、控制入
 
 React DOM 与安装协议桩不代替 Mac 桌面验证。当前 Linux 环境没有可用的完整原生沙箱，SDK probe 在 prompt 前正确拒绝；这项结果证明拒绝路径，不能冒充 Mac Seatbelt 成功。
 
-**尚需在用户 Mac 验证**：桌面安装与 UI 渲染、Seatbelt 探针、GUI 环境中的 CLI／凭证可见性、真实 Flash/GPT/Kimi/Codex 响应，以及真实机器重启后的恢复。当前不支持 DSH worker resume、附件传输、外部 Codex Pro adapter 消费或自动多 agent Teams 调度。
+**尚需在用户 Mac 验证**：桌面安装与 UI 渲染、Seatbelt 探针、GUI 环境中的 CLI／凭证可见性、真实 Flash/GPT/Kimi/Codex 响应，以及真实机器重启后的恢复。当前不支持 DSH worker resume、附件传输或自动多 agent Teams 调度。Codex Pro 已通过公开 API 接入，完整策略的事后检查边界见配置指南。
 
 ## 7. 开发与备用构建
 
-普通用户使用上面的 npm 安装流程。开发者需要 Go 1.27 或更高、Node.js 22 或更高及 Git，在仓库根构建：
+普通用户使用上面的 npm 安装流程。开发者需要 Go 1.27 或更高、Node.js 22.18.0 或更高及 Git，在仓库根构建：
 
 ```sh
 go build -o ./bin/flywheel ./cmd/flywheel
@@ -213,11 +224,14 @@ npm run build:npm
 
 ## 文档与代码入口
 
+英文用户文档包括 [入门](docs/en/getting-started.md)、[配置](docs/en/configuration.md)、[工作流](docs/en/workflow.md) 和 [DSH 插件说明](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md)。贡献者从 [Contributing](https://github.com/ckanner/flywheel/blob/main/docs/contributing.md) 开始，发行维护者见 [Releasing](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md)。
+
 | 路径 | 内容 |
 |---|---|
 | [docs/getting-started.md](docs/getting-started.md) | Mac 安装、首个任务、配置迁移与排错 |
 | [docs/design.md](docs/design.md) | 权威设计、不变量、闭环与边界 |
 | [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) | 本轮实施和验收记录 |
 | [docs/plans/2026-11-01-model-profiles-preflight.md](docs/plans/2026-11-01-model-profiles-preflight.md) | 配置、预检与面板后续实施计划 |
 | [docs/plans/2026-11-01-npm-installation.md](docs/plans/2026-11-01-npm-installation.md) | npm 安装、GUI 入口与发行验证计划 |
@@ -228,3 +242,7 @@ npm run build:npm
 | [internal/drivers/](internal/drivers/) | DSH／Kimi／Codex 与保留的兼容 driver |
 | [internal/verify/](internal/verify/) | 确定性验收、边界、Git 持久化与工作区 |
 | [docs/design-history-v0.24.md](docs/design-history-v0.24.md) | 历史设计与当时的研究、环境记录 |
+
+## 许可证
+
+当前源码与 Flywheel npm 包标记为 `UNLICENSED`，尚未授予开源许可证。英文文档和公开 npm 分发不改变这一状态；正式开源时需由维护者选择许可证，并同步源码声明与全部包的 metadata。第三方依赖遵循各自许可证。

package/bin/flywheel-codex-pro-worker.js

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

package/bin/flywheel.js

@@ -2,13 +2,14 @@
 // Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
 "use strict";
 
-const { loadNativePath, loadWorkerPath, runChild } = require("./runtime.js");
+const { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild } = require("./runtime.js");
 
 async function main() {
   const args = process.argv.slice(2);
   if (args[0] === "install" || args[0] === "setup") {
     return require("../npm/install.js").main(args.slice(1));
   }
+  assertSupportedNode();
 
   const env = { ...process.env };
   // An npm dependency's bin is not necessarily on a desktop application's
@@ -17,6 +18,9 @@ async function main() {
   if (env.FLYWHEEL_DSH_WORKER === undefined) {
     env.FLYWHEEL_DSH_WORKER = loadWorkerPath();
   }
+  if (env.FLYWHEEL_CODEX_PRO_WORKER === undefined) {
+    env.FLYWHEEL_CODEX_PRO_WORKER = loadCodexProWorkerPath();
+  }
   return runChild(loadNativePath(), args, { env });
 }
 

package/bin/runtime.js

@@ -47,6 +47,19 @@ function loadWorkerPath() {
     "the matching @ckanner/dsh-plugin-flywheel worker is missing; reinstall @ckanner/flywheel");
 }
 
+function loadCodexProWorkerPath() {
+  const name = "@ckanner/dsh-plugin-flywheel";
+  return packageEntry(name, "codex-pro-worker", ownPackage.dependencies?.[name],
+    "the matching @ckanner/dsh-plugin-flywheel Codex 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)) {
+    throw new Error("Node.js 22.18.0 or newer is required");
+  }
+}
+
 function signalExitCode(signal) {
   return constants.signals[signal] ? 128 + constants.signals[signal] : 1;
 }
@@ -84,4 +97,4 @@ function runChild(command, args, { env = process.env, cwd, label = "flywheel" }
   });
 }
 
-module.exports = { loadNativePath, loadWorkerPath, runChild };
+module.exports = { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild };

package/docs/configuration.md

@@ -1,5 +1,7 @@
 # 模型 profiles、阶段绑定与预检
 
+[English](en/configuration.md) · 简体中文
+
 Flywheel 在启动时加载一份完整配置，再把模型 profile 展开成每个阶段的实际绑定。模型选择是显式配置，不由另一个模型替你决定；修改配置后需要重新启动引擎。
 
 ## 1. 配置来源
@@ -20,14 +22,41 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
 
 | 字段 | 含义 | 示例 |
 |---|---|---|
-| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex` |
+| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`；`codex` 为显式旧 CLI 路径 |
 | `provider` | DSH SDK 已注册的 LLM adapter ID；仅 DSH 使用 | `deepseek-official`、`chatgpt` |
 | `channel` | 配置中的凭证／后备／计量渠道名称 | `deepseek-sdk`、`chatgpt-sdk`、`kimi-subscription` |
 | `profile` | 当前 Flywheel 配置内的一组模型字段引用 | `flash`、`gpt-review`、`kimi` |
 
 Flywheel 的 model profile 与 DSH 的 `sdk`／`desktop` profile 是两件事。前者复用模型定义，后者决定宿主实际加载的插件和授权配置。channel 别名本身不会切换 DSH 账号；给同一个 provider 起两个 channel 名称不等于拥有两份独立订阅或额度。
 
-DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex 和 Kimi 使用自己的 CLI 登录状态，不接受一个会被静默忽略的 provider。
+DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex Pro／旧 Codex CLI 和 Kimi 使用自己的登录状态，不接受一个会被静默忽略的 provider。
+
+### Codex Pro 默认与旧配置迁移
+
+0.28.0 的内嵌 hard 路由使用插件路径。下面是需放入自己完整配置的绑定片段，不是可替换全部配置的文件：
+
+```json
+{
+  "routes": {
+    "hard": {
+      "harness": "codex-pro",
+      "model": "gpt-6.1-sol",
+      "channel": "chatgpt-subscription",
+      "thinking": "high"
+    }
+  }
+}
+```
+
+完整 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`。
+
+已有配置不自动改写。要从旧路径迁移，在 `config inspect` 显示的有效文件中修改 inline harness 或其 profile，保留所选 model／thinking／channel，然后重启引擎。保留 `harness: "codex"` 则明确继续使用旧 CLI。`codex-pro` 必须提供 model 和 channel，不沿用旧 Codex driver 的隐式模型；`resident-session: true` 会在加载时拒绝。执行／评审每次创建 ephemeral 新会话，thinking 省略时为 high。
+
+`FLYWHEEL_CODEX_PRO_WORKER` 可显式指定 worker；通常由 npm 启动器解析同版本依赖。`FLYWHEEL_CODEX_BIN` 指定插件内部的 Codex 程序，默认 PATH 中的 `codex`；`CODEX_HOME` 可选择既有配置与登录目录。自定义环境需对启动引擎的进程可见，安装器不会复制凭证。
+
+插件在运行前确认模型、cwd、approval 和沙箱模式；Flywheel 在完整结果返回后检查实际策略及进程终态。workspace-write 允许工作区及 Codex 标准临时目录；额外的工作区外 writable roots、网络启用或不能确认的策略不能进入成功验收。**该完整策略检查发生在运行后，不能阻止自定义 Codex 配置已允许的访问。** 要求完整策略在任务前被拒绝的环境，应等待上游公开 pre-turn guard；doctor 会持续提示这一边界。
+
+指标的 `codex-pro-receipt` 保存完整 machine receipt，包含请求、实际配置、thread/turn、进程、清理、usage 和失败事实。effort 的 `accepted: true` 不等于服务器证明了实际推理强度，`effectiveEffort` 保留 null。仅 `usage.status: "complete"` 的本次增量进入已知预算；partial/unknown 原样留在回执并计入未知调用。插件不提供实际美元成本，原始 cost 保持 unknown；Flywheel 只有在用户显式配置 pricing 且 usage 完整时才能另行估算，估算不等于订阅账单。
 
 ## 3. 从完整示例开始
 
@@ -113,6 +142,8 @@ flywheel doctor --cwd /repo --task-dir /repo/docs/task --probe --json
 
 本地检查确认命令可用、版本响应可靠，以及声明的环境变量存在且非空，不显示变量值。`--probe` 才启动 DSH worker 验证 adapter 接受配置、cwd、完整沙箱、approval policy 和 SDK 正常关闭。相同 provider、channel、model、effort、cwd 和权限的探测去重；不同账号别名或读写权限不能相互代替。整体验证预算 40 秒，另留进程清理窗口。
 
+Codex Pro 本地检查额外实际导入公开 machine API，核对精确 0.8.0／协议 1、Node >=22.18.0 以及 Codex 命令版本；同一 worker 只查一次。`--probe` 不为此路径发送任务，实际模型、effort 与完整权限保持 unknown；它不会把成功导入插件当成账号、沙箱或推理能力已经验证。
+
 | 状态 | 解释 |
 |---|---|
 | `pass` | 本项已取得对应证据；只对该项有效 |

package/docs/en/configuration.md

@@ -0,0 +1,193 @@
+# Model profiles, stage bindings, and diagnostics
+
+[English README](../../README.en.md) · [中文](../configuration.md) · [Workflow](workflow.md)
+
+Flywheel loads one complete configuration, expands its model profiles, and resolves each stage's binding before starting. Model selection is explicit configuration. Restart the engine after changing it. This guide describes the 0.28.0 implementation; existing user configuration is not automatically migrated during installation.
+
+## Configuration precedence
+
+The discovery order is:
+
+1. Task directory: `flywheel.config.json`.
+2. Project Git root: `flywheel.config.json`.
+3. Global file: `~/.config/flywheel/flywheel.config.json`.
+4. Embedded defaults.
+
+Flywheel selects the **first complete file**. It does not merge fields, profiles, loops, routes, or channels across those locations. `FLYWHEEL_CONFIG` replaces the global file path only; it does not override an existing task or project file. `XDG_CONFIG_HOME` does not change the current default path.
+
+An unreadable higher-priority file, invalid JSON, or broken symlink is an error, not permission to use a different account's configuration. Inspect the selected source before editing:
+
+```sh
+flywheel config inspect --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --json
+```
+
+The result includes `source`, `scope`, resolved physical paths, and stage `bindings`. Without `--task-dir`, discovery starts at the selected project and lower levels. Inspection does not create global configuration or task state, read account tokens, or invoke a model.
+
+## Fields and identities
+
+| Field | Meaning | Example |
+|---|---|---|
+| `harness` | Process and tool-loop backend | `dsh`, `kimi`, `codex-pro`; `codex` is the explicit older CLI path |
+| `provider` | Registered DSH SDK LLM adapter ID; applies to DSH bindings | `deepseek-official`, `chatgpt` |
+| `channel` | A configuration label used for credentials, fallback, and accounting | `deepseek-sdk`, `chatgpt-sdk`, `kimi-subscription` |
+| `model` | Exact model identifier passed to the selected backend | `deepseek-flash`, `kimi-code/k3.1-pro`, `gpt-6.1-sol` |
+| `thinking` | Requested reasoning effort | `high` |
+| `profile` | Reusable model fields inside this Flywheel configuration | `flash`, `gpt-review`, `codex-pro` |
+
+A Flywheel model profile is different from a DSH `sdk` or `desktop` profile. The latter chooses the host's plugins and authorization configuration. A channel alias alone does not switch DSH accounts or create a separate subscription or quota pool.
+
+For DSH, the provider resolves from `binding.provider`, then `channels[channel].provider`, then the legacy channel name. Explicit binding and channel provider values must agree. Kimi and Codex use their own login state; a DSH provider cannot be attached to those harnesses and silently ignored.
+
+Only supported effort values should be used. The checked DSH Flash adapter accepts `off/low/high/max`; it has no `medium`. A configuration value names an intended binding, not evidence of account entitlement or measured model performance.
+
+## Start from a complete template
+
+Inspect either bundled example:
+
+```sh
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+The first uses inline bindings. The second is a complete configuration with reusable profiles. If you choose to create a project configuration, first confirm that no file needs preserving; then export one template from the target Git root. For example, Bash's noclobber option prevents replacing an existing regular file:
+
+```sh
+(set -C; flywheel template flywheel.profiles.example.json > flywheel.config.json)
+```
+
+Do not create a task file containing only a few profiles and expect it to inherit the rest from the project file. An illustrative **fragment**, to incorporate into a complete file, is:
+
+```json
+{
+  "profiles": {
+    "flash": {
+      "harness": "dsh",
+      "provider": "deepseek-official",
+      "channel": "deepseek-sdk",
+      "model": "deepseek-flash",
+      "thinking": "high"
+    }
+  },
+  "routes": {
+    "default": { "profile": "flash" }
+  },
+  "loops": {
+    "intake": { "profile": "flash", "thinking": "low" }
+  },
+  "channels": {
+    "deepseek-sdk": {
+      "harness": "dsh",
+      "provider": "deepseek-official",
+      "env-key": null
+    }
+  }
+}
+```
+
+`loops` binds Plan, Review, Judge, Intake, and Garden. `routes` selects the Execute backend for default/frontend/hard packets. `drivers` selects real or mock drivers; it is not a provider-name mapping. The full default routing table is in the [README](../../README.en.md#default-model-routes).
+
+### Profile override and validation rules
+
+| Input | Effect |
+|---|---|
+| Stage omits a profile field | Inherit that field from the referenced profile |
+| Stage explicitly supplies `model`, `thinking`, `channel`, etc. | Override only that stage |
+| `thinking: ""` | Use the harness's default effort instead of re-inheriting the profile |
+| `resident-session: false` | Explicitly disable the stage's resume request |
+| `judge-panel: null` | Disable the optional second opinion |
+| Missing/empty profile `harness`, `model`, or `channel` | Configuration error |
+| Unknown profile, field, stage name, or harness | Configuration error |
+| A profile references another profile | Unsupported; configuration error |
+| `_note` or `_note_*` | Permitted explanatory metadata, excluded from execution bindings |
+
+`resident-session` belongs on a stage, not in a profile. Currently only Kimi Plan can resume, and only when harness, model, channel, working directory, and thinking match. This restores session history, not a permanently running process. Execution and review calls start fresh sessions.
+
+Legal existing zero values, including `env-key: null`, `retry.jitter: 0`, and `worktree.enabled: false`, remain meaningful. When changing a harness or channel, also inspect any inherited provider. Use `provider: ""` when necessary to clear an explicit value before resolving the newly selected DSH channel.
+
+## Codex Pro and migration
+
+The 0.28.0 embedded hard route uses this binding. This is a **fragment**, not a complete replacement configuration:
+
+```json
+{
+  "routes": {
+    "hard": {
+      "harness": "codex-pro",
+      "model": "gpt-6.1-sol",
+      "channel": "chatgpt-subscription",
+      "thinking": "high"
+    }
+  }
+}
+```
+
+The complete profile template uses `profiles.codex-pro` and references it from `routes.hard`. The npm dependency is exactly `dsh-subagent-codex-pro@0.8.0`. The worker imports its public `dsh-subagent-codex-pro/machine` entry and calls `runMachine` using protocol 1. The plugin itself runs Codex app-server and uses the existing Codex login.
+
+The external tool name `subagent_codex_pro` is not a DSH provider. This route does not create a parent DSH model to make a second delegation. Missing dependencies or invalid receipts fail; they do not trigger an implicit fallback to the older CLI driver.
+
+To migrate an existing configuration, use `config inspect` to locate the effective file. Change the hard route's inline harness or referenced profile from `codex` to `codex-pro`, retain the intended model/channel/thinking, inspect the result, and restart. Keeping `harness: "codex"` explicitly retains the older `codex exec` behavior.
+
+`codex-pro` requires nonempty model and channel values. It does not inherit the old Codex driver's implicit model. Omitted thinking defaults to `high`; `resident-session: true` is rejected. Each execute/review call uses a new ephemeral session.
+
+### Worker environment
+
+| Variable | Purpose |
+|---|---|
+| `FLYWHEEL_DSH_WORKER` | Optional DSH worker override; the npm launcher normally resolves the matching dependency |
+| `FLYWHEEL_DSH_BIN` | DSH command, otherwise `dsh` on PATH |
+| `FLYWHEEL_DSH_PROFILE` | SDK profile, default `sdk`; it must not be `desktop` |
+| `DSH_HOME` | Optional DSH configuration root, interpreted by DSH |
+| `FLYWHEEL_KIMI_BIN` | Kimi CLI override, otherwise `kimi` on PATH |
+| `FLYWHEEL_CODEX_PRO_WORKER` | Optional Codex Pro worker override; normally resolved by npm |
+| `FLYWHEEL_CODEX_BIN` | Codex executable used by the plugin, otherwise `codex` on PATH |
+| `CODEX_HOME` | Existing Codex configuration/login directory, interpreted by Codex |
+
+These settings must be visible to the process starting the engine. The installer does not copy authentication data. The managed GUI launcher records executable paths and the installation-time tool PATH; a terminal export alone does not change an already running desktop process.
+
+### Permissions, receipts, and cleanup
+
+The plugin checks the requested model, working directory, approval policy, and sandbox mode before a turn. Flywheel examines the complete returned policy afterward. Workspace-write permits the workspace and standard Codex temporary directories; extra external write roots, enabled network, or unconfirmed policy make the result ineligible for successful delivery.
+
+**The complete policy check happens after execution. It cannot prevent access already allowed by custom Codex configuration.** An environment requiring a full policy rejection before any turn needs an upstream public pre-turn guard. Kimi's current CLI integration also provides no OS-level sandbox guarantee; a configured permission requirement should not be read as proof of its enforcement.
+
+The `codex-pro-receipt` metric preserves the complete machine receipt, including requested and actual configuration, thread/turn IDs, process outcomes, cleanup, usage, and failures. An accepted effort request is not proof of effective server reasoning effort; `effectiveEffort` remains null.
+
+An abnormal worker exit does not prove the plugin's separately managed processes stopped. If cleanup cannot be confirmed after startup, the engine records the evidence, escalates, and ends the run instead of automatically retrying or falling back. Before resuming, confirm the owned app-server/guardian processes have terminated. See [recovery](workflow.md#7-stop-and-recover-without-losing-evidence).
+
+## Fallback and budgets
+
+Default profiles do not enable automatic paid fallback across channels. An explicitly configured `channels[channel].fallback` is a bounded chain and is used only when error classification and retry policy permit it. A fallback resolves provider and model for the newly selected channel; an omitted harness inherits the current harness.
+
+Metrics retain harness, provider, channel, and model separately. Provider remains null if the driver cannot confirm it. Missing usage and dollar cost remain unknown, including subscription calls. Numeric aggregates are lower bounds of known usage, not a complete bill.
+
+For Codex Pro, only complete usage for the current run enters known token accounting; partial/unknown usage remains in the receipt and counts as unknown calls. The plugin does not provide actual dollar billing. Explicit user pricing plus complete usage can produce an estimate, which remains distinct from the subscription bill.
+
+The default token budget is soft, with a daily limit of 2,000,000 tokens. A soft budget reports uncertainty. A hard budget stops when unknown usage makes compliance unverifiable. Disabling enforcement does not turn off accounting or convert unknown values to zero.
+
+Acceptance commands use a restricted environment. If the project requires additional tool variables such as `GOCACHE` or `GOPATH`, add their names to `verify.env-allowlist` and ensure they exist in the engine's environment. Do not put secret values into task contracts or committed configuration.
+
+## Diagnose without inference
+
+```sh
+flywheel doctor --cwd /absolute/path/to/repo --json
+flywheel doctor --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --json
+flywheel doctor --cwd /absolute/path/to/repo --task-dir /absolute/path/to/repo/docs/my-feature --probe --json
+```
+
+Without a task, doctor checks all configured bindings. With a task, it validates the Spec/packets and requires Plan, Review, Judge, enabled second opinions, and routes used by the packets; other bindings can be skipped. With no packets yet, it checks the default execution route and reports that preparation must finish. A real run still needs at least one reviewed legal packet.
+
+Local checks cover commands, versions, directories, configuration, and declared nonempty environment variables, without showing their values. `--probe` additionally initializes DSH SDK sessions, verifies accepted configuration, working directory, permissions, and normal shutdown. Identical probes are deduplicated only when their relevant identity and permissions match. The probe budget is 40 seconds plus bounded process cleanup time.
+
+Codex Pro checks actually import the public API and verify exact version 0.8.0/protocol 1, Node compatibility, and the Codex executable. `--probe` does not send a task through this path: account/model/effort and full runtime policy remain unverified. A successful import is not a successful model call.
+
+| Status | Meaning |
+|---|---|
+| `pass` | Evidence supports this individual check only |
+| `fail` | A blocker; overall `ok:false` and exit code 1 |
+| `warn` | A limitation or preparation state requiring interpretation |
+| `unknown` | Not verified, such as entitlement, quota, or real inference |
+| `skipped` | Not required, mock mode, duplicate probe, or an unmet prerequisite |
+
+No probe sends an inference prompt, runs L1/L2/L3, creates a worktree, or writes Flywheel task state. SDK initialization may contact a provider's catalog and write its own cache/session files; read-only here is scoped to Flywheel state and configuration. Recheck in the desktop panel because its PATH/profile/environment may differ from the terminal.
+
+Repository references: [inline defaults](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json), [complete profiles](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.profiles.example.json), [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md), and [worker protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md).