@ckanner/flywheel 0.32.1 → 0.33.1

package/docs/en/getting-started.md

@@ -5,10 +5,17 @@
 Install Flywheel, connect the backends you intend to use, then run a small task.
 This guide follows the current repository. Check the installed version and the npm
 version you choose; a merged change does not update an existing installation.
-Keep the CLI, platform packages, and DSH plugin at one version.
+Keep the CLI, bundled engines, and DSH plugin at one version.
 
 For the complete path through task branches and PR review, see [Workflow](workflow.md).
 
+From 0.33, `@ckanner/flywheel` is one complete package: CLI, DSH view/workers,
+embedded skills and four platform engines. No separate platform package or first-run
+engine download is needed. When upgrading from 0.32.x, quit DSH before running the
+installer; it replaces the old desktop package registration and preserves your
+configuration and histories. Reload DSH after setup. Existing old npm versions
+remain available for historical installations.
+
 ## 1. Prepare the environment
 
 | Requirement | Purpose |
@@ -146,7 +153,7 @@ capabilities or merge full worker histories into the parent trajectory. See the
 
 Setup writes `~/.config/flywheel/npm-launcher` and an installation record containing
 absolute Node/CLI paths and the checked DSH entry. An explicit `flywheelBinary`
-overrides the managed launcher. Missing records can use legacy PATH lookup;
+overrides the managed launcher. Without a record, the installed package uses its bundled CLI;
 invalid records or modified launchers fail visibly.
 
 After moving Node/the npm prefix or installing missing tools, rerun

package/docs/en/releasing.md

@@ -2,70 +2,59 @@
 
 [Documentation](../README.md) · English · [简体中文](../zh-CN/releasing.md)
 
-This runbook is for maintainers. Users should follow
-[getting started](getting-started.md). A source commit, GitHub Release, or
-successful `npm pack` does not establish that a version is available from npm.
-Actual releases and verification limits belong in the
-[validation records](../validation/README.md).
+This runbook is for maintainers. Users should follow [getting started](getting-started.md).
+A commit, tag, or successful pack is not a registry release. Record actual source,
+installation, registry and desktop results separately in [validation records](../validation/README.md).
 
-## 1. Release identity and prerequisites
+## 1. One complete package
 
-One release contains six packages at the same exact version, published in
-the following order:
+From 0.33, publish only **`@ckanner/flywheel`**. One tarball contains:
 
-| Order | Package | Contents |
-| --- | --- | --- |
-| 1–4 | `@ckanner/flywheel-{darwin,linux}-{arm64,amd64}` | Four platform-specific Go binaries |
-| 5 | `@ckanner/dsh-plugin-flywheel` | Desktop plugin and workers |
-| 6 | `@ckanner/flywheel` | User-facing CLI, installer, and documentation |
+- The CLI and explicit installer in `bin/` and `npm/`.
+- DSH host, client and machine workers in `dist/`; the Node modules use `.mjs`.
+- Four Go executables under `native/{darwin,linux}-{arm64,amd64}/flywheel`.
+- `native/manifest.json`, identifying their version, sizes and SHA-256 hashes.
+- Embedded skills/templates, paired guides, the MIT license and third-party notices.
 
-The meta package pins all five dependencies. Every Flywheel package declares
-MIT and includes its `LICENSE`; the plugin retains third-party notices.
-The Codex Pro dependency is pinned to 0.9.0 and bundled from the
-[recorded source candidate](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md). Claude Code
-Pro 0.4.0 remains an optional peer, not a seventh Flywheel release package.
+The launcher selects and verifies its own platform binary; it does not download a
+binary on first use or resolve an old platform/worker package. `plugins/dsh` is a
+**private source/build/test harness**, never a second publication target. The four
+old platform packages and `@ckanner/dsh-plugin-flywheel` are historical releases;
+this flow neither uploads new versions of them nor unpublishes their existing bytes.
 
-Use Git, Go **1.27**, Node **24.22.1**, and npm **12.2.1**, matching the
-repository workflows. The end-user Node requirement is lower; the release
-toolchain is deliberately fixed. The reviewed source must be clean, all six
-versions must agree, and the exact `vX.Y.Z` tag must point to HEAD. Never move
-an existing release tag or replace already-published package bytes.
+Codex Pro 0.9.0 remains bundled from its [reviewed source candidate](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md).
+The root and source-harness locks retain that tarball's real integrity. Claude Code
+Pro 0.4.0 is an optional external peer. Provider CLIs and account credentials are
+not included. Ordinary npm installation only places files; `install`/`setup` owns
+user setup, with no profile or credential changes hidden in postinstall.
 
-`candidate.json` records the source commit, tree, snapshot SHA-256, and each
-tarball's SHA-512 integrity. Build once, then verify, test, and publish those
-same tarballs. A candidate with `source.dirty: true` is for development only.
+## 2. Source and validation
 
-## 2. Validate the release source
+Use Go **1.27**, Node **24.22.1** and npm **12.2.1**, matching the workflows.
+Require reviewed source, a clean checkout, and `vX.Y.Z` pointing at exact HEAD.
+Never move a release tag, relabel a dirty candidate, or rebuild different bytes
+for an already uploaded version.
 
-Run the checks required by the [contribution guide](contributing.md) and
-the current [CI workflow](https://github.com/ckanner/flywheel/blob/main/.github/workflows/ci.yml):
+Run applicable [contribution checks](contributing.md):
 
-| Area | Required evidence |
+| Area | Evidence |
 | --- | --- |
-| Go | `make quality-gate` and the workflow's core-package race checks |
-| DSH plugin | Locked dependency installation, build, and behavior tests |
-| Backend boundary | DSH, Codex Pro, and Claude Code Pro offline bridge tests |
-| npm | `npm test` and real installation of the six-package candidate |
-| Native CLI | Build, version/help, and JSON configuration checks |
-| Session policies | `npm run test:sessions` with the built native binary |
-| Documentation | Links, language parity, packaged guides, and licenses |
-
-Prepare the exact optional Claude tarball using the workflow's pinned source
-SHA and SHA-256 check. For plugin/bridge tests, the workflow temporarily
-installs it as a development dependency and restores the source manifests.
-Export `FLYWHEEL_CLAUDE_CODE_PRO_TARBALL` as the absolute path to that verified
-tarball before running candidate installation tests.
-An absent optional peer does not count as a passed Claude backend check.
-
-These checks use isolated profiles and offline model fixtures. They do not
-establish live account readiness, model quality, or physical desktop layout.
-Record the actual platforms tested; cross-compilation does not establish
-runtime verification on the target platform.
-
-## 3. Build one candidate
-
-From the clean checkout of the reviewed release tag, run each command and
-stop on failure:
+| Go changes | `make quality-gate`, retaining per-function 100% coverage, and core race checks |
+| DSH and workers | Locked source-harness build/tests and real Go→Node offline bridges |
+| npm and release | `npm test`, one complete candidate build, and actual installation of that tarball |
+| Native/session changes | Native CLI checks and `npm run test:sessions` as applicable |
+| Migration | Fresh install, split-package upgrade, failure/rollback/cancellation and repeat setup |
+| Documentation | Paired guides, valid links, packaged documents and licenses |
+
+Install the exact reviewed Claude source tarball for its backend tests; absence
+or a skipped optional peer does not count as a pass. Set
+`FLYWHEEL_CLAUDE_CODE_PRO_TARBALL` to that tarball before installation tests.
+Source tests use isolated homes/profiles and offline model fixtures. They do not
+prove live account access, model quality, or physical desktop behavior.
+
+## 3. Build once and test the same artifact
+
+From the final clean tagged checkout, stop on any failure:
 
 ```sh
 FLYWHEEL_RELEASE_VERSION=$(node -p "require('./package.json').version")
@@ -76,132 +65,101 @@ node scripts/release-publish.js verify-candidate --directory dist-npm --source-s
 FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
 ```
 
-Set the Claude tarball environment variable described above before the final
-command. The build installs locked plugin dependencies inside an isolated
-source snapshot, with lifecycle scripts disabled, then builds the workers and
-four Go binaries. It does not reuse the caller's `node_modules` or `dist`.
-Root-level `npm install` is not required.
+The builder captures an isolated source snapshot, installs both locked dependency
+sets without lifecycle scripts, builds the plugin and four native binaries, and
+packs the root exactly once. It never reuses caller `dist/` or `node_modules/`.
+Candidate **format 2** records the source commit/tree/snapshot, dirty status and
+one tarball's SHA-512 integrity. Verification also opens the tarball and checks
+all four native hashes, required entry points, licenses and bundled adapter identity.
+Linux and macOS must install the same candidate, not separately repack it.
 
-Preserve `dist-npm/`, its `candidate.json`, source identity, toolchain versions,
-and validation results. Verify all six packed MIT licenses and the root and
-plugin language editions. If source changes before any upload, prepare a new
-candidate from the new reviewed source. After any upload, retain the original
-candidate and follow the recovery rules below.
+Keep `dist-npm/`, `candidate.json`, toolchain identity and results. Source changes
+before upload require a new reviewed candidate. After upload, retain those exact
+bytes; a source fix requires a new version.
 
-## 4. GitHub Actions publication
+## 4. Automatic GitHub Actions publication
 
 Pushing the reviewed tag triggers [publish.yml](https://github.com/ckanner/flywheel/blob/main/.github/workflows/publish.yml).
-An existing tag can also be supplied to its manual dispatch. Linux and macOS
-verify the same candidate artifact; the publish job refreshes remote refs and
-requires the tag to still identify the checked source.
-
-GitHub access and npm publication rights are separate. Configure trusted
-publishing for each of the six packages with owner `ckanner`, repository
-`flywheel`, workflow `publish.yml`, and no environment unless the workflow is
-changed to use one. Both **npm publish** and **npm dist-tag** permissions are
-needed. The workflow also supports an authorized `NPM_TOKEN` fallback.
-
-New packages require npm's initial package-creation authorization before
-their trusted publisher can be configured. Use the normal authorized npm
-flow; do not upload different placeholder bytes under the release version.
-See the official [trusted publisher](https://docs.npmjs.com/trusted-publishers/)
-and [dist-tag](https://docs.npmjs.com/adding-dist-tags-to-packages/) documentation
-for account setup. `npm whoami` identifies an account, not its publishing rights.
-
-Publication requires explicit repository visibility: `public` requires
-provenance; `private` disables unsupported private-source provenance. Choose
-the repository's actual visibility. Publishing a package does not change
-repository visibility, and OIDC authentication is separate from provenance.
-
-## 5. Publish locally from private source
-
-A maintainer can build from a normal Git checkout. With the current release
-policy, new uploads from a public repository must use section 4: the publisher
-requires provenance, which npm generates only in a supported cloud CI/CD
-environment, not an ordinary local browser-login session. See
-[npm provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
-The local upload example below applies only when the source repository is
-actually private. Do not label a public repository private to bypass this
-requirement. No downloaded archive is required. Complete source review and
-the checks above first. If Actions cannot run, record the maintainer's
-authorization, actual local results, and checks that were not performed;
-do not report unavailable CI as passing.
-
-From the same clean tagged source and its original candidate:
+Manual dispatch accepts an exact existing tag. Build and both OS checks precede
+the publication job, which rechecks source and tag identity.
 
-```sh
-npm login --auth-type=web --scope=@ckanner --registry=https://registry.npmjs.org/
-npm run release:local -- --repository-visibility private
-```
+Configure **one** npm Trusted Publisher for `@ckanner/flywheel`:
 
-Complete the normal browser/2FA prompts in the terminal. The publisher
-requires a TTY; do not pipe its output through `tee`.
-
-`release:local` performs these steps:
-
-1. Recheck clean source, exact local and remote tag, tree, snapshot, candidate
-   manifest, and package integrity.
-2. Run candidate installation, then verify the source and candidate again.
-3. Upload platform packages, plugin, and meta under `candidate-X-Y-Z`.
-4. Install the exact version from the official npm registry.
-5. Recheck source and remote tag, promote `latest` in the same order, and
-   verify all six tags and integrities.
-
-The command uses the repository's existing release checks. Only npm publish
-and dist-tag writes inherit terminal I/O; registry queries retain strict JSON
-parsing and bounded timeouts. The command does not log in, create or move
-tags, or change account security settings.
-
-For a reviewed older release that needs newer tooling, `--source-directory`
-can point at its exact tagged worktree and `--directory` at its original
-candidate. The source defaults to the tooling checkout; the candidate
-directory defaults to `dist-npm/` inside the selected source directory. Explicit
-relative paths resolve from the invocation directory. Do not copy newer
-tooling into old release source or rebuild an already-published version.
-
-## 6. Visibility, promotion, and retry behavior
-
-Packages first use the candidate tag. All exact versions and integrities must
-be visible and registry installation must succeed before `latest` moves.
-Platform packages are promoted first, the plugin next, and the user-facing
-meta package last. npm has no atomic six-package tag transaction.
-
-Only a structured E404 means a queried version is absent. Authentication,
-transport, cancellation, malformed output, or missing integrity fails the
-operation. Registry queries accept the supported scalar and single-element
-array response shapes; multiple results are rejected.
-
-After upload, visibility checks have a 180-second budget per package, with
-E404 backoff from 2 seconds to at most 15 seconds. Each read is bounded by
-30 seconds and the remaining budget. Promotion verification uses the same
-bounded approach for `latest` and integrity. It repeats reads, not writes,
-and refuses a newer `latest`, conflicting integrity, or invalid version.
+| Setting | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization/user | `ckanner` |
+| Repository | `flywheel` |
+| Workflow filename | `publish.yml` |
+| Environment | Empty, matching the workflow |
+| Permissions | Allow `npm publish` and `npm dist-tag` |
+
+The publication job uses OIDC only, with an empty npm user config; it does not
+fall back to a stored `NPM_TOKEN` or interactive browser authentication. The
+account's 2FA policy remains independent. Creating the trust relationship can
+require a maintainer security-key confirmation; that is initial setup, not a
+per-release approval. npm may mark a new connection pending validation until its
+first real CI publication. Saved settings or `npm publish --dry-run` do not prove
+that publication has succeeded. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+The public source repository requires provenance. Private-source publication
+explicitly disables unsupported provenance; it must never falsely claim that a
+public repository is private. If Actions is blocked by billing or another runner
+failure, report that separately from local checks. A successful CI verification
+of existing packages is not proof that fresh OIDC writes work.
+
+## 5. Publication order and recovery
+
+Publish the complete tarball under `candidate-X-Y-Z`, verify its exact registry
+integrity, and run the actual registry installation before moving `latest`.
+Finally verify `latest` and integrity. There is one package upload and one tag
+promotion, both authenticated by the CI identity; no six-package transaction is needed.
+
+Only a structured E404 means a version is absent. Authentication, transport,
+cancellation, malformed JSON and mismatched integrity fail visibly. Existing
+versions must match the saved candidate, and a newer `latest` must never be downgraded.
+Visibility checks retain their bounded 180-second window and repeat reads, not writes.
+If npm has accepted an upload but is still validating it, retain the artifact and
+wait for the exact version to become visible before resuming.
 
 | Failure | Recovery |
 | --- | --- |
-| Authentication or browser approval | Resolve the authorized npm login; retain the candidate. |
-| Some packages uploaded | Retry the original candidate; existing versions must match its integrity. |
-| Registry visibility timeout | Preserve the artifact and retry after the external issue is resolved. |
-| Installation or tag promotion failed | Resume with the same candidate; do not downgrade a newer `latest`. |
-| Source must change after upload | Use a new uniform version and a new reviewed tag. |
-| Original candidate is missing | Recover it; do not assume a rebuild has identical bytes. |
-
-With Actions, rerun failed jobs using the original artifact. Locally, rerun
-the final `release:local` command against the preserved source and candidate.
-
-## 7. Record completion
-
-Publication is complete only after all six exact versions and integrities,
-registry installation, and final `latest` checks have passed. Record those
-results separately from source review, local tests, CI, and desktop acceptance.
-For an additional exact-version installation check:
-
-```sh
-FLYWHEEL_NPM_VERSION=X.Y.Z npm run test:registry
-```
-
-Replace `X.Y.Z` with the released version. Record source SHA, candidate
-identity, actual platforms, failures/retries, and remaining limits in a dated
-validation record and release notes. See the
-[0.30.2 release record](../validation/2026-11-11-release-0.30.2.md) for a
-historical example; it is evidence for that release, not a live registry status.
+| OIDC authorization | Verify the exact package/repository/workflow and both allowed actions |
+| Interrupted upload | Read registry identity first; resume the same saved tarball |
+| Registry visibility timeout | Preserve accepted bytes and retry read-only verification |
+| Registry installation or promotion fails | Resume the same candidate; keep newer tags intact |
+| Code must change after upload | Use a new version and reviewed tag |
+| Candidate is missing | Recover the original artifact; do not assume a rebuild is identical |
+
+For an explicitly authorized **private-source** emergency only, `npm run release:local --
+--repository-visibility private` retains source/tag/candidate/installation checks and
+normal interactive npm authorization. It requires a TTY. An older release must use
+its own tooling, exact tagged worktree and original artifact format. Do not invoke
+the new single-package publisher against historical format-1 six-package candidates.
+
+## 6. User migration and acceptance
+
+`npx -y @ckanner/flywheel@latest install` remains the entry point. Wait for active Flywheel tasks to settle and quit DSH before
+migrating a split installation. Setup installs and verifies the complete desktop
+package, then removes the old `@ckanner/dsh-plugin-flywheel` through the official
+DSH CLI and verifies only the new identity remains. It preserves user configuration,
+modified skills and task histories; it does not rewrite `state.json`.
+
+A custom file/git legacy source fails before desktop-profile mutation; earlier
+completed installer steps remain in the report. If migration fails, report
+its actual partial state. Roll back only a replacement added by this attempt when
+the original old package is still confirmed present. Cancellation does not start
+new rollback processes; retry reads the profile again and completes the remaining
+work. Never report success while both identities remain. Existing global launcher
+records and explicit `flywheelBinary` overrides retain their checks and precedence.
+Without a record, the installed plugin can resolve its own bundled CLI; Node still
+needs to be available to the host.
+
+A complete release record includes source/candidate/registry identities, installation
+results and limitations. Separately verify CLI, skills, the installed desktop package,
+configuration and the reloaded native view. Running tasks must not be interrupted just
+to claim desktop acceptance; record a pending reload when necessary.
+
+An existing managed launcher must match the installed package version. After updating
+only the DSH copy, run setup for that version to refresh the managed installation;
+a stale record is reported instead of mixing a newer view with an older engine.

package/docs/validation/2026-11-13-release-0.32.1.md

@@ -0,0 +1,83 @@
+# 0.32.1：DSH 兼容系列范围与发行
+
+用户在将桌面升级到 DSH 0.2.2-rc.3 后要求检查并修复 Flywheel，明确要求结束逐 rc
+修改版本白名单的方式。本次沿用已授权的发布与安装流程。
+
+## 原因与修复
+
+原生插件详情确认 0.32.0 被 `engines.dsh` 的精确白名单标为未运行。四项 SDK 探测
+也失败；直接读取无推理 worker 回执，确认 SDK 同样拒绝加载该包的权限确认组件，
+随后因缺少 `policy.json` 返回 TRANSPORT。没有通过版本豁免绕过此检查。
+
+0.32.1 将宿主范围改为 `>=0.2.1-rc.5 <0.3.0-0`。DSH 判断范围时包含预发布版本，
+因此 0.2 系列后续 rc／补丁可自动准入；0.3 系列及其预发布版保持拒绝。
+宿主提供的 optional DSH peer 范围同时覆盖已有预发布系列，测试依赖锁定真实发布的
+0.2.2-rc.3。运行时所需服务、权限回执、会话身份与清理检查均未删除。
+
+测试中的上游兼容检查实现与 DSH rc.3 源码
+`38a6a5c965aa99ab525161efb7cc5cf1fe62fced` 比对未发生变化。版本范围测试覆盖后续 rc、
+正式版及补丁版准入、最低版本以下和下一 minor 预发布版拒绝；同时验证 npm 的
+默认 prerelease 匹配规则。范围是兼容策略，不代表所有未来宿主均已实测。
+
+## 发行身份
+
+- 源码／标签 `v0.32.1`：`0b26f59f70030d5fe51cd65d37b7ac1e6e9047b3`。
+- Git tree：`7d22489891dddd9eb8414d683d74b68708d3b420`。
+- 源码 snapshot SHA256：`249b85f88c1a20caa228ebcd48f220b9e1e98e05a5f4c2efddc421d1c92b2719`。
+- 候选清单 SHA256：`2cf9a845b07bde0a1fb62a41b663e37eb5e39784e7bbdd787fd3c61421859851`。
+
+六包从干净源码隔离构建、打包一次，认证重试始终复用原始产物。
+全部 `candidate-0-32-1` 精确版本与 integrity 校验、官方 registry 安装通过后，
+再逐包提升 latest。最终六包 latest 及 integrity 均复核为 0.32.1。
+候选清单和原始 tarball 见 [v0.32.1 Release](https://github.com/ckanner/flywheel/releases/tag/v0.32.1)。
+
+## 实际检查
+
+| 检查 | 结果与范围 |
+| --- | --- |
+| 兼容范围回归 | 原实现 2 项失败、1 项通过；修复后 3/3 通过 |
+| macOS / Linux arm64 插件完整检查 | 各 304/304；旧 rc.5 宿主各 10/10；零跳过 |
+| 两平台跨进程桥接 | DSH、Codex Pro、Claude Code Pro 均通过，无跳过 |
+| 两平台 npm 单元与发行协议 | 各 142/142 通过 |
+| 同一正式候选安装 | macOS arm64、Linux arm64 各 10/10，无跳过 |
+| 官方 registry 真实安装 | 精确 0.32.1、原生 CLI、11 个 Skill 通过；桌面注册部分为 CLI 协议桩 |
+| 实际 rc.3 SDK | 隔离候选 worker 和安装后 worker 的四项无推理探测均 pass |
+| 安装内容完整性 | 入口包 151 文件、全局插件 106、桌面插件 106、当前平台包 3，与原始 tarball 逐文件一致 |
+| 已安装技能 | 11 个 Skill 的 13 个内容文件与发行 tag 一致 |
+
+`cmd/`、`internal/`、`templates/`、`skills/` 相对 v0.32.0 没有差异。
+本轮没有重跑未改变的 Go 全量覆盖率、核心 race 或会话实验；其精确源文件对应的证据见
+[0.32.0 发行记录](2026-11-13-release-0.32.0.md)。本轮重新运行了受 rc.3 测试依赖影响的
+插件、公开 SDK、桥接和实际安装检查。Codex Pro vendor integrity 保持不变；可选
+Claude 0.4.0 使用 SHA256 为
+`125951f39d27a87072a9dc20c622a19089ad7ba84b69ba6228e1fbb03f46f581` 的已审查原包。
+
+## 本机状态
+
+CLI 和 desktop profile 插件均已安装 0.32.1，安装报告 `ok:true`、`ready:true`。
+默认模板未改动；用户配置原始字节保持一致，SHA256 为
+`20fae2b10ad725bf5f7c06080201d1b37142f08ec74d835c053f7106d07006e9`。
+安装前七个配置、安装与 profile 元数据文件已备份并核对摘要，目录为
+`~/.config/flywheel/backups/pre-0.32.1-20261114T015927Z/`，后缀为 UTC 时间。
+未添加 0.32.1 的精确版本豁免，未修改用户账号或模型设置。
+
+**桌面重载与新版原生画布验收仍待完成。** 曾观察到上一轮会话结束，但正常退出前
+再次读取桌面时发现用户已启动新一轮对话，因而没有退出 DSH。磁盘安装和 SDK 探测
+不等于当前桌面进程已经换版；继续遵守用户先前“等现有任务结束后再重载”的要求。
+
+## 保留的失败与限制
+
+- 初次更新测试锁文件遇到 rc.2/rc.3 传递 peer 冲突；移除旧 DSH 测试依赖解析记录后
+  重新正常解析，没有使用 force 或 legacy-peer-deps。非 DSH 锁条目没有变化。
+- 首包与插件包曾发生 npm 认证会话失效（authId 404）。实际 registry 核对后续发，
+  未更换候选。首包被接受后超过 180 秒尚不可见，发行器按规则停止；其余无依赖
+  平台包上传使用相同源码、标签、候选及 integrity 前置检查，四个平台全部公开并
+  核对后才恢复标准发行器上传插件和入口包。
+- [发布 Actions 43469804204](https://github.com/ckanner/flywheel/actions/runs/43469804204)
+  和 [CI 43469804576](https://github.com/ckanner/flywheel/actions/runs/43469804576) 未通过。
+  发布 preflight 没有执行步骤；annotation 指明账号付款或 spending limit 问题。
+  本机验证不冒充 Actions 通过。
+- SDK 探测 `inferenceTested:false`；账号授权／额度、真实模型质量、全部任务恢复场景
+  和未来 DSH 版本的实际接口兼容性不由此建立。
+
+本记录为发行后文档，不移动 tag，不改写已发布 tarball。

package/docs/validation/2026-11-14-release-0.33.0.md

@@ -0,0 +1,49 @@
+# 0.33.0 单包正式发行与桌面验收
+
+[验证索引](README.md) · [单包工程验证](2026-11-14-single-package.md)
+
+## 正式身份
+
+- PR：[#45](https://github.com/ckanner/flywheel/pull/45)。
+- 标签：`v0.33.0`，源码 `ac1ed320c68f6a8a466005985264e65b5a72fad9`。
+- tree：`7e95a8219705354a3a26146facdd56182a971140`。
+- snapshot SHA-256：`707c11a714e300c62da9bd4d6d5dbf7cad8ea6c90c76a67a642e3aad298bfa78`，dirty=false，candidate format 2。
+- 唯一 npm 包：`@ckanner/flywheel@0.33.0`，tarball `ckanner-flywheel-0.33.0.tgz`，18,623,823 bytes。
+- tarball integrity：`sha512-cvXjIw9LblMJabnEHtPNjj34mbZdJVbwH/R38U+AUkpyxOKxbqzO/7kdV1IStOC+l+/r2mDWd8v1icdYG/ue6g==`。
+- candidate.json SHA-256：`d4bb51bf24f27a5d03cea7e78053d45cc7d265868286b1f0827144b3267edb15`。
+- [正式发布 workflow](https://github.com/ckanner/flywheel/actions/runs/43568347331) 构建一次，双 OS 使用原始产物；本机下载的 Actions ZIP 摘要也已核对。
+
+## 源码与候选验证
+
+PR CI 的 Linux 和 macOS 均通过，包括逐函数 100% Go 覆盖率、插件、桥接、实际 npm 安装和 36 条会话场景。
+PR 首次 macOS job 的 machine 测试包触发默认 10 分钟总超时；当时当前用例仅运行 2 秒。
+该用例本机连续 10 次通过，随后同提交、同候选、原断言和原时限复跑通过。
+保留[首次失败](https://github.com/ckanner/flywheel/actions/runs/43563991853/attempts/1)和[复跑通过](https://github.com/ckanner/flywheel/actions/runs/43563991853/attempts/2)，不声称累计耗时风险已被修复。
+
+正式标签的双平台验证均在首次运行通过：Go 全门禁、插件与兼容宿主、三项跨进程桥接、151 条 npm 检查、打包 Host／Client 10 条、安装 13 条、36 条会话场景；Linux 另通过核心 race。
+本机对下载的同一正式候选另通过 Host／Client 10 条和实际安装 13 条，无跳过。
+
+## 发布与安装回执
+
+正式 workflow 首次通过 OIDC 上传后，版本公开可见性超过 180 秒窗口，publish job 停止，未移动 latest。
+随后从 registry 核对到与候选一致的 SHA-512，仅重跑失败 job，复用原始 artifact；回执包含
+`Verified existing @ckanner/flywheel@0.33.0`，公开 npm 安装通过，OIDC dist-tag 更新及最终 latest 校验通过。
+未使用 npm token 回退或逐包浏览器认证；未重建或覆盖已接受版本。
+
+本机在 DSH 无活动会话后退出桌面并备份配置、安装记录及 profile 清单。CLI 和 desktop profile
+均升级至完整包 0.33.0，官方 CLI 移除旧插件注册；两处各 264 个文件与正式 tarball 一致。
+其他插件依赖、cordis 配置及兼容设置不变；pnpm 的 `minimumReleaseAgeExclude` 自动追加
+新包的精确版本，这是官方安装器产生的包管理元数据。全局配置与最新默认模板语义一致、
+原始字节不变，四项无推理 SDK 探测通过。真实账号推理未测。
+
+## 桌面验收失败与后续修复
+
+重载后视图出现，但任务与配置读取报 `generated Remote flywheelConsole/read field "sessionId" has no strict codec`。
+因此 **0.33.0 的桌面读取验收失败**，不能用源码／候选或 SDK 通过代替。
+
+客户端原来用 src-json 挂载只读 Remote，旧 renderer 测试模拟了 `$mount`，Host 测试则直接调用
+Gateway，遗漏真实 Client 注册。这一 descriptor 在 v0.32.1 源码中已经存在；不能据此次失败
+倒推旧版本曾完成该路径的真实验收。当前 DSH 0.2.2-rc.3 要求 strict 输入 codec。
+
+后续 0.33.1 保留单包结构，补充有实际校验的公开 codec 工厂，并让打包 Client descriptor
+通过真实 Client 和 Host Gateway。0.33.0 产物与标签保持不变；补丁的实际验收另行记录。

package/docs/validation/2026-11-14-single-package.md

@@ -0,0 +1,60 @@
+# 0.33.0 单包分发工程验证
+
+[验证索引](README.md) · [发行指南](../zh-CN/releasing.md)
+
+## 范围与身份
+
+基于 `63d8781ee1ece0cce443fa2e1ead62d1d6288817`，将 Flywheel 自身的六个发行包
+合并为一个 `@ckanner/flywheel@0.33.0`。`plugins/dsh` 保留为 private 源码测试区；
+CLI、Host、Client、worker 和四个平台引擎装在同一个 tarball，skills 和模板继续内嵌。
+不改 Go 状态机、模型默认值、权限或用户账号，不修改历史 npm 版本及其标签。
+
+开发候选：candidate format 2，dirty=true，snapshot
+`e2dfdcf243c0c77fdafc96f9c077e9059c2233d30e6eff3527434eecbd8d963a`，
+唯一 tarball `ckanner-flywheel-0.33.0.tgz` 为 18,621,751 bytes，integrity：
+
+```
+sha512-NJzZPwy6qBJaVBLwsw0xlfcKDkWMYmVkC7pQkVjd1h0jwmDZkqQP9UD9exo3PHaCu8fL4knRw9bYiVtwXEtnIA==
+```
+
+该候选仅用于工程检查；后续文档与 changelog 整理不回写此身份。正式发行必须从
+干净标签另建一次正式候选，双 OS 验证并上传原始 tarball。本记录不声明已发布。
+
+## 检查
+
+工具链 Node 24.22.1 / npm 12.2.1 / Go 1.27.3。Claude 使用已审查的真实 0.4.0
+源码包，SHA-256 `125951f39d27a87072a9dc20c622a19089ad7ba84b69ba6228e1fbb03f46f581`；
+Codex 0.9.0 维持 vendor 锁定及 bundle，未假设它们已在 registry 发布。
+
+- macOS 根 npm 单元及协议检查：151 通过，无跳过。
+- macOS 插件 304 通过，旧宿主兼容检查 10 通过，无跳过。
+- macOS 同候选：公开 Host／Client 10 通过，真实 npm 安装 13 通过，无跳过。
+  覆盖完整包入口、四引擎完整性、DSH SDK、Codex／Claude Machine、旧包迁移和重复安装。
+- Linux 非 root 容器：插件 304、旧宿主 10、根 npm 151、打包 Host／Client 10、
+  同候选安装 13 全部通过，无跳过；三项 Go → Node 桥接通过。
+- macOS 三项 Go → Node 离线桥接通过；Go 源码无改动，正式 CI 仍跑全量质量门禁。
+- 真实 DSH CLI 在隔离 HOME／DSH_HOME 完成旧 0.32.1 插件 → 完整包 → 移除旧名，
+  profile 最终只登记新包。该早期开发候选检查不代替最终正式候选和用户桌面验收。
+- 已改动且随包分发的 Markdown 相对链接检查通过；Git diff 空白检查通过。
+
+## 自审
+
+- 启动器只使用本包引擎和 worker，缺失、版本或摘要不匹配明确失败。
+- DSH 的模块 ID、Remote descriptor、bundle 与安装名一致；实际 tarball 的 `.mjs`
+  与客户端 bundle 经过真实公开 Host API 测试，而非只测源码区的 `.js`。
+- 迁移先安装并确认替代包，再移除旧名；损坏列表、定制来源、取消、部分失败均不报成功。
+  回退只移除已确认由本次新增且身份未变的替代包；预存或并发替换的包保持不动。
+- 显式 flywheelBinary 保持优先。完整包无受管记录时用自带 CLI；旧版受管记录必须
+  重新 setup，不混用新版界面和旧引擎。现有配置、skills 修改和任务数据保持原归属规则。
+- 正式 publish 使用 OIDC、同候选和 provenance；精确 registry 安装成功后才推进 latest。
+  保存 Trusted Publisher 设置不等于已完成首次自动发布，须以实际 CI 回执为准。
+
+## 初始失败及限制
+
+早期开发全量 npm 检查出现一次原有 registry 超时 fixture 的 pid marker 缺失；
+未改该用例、deadline 或断言，单独复查与后续全量 151 条均通过。此处保留初次
+失败，不据重跑断言其时序根因已消除。开发安装用例曾使用旧 `.js` 名及 macOS
+`/var` 别名断言，已分别更新为打包入口和物理路径后通过。
+
+尚未完成的交付项：精确提交 CI、正式标签候选、npm OIDC 发布／latest、用户 profile
+迁移与 DSH 重载后界面验收。离线协议检查不代表真实模型推理、计费或质量结论。

package/docs/validation/README.md

@@ -11,6 +11,9 @@ Historical records retain their original language and findings.
 
 | Date | Record |
 | --- | --- |
+| 2026-11-14 | [0.33.0 单包正式发行与桌面读取缺口](2026-11-14-release-0.33.0.md) |
+| 2026-11-14 | [0.33.0 单包分发工程验证](2026-11-14-single-package.md) |
+| 2026-11-13 | [0.32.1：DSH 兼容系列范围与发行（桌面重载待完成）](2026-11-13-release-0.32.1.md) |
 | 2026-11-13 | [0.32.0 正式发行与本机安装（桌面重载待完成）](2026-11-13-release-0.32.0.md) |
 | 2026-11-13 | [DSH 预热回执大小与 TTL 测试同步修复](2026-11-13-prewarm-receipts-and-expiry-tests.md) |
 | 2026-11-13 | [DSH 设置开关与最新工作台整合复核](2026-11-13-dsh-settings-controls.md) |

package/docs/zh-CN/configuration.md

@@ -581,7 +581,7 @@ full-access 核对 `danger-full-access`／`dangerFullAccess`，不将其称为
 
 | 环境变量 | 用途 |
 |---|---|
-| `FLYWHEEL_DSH_WORKER` | 可选 DSH worker 路径；npm 启动器通常解析同版本依赖 |
+| `FLYWHEEL_DSH_WORKER` | 可选 DSH worker 路径；npm 启动器通常解析自身包内的 worker |
 | `FLYWHEEL_DSH_BIN` | DSH 命令，默认 PATH 中的 `dsh` |
 | `FLYWHEEL_DSH_PROFILE` | SDK profile，默认 `sdk`，不能为 `desktop` |
 | `DSH_HOME` | DSH 自身解释的配置根目录 |