@ckanner/flywheel 0.22.1 → 0.28.0

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-dsh-worker.js

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

package/bin/flywheel.js

@@ -1,33 +1,30 @@
 #!/usr/bin/env node
 // Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
-//
-// npm bin shim（v0.22 平台包模式，esbuild 先例）：按 platform/arch 解析
-// optionalDependencies 里的平台二进制包并透传执行——无 postinstall、无网络
-// 下载、无 checksum 步骤（npm 自身的包完整性承担校验）。安装即得二进制，
-// 维护者与分用户用法完全一致。
 "use strict";
 
-const { spawnSync } = require("child_process");
+const { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild } = require("./runtime.js");
 
-const PLATFORM_MAP = { darwin: "darwin", linux: "linux" };
-const ARCH_MAP = { arm64: "arm64", x64: "amd64" };
+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 platform = PLATFORM_MAP[process.platform];
-const arch = ARCH_MAP[process.arch];
-if (!platform || !arch) {
-  console.error(`flywheel: unsupported platform ${process.platform}/${process.arch}（支持 darwin/linux × amd64/arm64）`);
-  process.exit(1);
+  const env = { ...process.env };
+  // An npm dependency's bin is not necessarily on a desktop application's
+  // PATH. Resolve this installation's worker without changing an explicit
+  // user override or relying on the shell's global npm prefix.
+  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 });
 }
 
-const pkg = `@ckanner/flywheel-${platform}-${arch}`;
-let bin;
-try {
-  bin = require.resolve(`${pkg}/flywheel`);
-} catch (_) {
-  console.error(`flywheel: 平台包 ${pkg} 未安装。npm 会按 os/cpu 自动选取 optionalDependencies——`);
-  console.error(`  若被 --no-optional 跳过，请去掉该标志重装：npm i -g @ckanner/flywheel`);
-  process.exit(1);
-}
-
-const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
-process.exit(result.status === null ? 1 : result.status);
+main().then(code => { process.exitCode = code; }).catch(error => {
+  console.error(`flywheel: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/runtime.js

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { constants } = require("node:os");
+
+const platforms = { darwin: "darwin", linux: "linux" };
+const architectures = { arm64: "arm64", x64: "amd64" };
+const forwardedSignals = ["SIGTERM", "SIGINT", "SIGHUP"];
+const ownPackage = require("../package.json");
+
+function packageEntry(name, entry, expectedVersion, missingMessage) {
+  let installed;
+  let entryPath;
+  try {
+    installed = require(`${name}/package.json`);
+    entryPath = require.resolve(`${name}/${entry}`);
+  } catch {
+    throw new Error(missingMessage);
+  }
+  // npm may legitimately hoist dependencies. Check the resolved package's
+  // identity, rather than assuming a particular machine's node_modules path.
+  // A partial installation must not pick up an incompatible parent package.
+  if (installed.name !== name) {
+    throw new Error(`package identity mismatch for ${name}: found ${installed.name}; reinstall @ckanner/flywheel`);
+  }
+  if (typeof expectedVersion !== "string" || installed.version !== expectedVersion) {
+    throw new Error(`version mismatch for ${name}: expected ${expectedVersion}, found ${installed.version}; reinstall @ckanner/flywheel`);
+  }
+  return entryPath;
+}
+
+function loadNativePath() {
+  const platform = platforms[process.platform];
+  const arch = architectures[process.arch];
+  if (!platform || !arch) {
+    throw new Error(`unsupported platform ${process.platform}/${process.arch} (supported: darwin/linux × amd64/arm64)`);
+  }
+  const name = `@ckanner/flywheel-${platform}-${arch}`;
+  return packageEntry(name, "flywheel", ownPackage.optionalDependencies?.[name],
+    `platform package ${name} is missing; reinstall @ckanner/flywheel with optional dependencies enabled`);
+}
+
+function loadWorkerPath() {
+  const name = "@ckanner/dsh-plugin-flywheel";
+  return packageEntry(name, "worker", ownPackage.dependencies?.[name],
+    "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;
+}
+
+/** Preserve the native owner's cancellation and cleanup lifetime through npm. */
+function runChild(command, args, { env = process.env, cwd, label = "flywheel" } = {}) {
+  return new Promise(resolve => {
+    const child = spawn(command, args, { env, cwd, stdio: "inherit", shell: false, detached: false });
+    let cancelledBy;
+    let spawnFailed = false;
+    const listeners = new Map();
+    for (const signal of forwardedSignals) {
+      const listener = () => {
+        cancelledBy ??= signal;
+        // Go owns its worker groups. Keep this wrapper alive until Go confirms
+        // its own exit; killing only this PID would orphan that cleanup stack.
+        child.kill(signal);
+      };
+      listeners.set(signal, listener);
+      process.on(signal, listener);
+    }
+    child.once("error", error => {
+      spawnFailed = true;
+      console.error(`${label}: could not start ${command}: ${error.message}`);
+    });
+    child.once("close", (code, signal) => {
+      for (const [name, listener] of listeners) process.removeListener(name, listener);
+      if (spawnFailed) return resolve(1);
+      if (signal) return resolve(signalExitCode(signal));
+      // A child trapping termination as exit 0 still cannot turn cancellation
+      // into success. Preserve the native program's nonzero failure otherwise.
+      if (cancelledBy && code === 0) return resolve(signalExitCode(cancelledBy));
+      resolve(code ?? 1);
+    });
+  });
+}
+
+module.exports = { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild };

package/docs/configuration.md

@@ -0,0 +1,157 @@
+# 模型 profiles、阶段绑定与预检
+
+[English](en/configuration.md) · 简体中文
+
+Flywheel 在启动时加载一份完整配置，再把模型 profile 展开成每个阶段的实际绑定。模型选择是显式配置，不由另一个模型替你决定；修改配置后需要重新启动引擎。
+
+## 1. 配置来源
+
+发现顺序为任务目录、项目 Git 根目录、全局文件、内嵌默认表，选择第一个存在的完整文件。全局默认路径为 `~/.config/flywheel/flywheel.config.json`；`FLYWHEEL_CONFIG` 可覆盖全局文件路径，但不能越过已经存在的任务／项目配置。当前不通过 `XDG_CONFIG_HOME` 改变该默认路径。
+
+高优先级文件不可读、JSON 无效或符号链接失效时直接报错，不悄悄使用其他账号或模型配置。不同文件的 profiles、loops、routes、channels 不逐字段合并。
+
+```sh
+flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
+```
+
+输出 `source`、`scope`、物理 `cwd/taskDir` 和按阶段排列的 `bindings`。`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，不把其他阶段忽略的请求显示为已生效。
+
+## 2. 四个概念各负责什么
+
+| 字段 | 含义 | 示例 |
+|---|---|---|
+| `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 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. 从完整示例开始
+
+查看默认内联表或可复用 profiles 表：
+
+```sh
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+确认目标没有需要保留的配置后，选择其中一份导出到项目根。已有配置先备份并审阅差异，避免 shell 重定向覆盖它。下面只是解释结构的片段；完整可用起点在第二份模板中：
+
+```json
+{
+  "profiles": {
+    "flash": {
+      "harness": "dsh",
+      "provider": "deepseek-official",
+      "channel": "deepseek-sdk",
+      "model": "deepseek-flash",
+      "thinking": "high"
+    },
+    "gpt": {
+      "harness": "dsh",
+      "provider": "chatgpt",
+      "channel": "chatgpt-sdk",
+      "model": "gpt-6.1-sol",
+      "thinking": "high"
+    }
+  },
+  "loops": {
+    "review": { "profile": "gpt" },
+    "judge": { "profile": "gpt", "model": "gpt-6-astra" },
+    "intake": { "profile": "flash", "thinking": "low" }
+  },
+  "routes": {
+    "default": { "profile": "flash" }
+  },
+  "channels": {
+    "deepseek-sdk": { "harness": "dsh", "provider": "deepseek-official", "env-key": null },
+    "chatgpt-sdk": { "harness": "dsh", "provider": "chatgpt", "env-key": null }
+  }
+}
+```
+
+这些模型名沿用本仓库的初始绑定，能否使用仍由实际账号和 adapter 决定。读取配置、看到模型名称、adapter 接受参数都不等于账号已获授权。DeepSeek 默认仅 Flash；profiles 不引入自动跨渠道付费回退。
+
+### 覆盖与错误规则
+
+| 情况 | 行为 |
+|---|---|
+| 阶段省略某字段 | 继承所引用 profile 的字段 |
+| 阶段显式写 `model`／`channel`／`thinking` 等 | 只覆盖该阶段，不修改共享 profile 或其他阶段 |
+| `thinking: ""` | 使用对应 harness 的现有默认 effort，不重新继承 profile |
+| `resident-session: false` | 明确关闭该阶段的恢复请求；不会丢失为缺省值 |
+| `judge-panel: null` | 关闭第二意见，保持默认行为 |
+| profile 定义缺 `harness/model/channel`，或这些字段为空／null／纯空白 | 加载失败 |
+| profile 不存在、未知字段、错拼阶段名、不支持的 harness | 加载失败，不静默回落 |
+| profile 再引用另一个 profile | 不支持继承链；加载失败 |
+| `_note`、`_note_*` | 允许配置对象中的说明文字，不进入执行绑定 |
+
+`resident-session` 是阶段策略，不能放进 profile。当前只有 Kimi 的 Plan 可恢复历史，且必须匹配实际 harness/model/channel/cwd/thinking；profile 名改了而实际值没变，不影响身份。其他执行、评审和 SDK 调用仍是新会话。
+
+旧内联绑定保留原有缺省行为，不强制迁移。`env-key: null`、`retry.jitter: 0`、`worktree.enabled: false` 等已有合法零值继续支持。显式切换 harness 或 channel 时，要一起核对继承的 provider；必要时用 `provider: ""` 清除显式值，再按新 channel 解析，不能保留另一个 adapter 的 ID。
+
+## 4. 后备渠道与记录
+
+`channels[channel].fallback` 仍是人工配置的有界后备链，只有既有错误分类／重试策略允许时才使用。切换后依据新渠道重新选择 provider 和模型；不会继续沿用原渠道的 provider。后备渠道省略 harness 时继承当前 harness，不回到链起点的后端。
+
+指标分别保存 `harness`、`provider`、`channel`、`model`。provider 来自 driver 可确认的结果，未知时为 null；channel 继续描述配置渠道。usage 和美元成本未报告时保持 unknown，订阅不会被当成已知零成本。profiles 不改变计费规则，也不会绕过 hard budget。
+
+## 5. 预检范围和结果
+
+```sh
+flywheel doctor --cwd /repo --json
+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 跳过真实工具检查，不冒充模型已验证。
+
+预检可提前运行，正式 `run`／`control start` 仍需至少一个已准备并审阅的合法 packet；没有 packet 的 warn 不表示引擎已经能从空任务开始。绑定中的 permissionMode 表示阶段要求，实际实施能力还取决于 harness，尤其 Kimi CLI 不能据此宣称拥有 OS 沙箱。
+
+本地检查确认命令可用、版本响应可靠，以及声明的环境变量存在且非空，不显示变量值。`--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` | 本项已取得对应证据；只对该项有效 |
+| `fail` | 存在阻断项，整体 `ok:false` 且退出码 1 |
+| `warn` | 限制或规划前状态，需要结合实际任务理解 |
+| `unknown` | 未验证，例如账号授权、额度与真实模型服务能力 |
+| `skipped` | 非必需绑定、mock、重复探测或前置检查失败等 |
+
+任何 probe 都不发送 `session/prompt`、不运行 L1/L2/L3、不写 Flywheel 状态或创建工作树；SDK 初始化可能访问 provider 目录并产生自己的会话／缓存文件。只读指 Flywheel 配置与任务状态，不表示整个宿主文件系统绝对无写入。
+
+桌面面板、`/flywheel` 和 `flywheel_control` 共用 `control config|doctor`，可省略 taskDir；只有 doctor 支持 `probe:true`。诊断阻断与传输失败分开显示。桌面使用的 PATH／profile／环境可能与终端不同，安装后应在面板里再检查一次。

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).