@ckanner/flywheel 0.31.1 → 0.32.0

package/docs/en/configuration.md

@@ -196,13 +196,17 @@ An existing complete file without `scheduler` normalizes to **serial**, and an
 explicit serial choice remains unchanged. Installing a new release does not replace
 that file. The [scheduler schema](https://github.com/ckanner/flywheel/blob/main/templates/scheduler-policy.schema.json)
 bounds total and per-channel concurrency from 1 to 8.
+Both new and existing configurations default to `dispatch: "batch"` and
+`prewarm: false`. These settings do not change the Quick/Full workflow or enable JEV.
 
 ```json
 {
   "scheduler": {
     "mode": "parallel",
     "max-parallel": 2,
-    "providers": {"deepseek-account": 1}
+    "providers": {"deepseek-account": 1},
+    "dispatch": "batch",
+    "prewarm": false
   },
   "worktree": {"enabled": true}
 }
@@ -239,6 +243,74 @@ backends that cannot separate a `workspace-write` sandbox root reject unsupporte
 split-directory requests before dispatch, without expanding permissions. See the
 [console guide](flow-console.md#parallel-execution) for registration and batch rules.
 
+### Ready queues and runtime preparation
+
+`scheduler.dispatch` accepts `batch` or `ready-queue`. Batch dispatch waits for the
+current bounded group before selecting more work. Ready queues admit the next
+already independent packet when an Execute/L1 slot becomes free. They apply to
+Full with parallel scheduling, a maximum above one, and automatic Worktree
+management. Quick, serial scheduling, a maximum of one, and automatic management
+off retain their existing path. Shared-checkout execution retains its batch rules,
+including when executors may register external Worktrees later.
+
+The first ready-queue window must have every Worktree prepared and saved before
+dispatch. Later packets prepare their directory before taking a freed slot. A
+preparation failure stops admission and cancels and awaits started workers; queued
+packets that have not been admitted create no directory or model invocation.
+Dependencies become ready only after delivery. Review, replanning and integration
+wait for all admitted workers to settle, and every combined candidate is rechecked.
+Existing total/channel limits, hard budgets, attempts and unknown-result recovery
+remain in force.
+
+A replacement packet does not recover or cancel a sibling's still-running model
+call. The coordinator retains those calls and their shared accounting. An unknown
+result or failed receipt persistence stops new admission immediately and must be
+reconciled before resuming.
+
+`--pause-before review` also applies to independent parallel Worktrees. Once all
+Execute/L1 work in the current group passes and its workers settle, the task pauses
+before any Review or integration, retaining the verified candidates. Batch mode
+finishes its admitted group; ready-queue mode may refill the fixed independent
+queue before reaching that boundary. Resuming the same task reuses valid execution
+evidence instead of repeating Execute. A candidate changed by later integration
+still requires validation again.
+
+`scheduler.prewarm: true` allows a serial packet to initialize one DSH Review
+runtime while its post-Execute deterministic checks run. Initialization sends no
+model prompt or Session request. Review inference still waits for its checks and
+normal admission. Parallel Execute/L1 lanes do not prepare runtimes: after their
+barrier, preparation can begin only in the serial Review path. Shared-candidate
+batches do not prewarm. The main overlap opportunity is therefore a serial
+Execute's L1 and applicable Quick checks, not every parallel lane's validation.
+
+Unused or incompatible runtimes must finish bounded cleanup before further model
+work. If an unused runtime reaches its 60-second lifetime before a formal start
+is attempted, one cold invocation may use the same persisted request identity and
+remaining time allowance. This requires an exact, durable no-dispatch receipt,
+confirmed SDK and process-group cleanup, and no cancellation or expired invocation
+deadline. It does not grant another attempt or reset a budget. Unknown cleanup
+remains blocking. Other harnesses start normally. Session history reuse is separate
+from runtime preparation and retains role isolation.
+
+Confirmed initialization failures preserve their reported error classification and
+the normal retry/fallback rules. An authentication or invalid-request failure does
+not become a transport retry or qualify as a harmless prepared-runtime expiration.
+
+In Settings → Execution, dispatch is a Batch/Ready queue selector and prewarm is
+an independent switch. The form shows unmet Ready queue configuration conditions
+without resetting the selected value; task eligibility is checked by the engine.
+Both options also remain available in advanced JSON. Saving
+applies to the next start; the current process retains its loaded policy. A resumed
+run still reconciles existing invocations and shared batches before new dispatch.
+An outstanding prepared worker also requires its original no-prompt cleanup
+receipt, synchronized file and directory, and confirmed worker/process-group exit,
+even after `prewarm` is disabled; see
+[prewarm recovery](session-recovery.md#dsh-runtime-preparation-after-a-restart).
+Both optimizations remain optional while live latency, resource use and adoption
+defaults are evaluated separately. Offline checks establish behavior and recovery,
+not a guaranteed speed or token improvement. See the
+[P5 implementation plan](../plans/2026-11-13-p5-ready-queue-prewarm.md) (Chinese).
+
 ## Session policy, history reuse, and invocation safety
 
 ```json
@@ -384,6 +456,12 @@ dispatch; `state.packets[*].execution-policy.history` records separate
 `quality-upgrade` and `channel-fallback` events with full before/after bindings,
 attempt and reason. Parallel packets retain independent records.
 
+With `jev.enabled`, confirmed failures can also select a legal binding through
+JEV. These switches are recorded as `jev-model-selection`, use the same
+`max-switches` and cold-start rules, and do not alter channel-error handling.
+The allowed bindings remain an explicit resource/permission declaration; the
+JEV switch does not add a provider, account or model to that set.
+
 `config inspect --json` exposes the complete declaration under
 `execution-policy`; the ordinary bindings table remains the configured baseline.
 Current choices belong to packet/session state. Doctor's existing binding probes
@@ -532,16 +610,33 @@ Codex Pro checks actually import the public API and verify exact version 0.9.0/p
 No probe sends an inference prompt, runs L1/L2/L3, creates a worktree, or writes Flywheel task state. SDK initialization may contact a provider's catalog and write its own cache files and temporary probe-session persistence; read-only here is scoped to Flywheel state and configuration. Recheck in the desktop panel because its PATH/profile/environment may differ from the terminal.
 
 
-## Optional JEV shadow evaluation
-
-`jev-shadow.enabled` defaults to false, including configurations that omit it. The
-global/project editor exposes the switch. During task execution it only captures
-local snapshots; it does not send HTTP requests on the task's critical path.
-A later explicit `flywheel shadow run` performs the optional network evaluation
-with separate accounting. Shadow results cannot change Quick/Full or authorize
-new actions. New decision adoption requires its own explicit opt-in and data
-boundary; the existing shadow switch does not grant it. See the
-[JEV guide](jev-shadow.md) for endpoint, version, credentials, budgets and recovery.
+## JEV decisions
+
+`jev.enabled` is the only JEV activation setting and defaults to false. The desktop
+editor exposes one switch; enabled investigation preparations automatically freeze
+an adoption policy for action selection, evidence-backed deferral and early report
+handoff. Confirmed implementation failures can also select bounded repair, an
+approved feedback check, replanning or an allowed execution binding. Task/New/Run
+share the same engine-owned policy. Disabling stops subsequent
+requests and adoption, while existing receipts and budgets are retained.
+
+There is no independent task shadow/advisory switch. Legacy `jev-shadow` is read
+only to migrate connection hints into a disabled unified configuration; editor saves
+remove the old key. Explicit new `jev` wins, and configuration still selects one
+complete task/project/global/embedded file without merging. Endpoint, fixed model,
+credential variable, limits, data categories and recovery are documented in the
+[JEV guide](jev.md).
+
+Packets may declare up to eight optional `feedback-checks`, using the same
+`cmd`/`script` and `expect` shape as an acceptance command. They are short,
+approved diagnostic candidates, not replacements for `acceptance.L1/L2/L3`.
+Add a concise `purpose` (up to 160 characters) explaining what each check can
+distinguish. JEV receives that approved purpose, not the command. A check without
+`purpose` remains executor guidance and is excluded from JEV's targeted candidates.
+Keep credentials, raw logs and command text out of the purpose. JEV may also use
+an eligible previously failed L1 check. Execution uses the existing
+verification timeout, environment allowlist and process cleanup rules. Changing
+these checks changes the contract identity and invalidates stale decisions.
 
 ## Reference files
 

package/docs/en/contributing.md

@@ -196,7 +196,7 @@ contract rules.
 | 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-shadow.md`, their input/output contracts, and dated evidence when new checks actually run |
+| 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 |

package/docs/en/flow-console.md

@@ -2,17 +2,15 @@
 
 [Documentation](../README.md) · English · [简体中文](../zh-CN/flow-console.md)
 
-The DSH Flywheel view brings task selection, workflow stages, configuration, session
+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).
 
 ## Find a task without entering paths
 
-The canvas starts with task selection. One registered task belonging to the current DSH conversation opens automatically; multiple tasks require a choice. Terminal runs record DSH's host session ID when it is available. 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.
+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.
 
-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.
-
-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.
 
@@ -21,25 +19,24 @@ Loading a skill does not start the engine. `flywheel-task` prepares the appropri
 | 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; select the intended task when there are multiple candidates |
-| `/flywheel-task <goal>` | Prepares, then starts | Launch and associate through `flywheel_launch`, then check status |
+| `/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. Tasks actually run from a standalone
-terminal remain selectable under Recent tasks on this computer.
+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 is read-only and does not replay uncertain operations.
+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.
 
-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
 
@@ -60,33 +57,73 @@ for the supported read/search actions, command protocol, and handoff requirement
 
 ## 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 navigation tabs are Workflow, Run history, and Configuration. 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 explains local capture and the separate explicit evaluation transfer. 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.
 
-The optional [JEV shadow evaluator](jev-shadow.md) is disabled by default. Enabling
-it captures a local task summary; only an explicit `shadow run` sends it for evaluation.
-Advice does not select workflow policy. Investigation decisions use a separate,
-explicit policy described in the [investigation guide](investigation.md).
+[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.
@@ -102,7 +139,7 @@ Explicitly independent packets with satisfied dependencies can be run ahead in t
 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 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:
@@ -115,6 +152,23 @@ 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.
 
+### 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.
@@ -144,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.
 
-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.