dsh-git-worktree 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+本项目的显著变更记录在此文件中。版本号遵循 Semantic Versioning；在 `0.x` 阶段，minor 版本可能包含需要迁移的公开能力调整。
+
+## [0.3.0] - 2026-08-17
+
+`0.3.0` 完善同一 isolated Session 的连续修改体验：未同步 Review 可以安全恢复编辑，成功交付并 cleanup 后也能保留 Session ID、immutable cwd 与完整对话开始下一轮。
+
+### Added
+
+- cleanup 后在原 isolated Session 中开始 iteration + 1；新 checkout 从最新 Local HEAD 创建，并通过 `predecessorCheckoutId` 保留上一轮交付记录与迭代血缘。
+- delivered composer dock 增加“开始下一轮修改”，模型增加 `worktree_begin_next_iteration`，人工命令增加 `/worktree next`。
+- Host、strict Typert Remote、Client Adapter 与 Console Contract 增加 `beginNextIteration`；Remote 方法总数由 13 个增加到 14 个。
+- cleanup 后 Harness 过滤缺失 cwd 的 Session 时，lookup adapter 可通过当前 live Session 的 immutable header cwd 恢复精确且唯一的 Workspace 身份。
+- 新增 `worktree_resume_revision`、`/worktree continue` 与 Ready 更多菜单“继续修改”，在不写入 Local 的情况下使未同步 Review 失效并恢复同一 iteration。
+- Worktree Console Contract、Host、strict Typert Remote 与 Client Adapter 增加 `resumeRevision`；Remote 方法总数由 14 个增加到 15 个。
+
+### Fixed
+
+- 修复 `worktree_ready_for_review` 输出 Schema，使其符合 Harness 工具结果契约。
+- 发布产物门禁同步校验新增的 `beginNextIteration` 与 `resumeRevision` Remote 方法。
+- 完善并稳定本地开发 Harness 的源码预览、验收输出提取、命令失败诊断与跨平台路径处理。
+
+### Safety
+
+- 下一轮仅允许已成功清理的 delivered owner，并校验 caller、Workspace、revision、Local Git common dir、managed path 与 predecessor lineage。
+- 如果上一轮 managed path 已重新出现或包含未知内容，拒绝覆盖；retained、cleanup-pending 与 recovery 状态必须先完成清理或恢复。
+- 创建中断且尚未形成 Worktree 时，reconcile 恢复 predecessor binding；存在无法确认的残留时进入 recovery 并保留现场。
+- live Session cwd fallback 对 cold、无 cwd、路径不匹配或歧义映射继续 fail closed。
+- resume-revision 严格校验 live owner Session、expected revision、expected review ID、Workspace/checkout 身份；转换只更新 registry delivery state，不修改 Local、Worktree bytes 或 Git refs。
+
+### Changed
+
+- Ready for Review 不再阻断普通对话：讨论类 follow-up 保持当前 Review；新的代码或文件修改由模型自动恢复 Working，不要求用户先同步或点击恢复编辑。
+- 重写中英文 README，补充当前 Session Target 流程、安全边界、命令、模型工具和已知限制。
+- `SessionCheckoutModule.beginNextIteration` 现在要求调用方传入 `expectedRevision`，避免基于过期 delivered 状态创建下一轮。
+
+## [0.2.0] - 2026-08-17
+
+`0.2.0` 将插件从单一 Worktree 管理器升级为 DeepSeek Harness 中完整、可验收、可撤回的 Worktree Session Target。
+
+### Added
+
+- 真实 source/target Session 分离：Host 分配唯一 checkout、managed root 与 target Session ID，source Session 始终保持 Local。
+- blank Local Session 的 pre-session **Worktree** 开关与确认弹窗：确认前零副作用，确认后才创建 target、迁移未发送的文字/图片并打开独立 Session。
+- Harness 官方 Slot 集成：
+  - Create/Ready ToolView；
+  - Header Session Target 状态胶囊；
+  - `conversation.input.dock` 的 Ready、Preview 与 Recovery 状态条。
+- Domi 式交付生命周期：
+  - Ready for Review；
+  - 不提交、可撤回的 Local Preview；
+  - Preview 验收提交；
+  - 撤回并恢复 Worktree 编辑；
+  - 跳过验收直接提交；
+  - cleanup 与 retain 策略。
+- 项目级单 Preview 验收槽位、持久 Preview receipt、内部 Git refs、crash reconcile 与 cleanup retry。
+- 13 个 strict Typert Remote 方法，覆盖 current/list/create/inspect、preflight、Preview/rollback/finalize、Discard、retention 与 cleanup。
+- sibling managed Worktree 路径与安全 fallback；短 checkout identity 冲突时自动扩展，旧 registry 路径继续可管理。
+- 一键本地 DSH 开发、临时 tarball 安装、profile smoke 与发布产物门禁。
+
+### Safety
+
+- Preview receipt 在触碰 Local 前持久化，并绑定 review、revision、isolated HEAD/fingerprint 和 Local HEAD/ref/fingerprint CAS。
+- Local staged、unstaged、untracked 状态在 Preview、rollback 和 finalize 中保持分层语义；无法证明无损时 fail closed。
+- 同分支 fast-forward 后的安全 rollback 使用三方反向合并，只移除 Preview delta，同时保留新 Commit 和 Preview 外 Local 修改。
+- branch switch、non-fast-forward、重叠冲突、Preview 已进入 Commit、额外 Preview 修改或最终 CAS 漂移会进入 detached/recovery 状态，不覆盖用户修改。
+- active Preview 的 Discard 必须先成功 rollback；detached Preview 保留 Worktree、receipt 与内部 refs 作为恢复证据。
+- target Workspace cwd 必须 canonicalize 到 Host 记录的 managed root；caller/project/workspace/owner/review identity 全部 fail closed。
+- owner Session live 后，source Session 不再拥有管理权限；其他 Session 不能依赖持久化 owner ID 越权管理。
+
+### Changed
+
+- Ready 主操作改为“同步到 Local 验收”；Preview 主操作改为“验收通过并提交”，撤回和 direct finish 收入“更多”菜单。
+- 普通验收界面改为中文优先的紧凑摘要，验证详情默认折叠，不显示 Diff/Inspect 或平铺 Retention。
+- 历史不可逆 `worktree_apply` 公开路径暂停；模型不再直接拥有 Finish、Discard 或 Remove 权限。
+- `WorktreeConsoleView`、Host 控制面和 strict Remote 管理能力继续保留，但可见的项目级 `conversation.view` Worktree 页签暂不挂载，优先稳定 pre-session、独立 target Session 与 composer 验收主流程。
+- managed Worktree 新路径采用 `<repo>--worktrees/<repo>--<checkout-short>--worktree`，不安全时回退到插件 stateDir。
+
+### Compatibility
+
+- 需要 DeepSeek Harness `0.1.0-rc.6` 包线与 Node.js 20 或更高版本。
+- pnpm 10 的 Git 源安装可能需要在 profile `pnpm-workspace.yaml` 中允许 `dsh-git-worktree` 执行 `prepare`。
+- `./manager` 不再是发布 export；Client/Host 集成改用正式 package entry、`./client`、strict `./typert` / `./remote` 与 `./console-contract`。
+- 已经使用旧不可逆 Apply 的历史记录不会自动迁移到 Preview 生命周期，Finish/Discard 会保守拒绝并要求人工检查 Local。
+
+## [0.1.2] - 2026-07-28
+
+- 发布初版 Domi-grade Worktree 管理、基础 apply/finish/discard 生命周期和安全清理。
+
+[0.3.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/wloops/dsh-git-worktree/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/wloops/dsh-git-worktree/releases/tag/v0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 wloops
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 wloops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,43 +1,187 @@
-# dsh-git-worktree
-
-Domi-grade git worktree isolation and delivery for DeepSeek Harness: permanent worktrees, a ready-for-review / apply / finish / discard lifecycle, conflict handling, and safe cleanup.
-
-> Ported from [Domi](https://github.com/wloops/domi)'s production worktree system (Session Target / Isolated Checkout), with the Local-preview surface removed to match the DSH sandbox model.
-
-## What you get
-
-| Capability | Description |
-| --- | --- |
-| `worktree_create` / `worktree_list` / `worktree_remove` | Permanent detached worktrees under `<repo>/.dsh-worktrees/`, recorded in a per-repo manifest and registered as DSH workspaces |
-| `worktree_ready_for_review` | Agent submits review facts (summary, validation tests, suggested commit message) |
-| `worktree_apply` | Deterministically merge the worktree's changes into your Local checkout — conflict-aware, fingerprint-CAS, never touches Local until the plan is verified |
-| `worktree_finish` | Commit the task delta onto your Local branch while preserving your own staged/working state |
-| `worktree_discard` | Drop the worktree (dirty confirmation required) |
-| `/worktree` | Human-facing command surface |
-| Safe cleanup | Retained worktrees expire, residue is quarantined, dirty worktrees are never silently deleted, no global `git worktree prune` |
-
-## Why worktrees live inside the repo
-
-DSH's `workspace-write` sandbox grants exactly the session workspace root. Worktrees therefore live at `<repo>/.dsh-worktrees/<name>` (same pattern as Codex's `.codex/worktrees`), so agent file tools and git operations stay inside the sandbox.
-
-## Install
-
-```sh
-# from npm (recommended)
-dsh plugin --profile web add dsh-git-worktree
-
-# or from GitHub source (built on install via the prepare script)
-dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.1.2
-```
-
-Git installs build the package on the fly. On pnpm ≥ 10 that build script is
-blocked until allowed: add `dsh-git-worktree: true` under `allowBuilds` in the
-profile's `pnpm-workspace.yaml`, then re-run the add command.
-
-## Status
-
-Pre-release (`0.1.0`). The state machine and apply engine are ported from Domi's production code (journal-based crash recovery, fingerprint CAS, Windows cleanup retries); the DSH tool surface is new and being hardened. Requires DSH `0.1.0-rc.6` line (`@deepseek-ai/dsh-tools` / `dsh-subprocess` / `dsh-commands`).
-
-## License
-
-MIT
+# dsh-git-worktree
+
+[![npm](https://img.shields.io/npm/v/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)
+
+**Run coding tasks in real Git worktrees, review the result in Local, and commit only after explicit human approval.**
+
+`dsh-git-worktree` is an experimental [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) plugin that turns a Git worktree into an isolated Session Target. The agent works in a separate checkout and Session; the original Local checkout stays under human control.
+
+[中文文档](README.zh.md)
+
+## Why use it?
+
+A normal agent session can modify the same working tree you are using. This plugin separates execution from acceptance:
+
+- **Real isolation** — each task gets a distinct Git worktree, Workspace, cwd, and Session ID.
+- **Human-gated delivery** — the model can prepare a review, but it cannot commit, discard, or clean up by itself.
+- **Reversible Local Preview** — inspect the exact change in Local before committing, then accept it or roll it back.
+- **Local changes are preserved** — staged, unstaged, and untracked Local state is kept separate from the task change.
+- **Fail-closed recovery** — stale reviews, conflicting edits, changed branches, and uncertain cleanup stop instead of overwriting data.
+
+> The project is still experimental. It provides a project-scoped Worktree Session workflow, 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
+```
+
+1. In a blank Local Session, turn on **Worktree** and confirm creation. The unsent text/image draft moves to the isolated Session; cancelling creates nothing.
+2. For an existing Local Session, the model can call `worktree_create`, after which you open the isolated Session from its ToolView.
+3. The agent edits and validates only inside the isolated cwd.
+4. The agent ends with `worktree_ready_for_review`, including changed files, validation evidence, and a suggested commit message.
+5. You choose what happens next:
+   - **Sync to Local for review**, then commit or roll the Preview back;
+   - **Skip review and commit directly**;
+   - **Discard** the task.
+6. After a successful commit and cleanup, the delivered Session can start the next iteration without losing its conversation. Harness keeps Session cwd immutable, so the plugin recreates only the previously cleaned, Host-owned managed path after strict identity checks.
+
+All acceptance paths revalidate the review revision, Worktree HEAD/fingerprint, and Local state before writing. Retained or cleanup-pending environments must be cleaned first; starting another iteration never silently removes them.
+
+## Requirements
+
+- Node.js 20 or newer
+- DeepSeek Harness `0.1.0-rc.6` package line
+- Harness Web client for the interactive Worktree controls
+- A Git repository
+
+## Install
+
+```bash
+# npm package
+dsh plugin --profile web add dsh-git-worktree
+
+# Git tag; prepare builds the Host and Client bundles
+dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.3.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.
+
+## User and model controls
+
+### Model tools
+
+| Tool | Purpose |
+| --- | --- |
+| `worktree_create` | Create a managed Worktree and reserve a distinct target Session without changing the current Session cwd |
+| `worktree_list` | List Worktrees visible to the current Session within the original project |
+| `worktree_resume_revision` | Automatically invalidate an unsynced review before new code/file changes and resume the same iteration without touching Local |
+| `worktree_begin_next_iteration` | Recreate a successfully cleaned delivered Session cwd for iteration + 1, preserving the same Session and conversation |
+| `worktree_ready_for_review` | Save the delivery report and stop for explicit human acceptance |
+
+Finish, Discard, and Remove are deliberately excluded from the model tool surface. While an unsynced review is waiting, ordinary discussion continues without changing it; if a follow-up requests code or file changes, the model calls `worktree_resume_revision` automatically. The user does not need to synchronize Local or click a recovery control.
+
+### User controls
+
+The Web UI provides the normal create, Preview, rollback, commit, retention, and discard actions. The same 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>
+```
+
+`finalize` uses the suggested commit message from the active review. `finish` is the explicit direct-commit path with a custom message.
+
+## Safety model
+
+The implementation ports Domi's hardened checkout/apply foundations to Harness's authoritative Workspace and Session cwd model. Important invariants include:
+
+- The initial Local source and isolated target use different Session IDs; later iterations keep the same isolated Session ID.
+- An active target is trusted only when its Harness Workspace resolves to the recorded managed root. A cleaned delivered target may temporarily reference its missing immutable cwd only when the Host path identity exactly matches the predecessor record.
+- One canonical Local project can have only one active Preview.
+- Preview receipts are persisted before Local writes so rollback/finalize can recover after a Host restart.
+- Preview, commit, rollback, and resume-revision paths use revision and identity checks; review-based paths bind the review ID, and resume-revision changes only registry delivery state after validating the managed checkout.
+- Cleanup verifies path identity, Git metadata, and the final fingerprint; uncertain residue is retained or quarantined.
+- Next iteration creation only reuses an absent path from a successfully cleaned predecessor, creates a new checkout record, and preserves the predecessor as recovery evidence.
+- Legacy records created by the old irreversible Apply flow are not automatically finished or discarded.
+
+For the detailed boundary and recovery design, see [Porting notes](docs/PORTING.md) and [Worktree Console architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md).
+
+## Local development
+
+Install dependencies and run the standard checks:
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run check:publish
+```
+
+For an end-to-end local Harness run:
+
+```bash
+pnpm run dev:dsh
+```
+
+This command builds the current checkout, packs it into a temporary local tarball, installs it into the `web` profile, verifies 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 to npm 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
+
+# Use an existing Git root, another port, or another profile
+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
+```
+
+When nearby DeepSeek Harness source checkouts are found, `dev:dsh` prefers a runnable candidate with `node_modules/tsx` installed. Select a checkout in any other location with `DSH_HARNESS_ROOT` or `--harness <path>`. Once a source checkout is selected, plugin installation, config validation, removal, and Web startup all use that source CLI without requiring a globally installed `dsh`. If an explicitly selected checkout has not installed its dependencies, the workflow fails before building and prints the corresponding `pnpm --dir <path> install` command. Only runs without a source checkout fall back to `dsh` on PATH.
+
+## Current limitations
+
+- No cross-project global sidebar manager yet.
+- The project-scoped Worktree Console implementation exists, but its visible `conversation.view` tab is not mounted in `v0.3.0` while the primary flow is stabilised.
+- In the verified Harness `0.1.0-rc.6` line, Workflow `agent({ isolation })` integration is not available.
+- In that Harness line, subagents inherit the parent Session cwd; they are isolated only when the parent is already a Worktree Session.
+- Dependency snapshot/restore and the complete collaborator handoff UI are deferred.
+- Immediate cleanup removes the isolated cwd, making that Session terminal; continue from Local or start a new iteration.
+
+## Documentation
+
+- [Porting from Domi to Harness](docs/PORTING.md)
+- [Worktree Console architecture](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)
+- [UI development notes](docs/UI-DEVELOPMENT.md)
+- [Release checklist](docs/RELEASE.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -1,41 +1,187 @@
-# dsh-git-worktree
-
-为 DeepSeek Harness 打造的 Domi 级 git worktree 隔离与交付插件：永久 worktree、ready-for-review / apply / finish / discard 完整生命周期、冲突处理与安全清理。
-
-> 移植自 [Domi](https://github.com/wloops/domi) 的生产 worktree 系统（Session Target / Isolated Checkout），为适配 DSH 沙箱模型移除了 Local Preview 面。
-
-## 能力
-
-| 能力 | 说明 |
-| --- | --- |
-| `worktree_create` / `worktree_list` / `worktree_remove` | 仓库内 `.dsh-worktrees/` 下的永久 detached worktree，manifest 记录 + 注册为 DSH 工作区 |
-| `worktree_ready_for_review` | Agent 提交验收信息（摘要、验证项、建议提交信息） |
-| `worktree_apply` | 确定性合并 worktree 改动回 Local checkout——冲突感知、指纹 CAS、plan 验证前绝不触碰 Local |
-| `worktree_finish` | 把任务增量提交到 Local 分支，同时保留你自己的 staged/working 状态 |
-| `worktree_discard` | 丢弃 worktree（dirty 需要显式确认） |
-| `/worktree` | 人类可用的命令入口 |
-| 安全清理 | 保留期到期自动清理、残余 quarantine、dirty 永不静默删除、不执行全局 `git worktree prune` |
-
-## 为什么 worktree 放在仓库内
-
-DSH 的 `workspace-write` 沙箱只授予会话工作区根。因此 worktree 位于 `<repo>/.dsh-worktrees/<name>`（与 Codex 的 `.codex/worktrees` 同模式），agent 的文件工具和 git 操作都留在沙箱内。
-
-## 安装
-
-```sh
-# 从 npm（推荐）
-dsh plugin --profile web add dsh-git-worktree
-
-# 或从 GitHub 源码安装（安装时通过 prepare 脚本自动构建）
-dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.1.2
-```
-
-Git 安装会在拉取后自动构建。pnpm ≥ 10 默认拦截依赖的构建脚本：在 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 下添加 `dsh-git-worktree: true`，然后重跑 add 命令。
-
-## 状态
-
-预发布（`0.1.0`）。状态机与 apply 引擎移植自 Domi 生产代码（journal 崩溃恢复、指纹 CAS、Windows 清理重试）；DSH 工具面为新增并正在加固。要求 DSH `0.1.0-rc.6` 线（`@deepseek-ai/dsh-tools` / `dsh-subprocess` / `dsh-commands`）。
-
-## 许可证
-
-MIT
+# dsh-git-worktree
+
+[![npm](https://img.shields.io/npm/v/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)
+
+**让 Agent 在真实 Git Worktree 中完成任务，在 Local 中验收，并且只在用户明确确认后提交。**
+
+`dsh-git-worktree` 是一个实验性的 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) 插件。它把 Git Worktree 变成独立的 Session Target：Agent 使用单独的 checkout 和 Session 工作，原始 Local 工作区始终由用户控制。
+
+[English](README.md)
+
+## 为什么需要它？
+
+普通 Agent Session 可能直接修改你正在使用的工作区。本插件把“执行任务”和“接受结果”分开：
+
+- **真实隔离**：每个任务都有独立的 Git Worktree、Workspace、cwd 和 Session ID。
+- **用户掌握交付权**：模型可以准备验收报告，但不能自行提交、放弃或清理。
+- **可撤回的 Local Preview**：提交前先在 Local 查看精确变更，可以验收提交，也可以撤回后继续修改。
+- **保留 Local 现场**：Local 中已有的 staged、unstaged 和 untracked 内容不会被混入任务提交。
+- **保守恢复**：历史验收卡、并发修改、分支变化或清理身份不确定时直接停止，不覆盖用户数据。
+
+> 项目仍处于实验阶段。当前提供的是项目级 Worktree Session 工作流，还不是跨项目的全局 Worktree Manager。
+
+## 工作流程
+
+```text
+Local Session
+    │
+    ├─ 创建隔离的 Worktree Session
+    ▼
+Agent 在 Worktree 中修改并验证
+    │
+    ├─ worktree_ready_for_review
+    ▼
+等待验收
+    │
+    ├─ 同步到 Local Preview ── 验收并提交
+    │                         └─ 撤回并继续修改
+    ├─ 跳过 Preview，直接提交
+    └─ 放弃任务
+    │
+    └─ cleanup 后在原 Session 开始 iteration + 1
+```
+
+1. 在 blank/new Local Session 中打开 **Worktree** 开关并确认。未发送的文字和图片草稿会迁移到隔离 Session；取消不会创建任何资源。
+2. 已存在的 Local Session 可以由模型调用 `worktree_create`，然后由用户从 ToolView 打开隔离 Session。
+3. Agent 只在隔离 cwd 中修改和验证代码。
+4. Agent 最后调用 `worktree_ready_for_review`，写入变更摘要、验证证据和建议 Commit Message，然后停止。
+5. 用户决定如何处理：
+   - **同步到 Local 验收**，再提交或撤回 Preview；
+   - **跳过验收，直接提交**；
+   - **放弃任务**。
+6. 成功提交并 cleanup 后，可以在原隔离 Session 中开始下一轮，不丢失现有对话。Harness 的 Session cwd 不可变，因此插件只会在严格身份校验后重建上一轮已经清理的 Host-owned managed path。
+
+所有验收路径在写入前都会重新校验 review revision、Worktree HEAD/fingerprint 和 Local 状态。Retained 或 cleanup-pending 环境必须先完成清理；开始下一轮不会静默删除这些环境。
+
+## 环境要求
+
+- Node.js 20 或更高版本
+- DeepSeek Harness `0.1.0-rc.6` 包线
+- 使用 Harness Web Client 才能获得完整交互界面
+- 当前 Workspace 必须是 Git 仓库
+
+## 安装
+
+```bash
+# npm 包
+dsh plugin --profile web add dsh-git-worktree
+
+# Git tag；prepare 会构建 Host 和 Client bundle
+dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.3.0
+```
+
+使用 pnpm 10 或更高版本时，Git 源安装可能需要先在 profile 的 `pnpm-workspace.yaml` 中加入：
+
+```yaml
+allowBuilds:
+  dsh-git-worktree: true
+```
+
+安装后正常启动 Harness，并以一个 Git 仓库作为 Workspace。
+
+## 用户与模型入口
+
+### 模型工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `worktree_create` | 创建 managed Worktree 并预留独立 target Session，不修改当前 Session cwd |
+| `worktree_list` | 列出当前 Session 在原始项目中可见的 Worktree |
+| `worktree_resume_revision` | 新的代码/文件修改前自动使未同步 Review 失效，在不触碰 Local 的情况下恢复同一 iteration |
+| `worktree_begin_next_iteration` | 为已成功清理的 delivered Session 重建 iteration + 1，并保持同一 Session 与完整对话 |
+| `worktree_ready_for_review` | 保存交付报告并停止，等待用户明确验收 |
+
+Finish、Discard、Remove 不向模型开放，避免用模型参数代替用户授权。未同步 Review 等待期间，普通讨论会直接继续且不改变验收稿；如果 follow-up 要求修改代码或文件，模型会自动调用 `worktree_resume_revision`。用户不需要先同步 Local，也不需要点击恢复编辑。
+
+### 用户操作
+
+Web UI 提供创建、Preview、撤回、提交、保留和放弃等常用操作。Host 控制的同类能力也可以通过 `/worktree` 命令调用：
+
+```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>
+```
+
+`finalize` 使用当前验收报告中的建议 Commit Message；`finish` 是由用户提供自定义消息的直接提交路径。
+
+## 安全模型
+
+实现把 Domi 中经过生产验证的 checkout/apply 安全基础迁移到 Harness 的权威 Workspace / Session cwd 模型。关键不变量包括：
+
+- 初始 Local source 与 isolated target 使用不同的 Session ID；后续 iteration 保持同一个 isolated Session ID。
+- 活动 target 的 Harness Workspace 必须解析到 Host 记录的 managed root。已清理的 delivered target 只在 Host Workspace 原始路径与 predecessor 记录精确一致时，才允许暂时引用缺失的 immutable cwd。
+- 同一 canonical Local 项目同时只允许一个活动 Preview。
+- 在写入 Local 前先持久化 Preview receipt，使 Host 重启后仍可恢复 rollback/finalize。
+- Preview、Commit、rollback 与 resume-revision 路径都使用 revision 和身份校验；基于验收报告的路径绑定 review ID，resume-revision 在验证 managed checkout 后只改变 registry delivery state。
+- 清理前验证路径身份、Git 元数据和最终 fingerprint；无法确认的残余会保留或 quarantine。
+- 下一轮只复用已成功清理且当前不存在的 predecessor path，创建新的 checkout record，并保留上一轮记录作为恢复证据。
+- 旧版不可逆 Apply 流程产生的历史记录不会被自动 Finish 或 Discard。
+
+详细边界与恢复设计见 [Domi 到 Harness 的迁移说明](docs/PORTING.md) 和 [Worktree Console 架构](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)。
+
+## 本地开发
+
+安装依赖并运行标准检查：
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run check:publish
+```
+
+端到端启动本地 Harness：
+
+```bash
+pnpm run dev:dsh
+```
+
+该命令会构建当前 checkout，将其打成临时本地 tarball，安装到 `web` profile，验证组合配置，准备受 marker 保护的临时 Git fixture，并默认在 `http://127.0.0.1:3081` 启动 `dsh web`。它不会发布 npm 包，也不会 push Git refs。
+
+常用变体：
+
+```bash
+# 只安装并验证当前快照，不启动 Web
+pnpm run dev:dsh:install
+
+# 验证已经安装的 profile
+pnpm run dev:dsh:smoke
+
+# 使用现有 Git 根目录、其他端口或其他 profile
+pnpm run dev:dsh -- --repo G:/path/to/repo --port 4090 --profile web
+
+# 移除开发安装和缓存的本地归档
+pnpm run dev:dsh:remove
+```
+
+如果发现附近的 DeepSeek Harness 源码 checkout，`dev:dsh` 会优先选择已经安装 `node_modules/tsx`、可直接运行的候选；源码位于任意其他目录时，可以通过 `DSH_HARNESS_ROOT` 或 `--harness <path>` 指定。选择源码 checkout 后，插件安装、配置验证、移除和 Web 启动都会使用该源码 CLI，不再要求全局安装 `dsh`；显式指定的 checkout 尚未安装依赖时，脚本会在构建前提示对应的 `pnpm --dir <path> install` 命令。只有未选择源码 checkout 时才回退到 PATH 中的 `dsh`。
+
+## 当前限制
+
+- 暂无跨项目全局侧栏 Manager。
+- 项目级 Worktree Console 实现仍保留，但 `v0.3.0` 暂不挂载可见的 `conversation.view` 标签页，当前优先稳定主流程。
+- 在已验证的 Harness `0.1.0-rc.6` 包线中，Workflow `agent({ isolation })` 集成尚不可用。
+- 在该 Harness 包线中，子 Agent 继承父 Session cwd；只有父 Session 已经是 Worktree Session 时才处于隔离环境。
+- dependency snapshot/restore 和完整 collaborator handoff UI 尚未实现。
+- 选择立即清理后，隔离 cwd 会被删除，该 Session 随即进入终态；后续应回到 Local 或开始新一轮任务。
+
+## 文档
+
+- [Domi 到 Harness 的迁移说明](docs/PORTING.md)
+- [Worktree Console 架构](docs/WORKTREE-CONSOLE-ARCHITECTURE.md)
+- [UI 开发说明](docs/UI-DEVELOPMENT.md)
+- [发布清单](docs/RELEASE.md)
+- [变更记录](CHANGELOG.md)
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -1,7 +1,7 @@
-# dsh-git-worktree bundle patch: one insert over the profile root, adding the
-# plugin row. Later profile layers and the user's own cordis.patch.yml address
-# this row by id; the last write wins per row.
-
-- insert:
-    - id: dsh-git-worktree
-      name: dsh-git-worktree
+# dsh-git-worktree bundle patch: one insert over the profile root, adding the
+# plugin row. Later profile layers and the user's own cordis.patch.yml address
+# this row by id; the last write wins per row.
+
+- insert:
+    - id: dsh-git-worktree
+      name: dsh-git-worktree

package/lib/adapters/lookup.d.ts

@@ -2,7 +2,9 @@
  * DSH lookup adapter: maps sessions and projects onto the harness's
  * `workspaceRegistry` service (retrieved dynamically, like the ecosystem's
  * plugins, because the published package version lags the rc.6 runtime). A
- * session's project is found by scanning workspace session accounts; a
+ * session's project is found by scanning workspace session accounts; when a
+ * cleaned immutable cwd makes Harness filter a still-live Session from that
+ * projection, the immutable live header may restore the exact mapping. A
  * project record maps to a workspace's `id`/`title`/`path`. Missing service or
  * records degrade to `undefined`, which the state machine treats as
  * recovery/orphan facts rather than failures.
@@ -24,5 +26,5 @@ export interface WorkspaceRegistryLike {
     create(path: string, title?: string): Promise<WorkspaceLike>;
     delete(id: string): Promise<boolean>;
 }
-/** Build the lookup port over the harness workspace registry (absent → all lookups miss). */
+/** Build the lookup port over Harness workspace and live-session projections. */
 export declare function createDshLookupPort(ctx: Context): SessionCheckoutLookupPort;