@ckanner/flywheel 0.22.1 → 0.27.3

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.27.3
+
+当前统一 npm 发行目标。本节记录修复内容，不代表本版门禁、registry 发布、latest 提升或用户 Mac 实机验收已完成。0.27.0／0.27.1 未上传 npm 包；0.27.2 的发行在验证阶段主动取消，未上传包，旧 tag 均保留不移动。
+
+- 兼容 npm 12 `view --json` 的单元素数组结果，同时保留 npm 11 标量结果；多结果、错误结构与缺失 integrity 仍拒绝，只有结构化 E404 可表示版本不存在。
+- 增加真实 npm CLI 对隔离本地 registry 的 `view` 协议回归，覆盖 latest、integrity、缺失字段及 E404／E403；不调用发布接口或真实账号。
+- CI、六包候选构建、双平台验证与 publish 统一固定 Node 24.22.1／npm 12.2.1，并记录实际工具版本，避免测试与发布使用不同 npm 协议；原有权限、候选身份和全部门禁保留。
+- 六个包、精确同版依赖、插件锁文件、构建入口和当前安装教程统一到 0.27.3。
+
+## 0.27.2
+
+[PR #19 CI](https://github.com/ckanner/flywheel/actions/runs/41388914605) 与 [main CI](https://github.com/ckanner/flywheel/actions/runs/41389529756) 均通过。随后预核真实 npm 12 的 `view --json` 发现单值结果变为数组，[0.27.2 发行 run](https://github.com/ckanner/flywheel/actions/runs/41389716920)在 preflight／build 成功后的 verify 阶段主动取消；未执行 npm 上传，不是 CI 失败。原 tag 保留不移动，后续修正版使用 0.27.3。
+
+- 控制面测试夹具通过原子替换发布完整状态 JSON，消除模拟引擎直接覆写文件时被并发读取到半写内容的竞态；控制接口和生产状态文件契约不变。
+- 发行构建兼容 npm 11 的单元素数组及 npm 12 按完整包名索引的单包对象 `pack --json` 输出，继续严格核对对象键、包名、版本、文件名及候选 integrity。
+- 六个包、精确同版依赖、插件锁文件、构建入口及当前安装教程统一到 0.27.2；保留旧版本的实际验证证据和失败发行记录。
+
+## 0.27.1
+
+修复私有 GitHub 仓库的 npm 发行路径。`v0.27.0` 的首个 publish run 在上传前因裸 `git fetch` 缺少认证而停止，未发布任何 0.27.0 npm 包；该 tag 保留为源码和验证记录，不移动。随后 [0.27.1 发行 run](https://github.com/ckanner/flywheel/actions/runs/41387321980) 的 macOS 验证通过，但 Ubuntu 验证因控制面测试夹具的状态文件写入竞态失败，publish job 跳过，未上传任何 0.27.1 npm 包。0.27.1 tag 同样保留，后续修正版使用 0.27.2。
+
+- 发布 job 在工具链准备后，通过官方 checkout 的短暂只读认证刷新 source 与完整 refs，随后下载候选并检查精确 tag；不再执行凭证已清理后的远端 fetch。
+- 发布命令要求显式仓库可见性。public 保留 provenance；private 使用 `--provenance=false`，符合 npm 不支持私有源码仓库证明的限制，未知值在 registry 请求前失败。仓库可见性、六包 integrity、完整门禁和 latest 提升顺序不变。
+- 增加私有仓库发布协议回归，实测显式参数覆盖 npm 环境默认值；六包、锁文件、构建入口和当前用户教程同步到 0.27.1。
+
+## 0.27.0
+
+DSH 桌面集成、可靠交付闭环与 npm 一条命令安装。此节记录对应版本的源码变更，不单独证明 npm 已发布或用户 Mac 已验收；用 `npm view @ckanner/flywheel version` 核对实际发行。旧 0.22.1 不包含本节新增安装和 DSH 接口。安装与迁移见 [入门教程](docs/getting-started.md)。
+
+- **启动期间的停止快照**：修复真实子进程已经运行、`Cmd.Start` 尚未返回登记时，`KillActiveChildren` 可能取得空快照的竞态；启动与登记由同一把快照锁保护，失败路径也释放锁。新增真实进程的确定性回归，原验收停止测试及 3 秒期限保持不变。正常 machine SIGTERM 路径已有 context 取消兜底，本修复补足独立 kill snapshot 的已启动进程契约。
+- **npm 一条命令安装**：新增 `npx -y @ckanner/flywheel@latest install` 与 `flywheel setup`，全局安装精确同版 CLI、平台二进制、worker、10 个内嵌 skills，再通过已有桌面 DSH 的正式接口注册并核验插件。支持 prefix／project／DSH 命令／profile、显式跳过、超时和 JSON 输出；普通 npm 包安装不通过 postinstall 修改用户目录。
+- **软件安装与运行准备分开报告**：本地 doctor 有效失败保留完整检查项，允许 `ok:true, ready:false`；账号状态保持 unknown，不自动安装／登录其他 harness，不发送模型 prompt。取消、超时、损坏协议和版本漂移阻止安装成功，报告已完成步骤。
+- **Mac GUI 自动入口**：生成使用绝对 Node／CLI 路径的 launcher 和带 SHA-256 的安装记录，桌面插件自动发现并验证；用户显式 `flywheelBinary` 优先。损坏或改动的入口明确失败，不静默使用其他版本，无需手写 GUI 启动脚本。
+- **skills 更新保护**：快照清单校验内容、类型和模式，用户修改、新增／删除文件及未归属目录保留并报告冲突；逐 skill 暂存、rename 和失败回滚。旧纯文本标记仅在完整内容匹配时迁移。新增 `install-skills --json` 的完整逐项结果。
+- **npm 启动器生命周期**：异步启动真实 Go 进程，传递取消信号并等待清理完成；核对原生包／worker 的精确版本，兼容依赖提升，避免启动旧二进制或留下 wrapper 的子进程。
+- **六包发行门禁**：meta、四个平台包和 DSH 插件统一版本。先构建 worker，在隔离副本构建并打包一次，再于 Linux／macOS 验证同一候选的真实 npm 安装。发布要求 HEAD 精确 tag 与干净来源；已存在版本核对 integrity，只有明确 404 视为不存在；全部包与精确版本安装验证通过后才更新 latest，且不倒退标签。
+- **GitHub 可信发布**：参考现有 DSH 插件的 Actions 流程，固定发布工具链为 Node 24.22.1／npm 12.2.1，支持 OIDC 的 publish 与 dist-tag；无 token 时使用独立空 npmrc，有 token 时保留后备认证。补充六包逐项授权、精确 tag 触发及原候选重试的维护者指南。
+
+- **配置与模型 profiles**：新增可复用 `profiles`、阶段引用与显式覆盖；DSH `provider` 和账号 `channel` 分离，所有角色和渠道降级均传递实际 provider；指标分别保留两者。严格拒绝未知字段、无效引用和 provider 冲突，兼容旧内联绑定与合法显式零值。
+- **只读预检**：新增 `config inspect`、`doctor` 和相应 control actions；检查有效配置、工具和任务所需路由。可选 SDK probe 验证配置、目录、沙箱与关闭，零推理，整体验证有界；账号、额度与实际模型能力明确标为未验证。
+- **桌面可观察性**：面板展示配置、逐项诊断、完整 packet 状态与未知计量；区分完成、暂停、停止和升级，路径切换后忽略迟到的旧响应；增加宿主 React 18 对应的真实 DOM 交互回归。
+- **DSH 入口与 worker**：新增 `control start/status/stop`、桌面面板、人工命令与模型工具。Go 继续独占状态；worker 校验 provider/model/cwd/effort、权限、可靠终态及 SDK 关闭。
+- **模型路由**：默认 DeepSeek Flash 实现，Kimi CLI 规划／前端／整理，DSH ChatGPT provider 评审／终验，独立 Codex CLI 处理困难任务。Kimi 不使用 ACP；外部 Codex Pro adapter 与原生 LLM provider 分开，当前路由不隐式消费外部 subagent 工具。
+- **可靠性**：验证证据绑定候选和契约；契约修订跨重启失效旧证据；L1、Review、里程碑 gate 与 Judge 前后检查身份；提交及合并后确认持久化结果，失败保留 worktree。
+- **发布前复核**：修复从子目录漏读项目配置；持久化检查独立核对执行位与链接类型；验收输出截断不能因退出码符合预期而通过。CI 增加 Linux／macOS 插件、跨进程和 npm 安装检查；Actions artifact 用于传递和审查候选，正式用户从 npm 安装。
+- **Mac CI 修复**：任务目录和 Git 执行根统一使用物理路径，避免 `/var`／`/private/var` 别名造成账本、报告和恢复判断失真；补充真实符号链接启动／恢复回归，并消除 Kimi 路径断言与 Zcode fixture 的写入／退出竞态。进程组清理探测的暂态 `EPERM` 在原宽限内重试，仍须确认 `ESRCH`；持续权限错误继续阻止交付。
+- **生命周期与计量**：按运行 token 停止、运行 lease 防重入、超时／取消／清理失败严格区分；未知 usage/cost 不再当成零。
+- **测试与文档**：普通单测／回归可随实现修改，冻结验收显式保护；保留逐函数 100% Go statement coverage；更新全部内嵌 skills 的控制接口、单环语义与配置说明，补充完整 Mac 安装和首个任务教程。
+- **兼容边界**：旧配置不自动迁移；任务／项目／全局配置选择首个完整文件，不深度合并。Mac 桌面渲染、Seatbelt 和真实账号调用仍需用户环境验收；离线通过不等于实机通过。
+
 ## 0.22.1 (2026-09-14)
 
 修复 0.22.0 meta 包缺 bin shim：`bin/flywheel.js` 此前被 .gitignore 的 `/bin/`（postinstall 下载目录时代的遗留规则）挡在 git 之外——CI checkout 无此文件，发布的 meta 包只有 3 个文件、`flywheel` 命令不存在。本版将 shim 入库并全量 bump 版本；旧 0.22.0 meta 请勿使用。
@@ -13,4 +63,4 @@
 - **配置四级发现链**：任务目录 → 项目根 → 全局 `~/.config/flywheel/flywheel.config.json`（首装自动物化，可直接编辑）→ 内嵌法定表兜底。
 - watchdog 交互钩子（协议驱动）、multimodal 执行路由、`FLYWHEEL_CONFIG` 覆盖。
 
-更早历史见 docs/design.md 变更记录。
+更早历史见 [历史设计](docs/design-history-v0.24.md) 的变更记录。

package/README.md

@@ -1,162 +1,230 @@
 # Flywheel（飞轮）
 
-Loop Engineering 系统：外部编排器进程（不是 agent）驱动多个 agent loop（规划/执行/评审/终验），接收已冻结的需求，自动完成软件任务的规划、实现、评审与分层验证，全程可无人值守，异常时升级给人。
+Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-- 编排器 = 确定性 Go 代码（机械状态转移，设计铁律 1）
-- 角色与知识 = Agent Skills（本仓库 `skills/`，只是"按钮"）
-- 契约 = `docs/<slug>/` 下的静态文件（spec.md + task-packet + state.json，全部进 git）
+当前 **v0.27.3 实施版**以 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务可走独立 Codex CLI。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
 
-权威设计文档：**[docs/design.md](docs/design.md)**（v0.22，变更记录在文件头）。仓库工作宪法：[AGENTS.md](AGENTS.md)。
+**本教程适用于 0.27.3 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
 
-## 安装（npm，平台二进制包模式）
+测试结果与实机边界见[验证记录](docs/validation/2026-11-01-npm-installation.md)。旧版本的选型、维护机环境与演练记录保存在[历史设计](docs/design-history-v0.24.md)，不代表当前默认值或用户机器状态。
 
-```bash
-npm i -g @ckanner/flywheel     # 平台二进制经 optionalDependencies 自动就位，无 postinstall 下载
-flywheel install-skills        # skills 物化 + 全局配置 ~/.config/flywheel/flywheel.config.json 一次就位
+首次使用请按 [Mac 安装与首个任务教程](docs/getting-started.md) 完成安装、配置、无推理检查和小任务验收。本文保留各接口与设计边界的速查。
+
+## 1. 一条命令安装
+
+已有 **Node.js 22 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
+
+```sh
+npx -y @ckanner/flywheel@latest install
 ```
 
-- 安装完全自包含：契约 schema、skills 快照、§13 法定配置表全部内嵌二进制，**无需 clone 本仓库**；维护者与分用户用法完全一致。
-- 支持平台：darwin/linux × amd64/arm64（`os`/`cpu` 字段自动选取，`--no-optional` 会导致平台包缺失）。
-- 非 npm 渠道：[GitHub Releases](https://github.com/ckanner/flywheel/releases) 下载平台 tar.gz（`shasum -a 256 -c checksums.txt` 校验）。
-- 开发机源码运行：`go install ./cmd/flywheel`；`flywheel install-skills --link` 可选软链源码树（仅维护者便利，非安装路径）。
+Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制和 DSH worker 装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
 
-## 本机环境事实（维护机，v0.22）
+安装完成会显示每个步骤和本地预检结果。`ok:true` 表示软件安装成功；`ready:false` 表示当前配置仍有运行阻断项，例如缺少 Kimi／Codex CLI，二者可以同时出现。安装器不替换现有 DSH，也不安装或代登录 Kimi／Codex，不代配 DeepSeek API 凭证。运行真实任务前需完成所选渠道的准备。
 
-- macOS arm64；Go 工具链经 mise 管理（go@1.27.0）——shell PATH 可能残留旧版路径，新会话先 `go version` 核对。
-- **zcode**：driver 默认 `node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs app-server`（app 内置 runtime，随桌面自动更新；`FLY_ZCODE_SERVER_BIN` 覆盖 launcher，`FLY_ZCODE_BIN` 只管桌面注册二进制——v0.22 语义拆分）。Z.AI Coding Plan 凭证在 `~/.zcode/cli/config.json`（provider zai）；app-server 协议 live 冒烟 2026-09-10 通过（8.2s 全闭环）；协议无公开文档——桌面大版本更新后跑协议探针（design.md §10-5）。
-- **codex**：CLI 已升 0.154.0（gpt-6-astra 硬门槛 ≥0.154 npm / ≥0.153 app 内置）；chatgpt 订阅 OAuth 已登录。注意：代理经 HKG 节点偶发 403，重试即过。
-- **kimi code**：订阅 OAuth 登录在；stream-json 无 usage 暴露——Plan 的 token 不可观测（接受现状，看门狗兜底）。
-- **omp（B 通道）**：已装、`zhipu-coding-plan` provider 配好（智谱国内计划）——zcode 协议漂移时的应急通道。
+默认使用 npm 的全局 prefix 和用户级 skills 目录。没有全局目录写权限时，可显式选择用户目录：
 
-## 安装 skills 到 kimi code / pi
+```sh
+npx -y @ckanner/flywheel@latest install --prefix "$HOME/.local"
+```
 
-kimi code、pi、Warp 均实现 Agent Skills 标准并扫描共享安装点 `~/.agents/skills/`：
+自定义 prefix 后，如需在终端直接输入 `flywheel`，将该 prefix 的 `bin` 加入自己的 shell PATH。`--project`、`--dsh-bin`、`--profile`、`--no-dsh`、`--no-global` 和超时参数见[完整教程](docs/getting-started.md#2-一条命令安装)。
 
-```bash
-# 默认：软链（仓库即唯一信源，改了即生效；幂等，重复运行报告"已安装，跳过"）
-flywheel install-skills
+普通 `npm install --global @ckanner/flywheel` 只安装包文件，不通过 postinstall 修改用户的 skills、配置或 DSH profile。已经用它安装的用户可显式运行 `flywheel setup --no-global` 完成配置；`install` 与 `setup` 共用安装流程，默认都会确保本版全局包已安装。
 
-# 替换已存在的条目
-flywheel install-skills --force
+## 2. DSH 入口与独立 worker
 
-# 复制快照（用于发布，而不是软链）
-flywheel install-skills --copy
+本实现针对已核对接口的 **DSH Mac 桌面 0.2.1-rc.5**。先核对 About、`dsh --version` 和命令实际来源。它不要求 alpha、OAR、Forge、Teams 或一直存活的桌面父智能体。
 
-# 安装到某个项目根的 .agents/skills/（项目级）
-flywheel install-skills --project /path/to/project
-```
+上一节的安装器使用**桌面安装的 `dsh` 命令**执行正式插件管理接口：`dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<本次版本>`，然后通过 `plugin list` 核对版本。普通 npm DSH CLI 不能管理保留的 `desktop` profile；命令不在 PATH 时用 `--dsh-bin` 指定已核对的桌面命令入口。安装后按宿主提示重新载入。不要猜测 `.app` 内部可执行文件路径。
+
+原生 worker 使用独立的 SDK profile。桌面装有某个 provider，不代表 SDK profile 已经加载或授权。DeepSeek 使用实际 provider `deepseek-official`；GPT 原生路由要求在 SDK profile 中配置对应的 ChatGPT adapter，例如本轮核对的版本：
 
-> 调用形态按 harness 而异：kimi code 与 pi 为 `/skill:<name>`；Warp 为 `/<name>`；
-> Claude Code 经 Skill 工具加载。`whenToUse`/`arguments` 是 kimi code 定义的字段
-> （自动调用依据），不在 agentskills.io 标准内，其他 harness 会无害忽略。
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
 
-装完后在 kimi code 或 pi 里用 `/skill:<name>` 调用，例如 `/skill:flywheel-run`。安装时会在 skills 安装点写入锚文件 `flywheel-home.txt`，skill 用它定位本仓库根。
+这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会自动迁移桌面凭证，也不证明账号可以调用默认表里的所有模型。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider；Flywheel 的 `hard` 路由使用独立 Codex CLI。
 
-## skills 一览（都只是按钮，不含 loop 逻辑）
+### worker 入口配置
 
-| 调用 | 作用 |
+| 环境变量 | 默认值与作用 |
 |---|---|
-| `/skill:flywheel-new` | 对话式任务生成器：调研仓库 → 问意图 → 生成契约 → 逐条试跑验收命令留证 → 停下等人审 |
-| `/skill:flywheel-run` | 以独立进程拉起编排器（触发全部 loop）；可选 `pause=review` 监督冻结点 |
-| `/skill:flywheel-plan` | 只触发 Plan Loop 单步 |
-| `/skill:flywheel-exec` | 只触发 Execute Loop（可指定 packet） |
-| `/skill:flywheel-review` | 只触发 Review Loop（可指定 unit） |
-| `/skill:flywheel-verify` | 只触发确定性验证闸门 L1/L2/L3（无模型） |
-| `/skill:flywheel-status` | 只读进度（state.json/指标/缓存命中率/inbox；推进超时→停滞提示） |
-| `/skill:flywheel-stop` | 停止编排器进程，状态定格 |
-| `/skill:flywheel-intake` | 外挂：扫任务源 → triage-inbox → LLM 分诊建议（不冻结需求） |
-| `/skill:flywheel-garden` | 外挂：retro 失败模式 + 知识资产腐烂 → 提案（需人审） |
+| `FLYWHEEL_DSH_WORKER` | npm 启动器自动解析同版本依赖中的 worker 绝对路径；显式环境变量优先。直接运行 Go 二进制时默认从 PATH 查找 `flywheel-dsh-worker` |
+| `FLYWHEEL_DSH_BIN` | PATH 中的 `dsh`；建议固定为已核对的官方命令入口 |
+| `FLYWHEEL_DSH_PROFILE` | `sdk`；必须是 SDK profile，不能是 `desktop` |
+| `DSH_HOME` | 交给 DSH 的自定义配置根；不设置时沿用 DSH 自己的默认行为 |
+| `FLYWHEEL_KIMI_BIN` | PATH 中的 `kimi`；可指定 Kimi CLI 的绝对路径 |
+
+Codex CLI 通过 PATH 中的 `codex` 启动。所有选定 CLI、Node 与账户配置必须对**启动 Go 引擎的进程环境**可见。
+
+安装器自动生成 `~/.config/flywheel/npm-launcher` 和 `installation.json`：记录绝对 Node／CLI 路径、已核对的 DSH 入口及安装时可见的工具 PATH。桌面插件未显式配置 `flywheelBinary` 时，读取这份安装记录，校验 launcher 是普通可执行文件且 SHA-256 匹配后使用。**无需手写 GUI 启动脚本或修改 profile 配置。**
+
+用户原有的显式 `flywheelBinary` 优先，安装器不会替用户覆盖它。安装记录不存在时保留 PATH 查找兼容行为；记录或 launcher 已损坏／被修改时明确失败，不悄悄使用另一份引擎。升级 Node、移动全局 prefix 或新增 CLI 后，可在工具均可见的终端运行 `flywheel setup --no-global` 更新安装记录；先保存自己对 launcher 的修改，冲突不会被覆盖。终端里的 `export` 本身不会改变已运行的桌面进程，仍需在面板内复验。
 
-内置 skill 目录也可用 CLI 直接查看：`flywheel skills list` / `flywheel skills read <name>`（go:embed 内嵌，无需源码树）。
+### 不调用模型的检查
 
-## 使用全流程（最小示例，详见 [docs/design.md](docs/design.md) §12）
+在实际目标仓库目录、使用与引擎 worker 相同的环境变量执行：
 
-```bash
-# 1. 在 harness（kimi code 或 pi）里生成任务契约
-/skill:flywheel-new 把"给网关加 /health 端点"做成 flywheel 任务
-#    → 生成 docs/<slug>/{spec.md, task-packet-*.md, state.json, flywheel.config.json}
-#    → skill 会把契约 git add + commit，然后停下
+```sh
+flywheel config inspect --cwd "$PWD" --json
+flywheel doctor --cwd "$PWD" --json
+flywheel doctor --cwd "$PWD" --probe --json
+```
+
+`config inspect` 只读展开有效配置；`doctor` 检查目录、配置、所需命令与声明的环境变量。加 `--task-dir docs/my-task` 会校验 Spec/packet，并把工具检查缩小到任务所需阶段与路由；不指定任务时检查全部配置绑定。没有 packet 时按规划前状态检查默认路由，不会擅自生成契约。
+
+`--probe` 进一步启动本地 DSH SDK、创建会话、核对 cwd／权限并关闭，**不发送推理 prompt、不运行验收命令**；provider 初始化可能查询模型目录。输出保留 pass/fail/warn/unknown/skipped，阻断项使退出码为 1；没有阻断项也不能证明账号授权、订阅额度或真实模型推理可用。相同账号／模型／目录／effort／权限的 SDK 检查去重，检查预算 40 秒，进程各收尾阶段有 5 秒宽限，保守预留另 15 秒清理。不会物化全局配置、写任务状态或创建 worktree。
+
+完整安装、权限、生命周期说明见 [DSH 插件 README](plugins/dsh/README.md)，线协议见 [PROTOCOL.md](plugins/dsh/PROTOCOL.md)。
+
+## 3. 当前默认路由
+
+默认内联模板是 [templates/flywheel.config.example.json](templates/flywheel.config.example.json)，可复用配置见 [profiles 示例](templates/flywheel.profiles.example.json) 与[配置指南](docs/configuration.md)。`harness` 指执行后端，`provider` 是 DSH SDK 实际注册的 LLM adapter ID，`channel` 是本配置的账号／计量渠道名；`model` 与 `thinking` 逐调用传入。旧配置未写 provider 时继续把 DSH channel 解释为 provider ID。
 
-# 2. 人审契约（关键 checkpoint，不可省）：需求编号、验收命令、边界、试跑证据
-#    （生成器已逐条试跑 L1 命令并把退出码/输出记入 spec 附表——审它别跳过）
+| 阶段或执行路由 | Harness | Provider／渠道 | 模型 | Thinking |
+|---|---|---|---|---|
+| Plan | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high`，匹配身份后可恢复会话 |
+| Execute `default` | DSH SDK | `deepseek-official` | `deepseek-flash` | `high` |
+| Execute `frontend` | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+| Execute `hard` | Codex CLI | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
+| Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high`，只读 |
+| Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high`，里程碑终验 |
+| Intake | DSH SDK | `deepseek-official` | `deepseek-flash` | `low` |
+| Garden | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
 
-# 3. 启动（在 harness 里扣扳机；编排器是独立进程，关窗不影响运行）
-/skill:flywheel-run docs/<slug>            # 全自动
-/skill:flywheel-run docs/<slug> review     # 监督模式：Review 前冻结，等你看完再续
+这些是可编辑的初始绑定，并非模型排名或性能承诺。DeepSeek 只用 Flash；当前 Mac rc.5 的合法 effort 为 `off/low/high/max`，没有 `medium`。双 judge 默认关闭，也不默认跨渠道付费降级。`multimodal` 暂无默认绑定：当前 bridge 只有文本契约，模型名称或目录里的 vision 标记不能证明附件已正确传递。
 
-#    单步玩法：--only execute / verify / review（与 pause-before 互斥）
+Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。DSH/Codex 使用明确的 workspace-write 或 read-only 与禁止扩权策略。具体账号的可用模型、额度和使用授权需要由所选服务确认。
 
-# 4. 观察与干预（在哪都行，全是文件操作）
-flywheel status docs/<slug>
-flywheel stop docs/<slug>
+usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免费。默认 soft token budget 会报告未知量；hard budget 无法证明未知用量未超额时停止。汇总数字是已知量下限。
 
-# 5. 交付：分支/PR 留给人最终确认合并（外层循环归人）
+### 迁移已有配置
+
+配置按**第一个存在的完整文件**选择，不逐字段合并：任务目录 → 项目根 → 全局 `~/.config/flywheel/flywheel.config.json` → 二进制内嵌模板；`FLYWHEEL_CONFIG` 可指定全局配置路径。已有文件不会因升级自动改写。
+
+可用新二进制查看模板，再审阅并迁移自己的配置：
+
+```sh
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 ```
 
-单 loop 手动触发（旁路常开）：`flywheel run docs/<slug> --only execute --packet M02-T03`、`--pause-before review` 逐步监督。
+`drivers` 选择 `real/mock`，不是模型或 provider 名称。模型在 `loops` 和 `routes` 配置，可直接写字段，也可引用 `profiles` 后按需覆盖。未知 profile、拼错字段、模型字段的 null 和 provider 冲突会拒绝加载；允许 `_note` 注释，原有 `env-key:null`、`judge-panel:null` 仍合法。渠道别名不会自动切换 DSH 账号，授权仍由选定 SDK profile/provider 管理。修改运行配置后重启引擎；Plan 不允许悄悄改模型、权限或其他运行配置。
 
-## 目录结构
+## 4. 创建、运行和观察任务
 
+先在目标 Git 仓库准备并审阅 `docs/<slug>/` 中的 Spec、packet 与配置：需求编号、L1/L2/L3 命令、禁止修改的验收路径和失败出口都应明确。模板可通过 `flywheel template` 查看；可选的 `flywheel-new` skill 用于辅助生成，最终仍由人确认契约。不要把 DSH 面板当成需求生成器。
+
+桌面面板位于会话输入区底部的 **Flywheel** 按钮。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。面板展示实际阶段绑定、检查项、完整 packet 列表与未知用量，原始 JSON 可按需展开。也可使用人工命令：
+
+```text
+/flywheel {"action":"status","taskDir":"/repo/docs/my-task","cwd":"/repo"}
 ```
-cmd/flywheel/            # main() 单行桩（os.Exit(cli.Execute())）
-internal/
-  cli/                   # cobra 命令树：run/status/stop/intake/garden/install-skills/skills
-  machine/               # 状态机（DESIGN §6 刻意做薄）：runTask/runSingleStep/steps
-  contract/              # 契约解析 + JSON Schema 校验单一信源（templates/*.schema.json）
-  state/                 # state.json CAS 账本（tmp+rename 原子写）
-  donereport/            # done-report 解析与格式校验
-  exitcontract/          # 出口契约三正交量判定
-  verify/                # L1/L2/L3 闸门 + git diff 边界 + worktree 隔离 + 单元提交
-  watchdog/              # 双计时看门狗（流 idle + wall-clock；进程组 kill + quiescence）
-  errs/                  # 错误分类/退避/降级集（RE2 等价改写）
-  fallback/              # 渠道降级链（绑定表改写）
-  circuitbreaker/        # 预算熔断（off|soft|hard）+ DC4 空转检测
-  defectinjection/       # 缺陷注入抽检（DC3）
-  metrics/               # JSONL 指标（模型/token/成本/缓存命中/prompt 哈希）
-  prompts/               # 提示词构建（§8 缓存纪律：稳定前置/易变尾部）+ 裁决解析
-  drivers/               # mock（测试）/ pi / omp（B 通道）/ zcode（app-server）/ codex / kimi（长驻会话）
-  config/                # 法定配置表加载与校验
-  childenv/              # 子进程环境白名单（凭证卫生 §9）
-  ledger/                # 账本区路径分类（边界判定的单一信源）
-  modules/               # 外挂：intake/garden/install-skills/module 共享上下文
-  skillsembed/           # go:embed skills 数据层（skills list/read + 规范门禁测试）
-templates/               # 契约模板与 schema（task-packet / spec / state 示例）
-skills/                  # 10 个 SKILL.md（Agent Skills 标准）+ embed.go
-scripts/                 # npm 分发安装器（lark-cli 模式）
-drills/                  # 实证演练记录（403 降级、缺陷注入）
+
+面板、人工命令和 `flywheel_control` 模型工具复用同一组 Go 接口：
+
+```sh
+flywheel control start --task-dir /repo/docs/my-task --cwd /repo
+flywheel control status --task-dir /repo/docs/my-task --cwd /repo
+flywheel control stop --task-dir /repo/docs/my-task --cwd /repo
+flywheel control config --cwd /repo
+flywheel control doctor --task-dir /repo/docs/my-task --cwd /repo --probe
 ```
 
-## 任务目录（docs/<slug>/，目标仓库内，全部进 git）
+`start` 派生独立后台引擎，日志进入任务目录的 `orchestrator.log`；关闭面板或桌面不等于停止任务。`status` 只读。`stop` 向本次运行提交带随机 token 的停止请求，等待本次引擎退出受管调用栈、释放任务 lease 后才保存停止状态；不按文件里的 PID 盲目发送信号。引擎只管理本次拥有的进程组；已观测的 `CleanupError` 仍保留在证据和指标中、阻止交付，需要按错误记录处理，`stopped` 不代表任意逃逸进程已清理。停止等待最长 45 秒，桌面入口预留 60 秒。
+
+控制接口始终返回一个 protocol 1 JSON；`ok` 表示控制操作成功，任务是否完成应看 `state.status`。`config` 返回 `configuration`，`doctor` 返回 `diagnostic`；诊断有阻断项时保留完整报告并返回退出码 1，不能当成空白传输错误。若启动就绪超时，后台引擎可能仍在加载：先刷新状态和查看日志，不要另起重复任务。
+
+原有前台／单步 CLI 仍可使用；这些命令应在目标仓库根目录运行：
 
-生成时（/skill:flywheel-new）：`spec.md`（编号需求）+ `task-packet-*.md`（契约）+ `state.json`（初始状态）+ `flywheel.config.json`（法定配置表）。
+```sh
+flywheel run docs/my-task
+flywheel run docs/my-task --pause-before review
+flywheel run docs/my-task --only execute --packet M01-T01
+flywheel run docs/my-task --only verify --packet M01-T01
+flywheel status docs/my-task
+flywheel stop docs/my-task
+```
+
+`--only` 与 `--pause-before` 不能同时使用。前台 `run` 的退出码为 0 成功、1 用法／运行错误、3 升级／预算／单步失败、143 中断；控制命令的操作失败返回 1。
 
-运行后逐渐多出：
+### 已安装的 skills
 
+```sh
+flywheel install-skills
+flywheel install-skills --project /path/to/project
+flywheel skills list
+flywheel skills read flywheel-new
 ```
-reports/<packet-id>.done.json   # 每个单元的 done-report（executor 自报，三级证据之一）
-metrics.jsonl                   # 每次 spawn 一条：模型/harness/token/成本/缓存命中/耗时/错误码
-retro.md                        # 单元完成行 + 里程碑汇总（§5.3 字段）
-inbox.md                        # 升级叫人的入口（正常应为空）
-triage-inbox.md                 # intake 候选（跑了 flywheel intake 才有）
-garden-proposals.md             # garden 提案（跑了 flywheel garden 才有）
-approvals/<packet-id>.json      # live 凭证任务的人工批准文件（需要时）
-orchestrator.pid / orchestrator.log   # 运行中的进程文件与日志
+
+一条命令安装已包含全部 10 个 skills。默认把 Go 内嵌快照安装到 `~/.agents/skills`，`--project` 改为项目的 `.agents/skills`；上述命令可用于补装、检查或显式安装项目范围的副本。
+
+每个快照保存带文件内容 hash 的 `.flywheel-snapshot` 清单。重跑先校验当前树：未改过的自有快照可更新，相同内容跳过；用户修改、新增／删除文件、链接或未标记目录都保留并报告冲突。更新按每个 skill 暂存、rename 替换，失败时回滚，不会因为存在一个标记就覆盖用户内容。旧纯文本标记仅在整棵目录与当前内嵌内容一致时迁移。冲突恢复见[升级教程](docs/getting-started.md#8-升级排错与卸载)；`--force` 只用于源码 `--link` 模式，不能绕过默认快照保护。
+
+安装同时会在全局配置不存在时生成默认配置，已有配置保留。源码开发者才使用 `--link`。skills 只是 CLI 操作按钮，宿主的发现规则和调用语法按其配置使用，不能承担重试或状态机逻辑；安装成功不等于所有宿主已经发现它们。可用按钮涵盖 new、run、plan、exec、review、verify、status、stop、intake、garden。
+
+## 5. 什么才算完成
+
+执行者可以一起修改实现、单测和回归测试；冻结验收通过 packet 的 `boundaries.must-not-touch` 或配置的 `protected-test-patterns` 显式保护。100% 覆盖率仍是本项目的门禁，断言是否有效由验收和独立评审共同检查。
+
+L1 在命令前后检查候选身份。验收过程中代码或契约变了，即使命令 exit 0 也不能继续交付。Review 同样必须针对当前候选；最终 L2/L3 与 Judge 还会核对主 checkout 的前后身份。正常完成需要代码实际提交、合并到本地目标 checkout，并确认提交后的 Git tree 与已验证候选一致；commit hook 修改 index 或文件也不能绕过这一步。任务最终完成前再次检查持久化状态，重启不会把上次验收留下的未提交副作用当成交付。
+
+Plan 只能直接修改任务目录内的 Spec 和 packet。它若修改外部验收、实现或运行配置，引擎保留现场并停止，不自动提交或丢弃。修订后的契约 fingerprint 会跨重启保存：旧 completed 单元的契约或验证策略改变时重新打开，早先已关闭的里程碑也会被重新调度。同一 run 对一个里程碑最多访问 3 次，再反复重开就升级给人。最终要求所有当前契约单元完成、里程碑关闭。
+
+提交或合并失败保留工作区。交付已持久化而仅工作区清理失败时，可以完成，但必须保留 worktree 引用和 `cleanup-error`，供后续处理。非 Git 演练不能完成。Flywheel 任务引擎本身不会自动 push、发布或合并远端 PR；这些仓库管理操作按使用者的授权另行执行。
+
+任务目录保存契约、状态、报告、复盘、升级记录和指标。`state.json` 只有 Go 可以写；执行报告先写在单元 worktree 内，再由 Go 校验并归档。日志、PID、运行锁、停止请求和其他易变运行文件排除在自动提交之外。
+
+## 6. 验证与当前边界
+
+```sh
+make test
+make coverage
+make quality-gate
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+npm test
+npm run build:npm
+FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
 ```
 
-## 测试
+Go 的交付门禁是 vet、格式检查与**逐函数 100% statement coverage**；statement coverage 不等于分支覆盖或真实模型质量。测试使用真实 Git、hook、index、worktree、子进程与协议桩，默认不需要账号或模型调用。
 
-```bash
-make test            # go test ./... 全部包
-make coverage        # 覆盖率门禁（cmd 桩除外，逐函数 100%）
-make quality-gate    # vet + fmt-check + coverage（CI 同款）
+DSH 检查包括离线 worker 生命周期、事件与 usage 折叠、控制入口一致性、真实 React DOM 交互、Go → Node → SDK 协议桩，以及前轮官方 npm rc.5 的真实 Host 注册和 SDK 初始化／关闭。npm 检查覆盖安装与取消、同版包解析、GUI 安装记录及发行门禁；`test:install` 使用构建出的六个真实 npm 包和隔离环境验证安装，DSH 命令由协议桩替代，不使用用户 profile 或模型账号。
+
+React DOM 与安装协议桩不代替 Mac 桌面验证。当前 Linux 环境没有可用的完整原生沙箱，SDK probe 在 prompt 前正确拒绝；这项结果证明拒绝路径，不能冒充 Mac Seatbelt 成功。
+
+**尚需在用户 Mac 验证**：桌面安装与 UI 渲染、Seatbelt 探针、GUI 环境中的 CLI／凭证可见性、真实 Flash/GPT/Kimi/Codex 响应，以及真实机器重启后的恢复。当前不支持 DSH worker resume、附件传输、外部 Codex Pro adapter 消费或自动多 agent Teams 调度。
+
+## 7. 开发与备用构建
+
+普通用户使用上面的 npm 安装流程。开发者需要 Go 1.27 或更高、Node.js 22 或更高及 Git，在仓库根构建：
+
+```sh
+go build -o ./bin/flywheel ./cmd/flywheel
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+npm run build:npm
 ```
 
-单元测试覆盖率 100% 是硬门禁（用户确立的设计纪律：反向驱动松耦合与可注入性）；
-v0.18 起按**逐函数**检查——任何函数 <100% 直接失败，不再只看总数。mock 驱动覆盖全部编排逻辑，
-可在无凭证环境完整运行；verify/watchdog 用真实 git 与真实子进程组测试。
+`build:npm` 先构建 worker，再在隔离目录打包 meta、四个平台包和 DSH 插件，输出到 `dist-npm/`。六个包版本必须一致；本地 tarball 和 Actions artifact 用于开发、验证或备用分发，不是日常用户的安装入口，也不等于已签名的 Mac 安装程序。源码构建及开发模式 skills 说明见[教程末节](docs/getting-started.md#9-开发与备用构建)。
 
-## 文档入口
+## 文档与代码入口
 
-- [docs/design.md](docs/design.md) — 权威设计文档（§2 设计铁律是最高约束）
-- [AGENTS.md](AGENTS.md) — 仓库工作宪法（构建/闸门/硬契约）
-- [drills/](drills/README.md) — 实证演练记录与环境事实基线
+| 路径 | 内容 |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | Mac 安装、首个任务、配置迁移与排错 |
+| [docs/design.md](docs/design.md) | 权威设计、不变量、闭环与边界 |
+| [docs/configuration.md](docs/configuration.md) | profiles、阶段覆盖、provider／channel 与预检语义 |
+| [docs/plans/2026-11-01-dsh-integration.md](docs/plans/2026-11-01-dsh-integration.md) | 本轮实施和验收记录 |
+| [docs/plans/2026-11-01-model-profiles-preflight.md](docs/plans/2026-11-01-model-profiles-preflight.md) | 配置、预检与面板后续实施计划 |
+| [docs/plans/2026-11-01-npm-installation.md](docs/plans/2026-11-01-npm-installation.md) | npm 安装、GUI 入口与发行验证计划 |
+| [plugins/dsh/README.md](plugins/dsh/README.md) | DSH 安装、独立 SDK profile 与本机检查 |
+| [plugins/dsh/PROTOCOL.md](plugins/dsh/PROTOCOL.md) | worker v1 请求、事件、终态和 usage 契约 |
+| [templates/](templates/) | 契约、配置模板与 JSON Schema |
+| [internal/machine/](internal/machine/) | 状态机、契约修订、证据、生命周期 |
+| [internal/drivers/](internal/drivers/) | DSH／Kimi／Codex 与保留的兼容 driver |
+| [internal/verify/](internal/verify/) | 确定性验收、边界、Git 持久化与工作区 |
+| [docs/design-history-v0.24.md](docs/design-history-v0.24.md) | 历史设计与当时的研究、环境记录 |

package/bin/flywheel-dsh-worker.js

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

package/bin/flywheel.js

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

package/bin/runtime.js

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