@ckanner/dsh-plugin-flywheel 0.27.3 → 0.28.1

package/PROTOCOL.md

@@ -1,6 +1,6 @@
-# Go ↔ DSH worker 协议 v1
+# Go ↔ DSH / Codex Pro worker 协议 v1
 
-此文件是 `internal/drivers/dsh.go` 与本目录 worker 的互操作契约。Go 负责状态机、验收、费用上限及最终进程组清扫；worker 负责一个独立的官方 DSH SDK 进程。两者之间只有本地 stdio，不开放 HTTP 端口。
+此文件记录两种独立 worker 协议。前半部分对应 `internal/drivers/dsh.go` 与官方 DSH SDK worker；[Codex Pro 部分](#codex-pro-worker协议)对应 `internal/drivers/codex_pro.go` 和插件 machine API worker。Go 负责状态机、验收、费用上限及最终进程判断；worker 仅执行一次有边界的调用。两者之间只有本地 stdio，不开放 HTTP 端口。
 
 ## 启动与输入
 
@@ -89,6 +89,58 @@ v1 每次调用使用全新 session。Go 重试时重新提交冻结任务输入
 
 Go 的 `DSHArgs.Doctor` 使用这个入口；为保持 v1 必填 `prompt` 的 admission schema，它会用固定的探针说明替代调用者文本，worker 不将其交给 `session/prompt`。doctor 仍必须具备匹配的 ready、可靠 result、正常 SDK shutdown 与物理退出，不能因为没有推理而放松清理或权限检查。
 
+## Codex Pro worker协议
+
+公开入口为 `@ckanner/dsh-plugin-flywheel/codex-pro-worker`，可执行入口为 `flywheel-codex-pro-worker`。`FLYWHEEL_CODEX_PRO_WORKER` 允许显式覆盖；npm 启动器解析同版本依赖，不依靠碰巧可用的全局旧 worker。worker 实际导入已发布的 `dsh-subagent-codex-pro@0.8.0` 的 `./machine` API，严格检查包名、版本和机器协议 1。Node 最低 22.18.0，仅支持 macOS／Linux。
+
+### 请求与父进程连接
+
+```json
+{"type":"start","protocol":1,"requestId":"call-123","cwd":"/absolute/worktree","model":"gpt-6.1-sol","reasoningEffort":"high","permissionMode":"workspace-write","prompt":"执行冻结工作单元","timeoutMs":1800000}
+```
+
+只接受这些字段；不接受 provider、resume、threadId、额外写目录、任意 CLI 参数或危险权限模式。requestId 非空且最多 256 字符；cwd 为绝对路径，Go 先规范化成物理目录。model／reasoningEffort／prompt 必须是非空文本，permissionMode 仅 read-only／workspace-write。timeoutMs 显式值必须为 1–2,147,483,647 的安全整数，省略使用上游 600,000 毫秒；worker 不接受通过 0 关闭期限。Go 传递有效 wall deadline 和 high 默认 thinking；worker 将 reasoningEffort 映射到 machine 的 effort，固定 threadMode=ephemeral、command=`FLYWHEEL_CODEX_BIN` 或 `codex`，不恢复旧线程。
+
+**这里与 DSH worker 的 EOF 语义不同：Go 写入一行后保持 stdin 开放。** stdin 是父进程的存活连接；未完成前 EOF、读取错误或第二条非空输入触发 AbortSignal，并等待插件有界清理。不能用 `echo … | worker` 的关闭 stdin 行为冒充正常调用。运行请求首行等待上限 10 秒；请求最多 1 MiB，machine 原始输出上限 1 MiB，序列化 progress 累计最多 1 MiB，完整终态帧最多 8 MiB。超限明确失败，不能裁掉回执后判成功。
+
+### 进度与完整结果
+
+零或多个进度帧：
+
+```json
+{"protocol":1,"type":"progress","requestId":"call-123","text":"插件报告的活动"}
+```
+
+最后恰好一个 result，字段结构如下，`receipt` 为插件实际完整对象：
+
+```json
+{"protocol":1,"type":"result","requestId":"call-123","adapter":{"package":"dsh-subagent-codex-pro","version":"0.8.0","protocol":1},"receipt":null,"error":{"code":"INVALID_REQUEST","message":"启动请求未通过校验"}}
+```
+
+启动前不能获得 machine receipt 时为 null。运行已开始则即使失败也保留完整 receipt；`error` 非 null、重复／丢失 result、尾部垃圾、请求身份或 adapter 版本不符都不能成功。本通道没有 DSH `ready` 帧，不能据此虚构运行前完整沙箱握手或实际 effort 回显。
+
+Go 同时校验外层 worker 物理终态和插件 receipt：请求及 run/thread/turn 身份、模型、cwd、approval=never、实际沙箱模式、完整 sandboxPolicy、stopReason、cleanup 与执行事实。workspaceWrite 的显式 writableRoots 必须处于工作区内，networkAccess 必须明确 false；Codex 标准临时目录标记保留，不宣称只能写 cwd。插件 0.8.0 只在 turn 前检查模式等基本配置；完整策略是返回后的交付资格检查，**不能阻止自定义 Codex 配置已经允许的访问**。
+
+effort 的证据只可为 turn/start 请求接受，保留 `effectiveEffort:null`。usage 使用 `run` 增量，不能把 threadTotal 当成本次消耗；只有 complete 才记入可知预算，partial/unknown 原样存入 receipt 并增加未知调用计数。cached input／reasoning output 是总 input／output 的子项，不重复累加。订阅 costUSD 保持 null、costStatus 保持 unknown。receipt 没有实际 provider 时保持未知，不根据 channel 发明 provider。
+
+### 取消与进程终态
+
+worker 捕获 SIGINT／SIGTERM／SIGHUP，先取消并等待插件返回清理结果，再分别退出 130／143／129；父连接断开为失败。Go 为 Codex Pro worker 保留至少 10 秒终止宽限，全局 kill switch 不提前缩短该子进程的宽限。插件 guardian 拥有 app-server 进程组；worker 意外死亡由插件自己的连接与 guardian 负责终止其拥有的进程。Go 未收到完整回执时不能把内部清理记为已确认，主动脱离拥有进程组的外部程序不属于此保证。
+
+已启动 worker 后缺少可信 `cleanup.confirmed` 会记录 `CleanupError`，即使外层进程已退出。引擎和建议模块保存诊断后停止本次运行，不执行传输重试、渠道降级、Plan 冷启动或下一任务。完整回执中确认清理的普通服务错误仍使用原重试策略。恢复前先确认该次调用遗留的进程已停止；等待固定秒数不构成清理确认。
+
+正常完成后 app-server 仍可能需要 TERM/KILL 收尾。只有 completed、cleanup.confirmed、无取消／超时／截断／失败事实且外层 worker 正常退出时，才允许 receipt 中正常 terminationRequested 导致的信号或未知 Codex exit code。不能将 supervisor exit code 冒充模型进程的物理退出码，也不能把文本答案当终态证明。
+
+### 无推理诊断
+
+`flywheel-codex-pro-worker --doctor` 不读取 stdin，不调用 runMachine，不启动 app-server，仅导入并核验公开接口。成功返回单个 JSON：
+
+```json
+{"protocol":1,"type":"doctor","package":"dsh-subagent-codex-pro","version":"0.8.0","machineProtocol":1,"available":true,"inferenceTested":false}
+```
+
+Go doctor 同时检查 Node 与 Codex 命令。包导入成功不证明账号、模型、完整策略或真实推理能力，`--probe` 也不会对 Codex Pro 发模型任务。
+
 ## 桌面控制响应（独立于 worker JSONL）
 
 桌面控制层调用 Go 的 `control` 命令，只接收一个 JSON 文档，不把它与上述 worker 流混用。原 `start/status/stop` 字段不变，新增两种 action：
@@ -108,6 +160,33 @@ Go 的 `DSHArgs.Doctor` 使用这个入口；为保持 v1 必填 `prompt` 的 ad
 
 config/doctor 的 Go CLI 将 SIGTERM/SIGINT 转为 context 取消，等待 watchdog 收尾后才退出。控制调用取消或超过窗口时，host 先发 SIGTERM，诊断动作再留 20 秒让 Go 完成分阶段清理，仍未退出才 SIGKILL；取消始终报告控制失败，即使迟到结果成功也不覆盖它。start/status/stop 保持原控制进程的 500ms 收尾，后台引擎停止仍走独立 stop 协议。
 
+### DSH 命令失败与是否派发
+
+`/flywheel` 的 DSH command 结果仍使用 `kind:"success"` 或 `kind:"error"`。成功结果的 `text` 是上述 Go control JSON，包括具有合法诊断报告的 doctor 失败。新的 host 将所有 command 失败包装为以下独立 JSON，放在 `kind:"error"` 的 `text` 中；这不是 Go stdout envelope，也不改变 worker JSONL 或模型工具的异常接口：
+
+```json
+{"protocol":1,"type":"flywheel-control-error","action":"start","dispatch":"not-dispatched","message":"taskDir must be an existing directory"}
+```
+
+| 字段 | 语义 |
+|---|---|
+| `protocol`、`type` | 固定为 `1` 和 `flywheel-control-error`，用于区分命令失败与引擎结果 |
+| `action` | 可读取的请求 action 字符串；解析失败或没有字符串 action 时为 `null`；界面必须与自己的在途请求匹配 |
+| `dispatch` | `not-dispatched` 表示宿主证明本次请求没有启动 Go 控制进程；否则为 `unknown` |
+| `message` | 给用户诊断的错误文本，本身不证明进程是否启动，也不能作为另一个 envelope 递归解析 |
+
+只有参数／目录等派发前校验失败、派发前取消，以及进程创建失败且没有成功启动的证据，才能返回 `not-dispatched`。进入控制进程后出现的非零退出、超时、取消、坏 JSON 或任务身份不符都不能取得这项证明，即使错误文本包含相同 JSON。host 对普通错误同样增加外层 envelope，只把原始错误放入 `message`，避免进程返回的文字冒充宿主确认。
+
+界面只有在版本、类型、action、dispatch 和 message 都符合契约时才使用宿主证明。未知协议、旧 host 的纯文本错误、DSH 传输失败或丢失响应均保持 `unknown`。启动／停止的 `unknown` 结果必须先成功查询原任务状态，再决定后续变更；不得自动重试。已确认未派发的拒绝会显示原因，用户可以修正输入或环境后重新提交。一次未派发的状态查询也不能解除更早启动／停止留下的未确认结果。
+
+host 在调用 Go 前把任务和仓库目录规范化为真实路径，并校验引擎返回的任务身份。界面不能把用户输入的符号链接、`..`、尾部斜杠或 Mac `/var` 与 `/private/var` 的文本差异当作引擎身份错误；响应接纳依赖 host 的路径校验和当前请求关联。
+
+### 浏览器查看状态的边界
+
+浏览器端遵循[外部 plain-JS 插件实践](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/preset/agent-preset/skills/cordis-plugin-development/references/practices.md)，不运行时导入 Harness Client 包。插件自有的 store handle 只通过公开的 `spec`／`create()` 结构交给槽位注册；每个实例提供 `actions`、`getSnapshot()`、`subscribe()` 和 `clearPersisted()`，由宿主负责会话作用域、实例缓存与 hooks 绑定。当前没有持久化配置，`clearPersisted()` 不删除任何任务文件。
+
+异步控制层另有插件自有 observable，快照在未变化时保持同一身份，经 `inject.hooks` 交给宿主绑定；React 组件不自行订阅，不读取 ctx 或原始服务对象。路径草稿与控制快照只是查看缓存，不成为任务账本，也不写入新的 DSH 会话事件。模型可见的命令和工具结果仍由宿主原有记录机制处理。此查看契约不改变 Go control 协议、worker JSONL 或后台任务的停止语义。
+
 ## npm 安装报告与桌面入口
 
 以下是 Node 安装器的独立契约，不与 worker JSONL、Go control envelope 或任务 `state.json` 混用。入口为 `npx -y @ckanner/flywheel@latest install` 或已安装包的 `flywheel setup`；二者共用参数与行为。普通 npm 包安装没有修改用户目录的 postinstall，只有显式 install／setup 执行 skills、安装记录和 DSH profile 配置。
@@ -124,7 +203,8 @@ config/doctor 的 Go CLI 将 SIGTERM/SIGINT 转为 context 取消，等待 watch
 | `steps` | 顺序记录 `global-cli`、`skills`、`desktop-launcher`、`dsh-plugin`、`preflight`；失败时只含已开始的步骤 |
 | `ready` | 本地 doctor 是否无阻断项；诊断未完成时为 `false` |
 | `authentication` | 固定 `unknown`，没有自动登录或真实模型请求 |
-| `prefix`、`paths` | 得到后才记录；paths 包含 CLI、原生二进制、worker 与生成的 launcher 的绝对路径 |
+| `prefix`、`paths` | 得到后才记录；paths 包含 CLI、原生二进制、DSH worker、codexProWorker 与生成的 launcher 的绝对路径 |
+| `adapter` | 实际导入通过后记录 Codex Pro 包名、精确 0.8.0、protocol 1 与 inferenceTested=false；不代表账号已就绪 |
 | `skills` | 安装成功时的数量及准确目录；每项结果保存在 skills 步骤的 `summary` |
 | `diagnostic` | 合法的完整本地 doctor 报告，包括失败检查项；不执行 `--probe` |
 | `error`、`cancelledBy` | 失败原因、可选取消信号；不是成功结果的一部分 |
@@ -139,7 +219,7 @@ config/doctor 的 Go CLI 将 SIGTERM/SIGINT 转为 context 取消，等待 watch
 
 ### GUI 安装记录
 
-安装器生成 `~/.config/flywheel/installation.json`（0600）与 `npm-launcher`（0755）。记录包含 `protocol:1`、`owner:"@ckanner/flywheel"`、`version`、`prefix`、`cli`、`worker`、`node` 和 `launcher:{path,sha256}`。它只描述软件入口，不保存账号凭证，不构成第二份任务状态。
+安装器生成 `~/.config/flywheel/installation.json`（0600）与 `npm-launcher`（0755）。记录包含 `protocol:1`、`owner:"@ckanner/flywheel"`、`version`、`prefix`、`cli`、`worker`、`codexProWorker`、`adapter`、`node` 和 `launcher:{path,sha256}`。它只描述软件入口，不保存账号凭证，不构成第二份任务状态。旧记录仍按原字段读取，升级 setup 生成新字段；用户修改的 launcher 继续受保护。
 
 launcher 使用绝对 Node 与 CLI 路径，设置安装时可见的绝对工具 PATH 目录，并在用户没有显式设置 `FLYWHEEL_DSH_BIN` 时使用已核对的桌面命令。npm CLI 启动器解析版本一致的原生包和 worker，缺失或版本不匹配时拒绝继续，不隐式下载另一份二进制。临时 npx 缓存与 `node_modules/.bin` 不被记录成持久工具 PATH。
 

package/README.en.md

@@ -0,0 +1,349 @@
+# Flywheel for DSH
+
+[简体中文](README.md) · [Project overview](https://github.com/ckanner/flywheel/blob/main/README.en.md) · [Getting started](https://github.com/ckanner/flywheel/blob/main/docs/en/getting-started.md)
+
+This package connects the DSH desktop to Flywheel's deterministic Go engine and
+provides its DSH SDK and Codex Pro workers. The engine owns task state, budgets,
+verification, Git delivery, and process lifecycles. The desktop is a control and
+observation interface; it does not need a parent model session to keep a task alive.
+
+This guide describes the **Flywheel 0.28.1** interfaces. Source availability does
+not mean that npm `latest` already contains them. Check the registry version and
+the [release guide](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md) before installing. The desktop
+compatibility baseline is **DSH Mac 0.2.1-rc.5**, not a claim that every DSH build
+or provider adapter is compatible.
+
+**Flywheel 0.28.1 introduces the native conversation view.** Version `0.28.0`
+uses the composer popup. Upgrade the CLI and desktop plugin to the same new
+version; merging source does not update an installed plugin.
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| Flywheel conversation view | A native view alongside Chat and Trajectory for task progress, intervention, configuration, checks, and explicit start/refresh/stop |
+| `/flywheel` command | Invoke the Go control interface from an explicit desktop command |
+| `flywheel_control` tool | Expose the same control operations to the host model |
+| `flywheel-dsh-worker` | Run one native model session through an independent DSH SDK profile |
+| `flywheel-codex-pro-worker` | Call the public machine API of the pinned `dsh-subagent-codex-pro@0.8.0` package |
+
+The plugin has no separate task database and does not write `state.json`.
+Kimi CLI, Codex Pro, and the explicit legacy Codex CLI path have separate Go
+drivers. A DSH LLM provider and an external agent tool are different interfaces.
+
+The view answers which stage is running, what needs attention, which models are
+configured, and how to stop or recover the task. Requirement discussion, contract
+preparation, and ordinary conversation stay in DSH's chat and skills. Flywheel
+does not replace the host's composer, model selector, trajectory, or right sidebar.
+
+## Install the complete application
+
+You need **Node.js 22.18.0 or later**, npm, and the existing DSH Mac desktop with
+its desktop-installed `dsh` command. Verify the desktop version and the command
+you are actually running. Do not guess an executable path inside an application
+bundle.
+
+```sh
+npm view @ckanner/flywheel version
+npx -y @ckanner/flywheel@latest install
+```
+
+The explicit installer installs the resolved Flywheel version, the matching Go
+platform binary and workers, and ten embedded skills. It creates a desktop
+launcher, registers the same plugin version with the desktop profile, and checks
+the installed versions. It uses the desktop's plugin management interface:
+
+```text
+dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<resolved-version>
+```
+
+The standalone npm DSH CLI cannot manage the reserved `desktop` profile. If the
+desktop command is not on PATH, pass `--dsh-bin /absolute/path/to/dsh` to the
+Flywheel installer. Reload or restart as instructed by the host.
+
+Use `--prefix "$HOME/.local"` if you need a writable installation prefix, and add
+its `bin` directory to your shell PATH. `--no-dsh` explicitly skips desktop
+registration. Go CLI packages are provided for macOS and Linux, on arm64 and
+x64; Linux package availability does not establish support for the Mac desktop
+or its sandbox. See the [installation guide](https://github.com/ckanner/flywheel/blob/main/docs/en/getting-started.md)
+for the full options and supported workflow.
+
+Software installation and model readiness are separate. With `--json`,
+`ok: true` means installation succeeded; `ready: false` can still report missing
+Kimi or Codex executables or other local prerequisites. Authentication and actual
+inference remain unverified. Flywheel does not install or update DSH, sign in to
+model services, copy credentials, or provide subscription access.
+
+Ordinary `npm install --global @ckanner/flywheel` only installs package files.
+It has no postinstall hook that changes your profile or skills. To finish setup
+for an existing persistent installation, run:
+
+```sh
+flywheel setup --no-global
+```
+
+Installing `@ckanner/dsh-plugin-flywheel` alone gives you this plugin and its
+workers, not the complete Flywheel application.
+
+## Prepare the SDK profile and selected models
+
+The native DSH worker uses `sdk` by default. A provider installed or authorized
+in the desktop profile is not automatically present in the SDK profile.
+`FLYWHEEL_DSH_PROFILE` can select another SDK profile, but cannot select
+`desktop`. Keep `DSH_HOME` consistent with the configuration you intend to use.
+
+The native DeepSeek provider is `deepseek-official`, with `deepseek-flash` in
+the default configuration. At the checked rc.5 baseline its effort values are
+`off`, `low`, `high`, and `max`; there is no `medium`. Other providers have their
+own accepted values. For native GPT routes, install and authorize the selected
+ChatGPT adapter in the SDK profile. One checked compatibility example is:
+
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
+
+This example does not migrate desktop credentials or prove that your account
+can use every model in Flywheel's configuration. Confirm the exact model IDs
+and effort values against the selected provider. The
+[configuration guide](https://github.com/ckanner/flywheel/blob/main/docs/en/configuration.md) explains profiles,
+provider IDs, account channels, and existing-configuration migration.
+
+The default `hard` route uses `harness: "codex-pro"`. Its worker directly imports
+`dsh-subagent-codex-pro/machine`; the package runs Codex app-server using your
+existing Codex installation and login. It does not ask a DSH parent model to
+delegate again. `subagent_codex_pro` is not an LLM provider ID, and this route does
+not silently fall back to `codex exec`.
+
+| Setting | Meaning |
+|---|---|
+| `FLYWHEEL_DSH_BIN` | Explicit DSH executable; otherwise use the configured launcher environment or PATH |
+| `FLYWHEEL_DSH_PROFILE` | Independent SDK profile, default `sdk` |
+| `DSH_HOME` | Optional DSH configuration root |
+| `FLYWHEEL_DSH_WORKER` | Explicit DSH worker override; the npm launcher normally resolves the matching dependency |
+| `FLYWHEEL_CODEX_PRO_WORKER` | Explicit Codex Pro worker override; normally resolved by the npm launcher |
+| `FLYWHEEL_CODEX_BIN` | Codex executable used by the plugin, default `codex` |
+| `CODEX_HOME` | Optional existing Codex configuration and login directory |
+| `FLYWHEEL_KIMI_BIN` | Kimi executable for routes that use its CLI, default `kimi` |
+
+The selected executables and configuration must be visible to the process that
+starts the engine. A shell export does not update an already running desktop.
+
+## Check the installation without inference
+
+Run these from the task's integration worktree, after preparing and reviewing
+its contracts. Replace the task name with your own:
+
+```sh
+flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/my-task" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-task" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-task" --probe --json
+```
+
+Omit `--task-dir` to inspect the general configuration. Ordinary doctor checks
+local configuration and commands. `--probe` additionally initializes the DSH
+SDK, checks its working directory and permission enforcement, and closes the
+session. Provider initialization may query a model catalog or create SDK
+session/cache files, but it does not send an inference prompt or run task
+acceptance commands. It does not write Flywheel state or create worktrees.
+
+For Codex Pro, doctor imports the pinned machine API and checks local prerequisites;
+it does not start an inference task. The worker's narrower package check is:
+
+```sh
+flywheel-codex-pro-worker --doctor
+```
+
+Its successful response reports `available: true` and `inferenceTested: false`.
+Neither check proves account authorization, quota, model availability, or an
+actual inference result. Keep `warn`, `unknown`, and `skipped` distinct from
+`pass`. A blocking diagnostic returns exit code 1 with the report intact.
+
+## Use the desktop controls
+
+Open a DSH session and choose **Flywheel** in the native view bar alongside
+Chat and Trajectory. If the entry is not directly visible, check that bar's
+More menu. Select the absolute task worktree path as the repository directory
+and the task directory inside that same worktree. A blank repository field
+uses the current session's starting directory. Prepare and review the contracts
+first; the view does not turn an empty directory into a complete task plan.
+
+The panel, `/flywheel`, and `flywheel_control` share these Go operations:
+
+```sh
+flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/my-task"
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-task"
+flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-task"
+flywheel control config --cwd "$PWD"
+flywheel control doctor --cwd "$PWD" --task-dir "$PWD/docs/my-task" --probe
+```
+
+Starting a real task calls the selected models. `start` launches a background
+engine; closing the panel or desktop is not a stop request. Refresh status to
+observe it, and use `stop` to request shutdown. `ok: true` describes a successful
+control operation; task completion is recorded in `state.status`.
+
+Opening the view starts no task or probe. It reads on explicit actions, without
+automatic polling or task discovery. To observe a task started through another
+entry point, select its task directory and refresh. Effective configuration comes
+from the engine's selected file; installing the plugin or changing DSH's chat
+model does not migrate that configuration.
+
+### View, request, and task lifetimes
+
+Task and repository drafts and fetched snapshots are retained separately for
+each DSH session across Chat/Trajectory/Flywheel view switches while the host
+retains that session binding. They are not a task database or durable storage
+across binding release, plugin reload, or desktop restart. Only one control
+request is pending per session. Start/stop locks the directory fields while
+waiting. A read-only request allows path edits, but stays pending until its reply
+settles and rejects late results for the previous selection. Hiding a view does
+not make a pending operation complete.
+
+Task state is the last successful snapshot with its refresh time, not a live
+monitor. Failed reads retain valid prior content and show the failure. A lost,
+timed-out, or disconnected start/stop response means the outcome is **unconfirmed**;
+it does not prove that nothing started or that a task stopped. Refresh the same
+task first and inspect its log when needed before deciding how to recover.
+Until a successful status refresh reconciles that task, the view keeps the
+uncertainty visible and disables further starts and stops. It never automatically
+retries a start or stop.
+
+A missing directory or a control process that cannot be created is recoverable
+after correcting the input or environment only when the host supplies structured
+evidence that the request was not dispatched. An ordinary error, connection loss,
+or error-message text cannot establish that fact or dismiss an unconfirmed outcome.
+The `/flywheel` command's error `text` uses the JSON discriminator
+`type:"flywheel-control-error"`; its fields and compatibility behavior are defined
+in the [command failure protocol](PROTOCOL.md#dsh-命令失败与是否派发) (Chinese).
+
+Switching views, closing the session page, removing the plugin, or exiting DSH
+does not stop the independent Go task. Request an explicit stop and await engine
+confirmation. DSH's trajectory retains its own parent-session command and tool
+events. Complete SDK, Kimi, and Codex Pro worker histories are not automatically
+merged into that trajectory or presented as native DSH background tasks.
+
+### Host UI contract
+
+The client uses `ctx.slots.inject()` and a distinct `id: flywheel` in the
+`conversation.view` list. The host owns session scope and view navigation. Chat,
+Trajectory, the composer, and the right sidebar keep their existing entries;
+Flywheel neither shadows them nor draws a separate floating sidebar or composer
+popup. Long paths, model details, and errors wrap or scroll inside the view.
+
+As an external plain-JS plugin, the browser module imports only shared React at
+runtime. It does not import `ui-primitives`, `client-store`, or another Harness
+Client package. The plugin owns its buttons, inputs, viewing-state store handle,
+and observable; the host manages registered session instances and binds their
+read hooks. Locale comes through the injected service. Controls follow the
+checked host markup and interactions, consume semantic color aliases, inherit
+the host font, and mount compiled CSS Modules through the React view.
+
+The baseline is the exact source snapshot `b830ec950faba0a46dda564be3e2d854afed94f1`,
+which declares version `0.2.1-rc.5`: [external plugin practices](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/preset/agent-preset/skills/cordis-plugin-development/references/practices.md),
+[UI guidance](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/.agents/skills/dsh-client-ui-ux/SKILL.md),
+[layout](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/client/ui-layout/README.md),
+[conversation slots](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/client/ui-conversation/src/client/contract/slots.ts),
+and [slot lifecycle](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/docs/subsystems/slots.md).
+The view sits within Conversation's existing header and content geometry; it
+does not change global window-chrome clearance. Source-contract inspection does
+not establish a live Mac desktop pass.
+
+Offline UI checks execute the built plugin's own controls, store handle, and
+observable with React and jsdom. Component fixtures adapt slot bindings and
+Remote; a separate check uses the published rc.5 renderer, slots, and Cordis to
+exercise registration, session generations, declaration collapse/restoration,
+and disposal. These checks do not establish real browser geometry or Mac
+window behavior.
+
+Use one task integration worktree for preparation, planning, milestone
+verification, and the eventual PR. The engine manages packet worktrees for
+execution, L1, and review. A successful packet is merged into the branch of the
+checkout from which the engine was started. The engine does not push, open
+GitHub PRs, merge remote PRs, or publish packages. See the
+[worktree and PR workflow](https://github.com/ckanner/flywheel/blob/main/docs/en/workflow.md).
+
+## Permissions and lifecycle boundaries
+
+Desktop integration and worker policy have different scopes. The worker's
+temporary overlay applies only to its independent **SDK process**; it does not
+edit the desktop profile or remove the desktop's plugins, skills, tools, or UI.
+Conversely, desktop installation and sign-in do not prove that the SDK profile
+loads and authorizes the same capabilities. Verify each selected harness through
+its own configuration and supported authorization flow.
+
+The DSH worker requests `read-only` or `workspace-write`, fixes approvals to
+`never`, and verifies the effective SDK policy before sending the task prompt.
+In the checked Mac source, the DSH sandbox uses its Seatbelt runner and filesystem
+fence. Workspace writes include DSH's permitted temporary area; this is not a
+network-isolation guarantee. Missing or incomplete enforcement is a failure,
+not a reason to switch to unrestricted access.
+
+The SDK overlay disables worker-owned delegation, workflow/goal drivers, model
+titles, and automatic model compaction so the Go owner can bound work and
+account for model calls. It also currently disables the whole `tool-web` package,
+including both `web_search` and `web_fetch`. This is a conservative policy,
+not a claim that every DSH web operation requires a model: the official
+[web tool](https://github.com/deepseek-ai/deepseek-harness/blob/fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159/packages/web/tool-web/README.md)
+configures search and fetch independently, while the
+[DeepSeek search backend](https://github.com/deepseek-ai/deepseek-harness/blob/fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159/packages/web/web-search-deepseek/README.md)
+does use an auxiliary model request. This UI fix keeps worker policy unchanged.
+Restoring retrieval or [automatic compaction](https://github.com/deepseek-ai/deepseek-harness/blob/fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159/packages/compaction/compaction-basic/README.md)
+requires a separate check of accounting, budgets, cancellation, and directory
+ownership; the view's location does not establish those guarantees.
+
+Codex Pro uses fresh ephemeral calls and checks the model, directory, approval
+policy, and sandbox mode before execution. In version 0.8.0, the full
+`sandboxPolicy` reaches Flywheel only in the returned receipt. Flywheel rejects
+delivery when that policy permits unexpected writable roots or network access,
+but **this check happens after execution and cannot undo access already
+permitted by custom Codex configuration**. It is not a complete pre-execution
+policy guard. Kimi CLI print mode likewise does not provide an OS sandbox that
+this adapter can promise.
+
+A worktree separates Git working files and index state; it is not a security
+sandbox. The current engine can fall back to `in-place` if packet worktree
+creation fails. If the task requires strict workspace separation, stop and
+resolve that condition before continuing. Restarting alone does not convert
+saved `in-place` state into a new isolated worktree.
+
+Go owns worker shutdown; Codex Pro also owns a separate guardian/app-server
+lifecycle. Text output or the outer worker exiting does not prove that every
+owned process has stopped. When cleanup cannot be confirmed, Flywheel preserves
+the workspace and audit evidence and stops automatic retries, fallback, cold
+restarts, and later work in that run. Confirm the owned processes have ended
+before recovery. A successful stop operation is not proof that an arbitrary
+escaped process has been cleaned up.
+
+Complete receipts preserve configuration, usage, and termination evidence.
+Accepted effort is not proof of the server's effective reasoning effort.
+Unreported usage and dollar cost remain unknown; subscriptions are not recorded
+as free calls. The current DSH bridge does not support session resume or image
+and attachment inputs. Its protocol and implementation details are documented
+in [PROTOCOL.md](PROTOCOL.md) (Chinese).
+
+## Upgrade and maintain the desktop entry
+
+The installer records an absolute Node/CLI launcher under
+`~/.config/flywheel/`, including its content hash and the checked tool paths.
+An explicit plugin `flywheelBinary` setting takes precedence. Without an
+explicit setting, the plugin uses a valid installation record; only a missing
+record permits legacy PATH lookup. A damaged record or changed launcher fails
+visibly instead of selecting a different engine.
+
+After upgrading Flywheel, moving the npm prefix, changing Node, or adding a
+required CLI, run `flywheel setup --no-global` from a terminal where those tools
+are available. Retain your chosen prefix and DSH executable options. Reload the
+desktop as needed and run its checks again. Custom configuration and modified
+skills are preserved and reported as conflicts; save your changes and resolve
+the conflict rather than deleting their ownership records.
+
+Existing Flywheel configuration is not automatically migrated. To adopt the new
+plugin path from 0.27.x, change the effective hard-route harness from `codex` to
+`codex-pro`, including any referenced profile, and inspect the expanded result.
+The full upgrade and removal procedure is in
+[Getting started](https://github.com/ckanner/flywheel/blob/main/docs/en/getting-started.md).
+
+For source changes and offline verification, read the
+[contribution guide](https://github.com/ckanner/flywheel/blob/main/docs/contributing.md). The repository currently uses
+`UNLICENSED`; an npm release or a future public repository does not by itself
+establish an open-source license.