dsh-git-worktree 0.4.0 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,99 @@
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-08-28
+
+`0.7.1` 修正项目聚合侧边栏的 Managed owner 菜单边界：恢复安全的会话整理操作，隐藏尚不具备 Worktree 生命周期语义的普通 Fork，并继续阻止会破坏唯一 owner 不变量的入口。
+
+### Fixed
+
+- Managed owner 恢复官方重命名与归档；归档仅影响侧边栏可见性，不放弃任务、不清理 Worktree，也不改变交付状态。
+- 普通 Fork 从 Managed 菜单隐藏；Managed Workspace 的“新会话”和跨归属拖动继续被阻止，非法操作不再弹出浏览器原生提示框。
+- 强化冲突 Workspace 的 fail-open 防护，并更新项目聚合、Ready 界面截图与双语使用说明。
+
+## [0.7.0] - 2026-08-28
+
+`0.7.0` 新增项目聚合侧边栏，将 Managed Worktree 的唯一 owner Session 直接显示为原 Local 项目下的任务行，同时以 fail-open 拓扑、生命周期操作限制和上游版本门禁保持官方 Workspace 行为兼容。
+
+### Added
+
+- 新增项目聚合侧边栏：Local Workspace 继续承载普通多会话，每个 Managed Worktree 则直接显示为唯一 owner Session 任务行，并展示进行中、待验收、预览、恢复、已完成或已放弃状态。
+
+### Changed
+
+- Managed Workspace 不再以 UUID 长路径重复占用顶级项目；cleanup 后的历史 owner Session 继续依据插件 Registry 归入原 Local 项目。
+- Managed 任务行仅用于打开 owner Session，普通重命名、Fork、归档和拖动会被阻止，避免产生第二个会话或绕过 Worktree 生命周期；非托管 Workspace 保留官方操作，拓扑不可用时完整回退到原 Workspace 列表。
+- 修复项目聚合 Browser 的两阶段真实启动回归：先消除重复 `sidebar.workspaces.directoryFlow` 声明，再改为版本与 SHA-256 门禁的官方 Workspace Client 单次衍生加载，保留 `renderSlot`/目录选择授权，避免 shadow 崩溃后静默回退官方侧栏。
+- Managed Workspace 中可证明为空的预会话 launcher 不再阻止聚合；真实第二个 Session 仍 fail-open，物理 Workspace 未归并时也会禁止通过官方“新会话”入口创建第二个 Session。
+- Managed owner 行改用官方 Branch Icon 与独立状态 Badge，任务标题保持原文；窄侧栏会优先保留 Worktree 身份和交付状态，而不是把状态截断在标题末尾。
+
+## [0.6.1] - 2026-08-28
+
+`0.6.1` 统一 Preview 与最终保存的用户文案，修复 pre-session source launcher 对并发 Worktree 创建的阻塞，并让普通 Local Checkout 正确使用正常助手回复结束任务；同时将项目首页和完整使用指南重新分层。
+
+### Changed
+
+- Review 主操作改为更直接的任务文案：Ready 使用“预览修改”，Preview 使用“确认并保存”，Direct Finish 使用“跳过预览并保存”；同步更新恢复、Checkpoint 与确认弹窗文案，不改变 Host 交付语义。
+- 将中英文 README 收敛为 Mermaid 驱动的项目首页，新增双语 Usage 指南承接完整操作、恢复、命令与排错；同时修正 Checkpoint 迁移状态，并明确项目级 Worktree 插件与 Domi 桌面工作台之间的产品边界。
+
+### Fixed
+
+- pre-session handoff 成功后自动归档已清空的 Local source launcher，防止 Harness 的 New Session 复用该 reserved source 并错误阻塞下一项并发 Worktree 任务；owner Session 与项目级 Preview 串行约束保持不变。
+- 普通 Local Checkout 现在明确使用正常助手回复结束，不再被引导调用 Worktree-only Ready 工具；若模型仍误调用，Client 会隐藏预期的 `target_unselected` 结果，同时保留其他真实 Worktree 错误。
+
+## [0.6.0] - 2026-08-25
+
+`0.6.0` 为长任务增加 Host-authoritative Worktree Checkpoint：用户可以把精确 Ready/Preview 阶段保存为隔离 Worktree 内部 Commit，清理当前施工状态后继续开发，同时保持 Local 完全不参与阶段提交，最终仍只交付一个累计任务 Commit。
+
+### Added
+
+- Review 卡新增“保存阶段并继续”；active Preview 使用“撤回 Preview，保存阶段并继续”，两者都通过同一个 Host mutation 完成，不由 Client 拆分撤回与保存请求。
+- checkpoint domain、registry metadata、operation journal、内部 artifact retention 与 `recoverCheckpoint` 支持重启后收敛 HEAD/index，无法证明完整回滚时保留 `index.lock` 与恢复证据。
+- strict Host/Remote/Client contract 新增 generation-bound `checkpoint` 方法；请求绑定 exact owner、checkout、revision、review、generation 与 single-flight request ID，完成请求支持精确幂等重放。
+- Review 与关联 Manager 投影展示已保存阶段数量/摘要；Manager 继续只提供状态、导航和 owner lifecycle，不新增 Checkpoint mutation。
+
+### Safety
+
+- Checkpoint 只提交 managed Worktree 当前 staged、unstaged 与 untracked 的精确验收快照；Local branch/HEAD、refs、index、staged、unstaged、untracked 与 working-tree bytes 不被纳入阶段 Commit。
+- active Preview 必须先在 Host 锁内安全撤回；acceptance holder、identity、revision/review/generation、Worktree fingerprint 与最终 CAS 任一变化都在写入前 fail closed。
+- prepared Commit 先持久化 journal，再保留内部 ref；写后复验 detached HEAD、clean index 与 checkpoint tree。迟到请求、重复点击、旧 generation、外来 Session 和空阶段均被拒绝或安全去重。
+- Checkpoint 会使旧 Review、Preview、Delivery/Recovery proof 失效并恢复 Working；多次阶段 Commit 仍只作为 Worktree 内部历史，最终 Finish/Finalize 向 Local 生成一个累计任务增量 Commit。
+- strict Remote schema 保持 path-free，拒绝未知字段、危险路径和内部 `refs/dsh` 泄漏。
+
+### Changed
+
+- 包版本升级为 `0.6.0`；发布门禁与 Loader 方法面同步要求 `checkpoint` descriptor。
+- 中英文 README、架构与发布 smoke 补充 Checkpoint 状态、不变量、恢复和人工验证边界。
+
+## [0.5.0] - 2026-08-25
+
+`0.5.0` 完成冲突与 detached Preview 的 Host 权威恢复闭环：恢复决策绑定 durable proof、严格 Remote contract 与写前后 CAS 复验，并将运行基线统一升级到 DeepSeek Harness `0.1.1-rc.2`。
+
+### Compatibility
+
+- 将全部直接 DeepSeek Harness 依赖与完整 peer 图从 `0.1.0-rc.8` 统一升级到 `0.1.1-rc.2`，避免 rc.8/rc.2 混合 runtime。
+- rc.1 引入视觉模型支持并修复 Bubblewrap 可经宿主 `/proc/<pid>/root` 绕过文件约束的问题；插件不直接实现 sandbox，但使用修复后的统一 Host 包线。
+- rc.2 继续收敛图片 Files API、预处理与 attachment pipeline；本项目接触的 Commands wire 仅新增可选 `originalDimensions`，现有 Worktree 协议不消费该字段。
+- 验证结构化 Web Client 启动/inject、Session projection state/view 重构、Typert namespace 原子注册与 Connection transport hooks，不改变现有 Worktree Session Target、Recovery 与 Local 安全边界。
+- 移除已过期的 rc.8 `minimumReleaseAgeExclude`；rc.2 依赖图现可直接通过仓库供应链冷却策略。
+
+### Added
+
+- `preview_detached` 新增 Host-authoritative Recovery Preflight：严格只读核对 durable receipt、四个 retained refs、Local HEAD/ref/tree/index/fingerprint、acceptance holder，并分别给出 rollback/finalize 的可证明结论与 64 位 generation。
+- detached Preview 在同分支安全快进后可安全撤回或直接提交到最新 Local HEAD；写操作在 Host 锁内重算 proof/CAS，并保留后续 Commit、staged、unstaged 与 untracked 层。
+- 无法证明安全时，Review Recovery surface 可显式请求精确 owner Agent 只读分析，或创建基于最新 Local HEAD 的 fresh managed Worktree handoff；旧 Worktree、Local、receipt 与 retained evidence 保持不变。
+- Review Preflight 冲突新增显式“让 Agent 解决冲突”：先强制重检结构化 conflict identity，再通过 owner-only `resumeRevision` 恢复 Working，并使用 Harness 官方 `ISession.prompt()` 将 Local HEAD 与冲突文件交回精确 owner Session；不会自动 Preview、Finalize 或写入 Local。
+- `stale_isolated` 新增独立的“重新生成验收结果”链路：保持 Ready 与严格 Read Only，不恢复 Working、不修改文件，只要求 Agent 等待后台写入停止、重新验证并生成新的 Ready Review。
+- Preview/direct Finish 写前竞态返回 strict `worktree_apply_conflict` continuation，包含可去重的冲突 request ID、checkout/review/revision、Local HEAD 与受限冲突文件列表；显式恢复后由 Host 另行签发持久恢复 proof。
+
+### Fixed
+
+- rollback/finalize 增加独立写后 HEAD/ref/index/tree/fingerprint 验证；无法证明成功或完整回滚时保留 journal/artifacts 并进入 `recovery_required`，reconcile 不再仅凭 Commit HEAD 误报成功。
+- detached Recovery Remote contract 使用 strict schemas，拒绝未知字段、非法 OID/generation、绝对/父级冲突路径与越界身份；Client 使用 identity-keyed single-flight cache，并在每次写操作、分析或 handoff 前强制重检。
+- Recovery continuation 增加 Host-authoritative 持久 proof：conflict 在 mutation lock 内重跑 Preflight/CAS 后绑定 Ready/Working revision、review、Local HEAD 与安全相对冲突路径；`stale_isolated` 通过独立只读 Host 授权保持 Ready。浏览器持久请求严格穷举 kind 与精确字段，并在发送前逐字段复验 Host proof、cwd 与 active Session，关闭伪造 kind 绕过显式授权的路径。
+- Recovery continuation 支持持久未发送请求、single-flight、重复点击去重、Session loading/streaming 延迟、Session 切换中止、旧请求被新请求替换，以及发送结果未知或失败后的显式重试。
+- acceptance slot 从 `waiting` 释放为 `available` 时废弃旧 busy Preflight；自动预检失败不再因重渲染循环重试，改为用户显式“重新检查”。
+
 ## [0.4.0] - 2026-08-20
 
 `0.4.0` 将 Worktree 验收升级为可预检、可恢复、可核验的交付闭环，并把关联 Worktree 的状态与导航入口集中到 Session Header；同时适配 DeepSeek Harness `0.1.0-rc.8` 与新的 Node.js 运行要求。
@@ -141,6 +234,11 @@
 
 - 发布初版生产级 Worktree 管理、基础 apply/finish/discard 生命周期和安全清理。
 
+[0.7.1]: https://github.com/wloops/dsh-git-worktree/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/wloops/dsh-git-worktree/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/wloops/dsh-git-worktree/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/wloops/dsh-git-worktree/compare/v0.3.0...v0.3.1

package/NOTICE

@@ -0,0 +1,14 @@
+dsh-git-worktree
+
+The generated browser bundle includes software derived at build time from:
+
+  @deepseek-ai/dsh-client-ui-workspace 0.1.1-rc.2
+  Copyright (c) 2026 DeepSeek
+  Licensed under the MIT License
+  https://www.npmjs.com/package/@deepseek-ai/dsh-client-ui-workspace
+
+The upstream browser bundle is version- and SHA-256-gated by
+scripts/workspace-sidebar-upstream.mjs. Its official Workspace Browser,
+WorkspacePicker, locale dictionaries, stores, and directory-flow declarations
+are preserved. dsh-git-worktree wraps the Browser projection and applies
+fail-closed Managed owner row decorations for Worktree identity and status.

package/README.en.md

@@ -1,304 +1,127 @@
 # dsh-git-worktree
 
 [![npm](https://img.shields.io/npm/v/dsh-git-worktree)](https://www.npmjs.com/package/dsh-git-worktree)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-git-worktree)](https://www.npmjs.com/package/dsh-git-worktree)
 [![CI](https://github.com/wloops/dsh-git-worktree/actions/workflows/ci.yml/badge.svg)](https://github.com/wloops/dsh-git-worktree/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Let agents work in real Git worktrees, preview the result in Local, and commit only after explicit human approval.**
+**Let agents work in real Git worktrees, preview changes in Local, and save only after explicit human confirmation.**
 
-`dsh-git-worktree` is an experimental Session Target plugin for [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness). Each coding task runs in its own checkout and Session, so the Local workspace controlled by the user does not become the agent's construction site.
+`dsh-git-worktree` is an experimental Session Target plugin for [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness). Each coding task receives an independent checkout, Workspace, and Session so agent construction state does not leak into the user-controlled Local checkout.
 
-This is an independent community plugin. It is not an official DeepSeek project and does not imply endorsement, partnership, or authorization.
+This is an independently maintained community plugin. It is not an official DeepSeek project and does not imply endorsement, partnership, or authorization.
 
-This is more than a wrapper around `git worktree`. It provides a complete delivery lifecycle: create an isolated environment, iterate safely, prepare a review, preview the task in Local without committing, finalize one task-only commit, and preserve recovery evidence when safety cannot be proven.
+[中文](README.md) · [Full usage guide](docs/USAGE.en.md) · [Architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)
 
-> Its Worktree safety foundation originates from workflows used in the author's internal desktop project **Domi**. This plugin is independently adapted for Harness and does not require Domi to install or run.
+## Why use it?
 
-[中文文档](README.md)
+When an agent edits Local directly, task changes can mix with existing staged, unstaged, and untracked work. Multiple tasks may also compete for the same checkout. This plugin separates construction from delivery:
 
-## What problem does it solve?
-
-When an agent edits the current working tree directly, several concerns become entangled:
-
-- task changes mix with existing staged, unstaged, and untracked Local state;
-- multiple agent tasks sharing one checkout can overwrite files, switch branches, or contaminate each other's commit boundaries;
-- multiple tasks writing results into Local at the same time can interfere with Preview, conflict handling, and cleanup;
-- it becomes difficult to tell which bytes belong to the current task;
-- “show me the result” may already mean an irreversible write into Local;
-- commit, cleanup, and recovery decisions may depend too heavily on model judgment;
-- starting another coding round often means losing the original conversation or rebuilding its context.
-
-This plugin separates a coding task into two explicit boundaries:
-
-1. **The agent implements and validates in an Isolated Worktree.**
-2. **The user reviews the result in Local and decides whether to commit it.**
+- the agent edits and tests only inside an isolated Worktree;
+- the user first inspects a reversible Local Preview;
+- the Host saves only the current task delta, excluding unrelated Local work;
+- if safety cannot be proven, writes stop and recovery evidence is preserved.
 
 ## Highlights
 
-- **Real isolation** — every task gets a distinct Git worktree, Harness Workspace, cwd, and Session ID.
-- **Human-gated delivery** — the model may prepare a review, but it cannot Preview, Commit, Discard, or delete the Worktree by itself.
-- **Reversible Local Preview** — inspect the task in Local without creating a commit, then accept it or remove only that Preview.
-- **Local state preservation** — existing staged, unstaged, and untracked Local changes are not automatically folded into the task commit.
-- **Parallel preparation, serialized acceptance** — multiple Isolated Worktrees may prepare tasks concurrently, while one active Preview per Local project prevents review drafts from being written over each other.
-- **Stop on conflict instead of overwriting** — overlapping changes, Local drift, branch movement, or an inseparable delta enters conflict/recovery rather than silently choosing one side.
-- **Task-only commit** — acceptance creates one commit for the isolated task while preserving separable Local work.
-- **Continuous Session iterations** — after delivery and cleanup, iteration + 1 can start in the same Session with the full conversation intact.
-- **Automatic read-only Preflight** — once Ready, the Review card and composer dock show Local/Worktree HEAD, effective base, sync conditions, conflicts, and the acceptance slot without writing Local.
-- **Review-to-edit recovery** — an unsynced review does not block discussion; stale or conflicting reviews can return to the current Worktree with a prefilled request to revalidate and prepare a new review.
-- **Verifiable Delivery Proof** — after Finalize, the UI shows the Commit OID, Local branch/HEAD, file and validation summaries, and cleanup/retention results.
-- **Fail-closed recovery** — stale reviews, Local drift, branch changes, concurrent Previews, and uncertain cleanup stop instead of overwriting data.
-
-> The current scope is a project-scoped Worktree Session workflow, not a cross-project global Worktree Manager. The project is still experimental; use it first in Git repositories that you can recover independently.
+- **Project-grouped sidebar**: each Managed owner appears under its original Local project with a Branch Icon and status Badge; ordinary Local Sessions keep the official behavior.
+- **Real isolation**: every task gets its own Git Worktree, Workspace, and unique owner Session.
+- **Human acceptance**: Ready lets the user choose **Preview changes**, **Confirm and save**, or another explicit action.
+- **Reversible Preview**: changes reach Local without an immediate Commit and can be rolled back safely.
+- **Task-only save**: final delivery creates one Commit for the accumulated task delta.
+- **Save checkpoint and continue**: checkpoints remain inside the managed Worktree and still collapse into one final delivery.
+- **Safe recovery**: handles Local drift, conflicts, `preview_detached`, restarts, and interrupted cleanup.
+- **Parallel construction, serialized acceptance**: many Worktrees can run concurrently while each Local project accepts one Preview at a time.
+- **Continuous iterations**: after delivery and cleanup, the same Session and conversation can begin another round.
 
-### Parallel tasks and conflict boundaries
-
-Multiple tasks can edit, test, and prepare reviews concurrently in separate Worktrees, Workspaces, and Sessions without sharing one checkout. Local acceptance is deliberately serialized: one canonical Local project has one acceptance slot. Until the active Preview is committed or rolled back, another task receives `project_acceptance_busy` instead of layering another write into Local.
-
-“Parallel tasks” does not mean “automatically merge every conflict.” If a task overlaps Local changes, its review becomes stale, the branch moves non-fast-forward, or the Host cannot prove that Rollback/Finalize will preserve unrelated work, the operation stops and retains recovery evidence for the user to resolve.
+> The scope is a **project-scoped Worktree Session delivery plugin**, not a cross-project global Worktree Manager.
 
 ## Workflow
 
-```text
-Local Session
-    │
-    ├─ Create isolated Worktree Session
-    ▼
-Agent edits and validates in the Worktree
-    │
-    ├─ worktree_ready_for_review
-    ▼
-Ready for Review
-    │
-    ├─ Sync to Local Preview ── Accept and commit
-    │                         └─ Roll back and continue editing
-    ├─ Skip Preview and commit directly
-    └─ Discard
-    │
-    └─ After cleanup: start iteration + 1 in the same Session
+```mermaid
+flowchart LR
+    A[Local Session] -->|Create Worktree| B[Worktree Session]
+    B --> C[Agent edits and validates]
+    C --> D[Ready for Review]
+    D -->|Preview changes| E[Local Preview]
+    E -->|Confirm and save| F[Iteration delivered]
+    F -->|cleanup| G[Start next iteration]
+
+    D -.->|Save checkpoint and continue| H[Save checkpoint<br/>Return to editing]
+    E -.->|Undo this preview| I[Return to editing]
+    D -.->|Skip preview and save| F
 ```
 
-### 1. Create an isolated Session
-
-In a blank/new Local Session, enable **Worktree** and confirm creation. Nothing is created before confirmation. After confirmation, the unsent text and image draft is transferred to the new isolated Session.
-
-An existing Local Session may also ask the model to call `worktree_create`. The source Session remains Local and is never silently switched to another cwd.
-
-### 2. Work inside the Worktree
-
-The agent reads, edits, and validates only inside the isolated cwd. That cwd is a real Git worktree and is registered as a Harness Workspace, so Harness Workspace and Session boundaries remain authoritative.
-
-### 3. Prepare the review
-
-When implementation and validation are complete, the agent calls `worktree_ready_for_review` with:
-
-- a change summary;
-- changed files;
-- validation status and test commands;
-- a suggested commit message.
-
-This stores a review report. It does not write to Local and does not create a commit. Once Ready appears, the dedicated Review card and composer dock automatically run a strictly read-only Preflight that shows Local/Worktree HEAD, effective base, changed-file count, conflicts, and the acceptance slot. Both surfaces share the same read result, but Preview and direct Finalize always force a fresh check; cached display state is never write authorization.
-
-### 4. Choose how to deliver
-
-The user can then:
-
-- **Sync to Local for review** — create an uncommitted, reversible Preview;
-- **Accept and commit** — commit only the task delta;
-- **Roll back and continue editing** — remove the Preview and return to the Worktree;
-- **Skip review and commit directly** — use the guarded direct-delivery path after explicit confirmation;
-- **Discard** — clean up the task environment when all safety conditions pass.
-
-If Preflight reports `stale_local`, `stale_isolated`, or a conflict, old Preview/Finalize actions are disabled immediately. The user can check again or return to the current Worktree to revalidate and prepare a new review. `project_acceptance_busy` exposes only a path-free holder summary; navigation happens only after the Host re-proves checkout, owner Session, and canonical cwd identity. After Finalize, the Review surface retains a Delivery Proof rather than collapsing to a generic success message.
-
-### 5. Start the next round in the same conversation
-
-After a successful commit and cleanup, the current Worktree cwd is removed, but the Session and conversation remain. When the user requests more code or file changes, the plugin can recreate the immutable cwd from the latest Local HEAD and start the next iteration safely.
-
-Retained, cleanup-pending, and recovery states are never removed silently. They must be handled before another iteration can begin.
-
-## Screenshots
-
-The following screenshots show the primary delivery flow in the order a task normally follows it.
-
-### Create a Worktree Session
-
-After Worktree is enabled in a new Local Session, Harness explains the Session-switch boundary. The isolated Session is created and selected only after explicit confirmation.
-
-![Confirm creation and switch to a Worktree Session](docs/screenshots/01-create-worktree.png)
-
-### Prepare the review
-
-When implementation and validation finish, the agent prepares a Ready for Review report. The user can inspect the summary and validation evidence before syncing anything to Local.
-
-![Worktree changes ready for review](docs/screenshots/02-ready-for-review.png)
-
-### Review the Local Preview
-
-After synchronization, the task delta waits in Local as a reversible Preview. The user can commit it, roll it back and continue editing, or discard the task.
-
-![Task changes waiting for acceptance in Local Preview](docs/screenshots/03-local-preview.png)
+### Which action should I choose?
 
-### Confirm the commit and choose retention
-
-The default path confirms the Commit Message and cleans up the Worktree after submission. When further investigation is useful, the frozen runtime environment can instead be retained for the selected period.
-
-| Commit and clean up | Commit and retain the runtime environment |
+| Goal | Action |
 | --- | --- |
-| ![Confirm the task-only commit and clean up the Worktree](docs/screenshots/04-commit-confirmation.png) | ![Confirm the task-only commit and retain the runtime environment](docs/screenshots/06-retain-environment.png) |
-
-### Start the next iteration in the same Session
-
-After delivery and cleanup succeed, the conversation remains available and can begin another iteration from the latest Local HEAD.
-
-![Delivered Session ready to start the next iteration](docs/screenshots/05-next-iteration.png)
-
-## Design foundation and Harness adaptation
-
-The Worktree lifecycle and Git delivery engine are adapted from a mature desktop implementation that has been exercised in real workflows. The goal is not to copy its UI, but to preserve proven safety invariants:
-
-- managed checkout registry and revision CAS;
-- canonical path, Git common-dir, and git-dir identity checks;
-- complete fingerprints for staged, unstaged, untracked, binary, and deleted files;
-- receipt-first Local Preview, Rollback, and Finalize;
-- task-only commits that preserve unrelated Local work;
-- internal refs, journal recovery, retention, quarantine, and conservative cleanup;
-- fail closed whenever the Host cannot prove that a write is safe.
-
-DeepSeek Harness has a different Host and Session model from the original desktop host, so the integration was adapted rather than copied mechanically:
+| Inspect the result in Local first | **Preview changes** |
+| The Preview looks correct | **Confirm and save** |
+| Preserve progress during a long task | **Save checkpoint and continue** |
+| Ask the agent for more edits | **Continue editing** or **Undo this preview** |
+| Deliver without a Preview | **Skip preview and save** |
 
-- Harness Workspace and Session cwd are authoritative; the plugin registry is supporting state only;
-- Host capabilities are exposed through strict Typert Remote, while browser UI uses public Harness Client Slots;
-- Local source and Isolated target always use separate Sessions;
-- cleanup does not mutate Harness's persisted Session cwd; the next iteration recreates the same path only after strict identity checks;
-- the model creates targets, resumes editing, and prepares reviews, while user-controlled surfaces own Local writes, commits, and cleanup.
+See the [full usage guide](docs/USAGE.en.md) for detailed actions, recovery scenarios, and commands.
 
-See [Session Target porting notes](docs/PORTING.md) for the detailed identity, state, and recovery boundary mapping.
+## Quick start
 
-## Requirements
+### Requirements
 
-- Node.js `^22.19.0 || >=24.0.0`;
-- DeepSeek Harness `0.1.0-rc.8` package line;
-- Harness Web Client for the complete Worktree creation and acceptance UI;
-- a Git repository as the current Workspace.
+- Node.js `^22.19.0 || >=24.0.0`
+- DeepSeek Harness `0.1.1-rc.2` package line
+- Harness Web Client
+- A Git Workspace
 
-## Install
-
-Install the npm package:
+### Install
 
 ```bash
 dsh plugin --profile web add dsh-git-worktree
 ```
 
-Or install a specific Git tag:
+Or install a specific version:
 
 ```bash
-dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.4.0
-```
-
-With pnpm 10 or newer, a Git install may require this entry in the profile's `pnpm-workspace.yaml` before retrying:
-
-```yaml
-allowBuilds:
-  dsh-git-worktree: true
-```
-
-Start Harness normally after installation and open a Git repository as the Workspace.
-
-## Model tools and user controls
-
-### Model tools
-
-| Tool | Purpose |
-| --- | --- |
-| `worktree_create` | Create a managed Worktree from a Local Session and reserve a distinct target Session |
-| `worktree_list` | List Worktrees visible to the current Session in the original project |
-| `worktree_resume_revision` | Invalidate an unsynced review and resume the current iteration without touching Local |
-| `worktree_begin_next_iteration` | Recreate the Worktree cwd for a delivered and successfully cleaned Session |
-| `worktree_ready_for_review` | Save the delivery report and stop for explicit human acceptance |
-
-Finish, Discard, Remove, and Local Preview are not model tools. Ordinary discussion leaves a Ready review unchanged; only new code or file work needs to resume Working.
-
-### User controls
-
-The Web UI provides the normal create, Preview, rollback, commit, retention, continue-editing, and discard actions. The `Local / Worktree · status` capsule in the Session Header opens the current-target controls and the Linked Worktrees manager directly; a source Session or any linked target Session can view the same source-linked tasks, navigate to their Sessions, and manage its own Worktree without returning to the original project. The manager stays focused on status, navigation, and owner lifecycle actions and does not regain inspect/review expansion. Automatic Preflight, stale/conflict recovery, acceptance-slot navigation, and Delivery Proof remain in the dedicated Review card and composer dock. Equivalent Host-controlled operations are also available through `/worktree` commands:
-
-```text
-/worktree status
-/worktree list
-/worktree continue
-/worktree next
-/worktree finalize [<reviewId> <revision>] [cleanup|retain_24h|retain_3d|retain_manual]
-/worktree finish <commit message>
-/worktree discard
-/worktree remove <checkoutId>
+dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.7.1
 ```
 
-`finalize` uses the suggested commit message from the current review. `finish` is the explicit direct-commit path with a user-provided message.
-
-## Safety model
+Open a Git Workspace and enable **Worktree** when creating a Session. An existing Local Session can also let the model call `worktree_create`.
 
-Every acceptance operation is revalidated by the Host. Browser display state and model-provided identity data are never treated as authority.
+For the first run, complete one full create → Preview changes → Confirm and save → cleanup cycle.
 
-Important rules include:
+If pnpm build approval blocks a Git-source install, or you need complete commands and troubleshooting, see [Installation and troubleshooting](docs/USAGE.en.md#installation-and-troubleshooting).
 
-- Local source and Isolated target use different Session IDs;
-- an active target Workspace must canonicalize to the managed root recorded by the Host;
-- one canonical Local project can have only one active Preview; a waiting owner keeps read-only Preflight but loses Preview/Finalize capability;
-- an acceptance-slot blocker exposes only a path-free checkout/Session/state summary; opening it requires a fresh inspect plus owner and canonical-cwd verification;
-- automatic Preflight creates no plan, slot, Git ref, or Local write; Preview and direct Finalize bypass display caches and check again;
-- Preview receipts and internal refs are persisted before Local writes;
-- Preview, Rollback, Finalize, Discard, and resume-editing paths bind checkout, revision, review, and fingerprint identity;
-- Rollback removes only the delta proven to belong to the Preview and preserves separable Local changes made during review;
-- branch switches, non-fast-forward history, overlapping conflicts, committed Preview bytes, or additional drift enter recovery instead of being overwritten;
-- cleanup verifies managed-path identity, Git metadata, and the final fingerprint; uncertain residue is retained or quarantined;
-- durable Delivery Proof is bound to the exact Review and records Commit, Local branch/HEAD, changed files, and validation evidence; dynamic history evidence grants no mutation capability;
-- historical records from the old irreversible Apply flow are not automatically finished or discarded.
+## Screenshots
 
-See [Worktree Console architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md) for the complete state model and authorization matrix.
+### Project grouping and task status
 
-## Current limitations
+![Managed Worktrees grouped under the original Local project](docs/screenshots/00-project-sidebar.png)
 
-- There is no cross-project global Worktree Manager yet.
-- The linked Worktree Manager opens from the Session Header control; a persistent `conversation.view` tab is still not mounted.
-- Harness still presents Local and Worktree Sessions as separate Workspaces by canonical cwd. The plugin manager shows the `sourceSessionId` relationship without changing native sidebar grouping.
-- Workflow `agent({ isolation })` integration is not available in the verified Harness `0.1.0-rc.8` line.
-- Subagents inherit their parent Session cwd; they share the isolated boundary only when the parent is already a Worktree Session.
-- Dependency snapshot/restore and the complete collaborator handoff UI have not yet been implemented.
-- A reviewed stage cannot yet be saved as an internal checkpoint before continuing development.
-- An Isolated Session cannot yet request a bounded transaction to repair the real Local checkout directly.
-- Cleanup removes the current Worktree cwd, but a delivered Session can recreate the path and start another iteration after strict validation.
+### Prepare the review
 
-## Roadmap
+![Agent completes the task and prepares Preview changes](docs/screenshots/02-ready-for-review.png)
 
-The following items describe possible directions for continuing the project. They are not release-date commitments.
+See the [full usage guide](docs/USAGE.en.md#complete-delivery-example) for the complete flow.
 
-### Near term
+## Safety boundary
 
-- Continue improving marketplace presentation and end-to-end examples.
-- Continue hardening Ready, Preview, Rollback, Finalize, cleanup, and iteration recovery.
-- Improve error categories, recovery guidance, and compatibility across real Harness releases.
-- Re-evaluate whether a persistent Worktrees tab is still useful in addition to the Header Manager.
+The Host rechecks every Local write at execution time. Browser caches and model output are never write authority. The plugin validates Session, checkout, revision, Git identity, Preview receipt, and Local state; branch switches, overlapping conflicts, unknown residue, or insufficient recovery evidence fail closed.
 
-### Medium term
+For the full state machine, CAS, and recovery invariants, see:
 
-- Add “save stage and continue” so long tasks can record reviewed stages inside the isolated checkout, continue from a clean worktree, and retain stage history in final acceptance.
-- Evaluate a bounded Local repair transaction: a user-approved temporary authorization tied to the current Local state, allowing an Isolated Session to repair Local through restricted tools without changing its Session Target, then automatically resume the original task.
-- Port dependency snapshot/restore to reduce repeated setup across Worktrees.
-- Complete the collaborator/subagent handoff lifecycle so delegated work can be released and delivered safely.
-- Continue enriching linked Worktree listing, inspection, retention, and cleanup management.
-- Improve review presentation with clearer diff and validation information without weakening Host authority.
+- [Worktree Console architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)
+- [Session Target porting notes](docs/PORTING.md)
 
-### Long term
+## Current boundaries
 
-- Build a cross-project global Worktree Manager.
-- Integrate Workflow-level `agent({ isolation })` when Harness exposes a stable seam.
-- Add richer audit, runtime metrics, and recovery diagnostics.
-- Explore richer multi-task orchestration, serialized acceptance, and cross-Session handoff while preserving explicit human approval for every Local write.
+- A normal Managed owner is grouped under its original Local project. If the owner is missing, another Session exists, or membership conflicts, the original Workspace remains visible instead of hiding uncertain data.
+- Managed owners can be renamed and archived. Worktree-aware Fork is not implemented yet, so the ordinary Fork action is hidden in this release.
+- Child agents inherit the parent Session cwd; the plugin does not create per-child Worktrees.
+- Checkpoint does not support editing, deleting, reordering, or arbitrary rollback of history.
+- Domi's global Manager, Local Maintenance, dependency snapshots, and full collaborator lifecycle are outside this plugin's scope.
 
 ## Local development
 
-Install dependencies and run the standard checks:
-
 ```bash
 pnpm install
 pnpm run typecheck
@@ -307,34 +130,19 @@ pnpm run build
 pnpm run check:publish
 ```
 
-For an end-to-end local Harness run:
+Run the local end-to-end environment:
 
 ```bash
 pnpm run dev:dsh
 ```
 
-This command builds the current checkout, packs a temporary tarball, installs it into the `web` profile, validates the composed configuration, prepares a marker-protected disposable Git fixture, and starts `dsh web` at `http://127.0.0.1:3081` by default. It does not publish packages or push Git refs.
-
-Useful variants:
-
-```bash
-# Install and verify the snapshot without starting Web
-pnpm run dev:dsh:install
-
-# Verify the already-installed profile
-pnpm run dev:dsh:smoke
-
-# Select another Git root, port, profile, or Harness source checkout
-pnpm run dev:dsh -- --repo G:/path/to/repo --port 4090 --profile web
-
-# Remove the development install and cached local archives
-pnpm run dev:dsh:remove
-```
+See the [full usage guide](docs/USAGE.en.md#local-development) for more development commands and the [release checklist](docs/RELEASE.md) before publishing.
 
 ## Documentation
 
-- [Session Target porting notes](docs/PORTING.md)
+- [Full usage guide](docs/USAGE.en.md)
 - [Worktree Console architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)
+- [Session Target porting notes](docs/PORTING.md)
 - [UI development notes](docs/UI-DEVELOPMENT.md)
 - [Release checklist](docs/RELEASE.md)
 - [Changelog](CHANGELOG.md)