@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/en/contributing.md

@@ -0,0 +1,303 @@
+# Contributing to Flywheel
+
+English · [简体中文](../zh-CN/contributing.md) · [Documentation](../README.md)
+
+Start with the [project overview](../../README.md), the authoritative
+[system design](../design.md) (Chinese), and [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md).
+Flywheel is a deterministic Go orchestrator: models plan, implement, and review
+bounded tasks; code owns state transitions, verification, budgets, and process
+lifecycles. Contributions must preserve that boundary.
+
+## License and scope
+
+Flywheel is distributed under the [MIT License](../../LICENSE). Keep its copyright
+and license notice with copies or substantial portions of the software. Preserve
+third-party notices and the provenance of bundled dependencies; the repository's
+license does not replace their terms.
+
+Keep credentials, private project contents, and unredacted model/session logs out
+of issues, PRs, and fixtures. For a sensitive security report, request a private
+reporting route before disclosing details; the repository does not publish a
+separate response-time commitment.
+
+## Choose a branch and execution directory
+
+Use or reuse a worktree dedicated to the change. For a new change, when `origin`
+and `main` are the intended remote and base:
+
+```sh
+git status --short
+git fetch origin
+git worktree add -b task/my-change ../flywheel-my-change origin/main
+cd ../flywheel-my-change
+```
+
+Inspect an existing branch or directory before reusing it. Preserve other work
+and keep the change's contracts, configuration, checks, and commits in the same
+integration checkout. The original repository remains the session's project
+workspace; the integration checkout and packet worktrees are execution locations.
+When Flywheel develops the change, follow the effective `worktree.enabled` policy.
+The engine merges accepted packets into the integration checkout's current
+branch, not automatically into `main`.
+
+Worktrees isolate checkout files and the index; they are not security sandboxes.
+Serial execution can retain the documented `in-place` fallback. Parallel execution
+with automatic worktree management requires successfully created isolated
+worktrees. With automatic management disabled, shared execution uses batch-wide
+verification and delivery. See the [workflow](workflow.md) and
+[console](flow-console.md) guides for these distinctions and external directory
+registration.
+
+Prepare requirements, scope, and executable acceptance criteria before a large
+implementation. Open a Draft PR once there is a useful reviewable plan or change;
+one PR may cover several packets. Keep commits focused and use English
+Conventional Commit subjects, such as `fix: preserve cleanup evidence`.
+Agents follow the user's existing commit, push, and merge authorization without
+asking again for an already authorized step or extending it to a different action.
+
+## Implement against observable contracts
+
+The [design invariants](../design.md#2-设计不变量) and AGENTS file define the core rules:
+
+- Go and `internal/state` own task state. Writes use revision compare-and-set and
+  atomic replacement; models and skills never edit `state.json`.
+- Contract schemas define valid input. Validate at load time and update the design
+  before changing a wire contract, including the error taxonomy.
+- Test completion, cancellation, timeouts, and cleanup using observable results.
+  A terminal text marker or worker exit does not prove its child groups stopped.
+- Verification and independent review apply to the candidate that is committed
+  and merged. Preserve work and evidence when a gate or Git delivery fails.
+- Missing usage, cost, permission, or capability evidence stays unknown; it cannot
+  become success or zero cost.
+- Skills validate inputs and invoke the CLI. The desktop plugin consumes Go
+  control interfaces; neither owns a second state machine or retry loop.
+
+Use meaningful failure-path tests and narrow I/O injection points. Every measured
+Go function must reach 100% statement coverage; only the trivial `cmd/flywheel`
+entry stub is excluded. Preserve that gate and test behavior rather than repeating
+the implementation solely to increase the percentage.
+
+## Build and verification
+
+Source development needs **Go 1.27 or later** and Git. Flywheel's npm runtime
+requires **Node 22.18.0 or later**; the selected DSH release may require a newer
+Node version. CI and releases pin **Node 24.22.1 / npm 12.2.1**. Use those versions
+when reproducing package and installation evidence.
+
+Run the applicable checks from the repository root:
+
+```sh
+make quality-gate
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+FLYWHEEL_TEST_NODE_BRIDGE=1 go test ./internal/drivers -run '^Test(DSH|CodexPro|ClaudeCodePro)NodeWorkerOfflineBridge$' -count=1
+npm test
+npm run build:npm
+FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
+```
+
+| Change | Required verification |
+|---|---|
+| Go engine | `make quality-gate`: vet, formatting, tests, and coverage |
+| DSH plugin or worker | Plugin checks and the applicable Go-to-Node bridges |
+| npm installation or release | Root npm tests, a six-package candidate build, and installation of those tarballs |
+| Documentation | Links, anchors, fences, runnable examples, translation consistency, and affected embedding/package contents |
+
+The Claude bridge needs the exact optional 0.4.0 machine API in the worker's
+dependency tree. An absent-peer skip does not verify that backend. Preserve the
+reviewed source/tarball identity when using a source candidate. Codex Pro's
+bundled 0.9.0 source package is likewise pinned by its actual integrity and
+[vendor record](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md).
+
+For lifecycle, state, or process changes, reproduce the Linux CI race check:
+
+```sh
+go test -race ./internal/machine ./internal/verify ./internal/watchdog ./internal/drivers ./internal/cli ./internal/modules ./internal/diagnostic -count=1
+```
+
+For changes to session quality or the evaluation harness, use the fixed offline
+paired scenarios described in [Session evaluation](session-evaluation.md):
+
+```sh
+make build
+FLYWHEEL_EVAL_BINARY="$PWD/flywheel" npm run test:sessions
+```
+
+Default tests exercise real Git, processes, workers, and public adapter packages
+with offline fixtures. Installation tests consume actual candidate tarballs in an
+isolated registry and user directory; desktop registration uses a CLI fixture.
+Dependencies require registry access or the documented verified fixture. These
+checks do not establish live account access, model quality, subscription quota,
+or a real Mac desktop pass.
+
+CI uses the same candidate on Ubuntu and macOS, with race checks on Linux. Report
+what actually ran: unavailable CI remains unavailable, and cross-compiling a Mac
+binary does not establish its runtime behavior. Stop additional testing once the
+applicable gates and concrete remaining risks are resolved.
+
+## Keep documentation organized
+
+Documentation changes belong in the same PR as the behavior they describe. Identify
+which guides are affected before implementation, then update those guides in both
+languages. A narrow change does not require rewriting every guide or running every
+repository test.
+
+### Use the right source for each claim
+
+| Claim | Authoritative source | How to use it |
+|---|---|---|
+| Architecture, responsibilities, and invariants | [System design](../design.md), especially its design invariants | Treat these as intended constraints, not optional descriptions. |
+| Legal fields, types, required values, and wire formats | [Schemas and templates](https://github.com/ckanner/flywheel/tree/main/templates), the relevant parser, and [worker protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md) | Check examples against the applicable schema and implemented interface. A schema accepting a field does not prove a backend supports it. |
+| Defaults, precedence, migration, and model bindings | [Templates embedded from the current source revision](https://github.com/ckanner/flywheel/tree/main/templates) and [configuration parsing and normalization](https://github.com/ckanner/flywheel/tree/main/internal/config) | For an installed release, also verify that version's actual templates and `config inspect` output. Distinguish defaults, omitted-field compatibility, and the user's effective configuration; an older installation cannot establish new source defaults. |
+| CLI, worker, and desktop behavior | Current [CLI](https://github.com/ckanner/flywheel/tree/main/internal/cli), [drivers](https://github.com/ckanner/flywheel/tree/main/internal/drivers), and [DSH plugin](https://github.com/ckanner/flywheel/tree/main/plugins/dsh) implementation and relevant tests | Verify commands, lifecycle boundaries, permission support, and UI labels against the implemented path. |
+| Packaging, release order, and automated gates | [Package manifest](https://github.com/ckanner/flywheel/blob/main/package.json), lockfiles, [scripts](https://github.com/ckanner/flywheel/tree/main/scripts), and [workflows](https://github.com/ckanner/flywheel/tree/main/.github/workflows) | Document the commands and gates that exist. A policy in prose is not evidence that CI enforces it. |
+| Completed tests, releases, or evaluations | [Dated validation records](../validation/README.md) and [evaluation evidence](../evaluation/README.md) | Limit claims to the recorded source, platform, inputs, and results; past results do not establish current registry or live-account status. |
+
+When design and implementation disagree, record the mismatch and resolve the
+intended behavior from the task's accepted requirements and design constraints.
+Correct the implementation when it violates that contract; update the design when
+an intended design change is part of the task, then align code, tests, and guides in
+the same PR. Do not silently declare the code correct by weakening an invariant,
+or describe a planned capability as implemented. If the intended behavior remains
+unresolved, state that limit instead of inventing a resolution.
+
+### Put content in its canonical location
+
+The default root and plugin `README.md` are English, with `README.zh-CN.md`
+counterparts. `README.en.md` remains a compatibility link, not another manual.
+Current user and maintainer guides use matching filenames in `docs/en/` and
+`docs/zh-CN/`, with reciprocal language links and the appropriate documentation index.
+
+| Content | Canonical location |
+|---|---|
+| Product overview and first commands | Root READMEs |
+| Current installation, workflow, configuration, and maintenance | `docs/en/` and `docs/zh-CN/` |
+| Current architecture and invariants | `docs/design.md` |
+| Design proposals and their original context | `docs/plans/` |
+| Executed checks, environments, evidence, and limits | `docs/validation/` and `docs/evaluation/` |
+| Historical reviews and superseded material | `docs/reviews/` and `docs/archive/` |
+| Package-specific interfaces and provenance | `plugins/dsh/` |
+| Rules for contributors and coding agents | The paired contribution guides and [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md) |
+
+This repository's documentation is separate from the `docs/<task>/` contracts and
+runtime ledger created in a target repository.
+
+### Map a change to its documentation
+
+Use the following as an impact checklist. Update the named material only where the
+change affects its claims; design/schema/protocol changes also follow their own
+contract rules.
+
+| Change | Documentation to inspect and update when affected |
+|---|---|
+| Installation, upgrade, prerequisites, or setup | Root and plugin READMEs, `getting-started.md`, installation examples, and package contents |
+| CLI commands, control responses, workers, or backend support | `getting-started.md`, `workflow.md`, relevant backend guide, plugin README/`PROTOCOL.md`, and affected skill instructions |
+| Configuration, defaults, accounts, models, or permissions | `configuration.md`, `model-policy.md`, relevant README tables, actual template explanations, and migration instructions |
+| Scheduling, worktrees, execution locations, or delivery | `workflow.md`, `configuration.md`, `flow-console.md`, design sections, and affected skills |
+| Session reuse, recovery, handoff, or accounting | `session-recovery.md`, configuration/workflow/console sections, design, and affected worker contracts |
+| Desktop UI, task discovery, or operator controls | `flow-console.md`, plugin READMEs, and getting-started instructions that name the UI |
+| Evaluation tools, scenarios, or result interpretation | `session-evaluation.md` or `jev.md`, their input/output contracts, and dated evidence when new checks actually run |
+| Package layout, licenses, or release behavior | `releasing.md`, relevant installation instructions, manifests/lockfiles, packaged links, and applicable license/provenance notices |
+| A documentation move, rename, or heading change | Both documentation indexes, language links, all incoming paths/anchors, package lists, embedding references, scripts, and tests |
+| Contributor or AI operating rules | [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md), both contribution guides, and their navigation; keep the requirements consistent |
+
+The affected English and Chinese guides must ship in the same PR. Translate the
+meaning, not just the headings: commands, model IDs, JSON fields, examples, defaults,
+permissions, failure behavior, and capability limits must agree. A translation must
+not promise a broader capability or hide a limitation present in the other language.
+
+### Maintain readable structure and reliable history
+
+Update the section that owns a behavior; add a named subsection only when needed.
+Keep one page title, a logical heading hierarchy, short introductions, typed code
+fences, readable tables, and blank lines around headings and lists. Label fragments
+and placeholders, and use consistent terminology for project workspace, execution
+directory, task, packet, and session. Write concrete instructions rather than a
+conversation transcript. Do not prepend development updates to introductions or
+append unrelated status paragraphs after the license. Release changes belong in
+`CHANGELOG.md`; dated execution evidence belongs in validation records.
+
+Historical plans, reviews, archives, and validation records retain their original
+language and dated context. Preserve recorded dates, commits, trees, versions,
+hashes, inputs, platforms, and pass/fail/skip/not-run results. Correct a historical
+error with an explicitly labelled correction that identifies what changed and why;
+do not silently rewrite an old outcome or replace its candidate identity with a
+new one. Later completion belongs in a new dated record, linked from the old record
+when useful. Historical material does not need duplicate translations, but indexes
+must make its language and status clear.
+
+### Validate the affected documentation
+
+Before requesting review, check the items relevant to this change:
+
+- [ ] Update the owning section and affected English/Chinese counterparts in the
+  same PR, with equivalent meaning, matching filenames, and reciprocal language links.
+- [ ] Verify behavior and default claims against the relevant design, CLI, schema,
+  and source templates; support completed-test claims with matching dated evidence.
+  State unresolved differences and validation limits.
+- [ ] For moves or heading changes, use `rg` to check incoming paths and anchors in
+  guides, READMEs, skills, template embedding code, manifests, scripts, and tests.
+  Resolve links from the referring file; preserve historical immutable commit links.
+- [ ] Check local links, anchors, headings, fences, JSON/YAML examples, and safe shell
+  syntax as applicable; run `git diff --check`. Use a repository documentation checker
+  only if one exists; identify manual or ad hoc checks accurately.
+- [ ] For package or embedding changes, inspect the relevant build/pack output and
+  links in the actual candidate. Include relative-link targets or use repository URLs
+  for source-only material; an old tarball cannot verify newly edited documentation.
+- [ ] Record actual passed/failed/skipped/not-run results, methods, environments, and
+  applicable candidate identity in the PR. Do not imply unconfigured CI checks or
+  validation beyond the evidence; apply only gates relevant to the change.
+
+Use source/help inspection, syntax checks, or isolated fixtures for examples. Do not
+run live models, change accounts, install into real user profiles, publish, or deploy
+merely to check documentation; those actions require an already authorized task scope.
+
+## AI-assisted contribution workflow
+
+1. Establish the current task scope and existing authorization. Read applicable
+   repository instructions, inspect the branch, HEAD, and dirty work, and preserve
+   unrelated edits. Reuse the intended PR/worktree when continuing a task.
+2. Inspect the relevant authoritative sources and identify documentation impact
+   before implementation. Separate current behavior, proposed changes, and historical
+   evidence; surface unresolved design/code differences.
+3. Implement the scoped change and its affected bilingual documentation in the same
+   PR. Preserve the engine's state ownership, frozen contracts, and user customizations.
+4. Run the applicable checks and resolve concrete failures. Do not expand a small
+   documentation change into unrelated runtime work or live-account experiments.
+5. Review the final diff, relevant branch/base changes, translations, references, and
+   verification evidence. Recheck any conclusions invalidated by later edits.
+6. Complete the authorized commit/push/PR work and report the result. Reuse prior
+   authorization without asking again for the same action; a request for a PR alone
+   does not authorize merging, publishing, deploying, or changing repository visibility.
+
+## Prepare a reviewable PR
+
+Explain the concrete problem, the change and resulting behavior, the affected
+bilingual guides, and any intentionally unchanged documentation whose relevance is
+not obvious. Review the final diff and evidence independently of an implementing
+model's completion claim. Follow active merge requirements and the user's
+authorization; preserve required gates and repository settings.
+
+Record each applicable check as **passed**, **failed**, **skipped**, or **not run**,
+including the command/method, relevant environment, and reason for skipped or
+unavailable checks. Distinguish local evidence from remote CI and live validation.
+For package or release work, record the tested candidate's source commit/tree,
+snapshot hash, tarball integrity, and dirty/clean status as applicable. Do not attach
+results from a different source or candidate to the PR's final state without stating
+that limitation. Source merge and npm publication remain separate operations.
+
+## Release changes
+
+Follow the [release guide](releasing.md). All six Flywheel packages share one exact
+version with exact internal dependencies and the pinned Codex Pro runtime. Build
+once from final clean source and test those tarballs. Preserve the source commit,
+tree, snapshot hash, and package integrity values; the release tag must identify
+that source. Do not relabel a dirty candidate as a clean release or rebuild
+different bytes for a published version.
+
+Use the repository's release scripts for candidate checks, publication, registry
+verification, and promotion. Publish platform packages and the plugin before the
+meta package, test the exact registry version before moving `latest`, and verify
+all six tags and integrities. A partial publication resumes with the same
+candidate. Manual publication requires its own explicit authorization and an
+accurate record of completed and unavailable checks.

package/docs/en/flow-console.md

@@ -1,66 +1,148 @@
-# Flywheel workflow console
+# Workflow console
 
-This guide describes the current source. Source, development candidates, local installation and npm publication are separate acceptance boundaries. Keep the CLI, platform packages and DSH plugin at one version.
+[Documentation](../README.md) · English · [简体中文](../zh-CN/flow-console.md)
 
-## Find a task without entering paths
+The DSH Flywheel view brings the current task, workflow stages, configuration, session
+interaction, and delivery into one place. Keep the CLI, platform packages, and DSH
+plugin at the same version. For installation, see [Getting started](getting-started.md).
 
-The canvas starts with task selection. One registered task belonging to the current DSH conversation opens automatically; multiple tasks require a choice. Terminal runs also record DSH's host session ID. This is discovery metadata, never authorization. The UI reads Go state after finding an index entry; the index is not proof of liveness or completion.
+## Find a task without entering paths
 
-Older records without a host ID remain selectable under Recent tasks on this computer. Selection performs a read-only status query and associates the task with the conversation. Refreshing the list does not start, retry or replace a manually selected task. Read failures retain the existing canvas; unresolved operations still require reconciliation against their original task.
+The view follows the current conversation automatically; there is no task selector or editable path field. Its explicit tool association takes priority. Without one, the latest registered run with an exact matching host session ID opens. Foreign and ownerless runs are not shown. The index supplies identity only; Go status establishes progress. Unconfirmed operations retain their original target.
 
-There are no editable task/project path fields. The project workspace remains the original repository; the execution directory may be a task checkout or independent Worktree. These locations are displayed separately when known. The task folder contains the specification, acceptance checks and progress. A prepared task can be associated using read-only status and then selected from the list.
+The project, task folder, execution directory and branch appear directly when known. Use `flywheel_control status` in the intended conversation to associate a prepared or standalone terminal task. Old UI-generated status command records do not establish a new association.
 
 DSH keeps the original repository in the Session header and switches the current execution directory through its public API. The desktop Host periodically attaches Flywheel SDK sessions to matching existing projects; task status also ensures the original project is registered. It does not create a desktop workspace for every packet Worktree or rewrite old Session headers. Probes use temporary persistence, leaving no new user sessions. Native Providers start sessions in the project; task prompts name the actual execution directory for every shell/file operation. Backends unable to separate a `workspace-write` sandbox root reject that combination before dispatch instead of widening permissions. Full access and supported read-only modes retain their actual semantics.
 
-Loading a skill does not start the engine. flywheel-task prepares and calls flywheel_launch; a research/proposal-only response must explicitly say the engine was not started. Single-stage skills query flywheel_control status afterward to associate their canvas, or disclose the exact path when that tool is absent rather than claiming association.
+Loading a skill does not start the engine. `flywheel-task` prepares the appropriate contract and invokes either the bounded investigation control or `flywheel_launch` for implementation. A preparation/proposal-only response must explicitly say execution was not started. Single-stage skills query `flywheel_control status` afterward to associate their canvas, or disclose the exact path when that tool is absent rather than claiming association.
+
+| Conversation entry | Does it start the engine? | How the UI finds the task |
+|---|---|---|
+| `/flywheel-new <goal>` | Prepares contracts for review only | Before handing over the proposal, the assistant registers a candidate through read-only `status`; an uninitialized task shows its identity and location, not execution progress |
+| `/flywheel-run <task directory>` | Starts or resumes an existing task | Start and query the original task path to associate it with the conversation; the view follows the explicit association |
+| `/flywheel-task <goal>` | Prepares, then starts | Use investigation control for evidence collection or `flywheel_launch` for implementation, then check status |
+
+`new → run` and `task` use the same engine; the canvas is not exclusive to one
+skill. Writing task files alone does not register a view, and a failed association
+query must not be replaced with launch merely to populate the canvas. Report an
+unavailable association tool explicitly. Standalone terminal tasks without a host ID require an explicit association in the intended conversation.
+
+While the canvas is visible, registered-task discovery refreshes every five seconds.
+An observed running task refreshes status every two seconds, backing off to ten
+seconds after an unsuccessful response. Hidden documents skip those requests.
+Refresh uses a read-only Remote instead of a slash command, so it does not append chat events or JSON. Explicit mutations and uncertain-result reconciliation retain durable command receipts. Old chat records are preserved.
 
 ## This stage versus the full workflow
 
-When run.kind and control.kind identify the same single-stage operation, This run shows its recorded outcome. A review-only run defaults to **L1 → Review**, including the recorded verdict and score, while stating that overall delivery is not complete. Switch to Full workflow for the larger graph.
+When `run.kind` and `control.kind` identify the same single-stage operation, This run shows its recorded outcome. A review-only run defaults to **L1 → Review**, including the recorded verdict and score, while stating that overall delivery is not complete. Switch to Full workflow for the larger graph.
 
-Continue workflow is behind an explicit disclosure. A passed stage does not start subsequent stages or mark the task completed. Failed, cancelled and unknown operations cannot inherit an older green verdict. Run ID, HEAD and digests are collapsed under Run details and file locations.
+Continue workflow is directly visible when applicable. New-task launch options appear only before an engine state exists. A passed stage does not start subsequent stages or mark the task completed. Failed, cancelled and unknown operations cannot inherit an older green verdict. Run ID, HEAD and digests are directly visible in node details.
+
+## Investigation before implementation
+
+A task with a preparation record and no implementation state opens the investigation
+panel. It shows the goal, action budget, collected observations, truncated excerpts,
+decision receipts, and the evidence report. Continue investigation submits the current
+revision to Go; a pending invocation instead offers reconciliation of the original
+receipt. Unknown control results require status reconciliation before another mutation.
+Stop waits for the running owner to settle; it cannot turn a missing action receipt
+into a confirmed cancellation.
+
+The panel does not offer ordinary code-workflow launch while the task is in preparation.
+`awaiting-report` asks the host assistant to submit an evidence-based analysis; it is
+not implementation completion. A report-only goal ends with that report. An already
+authorized repair can proceed after a supported report and a valid Spec are prepared,
+retaining the original scope and usage. See [bounded investigation](investigation.md)
+for the supported read/search actions, command protocol, and handoff requirements.
 
 ## Configuration
 
-In an existing DSH conversation view, Flywheel remains after Statistics; the blank new-session landing page does not yet show these conversation views. Its pages are Workflow canvas, Global/project configuration, and Runs and comparison. Global settings require no task directory. Project settings target the selected Git root. Discovery still selects one complete file in task → project → global → embedded order; it does not deep-merge files.
+In an existing DSH conversation view, Flywheel remains after Statistics; the blank new-session landing page does not yet show these conversation views. Its primary navigation is Workflow and History; Settings opens a separate workspace. Global settings require no task directory. Project settings target the selected Git root. Discovery still selects one complete file in task → project → global → embedded order; it does not deep-merge files.
 
-Opening Configuration automatically reads the selected scope. Workflow policy, model assignments, budget/retries and JEV shadow advice have separate sections. Save and Discard appear beside the form only after edits. Ordinary saving takes one click; first enabling JEV confirms the task-summary transfer boundary. Serial mode omits concurrency controls. Minutes and seconds are converted precisely to engine millisecond fields.
+Opening Settings automatically reads the selected scope. Execution, Models and sessions, Budget and retries, JEV, and Advanced and diagnostics have separate sections. Save, Discard and Restore defaults stay in a fixed footer; Save is disabled without changes. Saving takes one click, including the single JEV master switch; the form explains supported decisions and the configured data scope. Serial mode omits concurrency controls. Minutes and seconds are converted precisely to engine millisecond fields.
 
-More configuration actions provides reload and installed-default restoration. Scope changes or reloads first disclose unsaved drafts; restoring defaults loads a pending full replacement before saving. Failures retain the draft and an uncertain save requires reconciliation. Go checks file identity, backs up the original and publishes atomically. A running engine retains its snapshot. The displayed source is file-level: task → project → global → installed defaults selects one file, not a per-field overlay. New files start from the installed template.
+Reload, complete JSON editing, diagnostics and raw responses live in Advanced and diagnostics. The narrow navigation row is fixed at 54px with 36px buttons (44px for coarse pointers); shorter content cannot stretch it. Leaving Settings, scope changes or reloads first disclose unsaved drafts; restoring defaults loads a pending full replacement before saving. Failures retain the draft and an uncertain save requires reconciliation. Go checks file identity, backs up the original and publishes atomically. Implementation runs retain their configuration snapshot. JEV additionally rechecks current activation and tighter permissions at decision boundaries; see [JEV recovery](jev.md#data-budgets-and-recovery). The displayed source is file-level: task → project → global → installed defaults selects one file, not a per-field overlay. New files start from the installed template.
 
 Resources include ChatGPT through DSH or Codex Pro, Kimi Code, DeepSeek Account (Flash by default), and optional Claude Code Pro. Defaults come from the embedded template. Use config inspect and doctor for actual backend capabilities. An absent peer or unsupported permission fails explicitly. Provider sign-in stays with its normal account flow.
 
 `permissions.bindings` overrides `loops.<role>`, `routes.<route>` or `judge-panel`. Unspecified bindings use the global policy. History overrides are role-based: execution routes share the execute policy while each packet keeps its own session. Scoped continuation requires the same task, role, goal and eligible binding; fresh also retains invocation-safety records.
 
+[JEV decisions](jev.md) use one default-off master switch. Enabling it activates
+supported investigation and failure-action decisions automatically, including approved
+execution-model choices. Configuration inspection is read
+only; it is not another switch. The investigation view shows the last observed JEV
+state, adopted versus baseline actions, and evidence-referenced deferral or early
+report effects. A stored state label is not a live re-read of configuration. These
+collection effects never mean the root cause is proven or implementation completed.
+
+### Switches and scheduling choices
+
+Settings uses one JEV master switch. Automatic task Worktree management and early
+DSH Review runtime preparation have their own switches in Execution. Each switch
+has an associated label, a visible On/Off state, and native checkbox keyboard
+behavior. Toggling edits the draft; Save changes writes the selected scope. No
+second JEV confirmation or task-specific enable switch is required.
+
+Parallel dispatch remains a two-option policy selector: Batch waits for the
+current batch, while Ready queue refills an available Execute/L1 slot with another
+eligible independent packet. The form preserves the selected policy and explains
+unmet configuration conditions; it cannot establish whether a future task will
+use Full or have independent work. Ready queue requires Full, parallel scheduling,
+a maximum above one and automatic Worktrees. Early runtime preparation is
+independent of JEV and only initializes a supported DSH Review SDK; no Session or
+model prompt is created before normal admission. Defaults remain Batch and
+preparation Off. See [runtime scheduling](configuration.md#scheduling-and-worktrees).
+
+Automatic Worktree management controls engine-owned directories. Turning it off
+does not delete existing directories or prohibit externally managed Worktrees.
+The JEV section explains the allowed data boundary and current-task disable
+semantics beside the fields. Disabling JEV or switching to serial discards the
+invalid input drafts hidden by that change and retains the last valid values;
+unrelated errors still require correction. Detected invalid fields entered through advanced JSON remain editable there and
+block Save until corrected; Go still validates the complete configuration.
+A valid connection, provider quota, explicit empty allowed-data list, role policy
+or budget is not reset by an unrelated switch. Invalid drafts and stale/unknown
+saves retain the existing protections.
+
+### Session defaults and stage overrides
+
+Execution sets the default fresh/scoped policy. Models and sessions lets each role inherit or override it. Execute routes share a role policy while packets retain independent histories. An explicit Plan choice reconciles the legacy Kimi history switch; inheritance preserves it. Nodes show actual session IDs, actions and reasons, not a resume inferred from configuration.
+
+### Optional usage budget
+
+Choose Off, Warn only, or Stop at limit. Off hides the threshold while retaining accounting. Warn only does not stop execution; a hard budget blocks new calls at the limit or when usage is unknown. Thresholds apply per task and UTC day; blank means no limit. Timeouts and transport retries remain independent, as do Provider quotas. The form reads actual settings and never silently changes an existing soft budget to off.
+
 ## Canvas and operations
 
-The left-to-right overview groups Plan/decomposition, scheduling, task branches, integration/final checks and PR/Merge. Selecting a node opens view-local Progress, Sessions and Run configuration details. Open task workflow drills into Execute, L1, Review and Git delivery; integration and remote delivery groups also expand. Colors have text labels. Identity, project/worktree, branch, HEAD, run ID, bindings and evidence come from actual receipts.
+The left-to-right overview groups Plan/decomposition, scheduling, task branches, integration/final checks and PR/Merge. Selecting a node directly shows its outcome, actions, configuration snapshot and actual role-session facts. Evidence and managed session interaction have separate explicit destinations. Open task workflow drills into Execute, L1, Review and Git delivery; integration can be inspected separately, while PR and Merge are separate nodes. Colors have text labels. Identity, project/worktree, branch, HEAD, run ID, bindings and evidence come from actual receipts.
 
 The canvas uses the available plugin width, with two-axis panning, zoom, fit width, current-step location, paging and a list alternative. New snapshots preserve the viewport and selection; location can switch to the running packet's page. Large tasks use bounded excerpts. Read full node evidence loads one packet with a matching fresh revision; it never changes the ledger.
 
 Focus canvas expands the view in a plugin-owned native dialog. Exit or Escape returns without starting or stopping the task. It does not change the DSH global layout or composer. Unknown operation outcomes exit focus mode so the original-invocation reconciliation action remains visible.
 
-Node operation confirmation freezes the observed revision; a changed snapshot invalidates it. Retry once requires a reason, while reopening a completed packet explains evidence invalidation. Review cannot run with a red current L1. Unqueried remote state, closed PR and merged PR remain distinct.
+Ordinary node operations dispatch once with the observed revision. Repair and retry records the explicit console action and adds one Execute/L1 attempt, without inventing an explanation for the failure. Reopening a completed packet still requires a reason and confirmation of downstream evidence invalidation; a changed revision invalidates that confirmation. Review cannot run with a red current L1. Unqueried remote state, closed PR and merged PR remain distinct.
 
 - Run stage submits the observed revision for lease-bound admission.
-- Continue once records a reason and adds one Execute/L1 attempt without resetting failures or billing.
+- Repair and retry records the explicit console action and adds one Execute/L1 attempt without resetting failures or billing.
 - Reopening a completed packet archives old evidence and invalidates downstream acceptance.
 - Git delivery requires current L1 and independent Review evidence.
 - Final acceptance runs milestone gates and Judge without starting Plan or unfinished execution units.
 - Continue workflow resumes the persisted Full or ultraWork/Quick policy.
 - Stop waits for managed work to settle; closing a view is not a stop.
 
-Explicitly independent packets with satisfied dependencies can be run ahead in isolated worktrees. Integration changes invalidate old acceptance. Each asynchronous node operation records running/passed/failed/cancelled and its reason. Quick retains deterministic checks and independent final Review; omitted Plan/Judge stages are not presented as passes.
+Explicitly independent packets with satisfied dependencies can be run ahead in their registered execution directories, subject to the selected worktree policy. Integration changes invalidate old acceptance. Each asynchronous node operation records running/passed/failed/cancelled and its reason. Quick retains deterministic checks and independent final Review; omitted Plan/Judge stages are not presented as passes.
 
 ## Parallel execution
 
+### Eligibility and limits
+
 Read `flywheel template scheduler-policy.schema.json` for the current fields and bounds. For example:
 
 ```json
-{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}}
+{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1},"dispatch":"batch","prewarm":false}}
 ```
 
-Provider-limit keys are account channel names. Eligibility comes from frozen packet contracts:
+Provider-limit keys are actual configuration channel names. The example uses the inline template's `deepseek-account`; a binding using `deepseek-account-sdk` needs that key instead. Eligibility comes from frozen packet contracts:
 
 ```yaml
 schedule:
@@ -70,7 +152,26 @@ schedule:
 
 Dependencies reference earlier known packet IDs. Writes are normalized relative paths or directory prefixes, without globs or escapes. Include ordinary tests/configuration and account for shared test resources. Undeclared independence, overlapping scopes and live-credential units remain serial.
 
-Configuration → Workflow policy → Automatically manage task Worktrees is on by default (`worktree.enabled`). It controls automatic directory creation/management independently from parallel scheduling. New defaults allow parallel execution with a limit of two; existing explicit serial settings remain unchanged. With automatic management off, tasks may run concurrently in the task checkout or choose their own Worktrees. Shared directories do not provide file isolation: write-scope conflicts, candidate drift and failed acceptance still stop progress.
+### Dispatch and runtime preparation
+
+The configuration editor also offers `scheduler.dispatch` and `scheduler.prewarm`.
+The defaults are `batch` and false. Selecting `ready-queue` fills a free Execute/L1
+slot from the remaining independent Full packets when automatic Worktree management
+is enabled and the parallel limit exceeds one. Review, replanning and integration
+retain the all-workers-settled barrier. Shared-checkout runs keep batch dispatch.
+
+Prewarming initializes one DSH Review runtime while a serial packet performs its
+post-Execute deterministic checks. It sends no model prompt until normal Review
+admission. Parallel Execute/L1 lanes and shared candidates do not prewarm; an
+independent cohort must settle before its serial Review path may prepare a runtime.
+Other harnesses use the cold path. Unused runtimes must finish bounded cleanup.
+Neither setting changes JEV activation, task qualification or completion gates.
+Saving takes effect on the next start. See [Configuration](configuration.md#ready-queues-and-runtime-preparation)
+for eligibility, recovery and the separate live-performance evaluation.
+
+### Execution directories
+
+Configuration → Workflow policy → Automatically manage task Worktrees is on by default (`worktree.enabled`). It controls automatic directory creation/management independently from parallel scheduling. The installation default allows parallel execution with a limit of two; existing complete files without `scheduler` remain serial, as do explicit serial settings. Parallel automatic management requires isolated worktrees and stops if creation fails; the legacy serial path can record an in-place fallback. With automatic management off, tasks may run concurrently in the task checkout or choose their own Worktrees. Shared directories do not provide file isolation: write-scope conflicts, candidate drift and failed acceptance still stop progress.
 
 To select another execution Worktree, the executor first prepares a clean checkout of the same repository and task baseline, unclaimed by another unit in this workflow and with a branch not shared by multiple Worktrees, then returns only `{"flywheelExecutionDirectory":{"cwd":"/absolute/worktree","branch":"actual-branch"}}` before implementation. Go validates and records it; the next invocation, tests, Review and delivery follow that directory. Registration is not task completion and its model usage is still billed. External Worktrees are retained. A prompt-only directory claim or edited state file cannot replace this registration.
 
@@ -78,6 +179,10 @@ Independent Worktrees permit concurrent Execute/L1. Shared checkouts run Execute
 
 Review, integration and milestone gates remain serial. A combined candidate is revalidated after incorporating earlier work. Bounded execution failures retain their escalation policy. Integration conflicts and failed gates preserve the worktree and evidence. Write scopes are orchestration/acceptance contracts; full access is not an OS sandbox.
 
+### Shared-checkout batches
+
+When a batch shares one checkout, all executor calls finish before L1 and independent Review validate the complete combined candidate. Changes are projected onto declared scopes; undeclared and forbidden paths still fail. This does not attribute filesystem writes to individual processes. Repairs invalidate earlier proofs. Only after every peer passes can code be committed and all completions published in one state CAS; failed publication never optimistically completes a subset. Mixed batches deliver the shared checkout first, then revalidate and integrate external Worktrees. Manual integration/final checks cannot bypass the batch barrier; resume the complete workflow. The canvas shows the cohort and previous error.
+
 ## Controlled Provider session interaction
 
 Read latest response opens the exact digest-bound receipt, not an invented native history path or a claim of complete provider history.
@@ -93,13 +198,23 @@ Each terminal line is a prompt. `/history` reads the latest response; `/reconcil
 
 Returning runs L1, applicable Quick gates and independent Review. Human text is not a passing verdict. Candidate-bound human-takeover evidence allows normal subsequent delivery. Release does not claim verification and cannot bypass unknown effects or cleanup. Milestone sessions currently expose read-only responses; interactive handoff is packet-scoped.
 
-Ledger storage v2 is accepted by the new engine alongside legacy v1. Older engines reject v2 rather than ignoring human ownership. Session policy-version remains 1; worker/lifecycle versions are independent.
+This return path requires an existing eligible managed session. It does not import
+an arbitrary patch prepared before the task, and running Verify followed by Review
+does not create that provenance. A general existing-candidate admission interface
+remains separate work.
+
+The engine accepts session ledger storage versions 1, 2 and 3. Human handoff
+requires at least v2; the first runtime prewarm records v3 so older engines reject
+cleanup responsibilities they cannot interpret. Later handoffs retain v3.
+Session policy-version remains 1; worker/lifecycle versions are independent.
+[Recovery](session-recovery.md#dsh-runtime-preparation-after-a-restart) explains the
+original cleanup receipt required after an interrupted preparation.
 
 ## Discovery and comparison
 
-CLI and desktop starts register run IDs. A conversation retains multiple confirmed task associations. The index lives in runs/ beside the global configuration, optionally overridden by absolute FLYWHEEL_RUNS_DIR. It shows the latest 100 registrations and never scans the disk. Query Go again for liveness.
+CLI and desktop starts register run IDs. A conversation retains multiple confirmed task associations. The index lives in `runs/` beside the global configuration, optionally overridden by absolute `FLYWHEEL_RUNS_DIR`. It shows the latest 100 registrations and never scans the disk. Query Go again for liveness.
 
-Run history uses a selection list with adjacent details for operation kind, branch, HEAD, contract/configuration conditions, elapsed time and newly observed attempts, failures and deliveries. Selecting a record does not launch it; opening its canvas refreshes current Go state. Metrics scope chooses the selected run or all calls for its task, including legacy observations. The reference compares conditions without changing the metrics target. Invocation/receipt reconciliation precedes aggregation; late receipts keep their original attribution and are not double-billed. A group with entirely missing cost shows Not reported, not $0.
+Run history is limited to the currently associated task and uses a selection list with adjacent details for operation kind, branch, HEAD, contract/configuration conditions, elapsed time and newly observed attempts, failures and deliveries. Selecting a record does not launch it; opening its canvas refreshes current Go state. Metrics scope chooses the selected run or all calls for its task, including legacy observations. The reference compares conditions without changing the metrics target. Invocation/receipt reconciliation precedes aggregation; late receipts keep their original attribution and are not double-billed. A group with entirely missing cost shows Not reported, not $0.
 
 Usage, cost and duration are known amounts, with missing/partial observations retained. Costs may include estimates from configured prices. Call failure rate is not code quality. Different conditions permit descriptive comparison only; quality conclusions require acceptance evidence and an independent oracle.
 
@@ -113,6 +228,9 @@ Merge rechecks the PR, head, base and checks, using `--match-head-commit`. It ne
 
 Retries reconcile existing PR/merge results before mutations. Missing receipts remain unknown. Remote state is separate from local engine completion. Publication must bind the actual merge commit and artifacts for its own validation; Merge does not automatically publish npm packages or deploy.
 
-The configuration panel also exposes default-off **JEV shadow evaluation (optional)**. See the [JEV guide](jev-shadow.md) for the switch, transmitted data and nonblocking failures. This requires the 0.30.1 CLI/plugin.
+## Related guides
 
-When a batch shares one checkout, all executor calls finish before L1 and independent Review validate the complete combined candidate. Changes are projected onto declared scopes; undeclared and forbidden paths still fail. This does not attribute filesystem writes to individual processes. Repairs invalidate earlier proofs. Only after every peer passes can code be committed and all completions published in one state CAS; failed publication never optimistically completes a subset. Mixed batches deliver the shared checkout first, then revalidate and integrate external Worktrees. Manual integration/final checks cannot bypass the batch barrier; resume the complete workflow. The canvas shows the cohort and previous error.
+- [Configuration](configuration.md): complete files, model bindings, permissions, and scheduling.
+- [Workflow](workflow.md): preparation, execution, and PR review checkpoints.
+- [Investigation](investigation.md): bounded evidence collection, reports, and optional JEV decisions.
+- [Recovery](session-recovery.md): durable receipts and unresolved invocation handling.