@ckanner/flywheel 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.31.0 — 项目归属与执行目录分离（发行候选）
+
+- Session 归属原仓库，执行、验收与交付仍绑定实际任务目录；提示词和界面分别展示两层位置。
+- DSH SDK Session 使用稳定项目 header 和公开目录切换；桌面 Host 通过 Workspace 注册表补齐归属，探测会话使用临时持久化目录。
+- 自动管理 Worktree 默认开启，与并行策略解耦；新默认允许并行，最大并发 2，仍核对任务依赖及写入范围。
+- 共享目录并发采用批次验收：所有执行结束后验证完整共同候选，返修导致旧证据失效时重验，全部通过后统一提交并原子完成整组；保留未知调用和清理阻断。
+- 关闭自动管理后允许并发，也支持执行者在实现前提交结构化目录提案；核对同仓库、基线、分支、干净状态和独占归属后登记，后续执行／Review／交付跟随该目录，外部 Worktree 保留。
+- 旧回执先按原身份核对；同项目的旧会话可继续使用，不重写历史头部。无法分离 workspace-write 沙箱根的后端明确拒绝该权限组合，不静默扩大权限。
+- 插件测试按文件串行运行，避免并发启动的测试进程挤占用于故障注入的真实截止时间；未放宽断言或 timeout。
+
+当前为本地候选，尚未提交、发布或安装；0.30.2 正式发行不包含本轮修复。
+
+## 0.30.2 — 画布优先的流程工作台
+
+- 大画布、原生专注视图、任务子图、跨分页定位与窄窗口列表；节点详情按进展／会话／本次配置组织。
+- 配置自动读取、中文阶段与推理选项、分钟／秒换算、相邻保存按钮；保护未保存草稿，恢复缓存时重新核对文件 revision。
+- 重试与运行确认绑定原 revision，待交付依赖不可绕过；受管会话续接命令使用原会话工作目录。
+- Quick 验证同时核对 L1 与终验结果；关闭的 PR 不冒充合并，旧远端快照在状态变更后失效。
+- 运行记录以列表与详情呈现，对照对象不改变指标查询目标；费用缺失不显示为零。
+- 保持 Go 控制边界和默认配置语义；JEV 继续默认关闭、只提供可选影子建议。
+
+本条描述发行内容；六包 registry 完整性、latest 与真实桌面安装分别验收。
+
 ## 0.30.1 — 任务发现与可选影子评估
 
 - 画布以任务选择为入口：按 DSH 会话 ID 找回 CLI 运行，旧记录一键选择；删除路径输入框，有实际位置时自动显示只读信息。

package/README.en.md

@@ -1,5 +1,7 @@
 # Flywheel
 
+Project workspaces and execution directories are separate: sessions belong to the original repository, while tasks may execute in independent Worktrees. Automatic Worktree management is enabled by default and is independent from parallel scheduling. Caller-selected execution directories are validated and registered by the engine. See the [flow console guide](docs/en/flow-console.md).
+
 English | [简体中文](README.md)
 
 Flywheel turns reviewed software requirements into bounded coding tasks with explicit acceptance criteria. A deterministic Go engine runs Plan, Execute, Review, and verification loops. Models propose plans, implement changes, and review candidates; the engine owns state, retries, budgets, workspaces, verification, local Git delivery, and stopping.
@@ -168,4 +170,6 @@ The package currently declares **`UNLICENSED`**. An open-source license has not
 
 The DSH view adds a horizontal task canvas, stage run/retry, per-stage configuration, controlled Provider-session interaction, declared parallel execution with serial integration, observed run metrics and PR/Merge receipts. See the [console guide](docs/en/flow-console.md). Source implementation does not imply npm publication or a local upgrade.
 
+The workbench prioritizes a large task overview, on-demand node details and separate task subgraphs. Configuration loads automatically into focused sections; adjacent save actions appear only after edits. Saved defaults apply to subsequent starts.
+
 Optional, default-off JEV shadow evaluation is included in the 0.30.1 source; see the [guide](docs/en/jev-shadow.md). Advice cannot change workflows, and observer failures do not block tasks.

package/README.md

@@ -1,5 +1,7 @@
 # Flywheel（飞轮）
 
+项目工作区与任务执行目录分开：Session 归属原仓库，任务可以在独立 Worktree 执行。配置页提供默认开启的“自动管理任务 Worktree”，与并行调度独立；自行选择目录须由引擎核对登记。详见[流程控制台](docs/flow-console.md)。
+
 [English](README.en.md) · 简体中文
 
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
@@ -290,4 +292,6 @@ npm run build:npm
 
 DSH 会话视图提供从左到右的任务画布、节点运行／重跑、按阶段配置、受管 Session 交互、声明式并行与串行集成、运行指标和 PR／Merge 回执。完整操作与当前能力边界见[控制台指南](docs/flow-console.md)。源码状态不等于 npm 已发布或本机已升级。
 
+工作台默认以大画布展示任务总览，节点详情按需打开，任务步骤在独立子图中展开。“配置”自动读取并分组编辑，修改后才出现相邻的保存操作；新配置只影响后续启动。
+
 可选、默认关闭的 JEV 影子评估源码实现见[使用说明](docs/jev-shadow.md)。开启仅记录建议，故障不阻断原流程；需要同版本 CLI／插件。

package/docs/configuration.md

@@ -418,7 +418,9 @@ DSH 的「全局 / 项目配置」先读取显式作用域和文件 revision，
 
 `permissions.bindings` 在全局 `permissions.mode` 上按 `loops.<role>`、`routes.<route>`、`judge-panel` 覆盖实际宿主权限，值为 `read-only`、`workspace-write` 或 `danger-full-access`。语法以 `permission-policy.schema.json` 为准；后端仍须证明支持该权限，不会把 Claude 原生审批模式伪装成只读沙箱。
 
-`scheduler` 的字段以 `scheduler-policy.schema.json` 为准。默认 serial；parallel 只并发满足冻结 `schedule.after/writes` 的独立单元，`max-parallel` 控制任务并发，`providers` 按实际账号渠道限流。hard 预算在确认计费前只允许一个模型调用。声明缺失或写入冲突不会被解释为独立。
+`scheduler` 的字段以 `scheduler-policy.schema.json` 为准。新默认允许 parallel（最大并发 2），已有显式 serial 保留；parallel 只并发满足冻结 `schedule.after/writes` 的独立单元，`max-parallel` 控制任务并发，`providers` 按实际账号渠道限流。hard 预算在确认计费前只允许一个模型调用。声明缺失或写入冲突不会被解释为独立。
+
+`worktree.enabled` 默认 true，只控制引擎自动创建／管理 Worktree；关闭不禁止并行，也不禁止用户或模型自行创建。项目归属与实际执行目录分别记录，外部目录登记协议见[流程控制台](flow-console.md)。当前原生后端不能把 `workspace-write` 沙箱根和项目目录独立设置，不支持的分离组合会在派发前失败；不会扩大权限来掩盖问题。
 
 例如把 Review 固定为只读，并允许两个已声明独立的任务并行：
 
@@ -426,7 +428,7 @@ DSH 的「全局 / 项目配置」先读取显式作用域和文件 revision，
 {
   "permissions": {
     "mode": "full-access",
-    "bindings": {"loops.review":"read-only","routes.hard":"workspace-write"}
+    "bindings": {"loops.review":"read-only"}
   },
   "scheduler": {"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}
 }

package/docs/en/configuration.md

@@ -363,7 +363,7 @@ Advanced callers send JSON on stdin to `flywheel control config-edit --cwd /abso
 
 `permissions.bindings` overrides the global mode by `loops.<role>`, `routes.<route>` or `judge-panel`, using read-only, workspace-write or danger-full-access. Read `permission-policy.schema.json` for the contract. Adapters must still prove the requested capability; native Claude approval modes are not advertised as an OS read-only sandbox.
 
-`scheduler` is defined by `scheduler-policy.schema.json`. Serial is the default. Parallel only dispatches independent units declared by frozen schedule.after/writes; max-parallel limits units and providers limits actual account channels. Hard budgets admit one model call until its accounting is durable. Missing declarations and overlapping write scopes are not independence.
+`scheduler` is defined by `scheduler-policy.schema.json`. The new default permits parallel execution with a limit of two; existing explicit serial settings remain unchanged. Parallel only dispatches independent units declared by frozen schedule.after/writes; max-parallel limits units and providers limits actual account channels. Hard budgets admit one model call until its accounting is durable. Missing declarations and overlapping write scopes are not independence.
 
 For example:
 
@@ -371,7 +371,7 @@ For example:
 {
   "permissions": {
     "mode": "full-access",
-    "bindings": {"loops.review":"read-only","routes.hard":"workspace-write"}
+    "bindings": {"loops.review":"read-only"}
   },
   "scheduler": {"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}
 }
@@ -382,3 +382,5 @@ This is a field excerpt, not a complete configuration replacement. The console r
 ## Optional JEV shadow evaluation
 
 `jev-shadow.enabled` defaults to false, including older configurations that omit it. The global/project editor exposes the switch. Enabling only observes new tasks; failures never block workflows or change Quick/Full. See the [JEV guide](jev-shadow.md) for endpoint, version pin, key variable and timeout. This feature requires the 0.30.1 CLI/plugin.
+
+Automatic Worktree management (`worktree.enabled`, default true) is independent from scheduling. Off neither prohibits parallel dispatch nor prevents callers from creating Worktrees. Project membership and execution directories are separate; see the [console guide](flow-console.md) for directory registration. Native backends without a separate `workspace-write` sandbox root reject unsupported split-directory requests before dispatch, without expanding permissions.

package/docs/en/flow-console.md

@@ -8,7 +8,9 @@ The canvas starts with task selection. One registered task belonging to the curr
 
 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 assistant and engine supply the location; known workspace, task-record location and branch values appear as read-only information, while missing values are omitted. The task folder contains the specification, acceptance checks and progress; the workspace is the actual execution project/worktree. A prepared task can be associated by the assistant using read-only status and then selected from the list.
+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.
+
+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.
 
@@ -22,7 +24,9 @@ Continue workflow is behind an explicit disclosure. A passed stage does not star
 
 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.
 
-Read a draft, edit the resource/Harness, model, effort, permissions and history policy, then inspect the target and diff. Version defaults replace the complete configuration. Go checks the content revision, backs up the original and publishes atomically. A running engine retains its snapshot; subsequent starts load the new settings.
+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.
+
+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.
 
 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.
 
@@ -30,9 +34,13 @@ Resources include ChatGPT through DSH or Codex Pro, Kimi Code, DeepSeek Account
 
 ## Canvas and operations
 
-The left-to-right canvas shows Plan/decomposition, scheduling, task branches, integration, final acceptance, PR and Merge. A packet expands into Execute, L1, Review and Git delivery. State colors have text labels. Details identify the DSH source conversation, project/worktree, branch, HEAD, run ID, actual invocation binding and failure evidence.
+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 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.
 
-The canvas supports panning, locating the current node and packet paging. Large tasks use bounded diagnostic excerpts. Read full node evidence loads one packet with a matching fresh canvas revision; it never changes the original ledger.
+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.
 
 - 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.
@@ -62,7 +70,11 @@ 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.
 
-Only Execute/L1 run concurrently. Each unit has a worktree; one Go coordinator serializes CAS writes and accounting. Hard budgets admit only one model call at a time, retaining its slot through durable accounting. Other modes enforce total and channel concurrency. Cancellation awaits every started worker.
+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.
+
+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.
+
+Independent Worktrees permit concurrent Execute/L1. Shared checkouts run Execute concurrently, then verify and review serially after all workers finish. One Go coordinator serializes CAS writes and accounting. Hard budgets admit only one model call at a time, retaining its slot through durable accounting. Other modes enforce total and channel concurrency. Cancellation awaits every started worker.
 
 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.
 
@@ -87,7 +99,7 @@ Ledger storage v2 is accepted by the new engine alongside legacy v1. Older engin
 
 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.
 
-Compare operation kind, branch, HEAD, contract/configuration conditions, elapsed time and newly observed attempts, failures and deliveries. Select an exact run or all calls for the current task, including unregistered legacy observations. Invocation/receipt reconciliation precedes aggregation; late receipts keep their original attribution and are not double-billed.
+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.
 
 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.
 
@@ -102,3 +114,5 @@ 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.
+
+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.

package/docs/en/session-recovery.md

@@ -79,3 +79,5 @@ The offline native fixture exercises the real Go engine, worker v3, and public p
 Recovery journals have private permissions, exclusive creation, identity/digest checks, and atomic persistence. Existing directories never authorize redispatch. They are task audit data and may contain model output and diagnostics; keep their access and backups with the task. Do not copy credentials or delete uncertain evidence during upgrades.
 
 There is currently no automatic journal-retention timer. Archive evidence through the project's task lifecycle after completion or explicit resolution of an unknown result. Deleting a journal is not a recovery procedure. `control status` and doctor are observation surfaces; models and skills never write `state.json`. Resume through the normal Go entry point from the original task directory so the engine can reconcile before making a new call.
+
+For shared-checkout execution, an Execute receipt fingerprints its declared write scope and binds that scope into the session identity. Independent peer changes do not discard a known invocation; changes within its own scope still reject stale receipts. L1, independent Review and collective delivery validate the entire combined candidate. Scoped receipts neither prove batch completion nor bypass unknown dispatch, outcome or cleanup.

package/docs/en/workflow.md

@@ -44,7 +44,9 @@ DeepSeek uses the existing signed-in, funded DSH account. `deepseek-official` AP
 
 Use the preparation model to identify risks and improve the contract. Increasing effort cannot repair missing requirements, an invalid test oracle, or an incorrectly chosen working directory. Later execution routes and the independent Review/Judge stages remain explicit configuration; see [Configuration](configuration.md).
 
-## 2. Create the task integration worktree first
+## 2. Choose the task execution directory
+
+First inspect the effective `worktree.enabled` setting. The default enabled mode follows the independent Worktree flow below. With automatic management off, use the selected task checkout; callers may still choose a Worktree and parallel scheduling remains independent. Session project membership is recorded separately from execution location. See the [console guide](flow-console.md).
 
 For an existing repository, create or deliberately reuse a task branch in its own worktree before invoking `flywheel-new`. The host or user performs this step. Choose unused names and substitute the repository's actual base branch:
 
@@ -147,7 +149,7 @@ Preflight does not infer with a model or execute acceptance commands. Its unknow
 
 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.
+DSH's `flywheel_launch` and `flywheel_control` start explicitly associate the supplied `taskDir` and `cwd` with the initiating session. CLI registrations can retain DSH's host session ID; independent terminal runs without that identity can be selected from Recent tasks and freshly queried. The UI has no editable task/project path fields: known locations appear read-only. The host directory comes from public `workingDirectory.get(session)`; a shell `cd` alone does not change it. The plugin does not scan or guess tasks.
 
 ### Working directory by stage
 

package/docs/flow-console.md

@@ -8,7 +8,9 @@
 
 旧版本记录没有会话 ID 时，从“本机最近任务”选择即可；选择会发送只读状态查询，并保存到当前会话关联。刷新任务列表不会启动、重试或切换你手动选中的任务。读取失败保留已打开画布；未确认的操作仍先核对原任务。
 
-界面不再提供任务路径／项目路径输入框，也不要求用户填写。助手与引擎提供实际位置；有值后显示为只读的工作区、任务记录位置及分支，没有值不显示空字段。任务文件夹保存说明、验收清单和进度，工作区是实际执行的项目／worktree。准备但尚未运行的任务由助手通过只读 status 关联，随后也能在列表中选择。
+界面不再提供任务路径／项目路径输入框。助手与引擎提供实际位置；有值后显示为只读信息。项目工作区是原仓库的稳定归属，实际执行目录可以是任务集成目录或独立 Worktree，两者分开显示。任务文件夹保存说明、验收清单和进度。准备但尚未运行的任务由助手通过只读 status 关联，随后也能在列表中选择。
+
+DSH Session 的原始项目目录保留为原仓库，运行时通过公开接口切换当前执行目录。桌面 Host 定期把 Flywheel SDK 会话登记到已有的匹配项目；读取实际任务状态时也会确保原项目已登记。不会把每个 packet Worktree 创建成新的桌面工作区，不修改旧 Session 的历史头部；旧会话只能按其真实目录归属。探测会话写入临时存储，退出后清理，不再污染用户会话列表。原生 Provider 在项目目录开会话，任务提示词明确列出实际执行目录；每次 shell／文件操作必须显式使用它。当前后端不能分离 `workspace-write` 沙箱根时，在派发前明确拒绝该组合，不自动扩大权限；完全权限及支持的只读模式保持其真实含义。
 
 Skill 已加载不代表引擎已经启动。`flywheel-task` 准备并通过 `flywheel_launch` 启动后才产生运行；只要求调研或方案时，助手应明确说明尚未启动。单阶段技能执行后通过 `flywheel_control status` 关联当前画布；没有该工具时明确给出路径，不能声称已关联。
 
@@ -22,7 +24,9 @@ Skill 已加载不代表引擎已经启动。`flywheel-task` 准备并通过 `fl
 
 在已进入对话视图的 DSH 会话中，Flywheel 排在“统计”之后；新会话的空白首页尚未显示这排会话视图。内部有“运行画布”“全局／项目配置”“运行与对比”。全局配置可在没有任务目录时编辑；项目配置写入所选 Git 项目根。任务配置仍具有最高优先级，取首个完整文件，不做字段深度合并。
 
-先读取草稿，再选择 Provider／Harness、模型、推理等级、权限与历史策略。“载入本版本默认值”导入完整默认模板；保存前显示差异与目标，Go 核对内容 revision、备份旧文件并原子写入。正在运行的引擎保留原快照，新配置在后续启动时加载。
+打开“配置”后自动读取所选范围，不必先点击读取按钮。按“工作方式／模型分配／预算与重试／JEV 影子建议”编辑；有修改才出现相邻的“保存修改／放弃修改”。普通保存一次点击，首次开启 JEV 先确认任务摘要发送边界。串行模式不显示并发数量；超时以分钟或秒编辑，并精确换算成引擎毫秒字段。
+
+“更多配置操作”提供重新读取和恢复安装版本默认配置。切换范围或重新读取会先提示未保存草稿；重置先载入待保存修改，保存时才替换文件。保存失败保留草稿，结果未知时先重新读取核对。Go 核对文件 revision、备份旧文件并原子写入。正在运行的引擎保留原快照，新配置在后续启动时加载。配置页显示真实文件与来源：文件按任务 → 项目 → 全局 → 安装默认选择，不逐字段叠加；尚未存在的配置文件以安装模板创建。
 
 支持的资源入口包括 ChatGPT · DSH、ChatGPT · Codex Pro、Kimi Code、DeepSeek Account（默认 Flash）及可选 Claude Code Pro。模型初值来自本版本模板，真实能力以 `config inspect`／`doctor` 为准。Claude 的可选适配器必须匹配公开 machine API；缺失或权限不支持会拒绝调用，不自动换后端。账号登录仍由各 Provider 自己完成。
 
@@ -30,9 +34,13 @@ Skill 已加载不代表引擎已经启动。`flywheel-task` 准备并通过 `fl
 
 ## 横向画布与节点操作
 
-主线从左到右展示 Plan／拆分、调度、任务分支、集成、终验、PR、Merge。点击任务展开 Execute、L1、Review、Git 交付。状态配合颜色和文字，运行与节点详情展示来源 DSH 会话、项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
+主线从左到右展示 Plan／拆分、调度、任务分支、汇总与终验、PR 与 Merge。点击节点打开视图内详情，按“进展／会话／本次配置”查看，不挤到画布下方。点击“展开任务画布”进入 Execute、L1、Review、Git 交付子图；汇总和远端交付也可展开阶段。状态配合颜色和文字，运行与节点详情使用真实项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
+
+画布占满插件可用宽度，支持双向拖动、缩放、适合宽度、定位当前步骤、分页与列表切换。新快照保留视角与选择；定位可跳到当前执行任务所在分页。大任务使用有界诊断摘要；“读取完整节点证据”按需加载选中节点，revision 与同一时刻的画布状态一起刷新。摘要不会改写原始账本。
+
+“专注画布”在插件拥有的原生对话框中扩大画布，退出或按 Escape 回到原视图，不启动或停止任务。它不修改 DSH 的全局布局或宿主输入区；操作结果未知时退出专注视图，显示原调用的核对入口。
 
-画布支持拖动、横移、定位当前节点和分组浏览。大任务使用有界诊断摘要；“读取完整节点证据”按需加载选中节点，revision 与同一时刻的画布状态一起刷新。摘要不会改写原始账本。
+运行节点前显示作用范围，确认绑定已观察的状态版本；状态变化后旧确认不可提交。失败任务的“重试一次”需要填写原因，已完成任务显示“重新执行”并说明证据失效范围。独立 Review 在当前 L1 未通过时不可运行。PR 尚未查询、已关闭、已合并分别显示，不把关闭的 PR 当作合并成功。
 
 | 操作 | 含义 |
 |---|---|
@@ -66,7 +74,11 @@ schedule:
 
 依赖必须指向较早编号的已知 packet；写入范围是规范相对路径／目录前缀，不支持通配符或越出项目的路径。声明要覆盖实现、普通测试和必要配置，并考虑共享测试服务等真实依赖。未声明独立性、写入范围冲突或需要 live 凭证的单元保留串行。
 
-只有 Execute／L1 并发，工作区各自独立；一个 Go 协调器串行 CAS 保存状态和用量。hard 预算只允许一个模型调用在飞，并在下一调用前确认前一笔计费。其他模式按最大并发与渠道限制接纳。停止会等待整批已启动工作收尾。
+“配置 → 工作方式 → 自动管理任务 Worktree”默认开启，对应 `worktree.enabled`。它只控制引擎自动创建／管理目录，不是“允许使用 Worktree”开关，也不控制能否并行。新默认 `scheduler.mode=parallel`、最大并发 2；已有显式串行配置仍保留。关闭自动管理后，可以在任务 checkout 并行，也可以由模型或用户自行选择 Worktree。共享目录没有文件隔离保证，写入范围冲突、候选变化和验收失败仍如实停止，不能把并发操作当作隔离证据。
+
+自行选择其他 Worktree 时，执行者先创建或选好同仓库、相同任务基线、干净且未被本流程其他任务单元登记的目录（分支也不能被多个 Worktree 共享），在实现前仅返回 `{"flywheelExecutionDirectory":{"cwd":"/absolute/worktree","branch":"actual-branch"}}`。Go 校验后登记到本任务，下一次执行、测试、Review、提交均使用该目录；登记本身不算完成任务，费用仍计入预算。外部 Worktree 不自动删除。不能只在 prompt 中声明目录、修改状态文件，或在未登记的目录实现后让引擎猜测位置。
+
+独立 Worktree 中 Execute／L1 可以并发；共享目录只并发 Execute，随后统一、串行验收与评审。一个 Go 协调器串行 CAS 保存状态和用量。hard 预算只允许一个模型调用在飞，并在下一调用前确认前一笔计费。其他模式按最大并发与渠道限制接纳。停止会等待整批已启动工作收尾。
 
 Review、集成与里程碑 gate 保持串行。后续分支吸收已完成成果后，在合成候选上重新验收。执行重试耗尽仍走原有升级策略；集成冲突或门禁失败保留 worktree 和失败证据。`writes` 是调度／验收契约，完全权限本身不提供 OS 沙箱。
 
@@ -91,7 +103,7 @@ flywheel session '/absolute/task-worktree/docs/task-slug' --key 'execute/M01-T01
 
 CLI 和桌面启动自动登记 run ID；会话投影保留多个已确认任务。登记位于全局配置旁的 `runs/`，可用绝对 `FLYWHEEL_RUNS_DIR` 覆盖。列表只读取明确登记，显示最近 100 项，不扫描整个磁盘；当前存活状态始终重新查询 Go。
 
-对比页面显示操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。可选准确 run ID，也可查看本任务全部调用（包括早期未登记记录）。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。
+“运行记录”以列表选择运行，在相邻详情中查看操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。选择记录不启动任务，打开画布会重新读取当前状态。指标范围可选“仅此运行”或当前任务全部调用（包括早期记录）；对照运行仅用于比较条件，不会悄悄改变指标查询目标。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。整组费用均缺失时显示“未报告”，不显示 $0。
 
 用量、费用和时延只表示已知量，缺失／部分数据单列，费用也可能来自配置单价估算。调用失败率不等于代码质量；条件不同的运行只并列展示，不伪称配对收益。完整的质量结论需要任务验收和独立 oracle。
 
@@ -106,3 +118,5 @@ CLI 和桌面启动自动登记 run ID；会话投影保留多个已确认任务
 已确认的创建／合并操作重跑时先核对已有结果。命令失败或回执丢失保留 unknown，不猜测远端成功。PR／Merge 状态与引擎的本地完成分开；发布应绑定实际 merge commit 和发布产物重新验收，不因点击 Merge 自动发布 npm 或部署。
 
 配置面板另提供默认关闭的 **JEV 影子评估（可选）**；开关、数据发送边界与失败回退见 [JEV 指南](jev-shadow.md)。此项需要 0.30.1 CLI／插件。
+
+关闭自动 Worktree 管理而直接共享同一 checkout 的批次，会先等所有执行调用收尾，再对完整共同候选运行各任务的 L1 和独立 Review。变更按声明范围投影，批次范围外与禁止路径仍拒绝；这不证明具体进程的文件归属。任一返修改变共同候选，旧证据须重验。全部通过后统一提交，并在一次状态 CAS 中完成整组；保存失败不乐观报告部分完成。混合批次先交付共享目录，再重新验证并集成外部 Worktree。手动集成／终验不能绕过批次屏障，需“继续完整流程”。画布显示批次成员和上次错误。

package/docs/session-recovery.md

@@ -79,3 +79,5 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 上游恢复目录与文件使用私有权限、独占创建、身份/摘要检查和原子持久化；已存在目录不会触发二次执行。它们属于任务审计证据，可能含模型输出与诊断。按任务一起保存、备份和控制访问，不复制凭证，也不因安装升级而删除未知调用的证据。
 
 当前没有自动删除这些恢复证据的保留计时器。确认任务完成或由人解决未知结果之后，才能按项目的任务归档流程处理；删除 journal 不是解除阻断的恢复方法。`control status`/doctor 是查看入口，模型与 skills 不修改 `state.json`。需要恢复时仍从原任务目录使用正常 Go 启动入口，由引擎核对并决定下一步。
+
+共享目录并行的 Execute 回执使用已声明写入范围的候选指纹，并把该范围绑定到会话身份；其他任务的独立变更不会导致本调用无故丢失归属。自己的范围变化仍拒绝旧回执。L1、独立 Review 与批次提交始终核对完整共同候选；范围回执不能证明整组完成，也不能绕过未知派发、结果或清理。

package/docs/workflow.md

@@ -71,7 +71,9 @@ Quick 不按文件数量判断风险。范围与实现模式必须明确、全
 默认的运行期 Plan 仍为 Kimi CLI `kimi-code/k3.1-pro / high`，详见
 [默认配置](../templates/flywheel.config.example.json)；Kimi 别名也须在本机可用。
 
-## 2. 先建立任务集成 worktree
+## 2. 选择任务执行目录
+
+先核对有效配置的 `worktree.enabled`。默认开启时采用下面的独立任务 Worktree 流程；关闭时不自动创建，使用已明确选择的任务 checkout，仍可由用户或模型主动选择 Worktree。Session 的项目归属始终与执行目录分开记录；并行设置独立，详见[控制台指南](flow-console.md)。
 
 假设当前位于业务仓库根目录，远端为 `origin`、目标分支为 `main`。
 将示例任务名与目录名替换为本次需求；不同任务使用不同名称。
@@ -191,10 +193,10 @@ flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
 
 预检不发送模型推理，不能证明账号额度或真实模型调用已经通过。启动会实际调用
 所选模型。DSH `flywheel_launch` 与 `flywheel_control` start 将明确的 `taskDir`
-和 `cwd` 关联到发起会话的 Flywheel 视图；单纯 shell 调 CLI 不会创建桌面会话关联。
-终端启动或另开已有任务时，仍可手动填“任务资料目录”和“项目目录”。后者仅在
-会话当前目录已经是同一 `repo_dir` 时可留空。插件通过公开
-`workingDirectory.get(session)` 读取目录；不扫描或猜测。仅在 shell 中 `cd`
+和 `cwd` 明确关联到发起会话的 Flywheel 视图。CLI 登记可带 DSH 提供的会话 ID；
+没有归属的独立终端运行可从“本机最近任务”选择，再查询真实状态。
+界面不提供任务／项目路径输入框，已知位置只读展示。插件通过公开
+`workingDirectory.get(session)` 读取宿主目录；不扫描或猜测。仅在 shell 中 `cd`
 不会改变 DSH 的会话目录，不要混用原 checkout 的账本和新 worktree。
 
 Full 的每个 packet 经实现、L1 与独立 Review 通过后，引擎提交并快进合入任务分支，
@@ -212,7 +214,7 @@ Full 的每个 packet 经实现、L1 与独立 Review 通过后，引擎提交
 ### 5.1 Skills 入口与各 Loop 的工作目录
 
 内置 skills 将任务 worktree 约定作为准备、启动、恢复和单环入口的检查步骤。
-`flywheel-task`／`flywheel-new` 在生成契约前创建或复用任务 worktree；`flywheel-run` 以及单环
+`flywheel-task`／`flywheel-new` 在生成契约前按自动管理设置和用户选择确定任务 checkout；`flywheel-run` 以及单环
 skills 从实际任务目录解析同一 worktree 根，再调用 CLI。默认不从 `main`、
 `master` 或 detached HEAD 启动开发；已有明确工作区选择与授权不重复询问。
 恢复复用原任务路径及引擎保存的 packet 状态，不为恢复另建一份任务或复制 state。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
@@ -49,10 +49,10 @@
     "docs/en/session-evaluation.md"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.30.1",
-    "@ckanner/flywheel-darwin-amd64": "0.30.1",
-    "@ckanner/flywheel-linux-arm64": "0.30.1",
-    "@ckanner/flywheel-linux-amd64": "0.30.1"
+    "@ckanner/flywheel-darwin-arm64": "0.31.0",
+    "@ckanner/flywheel-darwin-amd64": "0.31.0",
+    "@ckanner/flywheel-linux-arm64": "0.31.0",
+    "@ckanner/flywheel-linux-amd64": "0.31.0"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
@@ -60,10 +60,10 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.30.1 dist-npm",
+    "build:npm": "bash scripts/build-npm.sh 0.31.0 dist-npm",
     "test:sessions": "node scripts/test-session-evaluation.js"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.30.1"
+    "@ckanner/dsh-plugin-flywheel": "0.31.0"
   }
 }