@ckanner/flywheel 0.30.2 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.31.0 — 项目归属与执行目录分离（发行候选）
+
+- Session 归属原仓库，执行、验收与交付仍绑定实际任务目录；提示词和界面分别展示两层位置。
+- DSH SDK Session 使用稳定项目 header 和公开目录切换；桌面 Host 通过 Workspace 注册表补齐归属，探测会话使用临时持久化目录。
+- 自动管理 Worktree 默认开启，与并行策略解耦；新默认允许并行，最大并发 2，仍核对任务依赖及写入范围。
+- 共享目录并发采用批次验收：所有执行结束后验证完整共同候选，返修导致旧证据失效时重验，全部通过后统一提交并原子完成整组；保留未知调用和清理阻断。
+- 关闭自动管理后允许并发，也支持执行者在实现前提交结构化目录提案；核对同仓库、基线、分支、干净状态和独占归属后登记，后续执行／Review／交付跟随该目录，外部 Worktree 保留。
+- 旧回执先按原身份核对；同项目的旧会话可继续使用，不重写历史头部。无法分离 workspace-write 沙箱根的后端明确拒绝该权限组合，不静默扩大权限。
+- 插件测试按文件串行运行，避免并发启动的测试进程挤占用于故障注入的真实截止时间；未放宽断言或 timeout。
+
+当前为本地候选，尚未提交、发布或安装；0.30.2 正式发行不包含本轮修复。
+
 ## 0.30.2 — 画布优先的流程工作台
 
 - 大画布、原生专注视图、任务子图、跨分页定位与窄窗口列表；节点详情按进展／会话／本次配置组织。

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.

package/README.md

@@ -1,5 +1,7 @@
 # Flywheel（飞轮）
 
+项目工作区与任务执行目录分开：Session 归属原仓库，任务可以在独立 Worktree 执行。配置页提供默认开启的“自动管理任务 Worktree”，与并行调度独立；自行选择目录须由引擎核对登记。详见[流程控制台](docs/flow-console.md)。
+
 [English](README.en.md) · 简体中文
 
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。

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.
 
@@ -68,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.
 
@@ -108,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:
 

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` 关联当前画布；没有该工具时明确给出路径，不能声称已关联。
 
@@ -72,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 沙箱。
 
@@ -112,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`。
 将示例任务名与目录名替换为本次需求；不同任务使用不同名称。
@@ -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.2",
+  "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.2",
-    "@ckanner/flywheel-darwin-amd64": "0.30.2",
-    "@ckanner/flywheel-linux-arm64": "0.30.2",
-    "@ckanner/flywheel-linux-amd64": "0.30.2"
+    "@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.2 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.2"
+    "@ckanner/dsh-plugin-flywheel": "0.31.0"
   }
 }