@ckanner/flywheel 0.28.5 → 0.30.0

package/docs/en/session-evaluation.md

@@ -0,0 +1,120 @@
+# 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.
+
+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).
+
+## Bounded rebuilding
+
+`sessions.roles` accepts `fresh` or `scoped` for `plan`, `execute`, `review`, `judge`, and `judge-panel`. Unspecified roles inherit `sessions.mode`. Plan's explicit `resident-session:false` still prevents history reuse; explicit `sessions.roles.plan:"fresh"` also disables the legacy Kimi Plan continuation path.
+
+All `sessions.quality` thresholds default to `0`, meaning disabled. Existing default behavior is unchanged.
+
+| Setting | Trigger | What it establishes |
+|---|---|---|
+| `max-confirmed-turns` | Confirmed, safely attributed turns in the current generation reach the threshold | Reuse count, not demonstrated quality loss |
+| `max-unproductive-turns` | Consecutive Execute completions leave the candidate fingerprint unchanged | No candidate progress on disk, not an inference about private reasoning |
+| `max-run-input-tokens` | The last complete, attributable per-run input reaches the threshold | That run's measured input, not native history size or remaining context capacity |
+
+These thresholds permit rebuilding only after the previous invocation is consumed and its accounting state persisted, dispatch and outcome are known, cleanup is confirmed, and the candidate is identifiable. Unknown dispatch/outcome, unfinished lifecycle checkpoints, and unconfirmed cleanup first use P3 reconciliation or the existing escalation path. Partial/unknown usage cannot trigger the input threshold; confirmed-turn and unchanged-candidate thresholds remain independently usable. Usage uncertainty is preserved, and the existing hard budget can separately block another invocation. Consuming an invocation again cannot increment its counters again.
+
+Rebuilding records the reason, generation, and replaced invocation reference. The handoff uses the current Spec, packet, disk candidate, valid reports, verification evidence, and structured feedback. It does not transfer Executor private history to Reviewer. The new generation resets its quality counters while task attempts, failures, elapsed work, and budget accounting remain. This policy uses verifiable rebuilding, without an extra unmetered model call to compress history.
+
+## Three fixed policies
+
+Experiments hold the Git commit, contracts, models, effort, permissions, acceptance, and quality thresholds constant. Only Execute and Review history policies differ.
+
+| Report variant | Execute | Review | Plan / Judge / judge-panel |
+|---|---|---|---|
+| `fresh` | Fresh each time | Fresh each time | Explicitly fresh |
+| `executor-scoped` | Scoped to the same packet | Fresh each time | Explicitly fresh |
+| `role-scoped` | Scoped to the same packet | Scoped to the Reviewer's own review scope | Explicitly fresh |
+
+`role-scoped` implements the design's separate Executor and Reviewer histories; it does not share one thread across roles. Each case has at least two paired repetitions, each containing all three policies. Order rotates by case and repetition. Every trial uses a new isolated Git clone. The original repository is unchanged, and one trial's candidate or history is not given to another trial.
+
+## Prepare an executable corpus
+
+Prepare a complete Flywheel configuration with explicit `routes.default`, `loops.review`, and their channels. Use a backend and account configuration that can already execute tasks. The preparer reads this file without running a model or reading/copying account credentials.
+
+```sh
+node scripts/prepare-session-evaluation.js \
+  --config /absolute/path/flywheel.config.json \
+  --output /absolute/path/new-session-corpus \
+  --repetitions 2
+```
+
+The preparer creates a new local Git repository, exact commit, and `manifest.json`. It disables additional worktree creation equally for every trial because the evaluator already isolates each clone, and protects the frozen `eval/` checks. It does not overwrite the supplied configuration file.
+
+The generated configuration-change case uses `medium` / `high`. The selected model must accept both. For a backend with different effort values, edit the manifest's `configure` step before running to use another explicitly supported value. All three policies use that same edited manifest; no trial guesses or substitutes its own value.
+
+The built-in task is an independently testable code change: implement pure `compactRanges`, converting safe integer arrays into sorted maximal inclusive intervals, removing duplicates, handling negatives and empty input, and preserving the caller's array. Frozen L1 checks output. Final Review independently checks input preservation. A separate pinned oracle checks both. The model's done-report does not supply the evaluation score.
+
+| Scenario | Experiment | Required observation |
+|---|---|---|
+| `first-pass` | Run normally from an unimplemented function | Completed task with one Execute and one Review |
+| `l1-repair` | After the first execution, a fixed injector breaks output; real L1 rejects it and the engine repairs it | Failed L1 evidence and more than one Execute |
+| `review-return` | Inject an in-place input sort that preserves all output checks; L1 passes and Review should return it | Review return evidence and more than one Execute |
+| `long-context` | Put stable reference material in the actual Execute prompt's `cache-scope` | Measured per-run input reaches the manifest threshold; absent usage is unknown |
+| `stop-resume` | Pause normally before Review, then explicitly run again | Saved paused state followed by continuation; this is a stage-boundary pause |
+| `configuration-change` | Change the same binding's thinking after the first Execute, then execute again | A different effective binding fingerprint is observed |
+
+Controlled injectors modify candidate code only. The evaluator verifies that Go state, contracts, and configuration remain unchanged across injection. It does not fabricate L1, Review, receipts, metrics, or state. The stage-boundary pause complements the separate P3 tests for active-turn termination, ACK failure windows, and read-only recovery.
+
+Effective configuration lives outside the trial candidate and is selected with `FLYWHEEL_CONFIG`. Before the engine establishes its BaseRef, the evaluator removes overriding root/task configuration files in the disposable clone and commits this setup. Configuration changes therefore do not impersonate model edits to protected contracts. The source configuration and before/after bindings remain recorded.
+
+## Run real backend evaluation
+
+Build the current Go CLI and verify that the selected public adapter, native CLI, and account can execute tasks, then run:
+
+```sh
+node scripts/evaluate-sessions.js \
+  --manifest /absolute/path/new-session-corpus/manifest.json \
+  --flywheel /absolute/path/flywheel \
+  --output /absolute/path/new-session-results \
+  --live
+```
+
+`execution:"live"` requires `--live` and rejects mock driver bindings. The evaluator uses the supplied models and permissions without automatically choosing another model, channel, or broader permission mode. The output directory must not exist; saved experiments are never overwritten.
+
+Every invocation retains the engine's normal budget, stopping, and recovery rules. The manifest's `maxCalls` is an additional observed-call limit: every 50 ms, the runner checks persisted metrics and requests cancellation when the threshold is reached. In-flight calls and delayed metric writes can exceed it; it is not a transactional reservation before model dispatch. `runTimeoutMs` bounds each step, with up to 30 seconds allowed for cancellation cleanup. Forced termination, unknown dispatch/outcome, or unconfirmed cleanup stops the entire experiment and preserves available evidence without replay.
+
+## Interpret the report
+
+`report.json` records source commit/tree, manifest/configuration/engine/oracle SHA-256 hashes, timestamps, trial conditions, order, policy, step outcomes, and paired comparisons. Each trial also retains stdout/stderr, state snapshots, and original metrics. The independent oracle is copied from the fixed source commit outside the candidate and checked by hash before and after execution. Candidate tampering with that oracle stops the experiment.
+
+| Field | Meaning and limits |
+|---|---|
+| `quality.pass`, `omissions`, `regressions` | Independent oracle results; unfinished checks remain null. Engine completion is separate from quality. |
+| `repairRounds` | Total packet attempts beyond the first, from actual Go state |
+| `repeatedFindings` | Exactly repeated Review return reasons after whitespace normalization, not semantic equivalence |
+| `elapsedMs` | Engine run time; excludes clone, oracle, and injection overhead |
+| `usage.*.known` | Known complete per-run input/output/cacheRead/cacheWrite/totalTokens totals |
+| `observedCalls` / `missingCalls` | Calls with and without each metric; known totals are lower bounds when anything is missing |
+| `cost.knownUSD` | Known monetary cost, with missing costs counted separately; subscription billing is not assumed zero |
+| `actions`, `rebuildReasons` | Actual create/resume/rebuild counts and attributable reasons |
+| `recovery` | Resumes, failed or unknown resumes, unknown outcomes, unresolved invocations, and reconciliation count |
+| `scenarioCoverage` | Planned, observed, unobserved, and unknown separately; a scenario label alone is not evidence |
+
+P3 `record-kind:"reconciliation"` rows replace the original invocation's later-known facts using `reconciles-invocation`. They are audit corrections, not new model calls, and do not add the same usage or cost twice. Original audit rows remain preserved.
+
+Deltas require all three paired policies, matching fixed conditions, and equal observed role/harness/provider/channel/model sets. Missing usage makes that metric's delta null. The report does not automatically produce savings percentages. Establish quality and actual scenario coverage before interpreting performance changes.
+
+## Separate offline gates from live evidence
+
+The repository provides three distinct evidence paths:
+
+1. `node --test npm/test/session-evaluation.test.js` tests manifest validation, isolation, unknown usage, pairing, and stopping through an explicitly labeled runner protocol fixture.
+2. The command below runs the real Go CLI → worker 3 → actual public Codex 0.9 package → native CLI fixture for 36 trials. The fixture implements native protocol and controlled code work, never Go state/metrics/receipts. The real engine evaluates L1, Review, Git boundaries, and history decisions.
+3. `--live` performs actual backend inference and supplies model quality, cache, time, and cost evidence.
+
+```sh
+FLYWHEEL_EVAL_BINARY=/absolute/path/freshly-built-flywheel \
+FLYWHEEL_EVAL_OUTPUT=/absolute/path/new-native-evaluation \
+node scripts/test-session-evaluation.js
+```
+
+From the repository root, `npm run test:sessions` invokes the same gate with the same environment variables.
+
+The second path requires built `plugins/dsh/dist` files and the installed exact public Codex package. Missing binaries or dependencies fail rather than skip. It freezes worker and public package bytes in a separate directory. The native fixture requires an explicitly marked experimental CODEX_HOME and corpus, without actual account access. Its usage is synthetic protocol evidence, not measured model savings.
+
+Passing offline gates does not establish real-account or macOS lifecycle acceptance. If a live environment rejects permissions or times out during thread/start, retain that blocker as evidence. Keep default thresholds disabled until paired real results justify a specific change.

package/docs/en/session-recovery.md

@@ -0,0 +1,81 @@
+# 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.
+
+## Ownership
+
+| Layer | Responsibilities |
+|---|---|
+| Go engine | Task state, role/scope isolation, intent, candidate and contract guards, budgets, accounting, receipt consumption, delivery |
+| Flywheel worker v3 | Typed lifecycle frames, Go durable acknowledgements, cancellation; no task decisions |
+| Public machine API | Independent supervisor, private durable journal, native guardian, complete raw receipts, read-only `recoverMachine` |
+| Native Codex / Claude | Model/tool execution, native history, observed configuration and usage |
+
+The outer worker protocol is 3. The plugin request/receipt protocol remains 1, with lifecycle version 1. DSH and Kimi retain their existing normal-history and Go saved-receipt paths; the new plugin capabilities do not imply identical P3 support for those backends.
+
+## Durable acknowledgement before dispatch
+
+Go prepares the task's `.sessions/` parent and saves intent before an invocation. The upstream API exclusively creates the invocation's recovery subdirectory, named from a digest of the invocation ID. Recovery never scans global native history.
+
+Typed events include `thread-ready`, `dispatch-intent`, `dispatch-possible`, `turn-accepted`, `terminal`, and `cleanup-confirmed`. Events must reflect actual backend observations:
+
+- **Codex** reports its actual thread/configuration before `turn/start`. Go checks the complete permission policy, cwd, model, and identity before acknowledging. A failed acknowledgement prevents the next turn boundary.
+- **Claude** exposes native init only after prompt submission. It supports pre-dispatch intent/possible acknowledgements, but does not invent a pre-prompt thread-ready or native turn-accepted event. Its observed configuration remains a terminal admission check.
+
+Go correlates each event, atomically saves and `fsync`s its checkpoint and state, then sends the matching ACK. Missing, early, duplicate, mismatched, or expired ACKs cannot release execution. `persistent:true` describes requested history preservation; it does not prove that an empty thread has a resumable rollout.
+
+An independent supervisor owns the native guardian. Worker loss cancels unacknowledged steps and initiates native cleanup. The complete terminal receipt is durable before the terminal notification. A lost notification or final ACK does not rewrite a completed receipt as unexecuted.
+
+## Read-only recovery
+
+Restarting the same task lets Go use the original adapter version, request/run IDs, directory, and binding to call public `recoverMachine`. It reads exactly one invocation journal: no CLI startup, `thread/resume`, other-history search, or prompt resubmission.
+
+| Result | Interpretation |
+|---|---|
+| `terminal` | A complete original receipt is available; validate identity, outcome, cleanup, accounting, and original candidate evidence |
+| `pending` | No durable terminal receipt is available; this is not proof of a live process, and execution stays blocked |
+| `unknown`, corruption, or mismatch | The outcome is unproven; preserve evidence and block replay, including after switching modes or backends |
+
+Queries may be repeated. Cross-machine recovery requires the original data and environment and is not promised. Killing the supervisor itself can leave pending evidence. This is not an exactly-once execution guarantee.
+
+### A successful receipt also needs original candidate evidence
+
+At `cleanup-confirmed`, before acknowledging, Go captures the post-call candidate digest, original role guards, and Execute report. A recovered success may advance the task only with that original proof. A new workspace snapshot or rerun verification after restart cannot substitute for it.
+
+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.
+
+## 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.
+
+State uses CAS. Receipts, state, and metrics must be durable before success. A metrics append followed by failed state CAS does not create a duplicate row on retry; an existing row must still pass file and directory synchronization. Readable bytes alone do not prove durability.
+
+Unknown is not zero. Rebuilds, role overrides, new workers, and Quick-to-Full transitions never reset budgets, attempts, or unknown-call blocking. Budgets constrain new dispatches, while a completed result with complete evidence can still be consumed.
+
+## 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).
+
+Optional `sessions.quality` supports:
+
+| Field | Measured fact |
+|---|---|
+| `max-confirmed-turns` | Confirmed, deduplicated calls in the current role history |
+| `max-unproductive-turns` | Consecutive Execute calls leaving the candidate digest unchanged |
+| `max-run-input-tokens` | The last complete, attributable input token count, not an inferred context-window size |
+
+All thresholds default to disabled. They may rebuild only after the previous call has safely ended, been accounted, and been consumed. Unknown or pending results take precedence.
+
+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
+
+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`.
+
+## 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.

package/docs/en/workflow.md

@@ -4,9 +4,31 @@
 
 This guide describes the **current source implementation** and a recommended operating workflow. It does not assert that a particular npm version has been published. Check the registry when installing. The engine's local delivery and the host's GitHub operations are separate responsibilities.
 
+## 0. Normal entry: describe a goal and launch
+
+With a matching CLI/plugin release containing the adaptive workflow, use:
+
+```text
+/flywheel-task Fix the identified bug, add regression coverage, and complete verification. mode=auto
+```
+
+The current host conversation researches the code, creates or reuses the task integration worktree, prepares contracts and workflow facts, and calls `flywheel_launch`. Go validates eligibility and starts the engine; DSH associates that exact task with the initiating session's Flywheel view. There is normally no need to copy paths or repeat an authorization already given. Check `flywheel control launch --help` before relying on this new entry; older installation commands do not prove its availability.
+
+| Choice | Selection and loop |
+|---|---|
+| Auto, the new entry's default | Select Quick from supported contract facts; use Full when facts are insufficient or risks remain |
+| Quick | One milestone and packet: Execute, all required checks, one independent final Review, Git delivery |
+| Full | Plan, packet execution/review, integrated L2/L3, Judge |
+
+Quick requires clear scope, a known implementation pattern, complete verification mappings, and a final reviewer able to assess the whole task. Missing L2/L3 needs an explicit inapplicability reason. File count does not establish safety: authentication, permissions, payments, migrations, concurrency, and unresolved design use Full. An explicit Quick request still has to qualify. A verification gap or new risk causes a persisted upgrade to Full while preserving task identity, work, budget, and history.
+
+The first-success Quick path has two stage-agent calls, Execute and final Review. Host preparation, internal model/tool turns, and retries are separate. Required coverage, integration/user-path tests, and applicable defect sampling still run against the final candidate; Plan/Judge are recorded as not applicable with reasons, never as fabricated passes.
+
+Use `/flywheel-new` when the user only wants a proposal and `/flywheel-run <actual task path>` to start or resume an existing task. Preserve prior implementation and delivery authorization; honor an explicit request to review a proposal first. The sections below explain the individual checkpoints, not mandatory approval stops for the unified entry.
+
 ## 1. Choose a model for preparation
 
-Preparation turns a requirement into a Spec, task packets, acceptance commands, boundaries, and recorded dry-run evidence. `flywheel-new` uses the model selected in the host's current conversation. It does not switch that model based on `loops.plan`; that binding controls planning and revisions after the Go engine starts.
+Preparation turns a requirement into a Spec, task packets, acceptance commands, boundaries, and recorded dry-run evidence. `flywheel-task` and `flywheel-new` use the host's current conversation model. They do not switch it based on `loops.plan`; that binding controls planning and revisions after the Go engine starts.
 
 For accounts that expose the named models, these are practical starting points:
 
@@ -73,6 +95,8 @@ A runnable task needs a reviewed `spec.md` and at least one legal `task-packet-*
 - Frozen acceptance tests or other oracles, separately protected from implementation tests.
 - Actual dry-run results, with failure output and exit codes where applicable.
 
+The unified entry also records `workflow` in the Spec: version, requested mode, qualification facts, code evidence, risks, and reasons for inapplicable checks. See [Workflow policy and recovery](configuration.md#workflow-policy-and-recovery). A model's low-risk label alone is insufficient. Old contracts without this field remain Full.
+
 Run the stated commands before recording their results. An intentionally failing baseline can be valid evidence; a guessed passing result cannot. Ordinary implementation and regression tests can be added by the executor. Frozen acceptance and configuration must not be rewritten to make an implementation pass.
 
 Review the files, then commit the substantive initial contracts so packet worktrees can obtain them from Git. The following assumes the index has been checked for unrelated staged work:
@@ -121,16 +145,19 @@ flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 
 Preflight does not infer with a model or execute acceptance commands. Its unknown and warning results still need interpretation. Starting the real task invokes the configured models. A control response's `ok` describes the operation; final task completion is in `state.status`.
 
-To inspect the task in the Flywheel view, enter the supplied `task_dir`. Its optional project directory can stay blank only when the DSH session's current working directory is the same `repo_dir`. Current source reads it through public `workingDirectory.get(session)`; an explicit path takes precedence. A shell `cd` alone does not change the DSH session directory, so enter `repo_dir` if the session still points elsewhere. Skill calls do not automatically select the view's task, and the view does not infer, discover, or start a task automatically.
+For the new unified entry, use `control launch ... --mode auto` in place of `start`. It consumes prepared contracts and defaults to Auto. `start` and foreground `run` accept optional `--mode auto|quick|full`; omission retains the contract or persisted choice. Existing legacy state remains Full. Restarting or requesting Auto does not reclassify or downgrade an established Full task.
+
+DSH's `flywheel_launch` and `flywheel_control` start associate the supplied `taskDir` and `cwd` with the initiating session. Calling the CLI from a shell alone does not establish a desktop association. For terminal-started tasks or manual opening, enter the actual task directory and project root. The project field may be blank only if the DSH session directory already matches; it is read through public `workingDirectory.get(session)`. A shell `cd` alone does not change that directory. The plugin does not scan or guess tasks.
 
 ### Working directory by stage
 
 | Stage or entry | Working directory | Responsibility |
 |---|---|---|
-| `flywheel-new` preparation | Task integration worktree | Host creates or reuses it according to the skill |
-| Plan | Task integration worktree | Engine uses the startup root to revise the task contracts |
+| `flywheel-task` / `flywheel-new` preparation | Task integration worktree | Host creates or reuses it according to the skill |
+| Full Plan / revision after upgrade | Task integration worktree | Engine uses the startup root to revise the task contracts |
 | Execute, L1, Review | Current packet candidate workspace, normally its packet worktree | Engine creates, records, and reuses that workspace |
-| L2/L3, Judge | Task integration worktree | Engine checks the integrated milestone |
+| Quick's applicable L2/L3 | The same packet candidate, before final Review | The engine must not validate a stale integration checkout |
+| Full L2/L3, Judge | Task integration worktree | Engine checks the integrated milestone |
 | Intake, Garden | Selected task's worktree | Host selects the root; Go writes proposals |
 | Status, Stop | Original task directory and execution root | Query or stop the existing task without requiring a new worktree, branch switch, or commit |
 
@@ -138,13 +165,19 @@ Model-call permissions follow `permissions.mode`. Under `role-based`, the defaul
 
 Every loop does not create its own worktree. The outer task worktree spans the deliverable; a packet workspace spans its execution, acceptance, review, and delivery. Plan commits valid contract revisions in the integration worktree and attempts to fast-forward existing packet worktrees to that checkpoint while preserving implementation work. Conflicts stop for resolution.
 
-`flywheel-verify` runs deterministic acceptance only. With `--packet`, it runs that packet's L1. Without a packet, it checks unfinished packets' L1 and the current milestone's L2/L3. It does **not** call Review or Judge, create worktrees, or perform local delivery. It uses the available candidate workspace and may use the integration checkout when no packet worktree is available.
+Go schedules packets serially and does not need a persistent parent model session to supervise them. `sessions.mode=scoped` permits ordinary repairs to continue the packet's Executor history, and a Reviewer may continue its own independent history for the same review scope. Every re-review still checks the complete current candidate, contract, and applicable requirements; closing old findings is insufficient. Plan history is task/milestone scoped, primary Judge and second opinion are separate, and an explicit Plan `resident-session:false` remains effective. Parallel DAG scheduling and team communication remain outside this implementation.
+
+New configuration templates explicitly select scoped mode; old files without the setting retain fresh mode. Fresh disables general role history reuse while preserving the legacy Kimi Plan resident option. Both modes journal supported main-task Codex Pro, DSH, and Kimi calls. Other adapters, mock, and Intake/Garden retain their existing paths. History reuse does not remove verification requirements or add stages to Quick's two-call first-success path. See [Session policy](configuration.md#session-policy-history-reuse-and-invocation-safety).
+
+Saved receipt recovery retains the original candidate, contract, and role guard evidence. Re-running sampling or verification cannot replace evidence bound to a pending receipt. Consuming an already completed result makes no new model request and does not bill twice; budgets constrain new dispatches. P3 uses public Codex/Claude lifecycle events, durable Go ACKs, and read-only invocation journals; recovered success still requires the original post-call candidate and role proof. P4 adds role overrides, bounded quality rebuilds, and paired evaluation, with thresholds disabled by default and live effects separately measured. See [recovery and quality](session-recovery.md) and [paired evaluation](session-evaluation.md).
+
+`flywheel-verify` runs deterministic acceptance only. Full retains the existing packet L1 / milestone L2/L3 behavior; Quick also collects applicable L2/L3 in the actual candidate workspace. It does **not** call Review or Judge, create worktrees, or perform local delivery. `--only execute` remains a partial Execute/L1 loop. A Quick task's `--only review` performs final Review without delivery; a verification gap, upgrade verdict, or lost Quick eligibility immediately saves the one-way Full checkpoint. The next complete run enters Full. `--only plan` requires Full, so explicitly request `--mode full` when a Quick task needs planning. Resume the complete run to let Go handle the remaining stages and delivery.
 
 The bundled skills check task location before preparation, run, resume, and manual loop actions. By default, development starts outside `main`, `master`, a known default branch, or detached HEAD unless the user has explicitly chosen and authorized that location. Direct CLI and GUI actions do not read or execute `SKILL.md`, create the outer task branch, or inherit those host checks. Read-only status and stopping must remain available even when development-entry checks would fail.
 
 ## 6. Understand local completion before merging the PR
 
-A packet is delivered only after L1 and independent Review match its current candidate, and Git delivery is confirmed. The engine commits implementation changes, performs `git merge --ff-only` into the integration checkout, persists delivery state, and cleans up only when safe. Failed commits or merges preserve the workspace. Milestone completion additionally requires L2/L3 and Judge.
+A packet is delivered only after required checks and independent Review match its current candidate, and Git delivery is confirmed. The engine commits implementation changes, performs `git merge --ff-only` into the integration checkout, persists delivery state, and cleans up only when safe. Failed commits or merges preserve the workspace. Full additionally runs integrated L2/L3 and Judge. Quick runs applicable L2/L3 before a final Review that covers every requirement, acceptance sufficiency, and continued eligibility; it then persists that same candidate.
 
 After the complete task passes, inspect the integrated changes and push them:
 
@@ -168,7 +201,7 @@ flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 
 Check the stop result and the actual failure before resuming from the **same** root and task path with `control start` or `flywheel-run`. A startup readiness timeout is a reason to query status and logs, not to launch a duplicate run. A stopped engine does not prove that every separately managed process is gone.
 
-Codex Pro retains a machine receipt with configuration, process, cleanup, and usage facts. If cleanup is unconfirmed after the worker started, the engine escalates and stops the current run. It does not automatically try another channel, a transport retry, or a fresh Plan call. Confirm the task-owned plugin/app-server/guardian processes have ended before attempting recovery; a fixed delay is not evidence. Avoid broad process killing that could terminate unrelated sessions.
+Supported main-task adapters retain invocation facts and terminal receipts. Unknown dispatch, outcome, or cleanup blocks further execution in both session modes, including after a backend change. Confirm the task-owned plugin/app-server/guardian processes have ended when cleanup is uncertain; a fixed delay is not evidence, and process exit alone does not establish a known model outcome. Go must reconcile a trusted receipt against the original identity and evidence. Changing to fresh, switching task directories, resetting state, or retrying through another channel cannot bypass an unresolved invocation. Avoid broad process killing that could terminate unrelated sessions.
 
 For a delivery conflict, preserve the packet worktree, inspect Git state, resolve the conflict deliberately, then resume and let the engine revalidate evidence. Do not use forced cleanup or manual state edits as a recovery shortcut. Configuration changes require restarting the engine.
 
@@ -177,3 +210,7 @@ For a delivery conflict, preserve the packet worktree, inspect Git state, resolv
 The engine owns local state, bounded loops, verification, and Git delivery. The authorized host/user owns task-branch setup, GitHub pushes and PRs, remote CI policy, PR merge, and publication. Repository visibility and licensing are separate decisions.
 
 Implementation references: [engine](https://github.com/ckanner/flywheel/blob/main/internal/machine/run.go), [Git/worktree operations](https://github.com/ckanner/flywheel/blob/main/internal/verify/verify.go), [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md), and [bundled skills](https://github.com/ckanner/flywheel/tree/main/skills). Additional documentation: [Git worktree](https://git-scm.com/docs/git-worktree) and [GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request).
+
+## Interactive console delivery
+
+The [workflow console](flow-console.md) adds stage controls, handoff, declared parallelism and explicitly authorized PR/Merge operations. Local completion does not authorize remote writes. An earlier Draft PR is reconciled after push; publication validates the actual merge commit separately.

package/docs/flow-console.md

@@ -0,0 +1,90 @@
+# Flywheel 流程控制台
+
+本文描述当前源码中的控制台。源码、开发候选、本机安装与 npm 正式发行分别验收；不要仅凭本文判断 `@latest` 已包含这些功能。CLI、平台包和 DSH 插件必须同版。
+
+## 从配置开始
+
+DSH 的 Flywheel 会话视图仍排在“统计”之后。内部有“运行画布”“全局／项目配置”“运行与对比”。全局配置可在没有任务目录时编辑；项目配置写入所选 Git 项目根。任务配置仍具有最高优先级，取首个完整文件，不做字段深度合并。
+
+先读取草稿，再选择 Provider／Harness、模型、推理等级、权限与历史策略。“载入本版本默认值”导入完整默认模板；保存前显示差异与目标，Go 核对内容 revision、备份旧文件并原子写入。正在运行的引擎保留原快照，新配置在后续启动时加载。
+
+支持的资源入口包括 ChatGPT · DSH、ChatGPT · Codex Pro、Kimi Code、DeepSeek Account（默认 Flash）及可选 Claude Code Pro。模型初值来自本版本模板，真实能力以 `config inspect`／`doctor` 为准。Claude 的可选适配器必须匹配公开 machine API；缺失或权限不支持会拒绝调用，不自动换后端。账号登录仍由各 Provider 自己完成。
+
+`permissions.bindings` 可以覆盖 `loops.<role>`、`routes.<route>` 和 `judge-panel`；未覆盖项使用全局策略。会话策略按角色覆盖：执行 routes 共用 execute 的策略，各 packet 的历史仍隔离。scoped 只续接相同任务、角色、目标和绑定下可恢复的历史；fresh 也保留调用安全账本。
+
+## 横向画布与节点操作
+
+主线从左到右展示 Plan／拆分、调度、任务分支、集成、终验、PR、Merge。点击任务展开 Execute、L1、Review、Git 交付。状态配合颜色和文字，运行与节点详情展示来源 DSH 会话、项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
+
+画布支持拖动、横移、定位当前节点和分组浏览。大任务使用有界诊断摘要；“读取完整节点证据”按需加载选中节点，revision 与同一时刻的画布状态一起刷新。摘要不会改写原始账本。
+
+| 操作 | 含义 |
+|---|---|
+| 运行此阶段 | 提交已观察的 revision；Go 在任务租约内重新检查前置条件 |
+| 人工继续一次 | 填写原因，追加一次 Execute／L1 尝试；保留累计失败和预算 |
+| 已完成单元重跑 | 归档旧证据和提交回执，使当前与后续单元的候选证据失效 |
+| Git 交付 | 只在当前 L1 与独立 Review 通过后持久化当前单元 |
+| 终验 | 已集成单元的 L2／L3 与独立 Judge；不重新调用 Plan 或启动未完成单元 |
+| 继续整个流程 | 由 Go 继续已保存的 Full 或 ultraWork／Quick 策略 |
+| 停止 | 请求 Go 收束在飞子进程；关闭页面不代表停止 |
+
+有显式调度声明且依赖已交付的独立 packet 可单独提前执行，仍使用隔离 worktree。合并后的候选变化会使旧验收失效，必须重新验证和 Review。每个异步节点操作保存 running／passed／failed／cancelled 回执，失败原因不会仅留在后台日志。
+
+Quick 在 UI 中显示为 ultraWork／Quick；它仍要求确定性验证和独立最终 Review。Plan／Judge 按持久化策略标为不适用，不伪造完成状态。
+
+## 串行与并行
+
+配置入口为 `scheduler`，字段和边界以 `flywheel template scheduler-policy.schema.json` 为准。例如：
+
+```json
+{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}}
+```
+
+`providers` 的键是实际账号渠道名。并行资格来自冻结 packet 的声明，而不是模型临时口头建议：
+
+```yaml
+schedule:
+  after: [M01-T01]
+  writes: [src/search/, tests/search/]
+```
+
+依赖必须指向较早编号的已知 packet；写入范围是规范相对路径／目录前缀，不支持通配符或越出项目的路径。声明要覆盖实现、普通测试和必要配置，并考虑共享测试服务等真实依赖。未声明独立性、写入范围冲突或需要 live 凭证的单元保留串行。
+
+只有 Execute／L1 并发，工作区各自独立；一个 Go 协调器串行 CAS 保存状态和用量。hard 预算只允许一个模型调用在飞，并在下一调用前确认前一笔计费。其他模式按最大并发与渠道限制接纳。停止会等待整批已启动工作收尾。
+
+Review、集成与里程碑 gate 保持串行。后续分支吸收已完成成果后，在合成候选上重新验收。执行重试耗尽仍走原有升级策略；集成冲突或门禁失败保留 worktree 和失败证据。`writes` 是调度／验收契约，完全权限本身不提供 OS 沙箱。
+
+## 在同一 Provider Session 中接管
+
+任务节点显示准确的 Provider session。读取最近回复只读取摘要校验过的原回执，不宣称它是后端的完整历史。
+
+已确认收尾、已消费结果、绑定匹配的 packet session 可“暂停并接管”。接管标记持久化后，普通 run／单阶段操作不能绕过它。桌面输入的人工 Prompt 和 `flywheel session` 都通过原适配器恢复那个准确 thread，并继续预算与计费；恢复失败或需要重建时不冷启动替代。
+
+```sh
+cd -- '/absolute/task-worktree'
+flywheel session '/absolute/task-worktree/docs/task-slug' --key 'execute/M01-T01'
+```
+
+终端每行是一条 Prompt；`/history` 查看最近回复，`/reconcile` 核对原调用，`/return` 验证交回，`/release` 退出接管并保持暂停，`/quit` 保留接管退出。多行 Prompt 可用桌面文本框。
+
+“验证并交回”重新运行 L1、适用的 Quick gate 和独立 Review；人工回复本身不是通过证据。Go 保存绑定当前候选的 `human-takeover` 来源，后续正常交付仍由引擎完成。“退出接管”不声称验收成功；结果或清理未知时也不能借此解除阻断。里程碑会话目前提供只读回复，交互接管以 packet 为单位。
+
+会话账本存储为 v2，新引擎兼容旧 v1；旧引擎会拒绝 v2，避免忽略接管标记。配置的 `sessions.policy-version` 仍是 1，worker／lifecycle 协议不因此改变。
+
+## 发现运行与比较
+
+CLI 和桌面启动自动登记 run ID；会话投影保留多个已确认任务。登记位于全局配置旁的 `runs/`，可用绝对 `FLYWHEEL_RUNS_DIR` 覆盖。列表只读取明确登记，显示最近 100 项，不扫描整个磁盘；当前存活状态始终重新查询 Go。
+
+对比页面显示操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。可选准确 run ID，也可查看本任务全部调用（包括早期未登记记录）。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。
+
+用量、费用和时延只表示已知量，缺失／部分数据单列，费用也可能来自配置单价估算。调用失败率不等于代码质量；条件不同的运行只并列展示，不伪称配对收益。完整的质量结论需要任务验收和独立 oracle。
+
+## 远端 PR 与 Merge
+
+在 PR 节点先查询项目与远端状态。远端操作需要 GitHub CLI 的正常登录，以及当前本地任务完成、候选仍有有效验收、明确的仓库／HEAD／目标分支授权。已记录的项目远端发生变化会拒绝交付；fetch 与 push URL 必须指向同一仓库。
+
+推送使用已批准的 commit 和明确任务分支，不强推，不隐式跟随 tags 或推送 submodules。可选择独立的远端任务分支，不必切换本地 checkout。推送后重新查询已有 PR，避免把预先创建的 Draft PR 误当成需要重复创建。
+
+合并再次核对 PR、源 HEAD、base 和检查状态，并使用 GitHub CLI 的 `--match-head-commit`。不使用 admin 绕过，也不擅自开启 auto-merge。仓库要求 merge queue 时，“请求已接收”和“已合并”分别记录，以远端回执为准。接口语义见 [GitHub CLI 文档](https://cli.github.com/manual/gh_pr_merge)。
+
+已确认的创建／合并操作重跑时先核对已有结果。命令失败或回执丢失保留 unknown，不猜测远端成功。PR／Merge 状态与引擎的本地完成分开；发布应绑定实际 merge commit 和发布产物重新验收，不因点击 Merge 自动发布 npm 或部署。

package/docs/getting-started.md

@@ -8,12 +8,20 @@
 
 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](releasing.md#3-失败恢复)。
 
+**自适应工作流是本轮源码新增能力。** `/flywheel-task`、`control launch` 与 Auto／Quick／Full
+需要包含这些变更的同版本 CLI／插件；先核对 `flywheel control launch --help`，
+不要把旧发行包的基础安装成功当成新功能已生效。
+
 订阅预设迁移命令与 `permissions.mode` 从 **0.28.2** 开始提供。升级不会自动替换已有配置；先预览 `flywheel config migrate --preset subscriptions`，确认模型和完全权限后再以 `--apply` 应用并备份。
 
 **0.28.5 排序**：Flywheel 自定义会话视图排在内置“统计”之后，视图的打开与溢出菜单仍由 DSH 管理。
 
 **0.28.3 修复**：下文的 `deepseek-account` 默认和留空目录读取会话当前工作目录从 0.28.3 开始提供。0.28.2 仍使用 `deepseek-official` 与最初目录。安装前核对 registry 版本；升级保留已有配置，采用账号预设需要显式迁移。
 
+**可选 Claude 后端：**默认安装不要求 Claude。选择 `claude-code-pro` 时需额外安装 worker 能解析的配套 0.4.0 插件，并准备本机 Claude CLI／登录。具体版本、配置与源码候选边界见 [Claude Code Pro 指南](claude-code-pro.md)。
+
+Codex Pro 0.9.0 的已审查真实源码包随本次 Flywheel 插件 bundle，开发候选安装不依赖一个尚未发布的 registry 版本；[来源与摘要](../plugins/dsh/vendor/README.md)。P3/P4 的行为与实测边界见[恢复指南](session-recovery.md)和[对照评估](session-evaluation.md)。
+
 ## 目录
 
 1. [准备运行环境](#1-准备运行环境)
@@ -40,7 +48,7 @@
 | SDK profile 的 DeepSeek 和 ChatGPT provider | 默认实现／评审使用；配置与授权见下一节 |
 | Go 1.27 或更高 | 仅本文的 Go 示例和源码构建需要；npm 安装 Flywheel 不需要 Go 工具链 |
 
-安装器的前提是已有 Node／npm 和桌面 DSH；模型渠道可在安装后补齐。CLI 的登录和安装使用各自正式流程。默认复用 Kimi 订阅、ChatGPT 订阅和已登录、已充值的 DeepSeek 账号；DeepSeek API 是需要显式配置的可选渠道。安装 Flywheel 不会替这些工具登录、复制凭证或替换桌面程序。只运行默认小任务时不会使用 `hard` 路由，但所选 Plan、Execute、Review、Judge 均需要可用。
+安装器的前提是已有 Node／npm 和桌面 DSH；模型渠道可在安装后补齐。CLI 的登录和安装使用各自正式流程。默认复用 Kimi 订阅、ChatGPT 订阅和已登录、已充值的 DeepSeek 账号；DeepSeek API 是需要显式配置的可选渠道。安装 Flywheel 不会替这些工具登录、复制凭证或替换桌面程序。Full 需要所选 Plan、Execute、Review、Judge；合格 Quick 的正常路径只调用实际 Execute 路由与最终 Review，发生升级后才需要 Full 阶段。
 
 ## 2. 一条命令安装
 
@@ -58,8 +66,8 @@ npx -y @ckanner/flywheel@latest install --json
 
 两条命令选择一种即可。安装器按顺序完成：
 
-1. 把本次安装器的精确版本装到 npm 全局目录，解析适合本机的 Go 平台包、同版本 DSH／Codex Pro workers 及精确插件依赖 `dsh-subagent-codex-pro@0.8.0`，核对 CLI 版本。
-2. 从 Go 二进制安装全部 10 个 skills；全局配置不存在时生成默认配置，已有配置保留。
+1. 把本次安装器的精确版本装到 npm 全局目录，解析适合本机的 Go 平台包、同版本 DSH／Codex Pro workers 及精确插件依赖 `dsh-subagent-codex-pro@0.9.0`，核对 CLI 版本。
+2. 从 Go 二进制安装该版本的全部 skills（当前源码为 11 个）；全局配置不存在时生成默认配置，已有配置保留。
 3. 写入 GUI 启动器和安装记录，使用绝对 Node／CLI 路径。
 4. 通过现有桌面 `dsh` 注册精确版本的 Flywheel 插件，并通过 `plugin list` 验证安装结果。
 5. 执行不带 `--probe` 的本地 `doctor`，汇总工具、配置及目录检查结果。
@@ -103,7 +111,7 @@ flywheel setup --no-global
 
 安装器已经调用正式接口 `dsh plugin --profile desktop add --save-exact --ignore-scripts @ckanner/dsh-plugin-flywheel@<本次精确版本>`，随后通过 `list` 核对版本。无需再分别安装 worker 或手动选择压缩包。该命令必须来自桌面安装；独立 npm DSH CLI 不能管理保留的 `desktop` profile。按照宿主提示重新载入，在顶部“对话／轨迹”所在的原生视图栏选择 **Flywheel**；未直接显示时检查该栏的更多入口。
 
-这个视图用于控制和观察已经准备好的任务：看进度、人工处理项、实际模型和环境，显式启动、刷新或停止。它保留 DSH 的原生对话、轨迹、输入区、模型选择器和右侧栏；需求讨论与契约准备仍在原来的对话和 skills 中进行。视图不会自动发现别处启动的任务，需要选择相同的任务目录。
+这个视图用于控制和观察已经准备好的任务：看进度、策略、人工处理项、实际模型和环境，显式启动、刷新或停止。它保留 DSH 的原生对话、轨迹、输入区、模型选择器和右侧栏；需求讨论与契约准备仍在对话和 skills 中进行。新入口通过 DSH 工具 launch／start 关联具体任务；视图不扫描目录，终端另行启动的任务仍可手动打开。
 
 ### 原生 SDK profile
 
@@ -165,17 +173,20 @@ flywheel config inspect --cwd /absolute/path/to/target-repo --json
 
 ### 查看或补装 skills
 
-一条命令安装已经包含全部 10 个 skills，默认在 `~/.agents/skills`；使用它们仍是可选的，桌面面板和 CLI 可以独立工作。需要另外安装到目标项目时运行：
+一条命令安装包含所选版本的全部 skills（当前源码为 11 个），默认在 `~/.agents/skills`；使用它们仍是可选的，桌面面板和 CLI 可以独立工作。需要另外安装到目标项目时运行：
 
 ```sh
 flywheel install-skills --project /absolute/path/to/target-repo --json
 flywheel skills list
-flywheel skills read flywheel-run
+flywheel skills read flywheel-task
 ```
 
 安装输出会给出 `.agents/skills` 的准确位置。按宿主支持的发现规则启用目录，不能从文件已复制推断 DSH／Kimi 已自动发现。也可直接使用 Go CLI。
 
-DSH 在对话输入框用 `/flywheel-new`、`/flywheel-run`、`/flywheel-status`，也可从 `/` 菜单选择；Kimi 对应使用 `/skill:flywheel-new` 等语法。技能名相同，调用前缀随宿主不同。正常准备、启动和查状态可以全部在对话里完成，**不必先填写 Flywheel 视图**；视图用于另外打开已经准备好的任务。可复制的完整流程见[工作流](workflow.md#3-在任务-worktree-中准备并审阅契约)。
+DSH 用 `/flywheel-task <目标>` 准备并启动，`/flywheel-new` 只准备方案，`/flywheel-run`
+启动或恢复已有任务，`/flywheel-status` 查进度；也可从 `/` 菜单选择。Kimi 对应使用
+`/skill:flywheel-task` 等语法。准备、启动和观察可以全部在对话完成，**不必先填写
+Flywheel 视图**；DSH 启动工具会关联真实任务。完整流程见[工作流](workflow.md)。
 
 快照的 `.flywheel-snapshot` 清单记录文件内容 hash、类型与模式。重跑会跳过相同内容，更新未被修改的自有快照；用户修改、新增／删除文件、链接、未标记目录或损坏清单会保留并报告冲突。每个 skill 独立采用暂存、rename 和失败回滚，不会覆盖手工修改。旧纯文本标记只有在整个目录与当前内嵌内容相同时才能安全迁移。`--force` 只用于 `--link` 开发模式，不能绕过默认保护。安装会在全局配置缺失时创建它，但不会改写已有配置。
 
@@ -194,7 +205,10 @@ flywheel doctor --cwd "$PWD" --probe --json
 
 结果按 pass／fail／warn／unknown／skipped 展示；有 fail 时退出码 1，JSON 仍完整可读。即使 `ok:true`，unknown 的账号授权、订阅额度与实际推理仍未验证。Kimi/Codex 在这里只检查命令；Codex Pro 额外实际导入精确版本的公开 API，不会自动登录或试调用。Codex Pro 的完整沙箱策略只能事后审查，所以对应 sandbox 项会显示 warn，模型／配置／认证保持 unknown；`--probe` 也不会为它发送推理。DSH 同一账号、模型、effort、目录和权限只探测一次，总预算 40 秒另加清理窗口；超时后明确失败。
 
-未指定任务时检查全部配置绑定，可能包括首个任务用不到的 Codex hard 路由。准备好任务后可把范围缩小为所需的 Plan／Execute route／Review／Judge（以及显式启用的 judge-panel）：
+未指定任务时检查全部配置绑定，可能包括首个任务用不到的 Codex hard 路由。
+准备好任务后按 Spec／持久化策略缩小范围：Full 包含 Plan／实际 Execute route／
+Review／Judge 与启用的第二意见，合格 Quick 跳过 Plan／Judge／第二意见。
+它不重新分类已保存的任务，也不接收启动时另传的 `--mode` 覆盖：
 
 ```sh
 flywheel doctor --cwd "$PWD" --task-dir docs/add --probe --json
@@ -202,21 +216,28 @@ flywheel doctor --cwd "$PWD" --task-dir docs/add --probe --json
 
 尚无 packet 时按规划前状态预检默认执行路由，规划后应再检查。坏契约会报告阻断项，不能用探测通过代替 schema 校验。若 cwd、权限、provider 或沙箱检查失败，先修正相应配置，不把权限改成 full access 绕过。桌面视图的“配置与排查（按需）”提供“查看模型配置／检查安装与配置／检查 DSH 接入”，使用同一个 CLI 后端；安装、改配置或排错时按需使用，不是每次任务都必须手点的步骤。GUI 与终端环境不同的问题应在视图内复验。
 
-这允许在准备契约时提前排查安装，但正式启动仍需至少一个已审阅的合法 packet。完成下一节的小任务准备后，再运行带 `--task-dir` 的检查。
+这允许在准备契约时提前排查安装，但正式启动仍需至少一个合法 packet 和明确授权的需求。完成下一节的小任务准备后，再运行带 `--task-dir` 的检查。
 
 ## 6. 准备首个小任务
 
 已有业务仓库应先建立任务集成分支和独立 worktree，再生成契约；启动时的 `cwd` 指向该 worktree。完整步骤见[从需求准备到 PR 合并](workflow.md)，下面的小仓库示例用于首次运行验收。
 
-正常在 DSH 对话中发送 `/flywheel-new` 加上实际需求，助手按 skill 创建或复用任务 worktree，准备 `docs/<slug>/spec.md` 与 task packets，然后给出两个真实绝对路径：**项目目录**是代码所在 worktree，**任务资料目录**是其中保存本任务契约和后续状态／报告的 `docs/<slug>`。无需自己预先创建空目录或填写 UI；先审阅契约，再用这份真实路径启动。
+正常在 DSH 对话发送 `/flywheel-task <实际需求>`，可加 `mode=quick` 或 `mode=full`，
+默认 Auto。助手研究代码、创建或复用 worktree，准备 `docs/<slug>/spec.md` 与 packets，
+保存工作流事实，再启动并关联到视图。**项目目录**是代码 worktree，**任务资料目录**
+是其中保存契约和状态／报告的 `docs/<slug>`；工具会传递真实绝对路径，无需自行猜目录。
+只想先审阅方案时使用 `/flywheel-new`，之后沿用原路径与授权启动。
 
-首次建议使用单独的小仓库，便于分清安装问题和业务代码问题。npm 包附带的准备脚本会创建一个 Go 加法函数任务：初始实现故意错误，执行者需修复实现并补普通单测；独立 acceptance 测试不可修改。本示例需要 Go 1.27 或更高。
+首次也可使用独立小仓库区分安装与业务问题。npm 包附带的准备脚本创建 Go 加法函数任务：
+初始实现故意错误，执行者修复并补普通单测，独立 acceptance 不可修改。该兼容示例
+没有 workflow 字段，继续走 Full；要体验 Auto／Quick，优先使用上面的统一入口准备
+真实资格事实，不能只换启动参数伪造事实。本示例需要 Go 1.27 或更高。
 
 ```sh
 FLYWHEEL_PACKAGE="$(npm root --global)/@ckanner/flywheel"
 bash "$FLYWHEEL_PACKAGE/docs/examples/create-first-task.sh" "$HOME/flywheel-demo"
 cd "$HOME/flywheel-demo"
-git init
+git init -b main
 ```
 
 如果安装时使用了自定义 prefix，用 `npm root --global --prefix "$HOME/.local"` 等实际 prefix 定位包目录；不需要克隆源码。
@@ -248,11 +269,18 @@ go test -coverprofile=coverage.out . &&
 ```sh
 git add go.mod sum.go acceptance .gitignore flywheel.config.json docs/add
 git commit -m "docs: prepare first flywheel task"
+git worktree add -b task/add ../flywheel-demo-add
+cd ../flywheel-demo-add
 ```
 
-Git 提交身份必须已经按自己的设置配置。此时不应创建 `state.json`，它由引擎初始化。coverage 输出已被忽略，所以验收运行不会把生成物误判为候选代码漂移。
+Git 提交身份必须已经按自己的设置配置，工作区新目录不可被占用。后续在 `task/add`
+工作区运行，packet 合回该任务分支。此时不应创建 `state.json`，它由引擎初始化。
+coverage 输出已被忽略，所以验收运行不会把生成物误判为候选代码漂移。
 
-对于已有业务仓库，`flywheel-new` 使用当前 DSH 会话的模型生成契约；复杂需求建议选已授权的 `gpt-6-astra`、`high`，简单明确任务可沿用 Flash。它不会自动读取 `loops.plan` 来换模型，后者控制引擎运行后的 Kimi 规划／修订。可以通过 `flywheel-new` 生成并审阅契约，或者用 `flywheel template --list` 查看模板后手工准备。示例 auth 模板不是通用可运行任务，其中路径和验收命令必须改为真实项目的命令。不要照抄后直接启动。
+业务仓库的 `flywheel-task`／`flywheel-new` 都使用当前 DSH 会话模型生成契约，
+不读取 `loops.plan` 来换模型，后者只控制引擎规划／修订。也可查看
+`flywheel template --list` 后手工准备。示例 auth 模板涉及鉴权，不能因为 packet
+很小就标 Quick；路径与验收命令必须改为项目事实，不要照抄后直接启动。
 
 ## 7. 启动、观察、停止与恢复
 
@@ -265,9 +293,15 @@ flywheel control status --task-dir "$PWD/docs/add" --cwd "$PWD"
 
 在 DSH 对话中也可使用 `/flywheel-run <任务资料绝对路径>`、`/flywheel-status <同一路径>`，需要停止时用 `/flywheel-stop <同一路径>`。把占位内容替换成准备阶段给出的真实路径；这些技能会解析正确的项目根，不依赖先填写视图。
 
-`ok: true` 只表示控制操作成功；`running` 表示引擎运行状态，最终任务结果看 `state.status`。另选顶部 **Flywheel** 视图时，在“任务资料目录”填写同一个 `task_dir`。“项目目录”可留空，前提是 DSH 会话的当前工作目录已经是该任务的 `repo_dir`；任务在其他 worktree 时填写助手给出的项目路径。仅在 shell 中 `cd` 不会改变 DSH 的会话目录，技能也不会自动选择视图中的任务。按需展开“配置与排查（按需）”，再点击“启动／刷新状态／停止”。视图区分未初始化、运行、已完成、暂停、停止和升级，标明最近刷新时间；它不会自动轮询。
+`ok: true` 只表示控制操作成功；`running` 表示引擎是否在运行，完成看 `state.status`。
+DSH 工具 launch／start 会关联当前会话视图，确认关联后查询一次最新状态；终端
+启动或手动打开时，仍填写同一个 `task_dir` 与实际 `repo_dir`。项目目录仅在会话
+当前目录相同时可留空，shell `cd` 不改变会话目录。视图展示请求／生效模式、理由、
+阶段适用性、任务状态与刷新时间；不适用的 Plan／Judge 不算通过，也不会自动轮询。
 
-宿主保留会话绑定期间，路径草稿与快照会按会话保留，切换“对话／轨迹／Flywheel”不丢失；重新载入插件或桌面后可能需要重新选择路径。修改路径清除旧结果并忽略迟到响应，不会停止旧任务。每个会话只等待一个控制请求；启动或停止等待期间锁定目录输入。
+会话的工具／命令记录仍在时，重载可通过公开投影重建明确的任务关联；fork 不继承
+父会话关联。手动路径草稿与旧快照只是查看缓存，重载后可能需重选或刷新。修改路径
+忽略旧响应，不会停止旧任务。每个会话只等待一个控制请求，启动或停止期间锁定目录。
 
 启动或停止超时、断连后，后台任务的结果可能尚未确认。保留原任务目录，先“刷新状态”和查看日志；界面在成功核对该任务前禁止继续启动／停止，也不会自动重试。已有快照只是上次结果，不能凭页面关闭、切换会话或停止按钮失去等待状态推断引擎已经结束。原生轨迹保留父会话自己的记录，worker 完整历史不自动合并到其中。
 
@@ -279,7 +313,7 @@ flywheel control status --task-dir "$PWD/docs/add" --cwd "$PWD"
 flywheel run docs/add --pause-before review
 ```
 
-`control start` 当前不接受 `--pause-before`。`--only execute` 会运行 Execute 子环及 L1，直至通过或遇到失败出口；它不是一次模型调用。`--only review` 只返回评审裁决，不会自动跨到 Plan 修订。单环命令详见各内嵌 skill。
+`control launch` 和 `control start` 不接受 `--pause-before`，暂停模式不能与 `--only` 并用。`--only execute` 会运行 Execute 子环及 L1，直至通过或遇到失败出口；它既不是 Quick，也不是一次模型调用。Quick 的 `--only review` 使用最终 Review 协议，需要升级时立即保存单向 Full checkpoint，但不自动跨到 Plan 或执行本地交付；`--only verify` 在指定 packet 时仍包含候选上适用的 L2/L3。Quick 要单步运行 Plan，需明确 `--mode full` 升级。单环命令详见各内嵌 skill。
 
 观察人话摘要和日志：