@ckanner/flywheel 0.28.1 → 0.28.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.28.2
+
+- 修复 macOS 迁移故障测试的平台假设：使用路径解析 I/O 注入缝稳定验证无法解析相对全局路径时的无写入行为；生产路径解析仍使用 `filepath.Abs`，不跳过测试或放宽 100% 覆盖率门禁。
+
+- 新增显式 `config migrate --preset subscriptions`：预览并备份更新实际生效的旧模型配置，保留非模型设置，清理旧 Z.AI 后备路径，采用 ChatGPT／Kimi Code K3.1 Pro／DeepSeek Flash 与约定的 thinking；安装报告明确升级会保留旧配置。Kimi 缺省模型同步为 K3.1 Pro。
+- 新模板与显式迁移使用 `permissions.mode: full-access`，通过 DSH／Codex Pro 公开接口落实所有阶段完全权限和无需逐步确认；旧文件缺省保留 role-based。编排、预检、恢复身份与实际权限回执一致，保留冻结验收、候选身份和进程清理门禁。
+- 将 UI 路径和排障文案改为“任务资料目录”“项目目录（可选）”“检查安装与配置”“检查 DSH 接入”，说明任务由对话助手准备、项目目录可沿用会话、检查不发送模型消息，配置表展示可理解的权限名称。
+
 ## 0.28.1
 
 - 将 DSH 桌面控制界面迁入顶部原生 `conversation.view` 的 Flywheel 标签，移除遮挡对话和输入框的底部大浮层。按外部 plain-JS 插件规范只加载 React，控件、样式和快照由插件持有，通过公开 StoreHandle 与槽位接入宿主会话生命周期；使用宿主 locale 与语义颜色。配置按可换行卡片展示，桌面对话、轨迹、输入框和原生侧栏继续由 DSH 管理。

package/README.en.md

@@ -4,7 +4,7 @@ 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.1 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.
+This documentation describes the **0.28.2 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
 
@@ -38,8 +38,8 @@ These bindings are editable starting points, not a model ranking or a performanc
 | 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 |
+| Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high` |
+| Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high` |
 | Intake, optional | DSH SDK | `deepseek-official` | `deepseek-flash` | `low` |
 | Garden, optional | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
 
@@ -91,7 +91,7 @@ L1 validates a packet; L2/L3 validate integration and user paths at milestone sc
 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.
+- **Permissions are explicit.** New templates and the subscription migration select `permissions.mode:full-access` for every stage, using DSH/Codex full access with approval never and native Kimi print auto. Existing configurations without this field retain role-based permissions. Kimi does not provide an OS confinement guarantee; task and acceptance identity checks remain enforced.
 - **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.

package/README.md

@@ -4,7 +4,7 @@
 
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-当前 **v0.28.1 实施版**以 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)。
+当前 **v0.28.2 实施版**以 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.28.0 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
 
@@ -93,14 +93,14 @@ flywheel doctor --cwd "$PWD" --probe --json
 | 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`，只读 |
+| 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` |
 | Garden | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
 
 这些是可编辑的初始绑定，并非模型排名或性能承诺。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 与 never 审批策略。Codex Pro 在运行前核对模型、目录和沙箱模式，Flywheel 在结果返回后检查完整策略；工作区写入允许 Codex 标准临时目录，额外工作区外 roots 或启用网络的策略不能通过交付资格检查。这是事后校验，不能阻止自定义 Codex 配置已允许的访问；要求运行前完整策略阻止的环境需等待上游公开 guard。具体账号的可用模型、额度和使用授权需要由所选服务确认。
+Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。新模板及显式 subscriptions 迁移使用 `permissions.mode:full-access`，DSH/Codex 全阶段 danger-full-access＋never，Kimi print 为 auto；已有文件未声明时保持 role-based 的 workspace-write／read-only。Codex Pro 在运行前核对模型、目录和沙箱模式，Flywheel 在结果返回后检查完整策略；在受限模式，工作区写入允许 Codex 标准临时目录，额外工作区外 roots 或启用网络的策略不能通过交付资格检查；明确 full-access 则核对完全权限回执，不声称 OS 隔离。这是事后校验，不能阻止自定义 Codex 配置已允许的访问；要求运行前完整策略阻止的环境需等待上游公开 guard。具体账号的可用模型、额度和使用授权需要由所选服务确认。
 
 usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免费。默认 soft token budget 会报告未知量；hard budget 无法证明未知用量未超额时停止。汇总数字是已知量下限。
 

package/docs/configuration.md

@@ -18,6 +18,38 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
 
 展示值包含 Flywheel 已确定的 driver 默认：DSH／Codex／Kimi 的空 thinking 为 high，pi／omp／zcode 为 max；Kimi／Codex／Zcode 的空 model 使用各自 driver 常量。pi／omp 未指定模型时仍留空，表示 Flywheel 不能从配置确定它。`residentSession` 只有 Plan＋Kimi＋明确启用时为 true，不把其他阶段忽略的请求显示为已生效。
 
+### 将旧配置切换到已有的三种资源
+
+本轮源码新增的 `subscriptions` 预设只使用 ChatGPT 订阅、Kimi Code 订阅和 DeepSeek 付费 API（仅 Flash）。普通安装／升级仍保留已有配置；所以旧文件里的 Z.AI／GLM、Kimi K3 和旧 thinking 不会因升级 UI 自动消失。此迁移命令和 `permissions.mode` 需要包含本轮修复的 CLI 与同版本 worker，已发布的 0.28.1 不包含它们。
+
+在实际项目目录运行以下命令；若任务目录有单独配置，再加 `--task-dir /repo/docs/my-task`：
+
+```sh
+flywheel config migrate --preset subscriptions --cwd /repo --json
+flywheel config migrate --preset subscriptions --cwd /repo --apply --json
+flywheel config inspect --cwd /repo --json
+```
+
+第一条只预览。`--apply` 明确应用到当前实际命中的任务／项目／全局文件，并先备份原始字节。没有文件时写全局配置，不创建意外的项目覆盖。可以用 `--expect-sha256` 绑定之前预览的摘要；文件已经变化时拒绝陈旧应用。预算、worktree、验证、重试、价格和用户说明等非模型设置保留，Plan 明确设置的 `resident-session:false` 也保留。配置损坏、额外自定义路由／阶段或不支持的文件身份会明确阻断，不猜测替代。
+
+迁移写入完整的阶段模型、thinking 和渠道，去掉被替换绑定的旧 profile 引用，清除所选渠道的旧 fallback／模型映射，使旧付费渠道不再自动可达；未引用的自定义 profiles／channels 仍保留。默认关闭第二意见，并明确报告旧多模态路由被停用。默认分配仍是 Kimi K3.1 Pro high 负责 Plan／frontend／Garden，DeepSeek Flash high 负责普通执行、low 负责 Intake，GPT-6.1 Sol high 负责 hard／Review，GPT-6 Astra high 负责 Judge。hard 通过 Codex Pro 插件，Review／Judge 通过 DSH ChatGPT provider。Kimi 缺省模型同时更新为 `kimi-code/k3.1-pro`；显式写入的自选模型不会被仅修改 driver 缺省值覆盖。
+
+迁移不登录账号，也不发模型请求。当前运行中的任务继续使用启动时已加载的配置；新配置在下一次启动生效。检查迁移后的 source／scope／bindings，再按需要停止和恢复任务。
+
+迁移期间不要同时编辑目标文件。迁移锁协调 Flywheel 迁移进程；写入前再次检查文件，再原子替换完整文件，不提供对任意外部编辑器的原子 CAS。报告以 `configurationStatus` 区分拟议配置 `proposed`、重读确认的实际配置 `effective` 和写入后尚未确认的 `unconfirmed`；备份／写入失败不能把新模型显示成已生效。
+
+### 完全权限与无需逐步确认
+
+```json
+{"permissions":{"mode":"full-access"}}
+```
+
+新安装模板和显式 `subscriptions` 迁移都写入这一设置。全部阶段使用完全权限：DSH／Codex 请求 `danger-full-access` 与 `approval=never`，Codex Pro 通过其公开 machine API 映射，Kimi print 沿用原生 auto。它表示这些 worker 可以访问当前操作系统用户本来能够访问的文件和命令，并不从 DSH 对话框的权限下拉菜单继承。
+
+旧文件没有 `permissions` 时保持 `role-based`：Plan／Execute 为项目内写入，Review／Judge 为只读。两种策略都不等待交互审批；只读／项目限制下的 `never` 可能直接拒绝动作，不能把它等同于完全权限。`permissions.mode` 的拼写、类型和枚举都会在启动前校验。
+
+完全权限不会关闭 Flywheel 的任务边界、冻结验收、验证和候选身份检查。评审职责仍是评价已有候选，修改候选或验收条件不能取得有效通过。需要受限权限时显式使用 `role-based`；工作区隔离本身不是 OS 沙箱。
+
 ## 2. 四个概念各负责什么
 
 | 字段 | 含义 | 示例 |
@@ -54,7 +86,7 @@ DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider`
 
 `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 会持续提示这一边界。
+插件在运行前确认模型、cwd、approval 和沙箱模式；Flywheel 在完整结果返回后检查实际策略及进程终态。在 role-based 的 workspace-write 模式，允许工作区及 Codex 标准临时目录；额外的工作区外 writable roots、网络启用或不能确认的策略不能进入成功验收。显式 full-access 则核对 `danger-full-access`／`dangerFullAccess` 完全权限回执，不将其误报为受限沙箱。**该完整策略检查发生在运行后，不能阻止自定义 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 完整时才能另行估算，估算不等于订阅账单。
 
@@ -118,7 +150,7 @@ flywheel template flywheel.profiles.example.json
 | profile 再引用另一个 profile | 不支持继承链；加载失败 |
 | `_note`、`_note_*` | 允许配置对象中的说明文字，不进入执行绑定 |
 
-`resident-session` 是阶段策略，不能放进 profile。当前只有 Kimi 的 Plan 可恢复历史，且必须匹配实际 harness/model/channel/cwd/thinking；profile 名改了而实际值没变，不影响身份。其他执行、评审和 SDK 调用仍是新会话。
+`resident-session` 是阶段策略，不能放进 profile。当前只有 Kimi 的 Plan 可恢复历史，且必须匹配实际 harness/model/channel/cwd/thinking/permissionMode；profile 名改了而实际值没变，不影响身份。其他执行、评审和 SDK 调用仍是新会话。
 
 旧内联绑定保留原有缺省行为，不强制迁移。`env-key: null`、`retry.jitter: 0`、`worktree.enabled: false` 等已有合法零值继续支持。显式切换 harness 或 channel 时，要一起核对继承的 provider；必要时用 `provider: ""` 清除显式值，再按新 channel 解析，不能保留另一个 adapter 的 ID。
 

package/docs/en/configuration.md

@@ -2,7 +2,7 @@
 
 [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.
+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 follows the current source; existing user configuration is not automatically migrated during installation. The migration and permission-policy additions below are marked separately from the published 0.28.1 release.
 
 ## Configuration precedence
 
@@ -23,6 +23,38 @@ flywheel config inspect --cwd /absolute/path/to/repo --task-dir /absolute/path/t
 
 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.
 
+## Apply the subscription preset to existing configuration
+
+The new source-level `subscriptions` preset uses only ChatGPT subscriptions, Kimi Code subscriptions, and paid DeepSeek API access with Flash. Normal installation and upgrades preserve an existing configuration, so an old Z.AI/GLM route or Kimi K3 binding remains effective until explicitly migrated. This command and `permissions.mode` require a CLI and matching workers that include this change; published 0.28.1 does not include them.
+
+From the actual project, preview and apply the selected configuration. Add `--task-dir /repo/docs/my-task` when the task has its own configuration:
+
+```sh
+flywheel config migrate --preset subscriptions --cwd /repo --json
+flywheel config migrate --preset subscriptions --cwd /repo --apply --json
+flywheel config inspect --cwd /repo --json
+```
+
+The first command only previews. `--apply` backs up the original bytes and updates the effective task/project/global file; with no file, it creates global configuration. Optional `--expect-sha256` binds application to a preview. Changed source files, invalid input, unsupported file identities, and extra custom routes/stages are rejected. Budgets, verification, worktrees, retries, pricing, notes, and an explicit Plan `resident-session:false` are preserved.
+
+The preset replaces the model bindings, removes their old profile references, and clears fallback/model mappings on the selected channels so that the old paid routes are no longer automatically reachable. Unreferenced custom profiles and channels remain intact. It disables the optional second opinion and explicitly reports removal of the old unverified multimodal route. Kimi K3.1 Pro/high handles Plan, frontend execution, and Garden; DeepSeek Flash/high handles ordinary execution and Flash/low handles Intake; GPT-6.1 Sol/high handles hard execution and Review; GPT-6 Astra/high handles Judge. Hard execution uses Codex Pro; Review/Judge use the DSH ChatGPT provider. Kimi's omitted-model default is also `kimi-code/k3.1-pro`, without overriding an explicitly selected model.
+
+Do not edit the target file while migrating. The lock coordinates Flywheel migration processes; the source is checked again before a complete file is atomically replaced. This is not an atomic compare-and-set against arbitrary external editors. Reports distinguish proposed configuration (`configurationStatus: proposed`), re-read effective configuration (`effective`), and an unconfirmed post-write result (`unconfirmed`). A failed backup or write must not present the proposed models as already effective.
+
+Migration does not sign in or invoke models. Running tasks retain their startup configuration; the next engine start uses the migrated file. Review the resulting source, scope, and bindings before stopping/resuming an existing task as needed.
+
+## Full access without per-action approval
+
+```json
+{"permissions":{"mode":"full-access"}}
+```
+
+New installation templates and the explicit subscription migration select this mode for every stage. DSH/Codex request `danger-full-access` and `approval=never`; Codex Pro maps through its public machine API; Kimi print retains native auto behavior. This grants worker access within the current operating-system user's permissions. It is independent of the desktop conversation's permission dropdown.
+
+Existing files without this setting retain `role-based`: Plan/Execute request workspace-write, and Review/Judge request read-only. Neither policy waits for interactive approval. In restricted modes, `never` can reject an action; it does not itself grant full access. Invalid policy names and types fail before execution.
+
+Full access preserves task boundaries, frozen acceptance, verification, and candidate identity checks. A reviewer still cannot change the candidate or acceptance criteria and obtain a valid verdict. Select `role-based` explicitly when confinement is intended; a worktree is not an OS sandbox.
+
 ## Fields and identities
 
 | Field | Meaning | Example |
@@ -100,7 +132,7 @@ Do not create a task file containing only a few profiles and expect it to inheri
 | 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.
+`resident-session` belongs on a stage, not in a profile. Currently only Kimi Plan can resume, and only when harness, model, channel, working directory, thinking, and permission mode 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.
 
@@ -146,7 +178,7 @@ These settings must be visible to the process starting the engine. The installer
 
 ### 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 plugin checks the requested model, working directory, approval policy, and sandbox mode before a turn. Flywheel examines the complete returned policy afterward. In role-based mode, 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. Explicit full access verifies the matching `danger-full-access` sandbox and `dangerFullAccess` policy without claiming confinement.
 
 **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.
 

package/docs/en/getting-started.md

@@ -2,12 +2,14 @@
 
 [English README](../../README.en.md) · [中文](../getting-started.md) · [Workflow](workflow.md) · [Configuration](configuration.md)
 
-This guide covers **Flywheel 0.28.1**: npm installation, the DSH desktop and workers, configuration, preflight, a small task, and recovery. The checked desktop interface baseline is **DSH Mac 0.2.1-rc.5**. Real desktop UI, macOS permissions, authentication, and model inference still need testing on the intended machine.
+This guide covers **Flywheel 0.28.2**: npm installation, the DSH desktop and workers, configuration, preflight, a small task, and recovery. The checked desktop interface baseline is **DSH Mac 0.2.1-rc.5**. Real desktop UI, macOS permissions, authentication, and model inference still need testing on the intended machine.
 
 Before installing, check `npm view @ckanner/flywheel version`. Continue with these instructions once the registry has the version you intend to use. A merged source change or GitHub Release does not establish npm publication, and an older installed release may not include these interfaces.
 
 The top-level **Flywheel conversation view** below is available from `0.28.1`. Version `0.28.0` uses the composer popup; upgrade the CLI and desktop plugin to the same new version. Merging source or reloading the old version does not change that layout. CLI and task-directory interfaces remain the same.
 
+Subscription preset migration and `permissions.mode` are available from **0.28.2**. Upgrades preserve existing configuration; preview `flywheel config migrate --preset subscriptions`, review the model bindings and full-access policy, then explicitly apply it with `--apply` and a backup.
+
 ## 1. Prepare the environment
 
 | Requirement | Why it is needed |
@@ -99,6 +101,8 @@ After moving Node or the npm prefix, or installing previously missing tools, run
 
 ## 4. Select configuration and skills
 
+If the view still shows Z.AI/GLM or Kimi K3, inspect its configuration source: upgrades preserve that file. A version containing this change can back up and migrate it with `flywheel config migrate --preset subscriptions --cwd /repo --apply --json`; omit `--apply` to preview, and add `--task-dir` for task overrides. This selects ChatGPT/Kimi Code/DeepSeek Flash, the agreed efforts, and full access for every stage. See [migration and permissions](configuration.md#apply-the-subscription-preset-to-existing-configuration). Published 0.28.1 does not contain this command.
+
 Configuration precedence is task directory, project root, global file, then embedded defaults. The first complete file wins; files do not merge. Existing configuration is preserved during upgrades. Inspect the actual source:
 
 ```sh

package/docs/en/workflow.md

@@ -2,7 +2,7 @@
 
 [English README](../../README.en.md) · [中文](../workflow.md) · [Getting started](getting-started.md)
 
-This guide describes the **0.28.0 implementation** and a recommended operating workflow. It does not assert that a particular npm version has been published. Check the registry when installing. The engine's local delivery and the host's GitHub operations are separate responsibilities.
+This guide describes the **current source implementation** and a recommended operating workflow. It does not assert that a particular npm version has been published. Check the registry when installing. The engine's local delivery and the host's GitHub operations are separate responsibilities.
 
 ## 1. Choose a model for preparation
 
@@ -109,9 +109,11 @@ Preflight does not infer with a model or execute acceptance commands. Its unknow
 | Plan | Task integration worktree | Engine uses the startup root to revise the task contracts |
 | Execute, L1, Review | Current packet candidate workspace, normally its packet worktree | Engine creates, records, and reuses that workspace |
 | L2/L3, Judge | Task integration worktree | Engine checks the integrated milestone |
-| Intake, Garden | Selected task's worktree | Host selects the root; Go writes proposals. DSH/Codex request read-only; default Kimi has no OS-level read-only guarantee |
+| Intake, Garden | Selected task's worktree | Host selects the root; Go writes proposals |
 | Status, Stop | Original task directory and execution root | Query or stop the existing task without requiring a new worktree, branch switch, or commit |
 
+Model-call permissions follow `permissions.mode`. Under `role-based`, the default for existing files that omit this setting, Plan/Execute request `workspace-write`; Review/Judge and DSH/Codex (including Codex Pro) Intake/Garden request `read-only`. Under `full-access`, every stage requests full access through the selected backend's public interface. Kimi print retains native auto behavior and provides no claimed OS-level read-only or workspace confinement. Stage duties remain unchanged: reviewers evaluate candidates, auxiliary modules produce advice, and candidate identity checks still run before and after review. See [Configuration](configuration.md) for configuration and migration details.
+
 Every loop does not create its own worktree. The outer task worktree spans the deliverable; a packet workspace spans its execution, acceptance, review, and delivery. Plan commits valid contract revisions in the integration worktree and attempts to fast-forward existing packet worktrees to that checkpoint while preserving implementation work. Conflicts stop for resolution.
 
 `flywheel-verify` runs deterministic acceptance only. With `--packet`, it runs that packet's L1. Without a packet, it checks unfinished packets' L1 and the current milestone's L2/L3. It does **not** call Review or Judge, create worktrees, or perform local delivery. It uses the available candidate workspace and may use the integration checkout when no packet worktree is available.

package/docs/getting-started.md

@@ -8,6 +8,8 @@
 
 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](releasing.md#3-失败恢复)。
 
+订阅预设迁移命令与 `permissions.mode` 从 **0.28.2** 开始提供。升级不会自动替换已有配置；先预览 `flywheel config migrate --preset subscriptions`，确认模型和完全权限后再以 `--apply` 应用并备份。
+
 ## 目录
 
 1. [准备运行环境](#1-准备运行环境)
@@ -121,6 +123,8 @@ SDK worker 的临时权限与工具策略只用于其子进程，不改写桌面
 
 ## 4. 配置模型与 skills
 
+如果界面仍显示旧 Z.AI／GLM 或 Kimi K3，先看“配置来源”：升级会保留那份文件。包含本轮修复的新版本可用 `flywheel config migrate --preset subscriptions --cwd /repo --apply --json` 备份并迁移实际生效配置；需预览时去掉 `--apply`。任务有独立配置时加 `--task-dir`。该预设使用 ChatGPT／Kimi Code／DeepSeek Flash、约定的 thinking 和所有阶段完全权限；[迁移与权限说明](configuration.md#将旧配置切换到已有的三种资源)。已发布 0.28.1 尚无此命令。
+
 配置优先级是：**任务目录 → 项目根 → 全局 → 二进制内嵌模板**，选择第一个完整文件，不逐字段合并。默认全局路径是 `~/.config/flywheel/flywheel.config.json`；`FLYWHEEL_CONFIG` 只替换全局路径，不能越过已有任务／项目文件。
 
 查看当前二进制的配置：

package/docs/workflow.md

@@ -2,7 +2,7 @@
 
 [English](en/workflow.md) · 简体中文
 
-本文描述 **Flywheel 0.28.0**的推荐工作流。新默认 `hard` 路由使用
+本文描述 **Flywheel 当前源码**的推荐工作流。默认 `hard` 路由使用
 Codex Pro 插件 machine API；源码存在不代表 npm `latest` 已更新，安装状态见
 [发行指南](releasing.md)。下列命令是操作示例，不会因阅读本文自动执行。
 
@@ -149,10 +149,17 @@ skills 从实际任务目录解析同一 worktree 根，再调用 CLI。默认
 | Plan | 任务集成 worktree，修订任务契约 | 引擎使用启动时的根目录 |
 | Execute、L1、Review | 当前 packet 候选工作区；正常模式为 packet worktree | 引擎创建、记录并复用 packet worktree |
 | L2/L3、Judge | 任务集成 worktree | 引擎验证已集成的需求与里程碑 |
-| Intake、Garden | 所选任务所属 worktree | 入口解析目录，Go 写建议结果；DSH／Codex 后端请求只读，默认 Kimi 无 OS 级只读保证 |
+| Intake、Garden | 所选任务所属 worktree | 入口解析目录，Go 写建议结果 |
 | Status、Stop | 对应原任务路径与根目录 | 直接查询或停止，不要求为此新建 worktree、切分支或提交 |
 
-因此，每个 Loop 不会各自新建一份 worktree。任务 worktree 贯穿整个需求，
+模型调用的权限由 `permissions.mode` 决定：`role-based`（已有文件缺省）下，
+Plan／Execute 请求 `workspace-write`，Review／Judge 以及 DSH／Codex（含 Codex Pro）
+的 Intake／Garden 请求 `read-only`；`full-access` 下全部阶段通过所选后端正式接口
+请求完全权限。Kimi print 保持原生 auto，不提供可宣称的 OS 级只读或工作区沙箱。
+权限不改变阶段职责：评审只评价候选，辅助模块只产建议；评审前后的候选身份检查
+仍然执行。完整配置和迁移说明见[配置指南](configuration.md)。
+
+各 Loop 不会各自新建一份 worktree。任务 worktree 贯穿整个需求，
 packet worktree 贯穿该单元的执行、验收与评审；完成交付才由引擎处理本地合并
 与清理。恢复入口仍是 `flywheel-run`，没有另一个独立的 resume skill。
 `flywheel-verify` 只运行确定性验收：指定 packet 时只检查该单元 L1；未指定时

package/npm/install.js

@@ -335,6 +335,21 @@ async function install(options, { environment = process.env, cwd = process.cwd()
       const summary = parseDocument(result, "skills installation");
       item.summary = summary;
       if (summary.protocol !== 1 || !Array.isArray(summary.results) || summary.results.length === 0) throw new Error("invalid skills installation result");
+      if (!['created', 'existing', 'error'].includes(summary.config?.action) || typeof summary.config?.path !== 'string') {
+        throw new Error('skills installation did not report whether the model configuration was created or preserved');
+      }
+      report.configuration = {
+        path: summary.config.path,
+        action: summary.config.action,
+        preserved: summary.config.action === 'existing',
+        automaticMigration: false,
+        message: summary.config.action === 'existing'
+          ? '已有配置原样保留；升级不会替换旧模型、渠道或思考等级。'
+          : summary.config.action === 'created'
+            ? '新建全局默认配置；已有任务或项目配置仍优先。'
+            : '配置初始化失败；已有文件未被迁移。',
+        migration: { command: 'flywheel', args: ['config', 'migrate', '--preset', 'subscriptions', '--cwd', options.project || cwd] },
+      };
       requireSuccess(result, "skills installation");
       if (summary.ok !== true || summary.results.some(skill => ["error", "stale", "conflict"].includes(skill.action))) throw new Error("some skills were preserved due to conflicts; inspect the results and retry");
       report.skills = { count: summary.results.length, directory: summary.targetBase };
@@ -365,6 +380,7 @@ async function install(options, { environment = process.env, cwd = process.cwd()
       if (result.error || result.signal || ![0, 1].includes(result.code) || typeof diagnostic.ok !== "boolean" || !Array.isArray(diagnostic.checks)
         || diagnostic.ok !== (result.code === 0)) throw new Error("installed CLI returned an invalid preflight result");
       report.diagnostic = diagnostic;
+      if (diagnostic.configuration?.source) report.configuration.effectiveSource = diagnostic.configuration.source;
       report.ready = diagnostic.ok;
       if (!diagnostic.ok) { item.status = "warning"; item.reason = "components installed; resolve the reported harness/configuration prerequisites before running a task"; }
     });
@@ -407,6 +423,11 @@ async function main(args) {
     for (const item of report.steps) console.log(`  ${item.status.padEnd(7)} ${item.name}${item.error ? ": " + item.error : ""}`);
     if (report.paths?.launcher) console.log(`桌面启动入口: ${report.paths.launcher}`);
     if (report.skills) console.log(`Skills: ${report.skills.count} 个 → ${report.skills.directory}`);
+    if (report.configuration) {
+      console.log(`模型配置: ${report.configuration.path} — ${report.configuration.message}`);
+      const migration = report.configuration.migration;
+      console.log(`迁移预览: ${[migration.command, ...migration.args].map(shellQuote).join(' ')}（默认不写入；添加 --apply 明确应用并备份）`);
+    }
     if (report.ok && report.steps.some(step => step.name === 'dsh-plugin' && step.status === 'ok')) console.log("请按 DSH 提示重载插件。");
     if (report.ok) console.log("账号授权与真实模型任务尚未验证；先查看 doctor 的检查项。");
     if (report.diagnostic?.checks) for (const check of report.diagnostic.checks.filter(value => value.status === "fail")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
@@ -38,10 +38,10 @@
     "docs/examples/create-first-task.sh"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.28.1",
-    "@ckanner/flywheel-darwin-amd64": "0.28.1",
-    "@ckanner/flywheel-linux-arm64": "0.28.1",
-    "@ckanner/flywheel-linux-amd64": "0.28.1"
+    "@ckanner/flywheel-darwin-arm64": "0.28.2",
+    "@ckanner/flywheel-darwin-amd64": "0.28.2",
+    "@ckanner/flywheel-linux-arm64": "0.28.2",
+    "@ckanner/flywheel-linux-amd64": "0.28.2"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
@@ -49,9 +49,9 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.28.1 dist-npm"
+    "build:npm": "bash scripts/build-npm.sh 0.28.2 dist-npm"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.28.1"
+    "@ckanner/dsh-plugin-flywheel": "0.28.2"
   }
 }