@ckanner/flywheel 0.28.0 → 0.28.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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 管理。
+- 补齐界面异常恢复：单会话单个在途请求、启动／停止时锁定目标、忽略旧路径的迟到响应，显示最近确认时间；确定未派发的错误可修正后重试，执行结果未知则查询原目标确认后才允许新的变更。界面开关不自动启动、停止或探测任务。独立 SDK worker 的能力边界与桌面 UI 分开说明。
+
+- 新增仓库内 `release:local` 交互发布入口。维护者可从已固定的 release tag 在本机构建六包，再依次完成候选安装测试、远端 tag／源码／完整性复核、候选上传、registry 安装及 `latest` 提升，无需下载外部候选归档或人工复制发布适配器。新入口位于维护工具 checkout，支持独立的已打 tag 源码 worktree；保留既有标签与 CI 流程，失败时复用原候选。
+
 ## 0.28.0
 
 Codex Pro 默认接入。安装和迁移见 [配置指南](docs/configuration.md#codex-pro-默认与旧配置迁移)；源码、测试、CI 和 registry 发布证据分别记录，不用离线通过代替用户 Mac 实测。

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.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.
+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` |
 
@@ -78,6 +78,12 @@ 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.
 
+### Desktop task controls
+
+From `0.28.1`, the native **Flywheel** conversation view appears alongside Chat and Trajectory, preserving DSH's composer, model selector, and right sidebar. Version `0.28.0` uses the old composer popup; upgrade the CLI and desktop plugin to the same new version. Select a prepared task directory and its repository to inspect progress, intervention, effective models, and diagnostics, or explicitly start, refresh, or stop it.
+
+The view retains session-scoped drafts while the host retains the session binding and shows snapshots with their refresh time. It does not discover tasks or poll automatically. An unconfirmed start/stop outcome requires a successful refresh of the same task before further mutations; closing or switching the view does not stop the independent engine. DSH's trajectory keeps its parent-session records, without automatically merging independent worker history. Desktop capabilities and SDK worker policy have separate scopes; see the [plugin guide](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#use-the-desktop-controls).
+
 ## 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.
@@ -85,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.
@@ -122,6 +128,8 @@ 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.
 
+Maintainers can build the six packages from a tagged source checkout and use the repository's `npm run release:local` command for interactive publication. No prebuilt archive is required. The command runs candidate and registry installation checks before promoting `latest`; see [local publication from source](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md#local-build-and-publication-from-source) for the exact worktree and authentication steps.
+
 ## 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

@@ -4,7 +4,7 @@
 
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-当前 **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)。
+当前 **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 无法证明未知用量未超额时停止。汇总数字是已知量下限。
 
@@ -128,7 +128,7 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 
 先在目标 Git 仓库准备并审阅 `docs/<slug>/` 中的 Spec、packet 与配置：需求编号、L1/L2/L3 命令、禁止修改的验收路径和失败出口都应明确。模板可通过 `flywheel template` 查看；可选的 `flywheel-new` skill 用于辅助生成，最终仍由人确认契约。不要把 DSH 面板当成需求生成器。
 
-桌面面板位于会话输入区底部的 **Flywheel** 按钮。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。面板展示实际阶段绑定、检查项、完整 packet 列表与未知用量，原始 JSON 可按需展开。也可使用人工命令：
+从 `0.28.1` 开始，桌面控制面接入顶部“对话／轨迹”旁的原生 **Flywheel** 会话视图，保留 DSH 输入区、模型选择器和右侧栏。`0.28.0` 仍是旧底部弹层，需把 CLI 与桌面插件同版升级。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。视图展示最近刷新的任务结果、完整 packet 列表与未知用量，模型配置和诊断按需查看，原始 JSON 默认折叠。也可使用人工命令：
 
 ```text
 /flywheel {"action":"status","taskDir":"/repo/docs/my-task","cwd":"/repo"}
@@ -148,6 +148,8 @@ flywheel control doctor --task-dir /repo/docs/my-task --cwd /repo --probe
 
 控制接口始终返回一个 protocol 1 JSON；`ok` 表示控制操作成功，任务是否完成应看 `state.status`。`config` 返回 `configuration`，`doctor` 返回 `diagnostic`；诊断有阻断项时保留完整报告并返回退出码 1，不能当成空白传输错误。若启动就绪超时，后台引擎可能仍在加载：先刷新状态和查看日志，不要另起重复任务。
 
+视图草稿按 DSH 会话保留，展示的是带刷新时间的快照；不自动发现任务或轮询。启动／停止结果未确认时，先刷新同一任务再恢复操作。原生轨迹保留父会话已有记录，独立 worker 历史不会自动合并。桌面原生能力与 SDK worker 的临时策略属于不同范围，详见[桌面视图与运行边界](plugins/dsh/README.md)。
+
 原有前台／单步 CLI 仍可使用；这些命令应在目标仓库根目录运行：
 
 ```sh
@@ -222,6 +224,8 @@ npm run build:npm
 
 `build:npm` 先构建 worker，再在隔离目录打包 meta、四个平台包和 DSH 插件，输出到 `dist-npm/`。六个包版本必须一致；本地 tarball 和 Actions artifact 用于开发、验证或备用分发，不是日常用户的安装入口，也不等于已签名的 Mac 安装程序。源码构建及开发模式 skills 说明见[教程末节](docs/getting-started.md#9-开发与备用构建)。
 
+维护者可以直接拉取源码，在本机构建后运行仓库内的 `npm run release:local` 完成交互发布，无需下载预构建归档。工具会运行候选和 registry 安装测试，再按六包依赖顺序提升 `latest`；已存在 release tag 的具体步骤见[从源码本地发布](https://github.com/ckanner/flywheel/blob/main/docs/releasing.md#5-从源码本地构建并发布)。
+
 ## 文档与代码入口
 
 英文用户文档包括 [入门](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)。

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,10 +2,14 @@
 
 [English README](../../README.en.md) · [中文](../getting-started.md) · [Workflow](workflow.md) · [Configuration](configuration.md)
 
-This guide covers the **0.28.0 implementation**: 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 |
@@ -73,7 +77,9 @@ The installer uses the official desktop plugin interface with exact version sele
 dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<installed-version>
 ```
 
-This is the command shape used internally, not a placeholder to paste literally. An independent npm DSH CLI cannot manage the reserved `desktop` profile. Reload according to the host's instructions; the Flywheel button appears in the desktop input area.
+This is the command shape used internally, not a placeholder to paste literally. An independent npm DSH CLI cannot manage the reserved `desktop` profile. Reload according to the host's instructions and select **Flywheel** in the native view bar alongside Chat and Trajectory. Check that bar's More menu if the entry is not directly visible.
+
+This view controls and observes an already prepared task: progress, intervention, effective models, environment checks, and explicit start/refresh/stop. DSH keeps its chat, trajectory, composer, model selector, and right sidebar. Discuss requirements and prepare contracts through the original chat and skills. The view does not discover tasks started elsewhere; select the same task directory to observe one.
 
 The worker defaults to a separate **`sdk` profile**. A desktop provider installation or login does not prove that the SDK profile has the same configuration or authorization. DeepSeek uses `deepseek-official`; native GPT routing uses the ChatGPT adapter. The checked adapter baseline can be installed with:
 
@@ -83,6 +89,8 @@ dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 
 That is a checked compatibility version, not a claim about the latest adapter. Follow its authorization documentation for the chosen profile and keep `DSH_HOME` consistent. Do not copy tokens into task files or Git.
 
+The SDK worker's temporary permission and tool policy applies only to its child process. It does not edit the desktop profile or remove desktop capabilities. Worker-owned delegation, auxiliary model compaction, and currently the entire web tool are disabled. A native view does not make the worker inherit desktop plugins or merge its history. See the [plugin's lifecycle boundaries](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#permissions-and-lifecycle-boundaries) for the capability limits and separate work needed to restore retrieval safely.
+
 The hard route uses the installed `dsh-subagent-codex-pro@0.8.0` dependency's public machine API directly. It does not use `subagent_codex_pro` as a native LLM provider or require a parent model to delegate. Its underlying Codex app-server still needs the local Codex command and login.
 
 ### Desktop launcher
@@ -93,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
@@ -189,7 +199,13 @@ flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/add"
 flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/add"
 ```
 
-The desktop panel accepts the same two absolute paths. A control response's `ok` means the operation succeeded; task completion is determined by `state.status`. After a startup readiness timeout, query status and read logs before attempting another start.
+The top **Flywheel** view accepts the same two absolute paths. Expand its model-configuration and environment-check section when needed, then use the explicit start, refresh, or stop action. A control response's `ok` means the operation succeeded; task completion is determined by `state.status`. The view displays the last refresh time and does not poll automatically.
+
+Draft paths and fetched snapshots are retained separately for each session across view switches while the host retains that session binding; a plugin reload or desktop restart may require selecting the paths again. Path edits discard old results and reject late replies without stopping the old task. Only one control request is pending per session, and a start or stop locks directory inputs while waiting.
+
+After a start/stop timeout or disconnect, the background task's outcome may be unconfirmed. Keep the same task directory, refresh status, and inspect logs before deciding how to recover. The view disables further starts/stops until that task is successfully reconciled and never retries mutations automatically. A prior snapshot, closing a page, or switching sessions cannot prove the engine stopped. The native trajectory retains its parent-session records; full worker histories are not merged into it.
+
+If the host explicitly confirms rejection before the control process started, such as a missing directory, correct the path or environment and submit again. This requires structured host evidence; error-message text alone cannot establish that a lost request was never executed.
 
 For a foreground run that pauses before Review, use this instead of background start:
 
@@ -226,12 +242,15 @@ Existing hard-route configuration remains unchanged after upgrade. To adopt the
 | Symptom | First check |
 |---|---|
 | Missing `install` or `control` command | Published version, `flywheel version`, PATH, and any explicit desktop `flywheelBinary` |
+| The large composer popup is still present | Published `0.28.0` has the old layout; verify a build containing the conversation-view fix is installed, then reload as directed by DSH |
+| Flywheel is not directly visible in the top bar | Check More, plugin enablement, and the actual installed version; `/flywheel` and CLI remain diagnostic entry points |
 | Install succeeds but `ready:false` | Resolve the specific `diagnostic.checks` blockers |
 | Terminal works but the desktop does not | Managed launcher, explicit override, GUI PATH/profile/environment; rerun setup and check the panel |
 | A configuration edit has no effect | `config inspect` source and higher-priority task/project files; restart the engine |
 | Skill or launcher conflict | Preserve customizations, compare the specific files, and resolve the reported conflict without altering ownership hashes |
 | Worktree creation falls back in-place | Stop if isolation is required; inspect persisted mode and preserve work before recovery |
 | Cleanup is unconfirmed | Inspect task-owned processes and receipts before retrying; elapsed time alone is not proof |
+| Start/stop outcome is unconfirmed | Refresh the same task and inspect logs; timeout/disconnection proves neither no start nor a completed stop, and mutations are not retried automatically |
 
 Installation is not one atomic transaction across npm, DSH, and all skills. Correct the reported cause and retry; preserve completed steps and user files. Do not delete whole configuration directories or modify integrity manifests to bypass conflicts.
 

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

@@ -4,8 +4,12 @@
 
 本文适用于 **Flywheel 0.28.0 及以后的完整 npm 发行版**，覆盖 npm 一条命令安装 CLI、worker、DSH 插件与 skills，到配置、启动、观察、停止和恢复一个小任务。DSH 接口目标是已核对的 **Mac 桌面 0.2.1-rc.5**。真实桌面、Seatbelt 和账号调用仍需在自己的 Mac 验收，CI 不能代替这些检查。
 
+下文的顶部 **Flywheel 会话视图**从 `0.28.1` 开始提供。`0.28.0` 仍使用底部弹层；需要把 CLI 和桌面插件升级到同一新版本，源码合并或重新载入旧版本不会带来新布局。CLI 和任务目录接口保持一致。
+
 安装前用 `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-准备运行环境)
@@ -93,7 +97,9 @@ flywheel setup --no-global
 
 ## 3. 桌面入口和 SDK 配置
 
-安装器已经调用正式接口 `dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<本次精确版本>`，随后通过 `list` 核对版本。无需再分别安装 worker 或手动选择压缩包。该命令必须来自桌面安装；独立 npm DSH CLI 不能管理保留的 `desktop` profile。按照宿主提示重新载入，在会话输入区底部查找 **Flywheel** 按钮。
+安装器已经调用正式接口 `dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<本次精确版本>`，随后通过 `list` 核对版本。无需再分别安装 worker 或手动选择压缩包。该命令必须来自桌面安装；独立 npm DSH CLI 不能管理保留的 `desktop` profile。按照宿主提示重新载入，在顶部“对话／轨迹”所在的原生视图栏选择 **Flywheel**；未直接显示时检查该栏的更多入口。
+
+这个视图用于控制和观察已经准备好的任务：看进度、人工处理项、实际模型和环境，显式启动、刷新或停止。它保留 DSH 的原生对话、轨迹、输入区、模型选择器和右侧栏；需求讨论与契约准备仍在原来的对话和 skills 中进行。视图不会自动发现别处启动的任务，需要选择相同的任务目录。
 
 ### 原生 SDK profile
 
@@ -105,6 +111,8 @@ dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 
 随后按该 provider 的文档在对应 profile 完成授权，并保持一致的 `DSH_HOME`。不需要把凭证复制到任务契约或 Git。此处不把 `subagent_codex_pro` 当成原生 LLM provider。困难任务通过 `codex-pro` worker 直接使用已安装插件的公开 machine API，不需要 DSH 父模型再发一次工具调用。底层 Codex app-server 仍需本机 Codex 与登录；包依赖安装不代替它们。
 
+SDK worker 的临时权限与工具策略只用于其子进程，不改写桌面 profile 或移除桌面已有能力。它限制自主委派、辅助模型压缩等工作，当前还禁用整个 web 工具；移到原生会话视图不会让 worker 自动继承桌面插件或轨迹。能力范围及后续检索接入边界见[插件说明](../plugins/dsh/README.md#权限上下文与报告归档)。
+
 ### Mac GUI 的自动入口
 
 安装器在 `~/.config/flywheel/` 下生成 `npm-launcher` 和 `installation.json`。launcher 使用绝对 Node／CLI 路径，记录安装时已核对的 DSH 入口，并保留工具的绝对 PATH 目录；不会把临时 npx 缓存路径当成正式工具目录。npm CLI 启动器再解析与自身版本一致的 worker。
@@ -115,6 +123,8 @@ dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 
 ## 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` 只替换全局路径，不能越过已有任务／项目文件。
 
 查看当前二进制的配置：
@@ -243,7 +253,13 @@ flywheel control start --task-dir "$PWD/docs/add" --cwd "$PWD"
 flywheel control status --task-dir "$PWD/docs/add" --cwd "$PWD"
 ```
 
-`ok: true` 只表示控制操作成功；`running` 表示引擎运行状态，最终任务结果看 `state.status`。启动 readiness 超时后先刷新状态和看日志，不重复启动。也可以在 DSH 输入区的 Flywheel 面板填入同样两个绝对路径，先查看配置和检查环境，再点击“启动／刷新状态／停止”。面板区分未初始化、已完成、暂停、停止和升级；修改路径会清除旧视图，但不会停止旧任务。
+`ok: true` 只表示控制操作成功；`running` 表示引擎运行状态，最终任务结果看 `state.status`。也可以在顶部 **Flywheel** 视图填入同样两个绝对路径，按需展开“模型配置与环境检查”，再点击“启动／刷新状态／停止”。视图区分未初始化、运行、已完成、暂停、停止和升级，标明最近刷新时间；它不会自动轮询。
+
+宿主保留会话绑定期间，路径草稿与快照会按会话保留，切换“对话／轨迹／Flywheel”不丢失；重新载入插件或桌面后可能需要重新选择路径。修改路径清除旧结果并忽略迟到响应，不会停止旧任务。每个会话只等待一个控制请求；启动或停止等待期间锁定目录输入。
+
+启动或停止超时、断连后，后台任务的结果可能尚未确认。保留原任务目录，先“刷新状态”和查看日志；界面在成功核对该任务前禁止继续启动／停止，也不会自动重试。已有快照只是上次结果，不能凭页面关闭、切换会话或停止按钮失去等待状态推断引擎已经结束。原生轨迹保留父会话自己的记录，worker 完整历史不自动合并到其中。
+
+如果宿主明确报告请求在启动控制进程前已被拒绝，例如目录不存在，则修正目录或环境后可以重新提交；这与响应丢失后的结果未确认不同。界面只接受宿主的结构化确认，不通过错误文字推断任务没有执行。
 
 需要人工在 Review 前检查结果时，使用前台监督模式；它与后台 start 二选一：
 
@@ -299,6 +315,8 @@ launcher 被手工修改时，先备份修改。希望采用自动入口，可
 | 现象 | 先检查什么 |
 |---|---|
 | 没有 `install` 或 `control` 命令 | `npm view @ckanner/flywheel version` 与 `flywheel version`；是否仍是旧 0.22.1，PATH 或显式 `flywheelBinary` 是否指向旧版本 |
+| 仍看到底部大弹层 | 已发布的 `0.28.0` 是旧布局；核对是否安装了包含会话视图修复的构建，再按宿主提示重新载入 |
+| 顶部未直接显示 Flywheel | 检查视图栏更多入口、插件启用状态和实际版本；`/flywheel` 与 CLI 仍可用于诊断 |
 | 安装 `ok:true`，但 `ready:false` | 安装已完成；按 `diagnostic.checks` 补齐当前配置需要的 CLI、目录或环境变量，再运行 doctor |
 | npm 全局目录权限错误 | 使用自己可写的 `--prefix`，并把对应 `bin` 加入 shell PATH |
 | desktop profile 被拒绝 | `--dsh-bin` 是否指向桌面安装的命令，而非单独 npm 安装的 DSH CLI |
@@ -312,7 +330,7 @@ launcher 被手工修改时，先备份修改。希望采用自动入口，可
 | 改 channel 后账号没切换 | channel 是计量/配置别名；实际账号仍由 SDK profile/provider 的授权决定 |
 | doctor 有 unknown 或 skipped | unknown 不等于通过，skipped 可能是非任务路由、mock 或没有请求 SDK probe |
 | 费用显示未知 | 渠道未提供 cost／usage；unknown 不是免费，hard token budget 可能停止 |
-| 启动超时但日志继续增长 | 先用 control status 观察就绪状态，不重复启动第二个引擎 |
+| 启动／停止结果未确认 | 刷新同一任务并查看日志；超时或断连不证明任务未启动或已停止，不能自动重试变更 |
 | L1 在 exit 0 后仍拒绝 | 检查候选漂移、输出截断、超时／取消或进程收尾错误 |
 | 提交／合并／持久化检查失败 | 检查保留 worktree、hook 和 Git 差异，修复原因后恢复，不强制清理 |
 | skills 安装拒绝已有目录 | 查看具体冲突；可能是用户修改、未标记目录、损坏清单或旧标记。按上面的备份恢复流程处理，`--force` 不绕过默认保护 |

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.0",
+  "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,19 +38,20 @@
     "docs/examples/create-first-task.sh"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.28.0",
-    "@ckanner/flywheel-darwin-amd64": "0.28.0",
-    "@ckanner/flywheel-linux-arm64": "0.28.0",
-    "@ckanner/flywheel-linux-amd64": "0.28.0"
+    "@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",
+    "release:local": "node scripts/release-local.js",
     "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.0 dist-npm"
+    "build:npm": "bash scripts/build-npm.sh 0.28.2 dist-npm"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.28.0"
+    "@ckanner/dsh-plugin-flywheel": "0.28.2"
   }
 }