@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/en/model-policy.md

@@ -1,63 +1,155 @@
-# Reasoning effort and account selection
-
-[中文](../model-policy.md) · English
-
-Checked on 2026-11-05. This note separates documented capabilities, adapter behavior, engineering recommendations, and measurements. Official model documentation and request paths have been reviewed. **No representative Flywheel comparison of high, xhigh, and max has been run**, and no live user-account inference or quota check was performed. The defaults are editable starting points, not a measured optimum.
-
-## Why most bindings use high
-
-Seven of the eight stage/route bindings use `high`; Intake uses `low`. High matches the documented defaults for Kimi K3.1 Pro and DeepSeek Flash. GPT-6.1 Sol's API default is medium, so Flywheel explicitly requests a higher level. Astra's model page lists five levels without stating a universal API default. Sources: [Kimi models](https://www.kimi.com/code/docs/en/kimi-code/models), [DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode/), [Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol), and [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra).
-
-High provides an initial comparison baseline without starting every loop at maximum effort. More reasoning can help difficult tasks while adding latency and usage; it does not guarantee a better delivery on every task. OpenAI's [deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist) recommends representative evaluation before adopting xhigh/max for their additional cost and latency. That supports the evaluation method, not a claim that this project's defaults have already been benchmarked.
-
-## Effort values differ by backend
-
-| Current path | Checked capability | Flywheel request |
-|---|---|---|
-| GPT-6.1 Sol / Codex Pro 0.9.0 | Model supports `low/medium/high/xhigh/max`; machine API forwards effort | hard: high |
-| Sol and Astra / DSH ChatGPT provider | Models and checked provider catalog support `low/medium/high/xhigh/max`; serialized as `reasoning.effort` | Review and Judge: high |
-| Kimi K3.1 Pro / Kimi CLI | Native `low/high/max`, default high; thinking cannot be disabled | Plan, frontend, Garden: high |
-| DeepSeek Flash / DSH rc.5 | DSH accepts `off/low/high/max`, default high | ordinary execution: high; Intake: low |
-
-GPT supports xhigh and max; their absence from the defaults is a policy choice, not an interface limitation. These names are not a shared scale across providers. Kimi compatibility aliases xhigh/max/ultra resolve to native max. DeepSeek's generic API maps xhigh to high, while the DSH adapter used here rejects xhigh before that mapping because it accepts only the four listed values. Use max when explicitly selecting Flash's higher supported level. See the native model documentation above and DSH's [configuration](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/config.ts) and [serialization](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/serialize.ts).
-
-The ChatGPT provider snapshot is `388868f91bcdc05795fb94d21b868ded6d7219c9` (0.1.17): [dated model measurements](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/models/served.ts) and [request serialization](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/convert/request.ts). A catalog is not a live entitlement check for the user's account. The Codex Pro plugin name does not establish a separate server reasoning mode.
-
-## Stages worth comparing first
-
-These are **engineering recommendations inferred from stage responsibilities**, not measured performance results. This correction preserves effort choices; it adds no automatic escalation, effort-changing retry, or budget policy.
-
-| Stage | Baseline | Candidate comparison |
+# Models, reasoning effort, and accounts
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/model-policy.md)
+
+Flywheel selects a model through a stage or execution-route binding. The
+[default template](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json) is the source
+of truth for new configurations; an existing installation keeps its own
+configuration. These defaults are an editable baseline. The repository does not
+establish that they are the optimum for representative tasks, or that increasing
+reasoning effort improves every delivery.
+
+## Default bindings
+
+| Stage or route | Harness | Model | Access path | Effort |
+|---|---|---|---|---|
+| Plan | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+| Execute: default | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `high` |
+| Execute: frontend | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+| Execute: hard | `codex-pro` | `gpt-6.1-sol` | Codex login through the public machine API | `high` |
+| Review | `dsh` | `gpt-6.1-sol` | DSH `chatgpt` provider | `high` |
+| Judge | `dsh` | `gpt-6-astra` | DSH `chatgpt` provider | `high` |
+| Intake | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `low` |
+| Garden | `kimi` | `kimi-code/k3.1-pro` | Kimi Code subscription through the native CLI | `high` |
+
+The harness owns the agent/tool loop. A DSH `provider` selects its native LLM
+adapter, while a `channel` names the configured account/credential path. A
+`codex-pro` harness is not a DSH provider called `subagent_codex_pro`. Kimi uses
+its native CLI, not ACP. Auto, Quick, and Full do not change these bindings or
+increase effort automatically; see [Configuration](configuration.md).
+
+Claude Code Pro is available as an [optional backend](claude-code-pro.md), with
+no default stage or route assigned. Its profile uses an explicit native model
+and effort rather than an implicit replacement for another subscription.
+
+## Account selection
+
+The default and `subscriptions` preset use `deepseek-account` with
+`deepseek-flash`. Standard DSH desktop and SDK profiles under the same DSH home
+can share account authorization without an additional API key. Custom profiles
+must load the account service and adapter. Independent SDK calls still supply
+an explicit provider/model; changing the desktop chat model does not update
+Flywheel's bindings.
+
+`deepseek-official` is a separate API-key provider, selected only by explicit
+configuration. The default preset does not switch payment channels after an
+authentication or quota failure. User-configured fallback chains retain their
+own policy. ChatGPT and Kimi subscriptions likewise require the corresponding
+installed adapter or CLI and its supported login flow.
+
+Upgrades preserve existing user files. To adopt the subscription preset, inspect
+the effective complete configuration, preview the migration, then explicitly
+apply it as described in [Configuration](configuration.md). Restart the engine
+afterward; neither installing packages nor changing a desktop chat model
+migrates a running task.
+
+## Reasoning effort is backend-specific
+
+The following capabilities were checked for the documented integrations on
+**2026-11-05**. They are compatibility evidence for those snapshots, not a live
+catalog or an account-entitlement check.
+
+| Checked integration | Accepted request values | Notes |
 |---|---|---|
-| Intake | Flash low | high for ambiguous input or difficult merging/classification |
-| Plan | Kimi high | max for architecture, dependency, or acceptance-design problems |
-| Execute default | Flash high | max for difficult implementation or root-cause analysis; not xhigh |
-| Execute frontend | Kimi high | max for complex interaction state or cross-component consistency |
-| Execute hard | Sol high | prioritize xhigh comparisons; max for the hardest tasks |
-| Review | Sol high | xhigh for high-impact concurrency, consistency, or permission reviews |
-| Judge | Astra high | prioritize xhigh for high-impact milestone acceptance; max for the hardest cases |
-| Garden | Kimi high | low for routine organization; max for difficult cross-task synthesis |
-
-Hard execution tackles difficult implementation. Judge independently examines a whole milestone after L2/L3, making these two stages useful first comparisons. Changing every stage together makes the cause of any improvement harder to identify. OpenAI's [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) describes effort by task difficulty; applying that guidance to Flywheel's stages remains an inference.
-
-Change `thinking` in the effective complete configuration, inspect it, and restart the engine. Use `routes.hard.thinking` for hard only and `loops.judge.thinking` for Judge only. Stage overrides avoid changing every consumer of a shared profile. A task file with only those two fields is not a complete configuration and does not inherit the rest of the project file.
-
-For an actual comparison, hold the model, backend, context, task, and acceptance conditions fixed. Measure delivery success, first-pass acceptance, missed defects and false alarms, total time including rework, and input/output/reasoning/cache usage. Record observable subscription quota separately; unknown values remain unknown. API prices do not directly determine subscription task capacity.
-
-## Request evidence is not quality evidence
-
-Source and offline protocol tests establish field transmission and error behavior. SDK configuration acceptance or a successful machine-API request establishes acceptance at that interface. Independent effective-effort evidence and improved delivery quality require server evidence or actual task measurements.
-
-DSH `initialize` validates configuration but returns only serverInfo. Flywheel's `ready.reasoningEffort` echoes the request after initialization; it is not independent model-server attestation. Codex Pro separates `requestedEffort`, `accepted`, and unknown `effectiveEffort:null`. See the [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts) and [Codex Pro 0.9.0 protocol](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md). A no-inference doctor cannot establish account balance, real inference, or higher-effort benefits.
-
-## The funded DeepSeek account is the intended default
-
-Current source selects `deepseek-account` for Flash in defaults and the subscription preset. Standard desktop and SDK profiles can reuse account authorization under the same DSH home; an additional API key is unnecessary. `deepseek-official` remains a separate, explicitly chosen API-key provider, not an automatic fallback.
-
-Desktop login can initialize an account-model default, but independent SDK calls still need explicit provider/model values. Flywheel requests `deepseek-account` and `deepseek-flash`, preserving both the selected access method and the Flash-only choice. Authentication or quota failures are reported. The default preset has no cross-channel fallback; explicit user-defined fallback chains retain their existing policy.
-
-**Release and migration are separate:** 0.28.3 changes the embedded default to account access; 0.28.2 still embeds the API default. Upgrades preserve user configuration, so adoption requires 0.28.3 or later followed by explicit migration. See [Configuration](configuration.md#deepseek-account-and-api-key-providers) for credential-sharing conditions and the preview/apply workflow. No user credentials or running tasks were modified by this source change.
-
-## Optional Claude Code Pro
-
-Claude remains unassigned in the default model policy. The optional `claude-code-pro` harness accepts an explicit native model and low/medium/high/xhigh/max request; an installed CLI or account can reject a choice. No new model ranking or effort benchmark is implied. See [the adapter guide](claude-code-pro.md) for the companion 0.4.0 public API, full-access boundary, and usage semantics.
+| GPT-6.1 Sol / Codex Pro 0.9.0 | `low`, `medium`, `high`, `xhigh`, `max` | The machine API forwards the selected effort |
+| Sol and Astra / DSH ChatGPT provider | `low`, `medium`, `high`, `xhigh`, `max` | The provider serializes `reasoning.effort` |
+| Kimi K3.1 Pro / native CLI | `low`, `high`, `max` | Thinking cannot be disabled; compatibility aliases `xhigh`, `max`, and `ultra` resolve to native `max` |
+| DeepSeek Flash / checked DSH adapter | `off`, `low`, `high`, `max` | This adapter rejects `medium` and `xhigh` |
+
+Names do not form a common scale across providers. In particular, a generic
+API's compatibility mapping does not override the DSH adapter's own input
+validation. Use `max`, not `xhigh`, when evaluating Flash's higher supported
+level on this path. The adapter must reject an unsupported selection rather
+than silently choose another model or effort.
+
+Compatibility references: [Kimi model documentation](https://www.kimi.com/code/docs/en/kimi-code/models),
+[DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode/),
+[Sol model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol),
+[Astra model reference](https://developers.openai.com/api/docs/models/gpt-6-astra),
+[DSH DeepSeek configuration](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/config.ts),
+and [serialization](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/serialize.ts).
+The checked ChatGPT provider is 0.1.17 at `388868f91bcdc05795fb94d21b868ded6d7219c9`:
+[model catalog](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/models/served.ts)
+and [request serialization](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/convert/request.ts).
+
+## Choose and evaluate a baseline
+
+Seven of the eight default bindings use `high`; Intake uses `low`. Keeping a
+stable starting point makes comparisons attributable to a particular stage.
+The following candidates are engineering judgments based on stage
+responsibilities, not measured Flywheel quality results.
+
+| Stage | Candidate comparison |
+|---|---|
+| Intake | Compare `high` for ambiguous input, merging, or classification |
+| Plan | Compare `max` for difficult architecture, dependencies, or acceptance design |
+| Execute: default | Compare Flash `max` for difficult implementation or root-cause analysis |
+| Execute: frontend | Compare Kimi `max` for complex interaction state or cross-component consistency |
+| Execute: hard | Compare Sol `xhigh` first; evaluate `max` on the hardest tasks |
+| Review | Compare `xhigh` for concurrency, consistency, or permission reviews |
+| Judge | Compare Astra `xhigh` for high-impact milestone acceptance, then `max` where justified |
+| Garden | Compare `low` for routine organization and `max` for difficult cross-task synthesis |
+
+Change `thinking` in the effective complete configuration. For example, change
+`routes.hard.thinking` to affect only hard execution, or
+`loops.judge.thinking` to affect only Judge. A stage override avoids changing all
+consumers of a shared profile. Do not create an incomplete task configuration
+containing only these fields: configuration discovery selects one file rather
+than merging files.
+
+Hold the model, harness, context, task, permissions, and acceptance conditions
+fixed. Measure delivery success, first-pass acceptance, missed defects and false
+alarms, total time including rework, and input/output/reasoning/cache usage.
+Record observable subscription quota separately and preserve unknown values.
+API prices do not directly determine subscription task capacity. The
+[session evaluation guide](session-evaluation.md) describes the repository's
+paired experiment tooling; effort comparisons need their own fixed conditions.
+
+## Bounded model and effort experiments
+
+The optional [execution policy](configuration.md#bounded-execution-policy-opt-in)
+declares complete allowed bindings per route, including account, effort,
+permission and history mode. Auto/Quick/Full do not enable it. A confirmed
+repeated L1 stall may advance the declared experiment order within existing
+attempt/token budgets and an explicit switch limit. This deterministic rule
+does not prove the next model is better. Channel errors use separately declared
+fallbacks; neither mechanism may select an undeclared model or payment channel.
+
+When the single [JEV switch](jev.md) is enabled, a confirmed failure can also
+offer the already allowed bindings as decision candidates. The engine checks
+the frozen allowlist, permission, remaining attempts and switch budget before
+adoption. No extra JEV model-routing switch is required. Without an allowed
+alternative, the configured binding stays in use. A semantic choice is recorded
+as a choice, not as measured proof that the selected model is faster or better.
+
+Effort changes cold-start the role and record complete before/after bindings.
+Comparisons must include rereading, startup and actual known/unknown usage and
+cost. Offline tests run real engine repair and recovery paths with controlled
+driver results; they do not establish live model quality or speed. Use matched
+real tasks with frozen oracles before changing defaults or claiming savings.
+
+## Interpret configuration and quality evidence
+
+Source and offline protocol tests establish field transmission and error
+behavior. SDK or machine-API acceptance establishes acceptance at that interface.
+Independent effective-effort evidence and better delivery quality require
+backend evidence or actual task measurements.
+
+DSH `initialize` validates configuration but returns only server information.
+Flywheel's `ready.reasoningEffort` echoes the request after initialization;
+it is not independent model-server attestation. Codex Pro separates
+`requestedEffort`, `accepted`, and an unknown `effectiveEffort:null`.
+See the [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts)
+and [Codex Pro machine protocol](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md).
+A no-inference doctor cannot prove account balance, live inference, or the
+benefit of a higher effort setting.

package/docs/en/releasing.md

@@ -0,0 +1,207 @@
+# Releasing Flywheel
+
+[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).
+
+## 1. Release identity and prerequisites
+
+One release contains six packages at the same exact version, published in
+the following order:
+
+| 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 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.
+
+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.
+
+`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. Validate the release source
+
+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):
+
+| Area | Required 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:
+
+```sh
+FLYWHEEL_RELEASE_VERSION=$(node -p "require('./package.json').version")
+FLYWHEEL_RELEASE_SHA=$(git rev-parse HEAD)
+node scripts/release-preflight.js --version "$FLYWHEEL_RELEASE_VERSION" --tag "v$FLYWHEEL_RELEASE_VERSION" --json
+npm run build:npm
+node scripts/release-publish.js verify-candidate --directory dist-npm --source-sha "$FLYWHEEL_RELEASE_SHA"
+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.
+
+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.
+
+## 4. 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:
+
+```sh
+npm login --auth-type=web --scope=@ckanner --registry=https://registry.npmjs.org/
+npm run release:local -- --repository-visibility private
+```
+
+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.
+
+| 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.

package/docs/en/session-evaluation.md

@@ -1,8 +1,10 @@
 # Session quality policy and paired evaluation
 
-P4 provides two executable capabilities: bounded rebuilding based on confirmed facts, and paired experiments using three history policies on the same tasks. Rebuild thresholds default to disabled. The evaluator preserves original conditions and results, keeps missing usage unknown, and assumes no quality, cache, or speed benefit.
+[Documentation](../README.md) · English · [简体中文](../zh-CN/session-evaluation.md)
 
-See [configuration](configuration.md) for the policy and [recovery](session-recovery.md) for lifecycle and ledger semantics. Implementation entry points are the [quality policy](../../internal/machine/session_quality.go), [evaluator](../../scripts/evaluate-sessions.js), and [corpus preparer](../../scripts/prepare-session-evaluation.js).
+Flywheel supports bounded context rebuilding based on confirmed facts and paired experiments using three history policies on the same tasks. Rebuild thresholds default to disabled. The evaluator preserves original conditions and results, keeps missing usage unknown, and assumes no quality, cache, or speed benefit.
+
+See [configuration](configuration.md) for the policy and [recovery](session-recovery.md) for lifecycle and ledger semantics. Implementation entry points are the [quality policy](https://github.com/ckanner/flywheel/blob/main/internal/machine/session_quality.go), [evaluator](https://github.com/ckanner/flywheel/blob/main/scripts/evaluate-sessions.js), and [corpus preparer](https://github.com/ckanner/flywheel/blob/main/scripts/prepare-session-evaluation.js).
 
 ## Bounded rebuilding
 

package/docs/en/session-recovery.md

@@ -1,6 +1,27 @@
 # Interrupted calls and context quality
 
-This guide describes the P3/P4 source implementation. P1/P2 role-history continuation and saved-receipt consumption remain available. The new public contracts require **Codex Pro 0.9.0** or **Claude Code Pro 0.4.0**. Source readiness, npm publication, account access, and measured task outcomes are separate evidence.
+[Documentation](../README.md) · English · [简体中文](../zh-CN/session-recovery.md)
+
+Flywheel separates reuse of a role’s conversation history from recovery of an
+interrupted invocation. Fresh and scoped histories both retain invocation safety
+checks. Durable public-journal recovery requires **Codex Pro 0.9.0** or
+**Claude Code Pro 0.4.0**; DSH and Kimi retain their own supported recovery paths.
+
+## Resume an existing task
+
+Use the original task ledger and integration directory. Read its status, then
+request continuation through the normal engine entry point:
+
+```sh
+flywheel control status --cwd /repo --task-dir /repo/docs/my-task
+flywheel control start --cwd /repo --task-dir /repo/docs/my-task
+```
+
+The engine reconciles earlier calls before making another model request. A
+`pending` or `unknown` outcome can keep the task blocked; preserve its journals
+and diagnostics rather than deleting state or selecting a fresh session to
+force progress. A status response describes current facts, not permission to
+replay an unresolved call.
 
 ## Ownership
 
@@ -44,6 +65,49 @@ At `cleanup-confirmed`, before acknowledging, Go captures the post-call candidat
 
 A durable receipt without the Go candidate checkpoint may reconcile trustworthy usage while leaving business execution blocked. A proven pre-dispatch rejection may be treated as unexecuted only with confirmed cleanup and an unchanged original candidate and guard. Review/Judge contract and candidate checks remain mandatory.
 
+### Shared-checkout execution
+
+For shared-checkout execution, an Execute receipt fingerprints its declared write scope and binds that scope into the session identity. Independent peer changes do not discard a known invocation; changes within its own scope still reject stale receipts. L1, independent Review and collective delivery validate the entire combined candidate. Scoped receipts neither prove batch completion nor bypass unknown dispatch, outcome or cleanup.
+
+### DSH runtime preparation after a restart
+
+Optional `scheduler.prewarm` prepares a DSH Review runtime without a model prompt
+while deterministic checks run. Before starting it, Go saves a single
+`worker-prewarm` responsibility in task state, including the preparation identity,
+role/scope, binding and run. Its terminal receipt is private under
+`.control/prewarm/`; it is separate from a model invocation or passing Review.
+
+The complete terminal JSON is limited to 8 KiB after UTF-8 serialization, including
+escaped characters and the trailing newline. Long error diagnostics are shortened
+with a truncation marker; ordinary short errors and all identity, dispatch and
+cleanup fields remain intact. Diagnostic truncation does not relax any recovery
+check or turn an initialization failure into a safe-expiry fallback.
+
+A restarted engine never resumes that prepared worker. It may discharge the old
+responsibility only when the matching receipt proves that no prompt was submitted,
+SDK cleanup was confirmed, and both the recorded worker and its original process
+group have exited. Receipt publication synchronizes the file and its directory;
+recovery repeats those durability checks before clearing state. If no process was
+ever started, an explicit local no-process receipt can establish that fact;
+elapsed time or a missing PID cannot. Missing, oversized, corrupt or mismatched receipts, a
+live or unconfirmed process/group, or uncertain cleanup keep the task blocked.
+Turning prewarming off does not bypass reconciliation. After safe resolution,
+subsequent work follows the current configuration and its normal invocation checks.
+
+Within the same engine run, a safely expired unused runtime may fall back once to
+a cold invocation only before any formal start was attempted, with the same
+persisted invocation identity and its remaining deadlines. This is not restart
+reuse, a second billed model attempt, or a way around unknown effects. Cancellation,
+expired invocation deadlines, incomplete cleanup, or untrusted output prevent that
+fallback.
+
+Creating the first preparation record advances `state.sessions.version` to **3**
+and later operations retain that version. This storage compatibility marker makes
+older engines reject a task whose cleanup responsibilities they cannot interpret.
+The new engine still reads versions 1 and 2. `sessions.policy-version` remains 1;
+worker and lifecycle protocols retain their separate version contracts. Do not
+edit the storage version or delete receipts to force a downgrade.
+
 ## Accounting and budgets
 
 Consumed invocations do not create another model request or call count. If an unknown invocation later yields trusted usage, Go appends an auditable correction tied to the same call, provider, original day, and lifetime totals. Recovery does not recreate an expired daily bucket.
@@ -54,7 +118,7 @@ Unknown is not zero. Rebuilds, role overrides, new workers, and Quick-to-Full tr
 
 ## Bounded context rebuilds
 
-`sessions.roles` can override fresh/scoped independently for Plan, Execute, Review, and Judge. Other roles inherit the global mode. See [session configuration](configuration.md#session-policy-history-reuse-and-invocation-safety).
+`sessions.roles` can override fresh/scoped independently for Plan, Execute, Review, Judge, and judge-panel. Other roles inherit the global mode. See [session configuration](configuration.md#session-policy-history-reuse-and-invocation-safety).
 
 Optional `sessions.quality` supports:
 
@@ -68,16 +132,34 @@ All thresholds default to disabled. They may rebuild only after the previous cal
 
 A rebuild records its reason and generation and hands over current contracts, workspace, valid reports, verification, and structured feedback. It never imports another role's private transcript or issues an unmetered model-compression call. A returning Reviewer must still inspect the entire current candidate.
 
-## Paired P4 evaluation
+### Verified incremental inputs
+
+Explicit `sessions.context:"verified-incremental"` permits Execute to reuse a
+confirmed same-role stable contract after Go verifies that the consumed receipt
+proves `dispatched` and `completed`, together with the prompt version, current
+contract and readable context/cache file digests. A safe admission rejection or
+failed/cancelled turn may preserve the old thread, but cannot prove delivery of
+that turn's newly prepared authority; the next call resends full input. New
+input carries feedback, candidate identities, attempt and references. Changed or
+unavailable authority, legacy missing checkpoints and invalid context receipts
+select full input. The decision and reason are saved on the role record. Review
+and Judge keep full current inputs and never inherit Executor private history.
+
+An opt-in [execution policy](configuration.md#bounded-execution-policy-opt-in)
+can select another complete allowed binding. Every switch starts a new history
+generation, including effort-only changes. Explicit session mode is also part
+of the binding. Unknown/pending invocations reconcile first; fresh context cannot
+authorize replaying uncertain effects. Switch records separate quality upgrades
+from channel fallback and preserve the original task and packet budgets.
+
+## Paired evaluation
 
 The repository tools pin source and use an independent frozen oracle to compare fresh, Execute-only scoped, and role-scoped policies. The corpus covers first-pass success, L1 repair, Review return, long context, stop/resume, and configuration changes, with repeated trials and rotated strategy order. Reports retain quality, omissions, regressions, repair rounds, repeated findings, elapsed time, known/unknown tokens and cache use, rebuild reasons, and recovery failures. Actual state evidence determines whether a scenario occurred.
 
-The offline native fixture exercises the real Go engine, worker v3, and public plugin API. It validates the evaluator and safety behavior, not model quality, cache rates, or savings. Real paired results require an available native CLI, account, permissions, and model. Defaults remain unchanged until that evidence exists. See the [configuration guide](configuration.md) and the help for `scripts/prepare-session-evaluation.js` and `scripts/evaluate-sessions.js`.
+The offline native fixture exercises the real Go engine, worker v3, and public plugin API. It validates the evaluator and safety behavior, not model quality, cache rates, or savings. Real paired results require an available native CLI, account, permissions, and model. Defaults remain unchanged until that evidence exists. See the [paired evaluation guide](session-evaluation.md) for commands and report interpretation.
 
 ## Retention and operation
 
 Recovery journals have private permissions, exclusive creation, identity/digest checks, and atomic persistence. Existing directories never authorize redispatch. They are task audit data and may contain model output and diagnostics; keep their access and backups with the task. Do not copy credentials or delete uncertain evidence during upgrades.
 
 There is currently no automatic journal-retention timer. Archive evidence through the project's task lifecycle after completion or explicit resolution of an unknown result. Deleting a journal is not a recovery procedure. `control status` and doctor are observation surfaces; models and skills never write `state.json`. Resume through the normal Go entry point from the original task directory so the engine can reconcile before making a new call.
-
-For shared-checkout execution, an Execute receipt fingerprints its declared write scope and binds that scope into the session identity. Independent peer changes do not discard a known invocation; changes within its own scope still reject stale receipts. L1, independent Review and collective delivery validate the entire combined candidate. Scoped receipts neither prove batch completion nor bypass unknown dispatch, outcome or cleanup.