@cerbur/clutch-dsh-worktree 0.1.8 → 0.1.10

package/README.md

@@ -23,7 +23,7 @@ the adjacent Import tab, and a standard dropdown containing safe example branch/
 - Search Workspaces and create a Git Worktree and branch from an existing local branch.
 - Choose Import in the same dialog to discover unmanaged, branch-attached Git Worktrees linked to the Workspace repository. The first version omits the repository root and detached HEAD entries.
 - Register an existing Worktree in place without moving, copying, or editing its directory; the imported record uses `source: external` and then follows the same Session, binding, health, ordering, cwd, projection, refresh, and recovery flow as a plugin-created record.
-- Remove plugin-created and imported Worktrees through real `git worktree remove`; removing an imported Worktree can delete its linked directory and is called out in the confirmation dialog.
+- Archive Worktrees non-destructively (`status: removed`), preserving disk files, active bindings, and runtime cwd. Disk cleanup (`git worktree remove`) requires secondary confirmation: users must confirm all Sessions, subagents, and other tasks using the directory have stopped. Worktrees can also be forgotten from plugin management while retaining disk files and Sessions.
 - Create a normal Session from Main or a Session whose runtime cwd is an active Worktree, then
   open it directly.
 - For active Worktree Sessions, request the named `worktree-full-access` preset after an
@@ -53,7 +53,7 @@ the adjacent Import tab, and a standard dropdown containing safe example branch/
   Main/Local. A sidecar failure keeps the child available and exposes retryable binding recovery.
 - See ready, repair, active, and detached Worktree states, including retryable operation errors.
 - Use the shared Main and Worktree row options menu to copy the selected row's absolute path.
-  Main and detached rows show only `Copy path`; active Worktree rows also show `Remove Worktree`
+  Main and detached rows show only `Copy path`; active Worktree rows also show `Archive Worktree`
   with confirmation.
 - Create a new Worktree from the Local or an active Worktree's options menu. The Create dialog
   uses the selected row's current branch as its base and suggests the next available numbered
@@ -62,6 +62,7 @@ the adjacent Import tab, and a standard dropdown containing safe example branch/
   be reordered within their owning Workspace; order is stored in the plugin sidecar and Main is
   fixed first.
 - Persist Workspace, Main, and Worktree expansion choices in browser-local storage; the five-row Session overflow state remains transient and resets after refresh or parent collapse.
+- Provide a Collapse All button in the Worktree Header to collapse all Workspaces and Worktrees at once.
 - Highlight the DSH current Session in Worktree view; entering Worktree mode or switching the current Session temporarily reveals its Workspace/Main/Worktree path, expands Session overflow only when the row is outside the first five, clears a hiding search, and scrolls the row into view; this browser-local behavior does not change persisted expansion choices.
 - Keep the current local branch or Worktree branch visible as read-only context in the existing
   Conversation title row and in the blank-session Hero.
@@ -80,22 +81,14 @@ the adjacent Import tab, and a standard dropdown containing safe example branch/
 
 ### Compatibility and prerequisites
 
-- For development and source validation, use a clean checkout of the official [DeepSeek Harness
-  repository](https://github.com/deepseek-ai/deepseek-harness) on its current default branch. The
-  repository currently uses `master` rather than `main`; it is developer-preview software, so its
-  package and API contracts may change. Run the upstream install/build steps before installing
-  this plugin into that profile.
-- The target profile, such as `web` or `demo`, must already start successfully, and the plugin
-  must be installed into the same profile that launches the Web UI.
-- DSH Client must provide the native `@deepseek-ai/dsh-client-ui-conversation` package and its
-  `conversation.session.header.actions` seat.
-- Git must be installed and available on `PATH` for Worktree operations. A Workspace must be
-  inside a Git repository with an initial commit and at least one local branch. A missing Git
-  executable shows install guidance and no command block; a missing repository, initial commit,
-  or local branch shows copyable setup commands. The plugin does not run setup or installation
-  commands or modify Workspace files.
-- The package declares an installable `dsh.bundle` and provides `cordis.patch.yml`; its browser
-  UI is declared through the `dsh.client` metadata.
+The supported compatibility facts are:
+
+| Component | Min Version | Notes |
+| --- | --- | --- |
+| DSH Client | `>=0.1.2-rc.1` | Requires the Session/Workspace Controllers and Client Store |
+| DSH Host | `>=0.1.2-rc.1` | Requires the Typert Gateway `/api` protocol and subprocess capability |
+| Git | `>=2.20.0` | Requires worktree core commands and branch discovery |
+| Node.js | `>=20.0.0` | LTS is recommended |
 
 ## Installation
 
@@ -131,12 +124,13 @@ npm view @cerbur/clutch-dsh-worktree version --registry=https://registry.npmjs.o
 
 For source-based development or validation, prepare the upstream checkout first. The current
 upstream default branch is `master`; follow the repository's default branch if it changes later.
+For the minimum rc.1 compatibility validation path, check out `dsh-v0.1.2-rc.1`:
 
 ```bash
 git clone https://github.com/deepseek-ai/deepseek-harness.git
 cd deepseek-harness
 git fetch origin
-git pull --ff-only origin master
+git checkout dsh-v0.1.2-rc.1
 pnpm install
 pnpm run build
 ```
@@ -232,6 +226,13 @@ blank-session Hero. The displayed language follows DSH's current language settin
 
 ### Create a Worktree
 
+New directories use `$dshHome/clutch-dsh-worktree/worktree/wt_<12-hex-characters>`
+(15 characters in the folder name, with 48 bits of cryptographic randomness).
+Occupied directory names, Git registrations, and sidecar identities are automatically retried.
+After eight random candidates collide, numeric suffixes such as `_1` and `_2` are tried until
+available or cancelled. Existing Worktree paths and IDs stay unchanged; branch conflicts and
+other Git failures retain their normal error handling.
+
 1. Select a Workspace, press its `+`, choose a baseline local branch, and enter a Worktree name.
    The default branch name is `dsh/<8-character-random-string>`.
 2. To create a sibling from an existing Worktree, open that active Worktree's options menu and
@@ -239,8 +240,8 @@ blank-session Hero. The displayed language follows DSH's current language settin
    chooses the next available numeric suffix for the name; existing names are skipped.
 3. The target Worktree path must be absolute, belong to the same Project, and differ from the
    Project root. Relative paths, a different Project, or the Project root are rejected.
-4. Git must be installed and available on `PATH`. A missing Git executable shows install guidance
-   and no command block; install Git, restart DSH, and retry. If the repository, initial commit,
+4. Git must be installed and available on `PATH`. A missing Git executable shows install guidance and no command block;
+   install Git, restart DSH, and retry. If the repository, initial commit,
    or local branch is missing, follow the copyable setup commands in the dialog. The plugin only
    renders this guidance; it does not run setup or installation commands or edit business files.
 
@@ -249,7 +250,10 @@ blank-session Hero. The displayed language follows DSH's current language settin
 1. Select a Workspace, press its `+`, and choose the `Import` tab. The dialog loads Git-linked
    Worktrees for that repository through the existing DSH `/api` Connection.
 2. The first version lists only branch-attached, non-root Worktrees that are not already present
-   in the plugin sidecar. Detached HEAD entries are intentionally omitted. Candidates are presented
+   in the plugin sidecar. Detached HEAD, bare, prunable, missing-directory and missing-`.git`
+   entries are omitted. Managed health and import eligibility share one runtime status mapping;
+   importing rechecks that status. Locked Worktrees remain eligible when otherwise ready.
+   Candidates are presented
    in a standard dropdown; each option shows its branch first and absolute path as secondary
    diagnostic text.
 3. Choose an option and select `Import Worktree`. Registration writes only the plugin sidecar;
@@ -265,9 +269,10 @@ blank-session Hero. The displayed language follows DSH's current language settin
 
 - Use Main's `+` to create a normal DSH Session in the Project-root view.
 - Use a Worktree's `+` to create or reuse a Session with that Worktree as its runtime cwd. The
-  plugin calls the upstream runtime with `session.create({ cwd: worktreePath })`, then saves the
-  external binding and opens the Session. The browser-local `{ workspaceId, sessionId }` membership
-  projection is refreshed afterward, so the newly created Session does not briefly appear in Main.
+  plugin calls the DSH Session Controller with `ctx.sessions.create({ cwd: worktreePath })`, then
+  saves the external binding and opens the Session. The browser-local `{ workspaceId, sessionId }`
+  membership projection is refreshed afterward, so the newly created Session does not briefly
+  appear in Main.
 - The connector reuses an unarchived blank Session with the exact target cwd when possible. An
   already-bound Session opens directly; an unbound candidate is bound before projection and
   opening. Otherwise the new-Session flow is `create → bind → open → refresh`, and concurrent
@@ -325,19 +330,43 @@ blank-session Hero. The displayed language follows DSH's current language settin
 
 - Drag Worktrees within their owning Workspace. The ordered `worktrees` array is persisted in
   the plugin sidecar; Main is a fixed first row and Worktrees cannot move across Workspaces.
-- Open the shared Main and Worktree options menu to copy the selected row's absolute path. Main
-  and detached/removed Worktrees show only `Copy path`; active Worktrees also show `Remove
-  Worktree` with a confirmation dialog.
-- Imported Worktrees expose the same active options menu as plugin-created Worktrees. Removing
-  either source runs real `git worktree remove`; for an imported Worktree, the confirmation warns
-  that the linked Worktree directory may be deleted. Sessions are retained as detached bindings.
-- Removing a Worktree does not delete its Sessions. The relationship remains detached until it
-  is explicitly unbound. Deleting a Workspace removes only DSH's Workspace registration; its
-  directory, Sessions, Git Worktrees, and plugin sidecar remain.
-- After a successful removal, detached Sessions that still have Full Access are normalized to
-  `workspace-write + ask` when the public DSH permission service is available. An unavailable
-  service is reported as an unverified, retryable warning; it never grants Full Access to a
-  detached Session.
+- Newly created or imported Worktrees are inserted at the head of their Workspace's Worktree list; existing Worktree order is preserved and Main remains fixed first.
+- Open the shared Main and Worktree options menu to copy the selected row's absolute path. Active
+  Worktrees show `Copy path` and `Archive Worktree`. Archiving an active Worktree is an internal
+  archive operation: it sets `status: removed`, preserves disk files, active bindings, and runtime cwd,
+  and moves the Worktree into the default-collapsed `Archived` group at the bottom of the Workspace.
+- The `Archived` group is rendered at the bottom of the Workspace when archived Worktrees exist and is
+  collapsed by default. Its label includes the total archived Worktree count, even when collapsed.
+  Each Workspace tracks its own collapsed state independently.
+- Active Worktrees with `health: repair` also offer `Archive Worktree` to archive the record without
+  touching disk files or bindings. `recovery-needed` still blocks removal pending recovery.
+- For archived Worktrees whose disk has not been cleaned, the options menu provides:
+  1. `Unarchive Worktree`: Restores a metadata-archived Worktree whose disk directory is intact back to active status, without secondary confirmation.
+  2. `Clean Up Disk`: Prompts for secondary confirmation detailing the path and irreversible deletion,
+     tells you that the plugin does not check Session or subagent activity and requires you to confirm
+     that all tasks using the directory have stopped (otherwise deletion may cause task failures or data loss),
+     runs real non-forced `git worktree remove`, and upon success records
+     `diskCleanup: completed`, projects health as `cleaned`, transitions bindings to detached, and
+     normalizes Full Access permissions to `workspace-write + ask`. Disk removal commitment is decoupled
+     from permission normalization: once disk removal commits, the dialog closes and the record updates to
+     `cleaned`; any follow-up permission or refresh failure provides independent retry without re-executing disk removal.
+     Use `Retry` in the permission notice to retry only permission normalization for the cleaned Worktree.
+     If the Worktree directory or its `.git` entry was already deleted externally, confirming cleanup only marks
+     the plugin record as completed and detaches its bindings. It does not run Git removal or prune
+     stale Git registration. Any remaining directory and files are preserved. The completed status
+     reads `Worktree removed`, which does not imply residual files were deleted. Ordinary refreshes still show
+     missing directories as `repair` until cleanup is explicitly confirmed.
+  3. `Remove from Management`: Prompts for confirmation and removes the Worktree sidecar record and all
+     its bindings, while preserving disk files and native DSH Sessions. It retires in-flight fork operations,
+     recovery state, and permission notices for that Worktree. No Session activity check is required.
+- For archived Worktrees whose disk has already been cleaned (`health: cleaned`), the menu provides
+  `Remove from Management` to prune the sidecar record completely.
+- Session activity is informational and does not block cleanup or removal from management.
+  The default Host may report `unknown`. Before confirming disk cleanup, stop all tasks using
+  the directory yourself; the plugin does not verify that they have stopped. Native activity
+  changes and reopening the archived menu refresh its owning Workspace while retaining ready content.
+- Deleting a Workspace removes only DSH's Workspace registration; its directory, Sessions, Git Worktrees,
+  and plugin sidecar remain.
 - DSH-native Workspace rename/delete/reorder and Session menus remain available. Session drag
   ordering is limited to the current visual Main or Worktree group.
 - The Main group shows the current local branch as `Local (branch)` and falls back to `Local` if
@@ -352,13 +381,54 @@ blank-session Hero. The displayed language follows DSH's current language settin
 - When the Sidebar is collapsed, the footer keeps its icon-only native action geometry; the plugin
   does not render a separate `WT` rail control.
 
+### Reconcile a branch changed in Git
+
+After an external `git checkout`, the next Worktree read shows `old branch → current branch`
+and a branch-change warning. Reads occur on refresh and when opening a Worktree menu; the
+plugin does not watch Git continuously. Detached HEAD is shown explicitly. Session bindings
+and runtime cwd remain unchanged, and normal branch changes do not lock the Workspace.
+
+Choose `Adopt current branch` from the active or archived Worktree menu and confirm the
+displayed transition. This updates only the plugin's recorded branch. A changed branch or
+stale snapshot during confirmation is rejected; refresh and confirm again. Detached HEAD
+must first be switched to a branch in Git. Disk cleanup requires adopting the current branch
+first. Creating a Worktree on the old branch is allowed when Git proves the existing record
+has switched away; genuinely checked-out branches remain unavailable.
+
+Confirmation failures appear inside the dialog. Choose `Retry` to reload the observed branch
+and snapshot token, then confirm the updated transition; the old confirmation stays disabled
+until refresh succeeds. If the Worktree is no longer branch-drifted or has entered detached HEAD,
+the dialog closes. Creating a sibling Worktree uses the observed current branch, even before
+adoption; detached HEAD does not offer this action.
+
+For `recovery-needed`, the Worktree menu offers `Retry recovery` for its Workspace.
+This retries safe journal recovery; it does not adopt branches, delete unknown paths, or
+clear unresolved identity issues. Successful adoption and recovery refresh only the owning
+Workspace while preserving existing ready content. Legacy non-transactional branch observations
+are retired automatically; there is no need to edit sidecar JSON for ordinary checkout drift.
+
 ### Understand status and recovery messages
 
-- `ready` means the Worktree is available. `repair` identifies a missing or invalid Worktree,
-  Session, binding, or cwd. `recovery-needed` means a Git/sidecar operation or identity check is
-  unresolved and destructive actions are blocked. `detached` means the Git Worktree was removed
-  while the relationship was retained. An active binding pointing to a missing Worktree produces
+- Operation, permission, binding, and refresh failures use DSH's native toast, one at a time.
+  Unchanged errors are not repeated on every render. Full messages and existing Retry/Open
+  actions remain in the expandable Notification details and recovery entry after the toast fades.
+  Form validation and Workspace Git setup guidance remain next to their inputs.
+- Hover or focus an active Worktree row to see its status, path, and repair guidance for missing
+  directories/Git registration, branch drift/detached HEAD, or incomplete recovery. Opening its
+  menu or dragging suppresses the hover card. Archive confirmation explicitly preserves the
+  directory, Session bindings, and cwd for both plugin-created and external Worktrees;
+  Clean Disk remains a separate action.
+
+- `ready` means the Worktree is available. `cleaned` indicates disk cleanup completed while the
+  sidecar archive entry is retained. `repair` identifies a missing or invalid Worktree, Session, binding,
+  or cwd. `recovery-needed` means a Git/sidecar operation or identity check is unresolved and
+  destructive actions are blocked. `detached` means the Git Worktree was removed while the relationship
+  was retained. An active binding pointing to a missing Worktree produces
   an explicit repair warning or error; it never silently falls back to another Worktree.
+- Without a pending Git transaction, missing active or archived Worktrees remain `repair` and
+  can be archived without blocking healthy Worktree Session bindings. Legacy non-transactional
+  `WORKTREE_RECOVERY_REQUIRED` observations for existing, uncleaned records are retired under
+  the sidecar lock; pending transactions, unknown records, and identity-change issues still block.
 - Worktree health is a runtime Git projection and is not written to the sidecar. Git readiness
   failures are shown per Workspace: a missing Git executable shows installation guidance without
   commands, while repository, initial commit, or local branch failures show copyable setup
@@ -400,9 +470,10 @@ store a copy of `projectRoot` or any Session content. If the sidecar is unavaila
 the native Project/Session view remains readable and the plugin becomes degraded/read-only; an
 empty index must never overwrite the native DSH lists.
 
-The sidecar accepts v1 and v2 snapshots for backwards-compatible reads. Legacy records are
-normalized in memory, and the first successful mutation atomically upgrades the shard to v3.
-New v3 snapshots use a revision, an opaque repository fingerprint, and durable pending-operation
+The sidecar accepts v1, v2, and v3 snapshots for backwards-compatible reads. Legacy records are
+normalized in memory, and the first successful mutation atomically upgrades the shard to v4.
+Legacy removed records become `diskCleanup: completed`; v3 revisions are preserved.
+New v4 snapshots use a revision, an opaque repository fingerprint, and durable pending-operation
 metadata for Git create/remove. A transitional v3 snapshot containing an older raw repository
 field is read and cleaned on its next stable write. Invalid JSON, unknown schema versions, and
 invariant violations are reported as corruption rather than reset to an empty index.
@@ -430,7 +501,7 @@ it retains the marker and surfaces `WORKTREE_RECOVERY_REQUIRED` or
 also carry an opaque mutation token from the latest Worktree projection so a stale UI cannot act
 on a changed record.
 
-The Worktree session flow sends the independent Worktree cwd through the upstream DSH runtime and
+The Worktree session flow sends the independent Worktree cwd through the DSH Session Controller and
 keeps `{ workspaceId, sessionId }` as a browser-local membership projection rather than a
 persistent DSH attach. It does not modify DSH source, Session metadata, or native Workspace
 storage. The projection is replayed after native list refreshes and removed when the binding

package/README.zh.md

@@ -23,7 +23,7 @@ Session 元数据、原生列表和会话历史的唯一事实来源。插件只
 - 搜索 Workspace，并从已有 local branch 创建 Git Worktree 和 branch。
 - 在同一个弹窗中选择导入，发现与当前 Workspace repository 关联、尚未由 sidecar 管理且绑定 branch 的 Git Worktree。第一版不展示 repository root 和 detached HEAD 条目。
 - 导入只登记已有 Worktree，不移动、复制或编辑其目录；记录使用 `source: external`，之后与 plugin 创建的记录共享 Session、binding、health、排序、cwd、projection、刷新和恢复流程。
-- plugin 创建和导入的 Worktree 都通过真实的 `git worktree remove` 移除；移除导入的 Worktree 可能删除其关联目录，确认弹窗会明确提示。
+- 非破坏性归档 Worktree（`status: removed`），保留磁盘文件、活动 binding 与运行时 cwd。磁盘清理（`git worktree remove`）需经二次确认，由用户自行确认使用该目录的 Session/子代理与其他任务已停止；亦支持移出插件管理并保留磁盘文件与 Session。
 - 在 Main 或 active Worktree 下创建普通 Session 或 Worktree Session，并直接打开新会话。
 - 对 active Worktree Session，先经明确确认，再请求命名的 `worktree-full-access` 预设。它将
   DSH 的 `danger-full-access` 与 `ask` 组合：关闭关联 Git 元数据的文件系统限制，但保留
@@ -48,13 +48,14 @@ Session 元数据、原生列表和会话历史的唯一事实来源。插件只
   binding 恢复操作。
 - 查看 ready、repair、active 和 detached Worktree 状态，包括可重试的操作错误。
 - 通过 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径；Main 和 detached 行只显示“复制路径”，
-  active Worktree 额外显示“移除 Worktree”并要求确认。
+  active Worktree 额外显示“归档 Worktree”并要求确认。
 - 通过 Local 或 active Worktree 的选项菜单创建新的 Worktree。创建弹窗会以所选行的当前 branch
   为基线，并预填下一个可用的递增名称，例如 `feature-2` 或 `feature-3`；detached Worktree
   不显示该动作。
 - 继续使用 DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单。Worktree 可以在所属
   Workspace 内排序；顺序保存在插件 sidecar 中，Main 固定在第一位。
 - 将 Workspace、Main 和 Worktree 的展开选择保存到浏览器本地存储；Session 五行溢出展开保持临时状态，并在刷新或父级折叠后重置。
+- 在 Worktree Header 提供「全部折叠」按钮，支持一键折叠所有 Workspace 与 Worktree。
 - 在 Worktree view 高亮 DSH 当前 Session；进入 Worktree 模式或切换当前会话时，临时展开其 Workspace/Main/Worktree 路径；只有当前行不在前五行时才展开 Session 五行溢出，随后清空隐藏它的搜索并滚动定位；这一浏览器本地行为不改变已保存的展开选择。
 - 在已有 Conversation 的标题行以及新会话空白 Hero 中，以只读方式显示当前 local branch 或
   Worktree branch 上下文。
@@ -71,20 +72,14 @@ Session 元数据、原生列表和会话历史的唯一事实来源。插件只
 
 ### 兼容性与前置条件
 
-- 开发和源码验证应使用官方 [DeepSeek Harness 仓库](https://github.com/deepseek-ai/deepseek-harness)
-  的干净 checkout，并跟随仓库当前默认分支。该仓库当前使用 `master` 而不是 `main`，且仍是
-  developer preview，package 和 API contract 可能变化；在向 profile 安装本 plugin 前，先完成
-  upstream 的安装和构建步骤。
-- 目标 profile（例如 `web` 或 `demo`）必须已经可以正常启动，且 plugin 必须安装到实际
-  启动 Web UI 的同一个 profile。
-- DSH Client 必须提供原生 `@deepseek-ai/dsh-client-ui-conversation` package 及其
-  `conversation.session.header.actions` seat。
-- Worktree 操作要求 Git 已安装且可在 PATH 中使用。Workspace 必须位于 Git repository 中，
-  且至少有一个初始 commit 和本地 branch。Git 可执行文件缺失时显示安装提示且不显示命令块；
-  缺少 repository、初始 commit 或本地 branch 时显示可复制的 setup 命令。插件不会执行 setup
-  或安装命令，也不会修改 Workspace 文件。
-- package 声明了可安装的 `dsh.bundle` 并提供 `cordis.patch.yml`；浏览器 UI 通过
-  `dsh.client` metadata 声明。
+兼容性事实表如下：
+
+| 组件 / Component | 最低版本 / Min Version | 说明 / Notes |
+| --- | --- | --- |
+| DSH Client | `>=0.1.2-rc.1` | 依赖 Session/Workspace Controller 及 Client Store |
+| DSH Host | `>=0.1.2-rc.1` | 依赖 Typert Gateway `/api` 协议与 subprocess capability |
+| Git | `>=2.20.0` | 要求支持 worktree 核心命令与 branch 发现 |
+| Node.js | `>=20.0.0` | 推荐使用 LTS 版本 |
 
 ## 安装
 
@@ -118,13 +113,14 @@ npm view @cerbur/clutch-dsh-worktree version --registry=https://registry.npmjs.o
 ### 准备当前 upstream DSH checkout
 
 进行源码开发或验证时，先准备 upstream checkout。当前 upstream 默认分支是 `master`；如果仓库
-未来切换默认分支，应跟随仓库的当前默认分支。
+未来切换默认分支，应跟随仓库的当前默认分支。最小 rc.1 兼容性验证路径切换到
+`dsh-v0.1.2-rc.1`：
 
 ```bash
 git clone https://github.com/deepseek-ai/deepseek-harness.git
 cd deepseek-harness
 git fetch origin
-git pull --ff-only origin master
+git checkout dsh-v0.1.2-rc.1
 pnpm install
 pnpm run build
 ```
@@ -217,6 +213,12 @@ pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 
 ### 创建 Worktree
 
+新目录使用 `$dshHome/clutch-dsh-worktree/worktree/wt_<12-hex-characters>`
+（文件夹名为 15 个字符，包含 48 位加密随机数）。
+目录名、Git 登记或 sidecar 身份已被占用时自动换名重试；八个随机候选均冲突后，
+依次尝试 `_1`、`_2` 等数字后缀，直到找到可用名称或取消。
+已有 Worktree 的路径和 ID 保持不变；分支冲突与其他 Git 失败沿用原有错误处理。
+
 1. 选择 Workspace，点击它旁边的 `+`，选择基线 local branch，并填写 Worktree name。默认
    branch 名称为 `dsh/<8-character-random-string>`。
 2. 如果要从已有 Worktree 创建同级 Worktree，打开该 active Worktree 的选项菜单并选择
@@ -234,7 +236,10 @@ pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 1. 选择 Workspace，点击旁边的 `+`，再选择 `导入` Tab。弹窗通过现有 DSH `/api` Connection
    加载该 repository 的 Git Worktree 候选项。
 2. 第一版只列出绑定 branch、不是 repository root、且未出现在 plugin sidecar 中的 Worktree。
-   detached HEAD 会被省略；候选项通过普通下拉框选择，每个选项先显示 branch，再显示绝对路径
+   detached HEAD、bare、prunable、目录缺失和 `.git` 缺失的条目会被省略。
+   已管理 Worktree 的 health 与导入资格共用运行时状态映射，提交导入时重新校验；
+   locked Worktree 在其他条件满足时仍可导入。
+   候选项通过普通下拉框选择，每个选项先显示 branch，再显示绝对路径
    作为诊断信息。
 3. 在下拉框中选择一个选项并点击 `导入 Worktree`。登记只写入 plugin sidecar，已有 Worktree 目录和 Git
    工作状态保持不变。随后会在该 Worktree cwd 创建或复用 Session，并执行与创建相同的
@@ -247,10 +252,10 @@ pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 ### 创建 Main 和 Worktree Session
 
 - 使用 Main 的 `+`，在 Project 根目录视角中创建普通 DSH Session。
-- 使用 Worktree 的 `+`，创建或复用 runtime cwd 指向该 Worktree 的 Session。插件通过 upstream
-  runtime 调用 `session.create({ cwd: worktreePath })`，随后保存外部 binding 并打开该 Session。
-  当前浏览器内的 `{ workspaceId, sessionId }` membership projection 会在之后刷新，因此新建
-  Session 不会短暂出现在 Main 中。
+- 使用 Worktree 的 `+`，创建或复用 runtime cwd 指向该 Worktree 的 Session。插件通过 DSH
+  Session Controller 调用 `ctx.sessions.create({ cwd: worktreePath })`，随后保存外部 binding
+  并打开该 Session。当前浏览器内的 `{ workspaceId, sessionId }` membership projection 会在
+  之后刷新，因此新建 Session 不会短暂出现在 Main 中。
 - 如果存在目标 cwd 完全匹配的未归档 blank Session，连接器会优先复用它。已绑定的 Session
   会直接打开；未绑定的候选会先 binding，再 projection 和打开。否则执行
   新建路径执行 `create → bind → open → refresh`，同一个 Worktree 的并发点击会合并。
@@ -298,17 +303,27 @@ pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 
 - 在所属 Workspace 内拖动 Worktree。排序持久化在 plugin sidecar 的有序 `worktrees` 数组中；
   Main 是固定的第一行，Worktree 不能跨 Workspace 移动。
-- 打开 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径。Main 和 detached/removed Worktree
-  只显示“复制路径”；active Worktree 还显示“移除 Worktree”并要求确认。
-- 导入的 Worktree 与 plugin 创建的 Worktree 显示相同的 active 选项菜单。两种来源都执行真实
-  `git worktree remove`；导入项的确认文案会警告关联 Worktree 目录可能被删除。Session 会
-  保留为 detached binding。
-- 移除 Worktree 不会删除其 Session。关系会保留为 detached，直到显式解绑。删除 Workspace
-  只会删除 DSH 的 Workspace registration；其目录、Session、Git Worktree 和 plugin
-  sidecar 会保留。
-- Worktree 成功移除后，如果公共 DSH 权限服务可用，仍处于完全访问的 detached Session 会
-  归一化为 `workspace-write + ask`。权限服务不可用时显示未验证且可重试的警告；不会向
-  detached Session 自动授予完全访问。
+- 新创建或新导入的 Worktree 会插入所属 Workspace 的 Worktree 列表队头；已有 Worktree 顺序保持不变，Main 固定在第一位。
+- 打开 Main 和 Worktree 共用的选项菜单复制所选行的绝对路径。active Worktree 提供“复制路径”与
+  “归档 Worktree”。归档 active Worktree 属于内部归档操作：将其标记为 `status: removed`，完整保留
+  磁盘目录、关联 binding 与运行时 cwd，并将该 Worktree 沉底移动到工作区底部的“已归档”（Archived）分组中。
+- 工作区底部在存在已归档 Worktree 时渲染“已归档”分组，默认处于折叠状态；标题显示已归档 Worktree 总数，收起时仍然显示。每个 Workspace 维护独立的折叠状态。
+- `health: repair` 的 active Worktree 也提供“归档 Worktree”，仅归档记录，保留磁盘文件和 binding。`recovery-needed` 状态仍须先处理恢复问题，不能归档。
+- 对于未清理磁盘的已归档 Worktree，选项菜单提供：
+  1. “取消归档”（Unarchive Worktree）：对于仅元数据标记归档且磁盘未清理的 Worktree，可直接在菜单中点击取消归档，无需二次确认弹窗，立即恢复为活跃状态。
+  2. “清理磁盘”（Clean Up Disk）：弹出二次确认弹窗（明确提示工作树路径与破坏性删除不可逆），告知插件不核验 Session/子代理活动，
+     请用户自行确认使用该目录的任务均已停止，否则删除可能导致任务失败或数据丢失；执行真正的非强制 `git worktree remove`，
+     成功后记录 `diskCleanup: completed`，运行时健康状态投影为 `cleaned`，关联 binding 转为 detached，并将完全访问权限
+     归一化为 `workspace-write + ask`。磁盘清理提交与权限后续解耦：清理成功即确认提交、关闭对话框并将状态转为 `cleaned`；
+     权限归一化失败或刷新异常提供独立恢复，不重复执行磁盘删除。
+     点击权限提示中的“重试”（Retry），仅重试该已清理 Worktree 的权限归一化。
+     如果 Worktree 目录或其 `.git` 入口已在外部删除，确认清理只将插件记录标记为完成并将 binding 转为 detached，
+     不再执行 Git 删除，也不清理残留 Git registration。剩余目录和文件完整保留，完成状态显示
+     “Worktree 已移除”，不代表剩余文件已被删除。普通刷新仍显示 `repair`，直到用户显式确认清理。
+  3. “移出管理”（Remove from Management）：弹出确认弹窗，删除该 Worktree 的 sidecar 记录与全部关联 binding，完整保留
+     磁盘文件与 DSH 原生 Session；同时定向淘汰该 Worktree 的未决 fork 恢复、投影与权限提示。不需要校验 Session 活动。
+- 对于已清理磁盘的 Worktree（`health: cleaned`），选项菜单提供“移出管理”以从 sidecar 中彻底移除该记录。
+- 删除 Workspace 只会删除 DSH 的 Workspace registration；其目录、Session、Git Worktree 和 plugin sidecar 会保留。
 - DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单继续可用。Session 拖动排序
   限定在当前视觉 Main 或 Worktree 分组中。
 - Main 分组显示当前 local branch：有分支时为 `本地（branch）`，DSH 没有返回当前分支时
@@ -322,11 +337,43 @@ pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
 - Sidebar 折叠后，footer 保留原生的 icon-only action 尺寸和排版；插件不会再绘制独立的
   `WT` rail control。
 
+### 同步在 Git 中切换的分支
+
+外部执行 `git checkout` 后，下次 Worktree 读取显示“旧分支 → 当前分支”与分支变化提示。
+刷新或打开 Worktree 菜单时会读取，插件不持续监听 Git。分离 HEAD 会明确标注。
+Session binding 和运行时 cwd 保持不变，普通分支切换不会锁住整个 Workspace。
+
+在活动或归档 Worktree 菜单中选择“采用当前分支”（`Adopt current branch`）并确认，
+只更新插件记录的分支。确认期间 Git 分支或快照已变化时会拒绝操作，请刷新后重新确认。
+分离 HEAD 必须先在 Git 中切换到分支；清理磁盘前必须先采用当前分支。
+Git 明确证明原记录已切走时，允许用空闲的旧分支创建 Worktree；真正被 checkout 的分支仍不可用。
+
+确认失败会在弹窗内显示错误。点击“重试”（`Retry`）重新读取当前分支和快照 token，
+再确认更新后的分支变化；刷新成功前不能再次提交旧确认。如果 Worktree 已不再处于
+分支漂移状态或进入分离 HEAD，弹窗会关闭。从该行创建新 Worktree 使用读到的当前分支，
+无需先采用分支；分离 HEAD 不提供此操作。
+
+`recovery-needed` 行的菜单提供“重试恢复”（`Retry recovery`），作用于所属 Workspace。
+该操作只重试安全 journal 恢复，不自动采用分支、不删除未知路径、不清除未解决的身份问题。
+采用分支和恢复成功后只刷新所属 Workspace，并保留现有 ready 内容。
+旧版非事务分支观察标记会自动淘汰，普通 checkout 漂移不需要手工编辑 sidecar JSON。
+
 ### 理解状态与恢复提示
 
-- `ready` 表示 Worktree 可用。`repair` 表示 Worktree、Session、binding 或 cwd 缺失/无效。
-  `recovery-needed` 表示 Git/sidecar 操作或身份校验尚未解决，破坏性操作会被阻止。
-  `detached` 表示 Git Worktree 已被移除，但关系仍然保留。active binding 指向缺失
+- 操作、权限、绑定和刷新失败统一使用 DSH 原生 toast，逐条显示；相同错误不会随每次渲染重复提示。
+  toast 消失后，完整信息及原有重试/打开操作仍保留在可展开的“提示详情与恢复操作”入口。
+  表单校验和 Workspace Git 初始化指引保留在对应输入附近。
+- 悬停或聚焦 active Worktree 行可查看状态、路径以及目录/Git 登记缺失、分支漂移/分离 HEAD、
+  恢复未完成的处理指引。打开菜单或拖动时不显示 hover 卡片。归档确认明确说明插件创建及外部
+  Worktree 都保留目录、Session 绑定和 cwd；“清理磁盘”仍是独立操作。
+
+- 没有未完成 Git 事务时，目录缺失的 active 或 archived Worktree 保持 `repair`，可归档，
+  不会阻断健康 Worktree 的 Session 绑定。指向现有且未清理记录的旧版无事务
+  `WORKTREE_RECOVERY_REQUIRED` 观察标记在 sidecar 锁内淘汰；未完成事务、未知记录和身份变化问题仍然阻断操作。
+
+- `ready` 表示 Worktree 可用。`cleaned` 表示磁盘清理已完成且保留 sidecar 归档条目。
+  `repair` 表示 Worktree、Session、binding 或 cwd 缺失/无效。`recovery-needed` 表示 Git/sidecar
+  操作或身份校验尚未解决，破坏性操作会被阻止。`detached` 表示 Git Worktree 已被移除，但关系仍然保留。active binding 指向缺失
   Worktree 时会显示明确的 repair 警告或错误，不会静默切换到其他 Worktree。
 - Worktree health 是 Git 的运行时 projection，不写入 sidecar。Git 前置条件失败按
   Workspace 显示提示：Git 可执行文件缺失时显示安装提示且不显示命令块，缺少 repository、
@@ -363,8 +410,13 @@ DSH 管理原始 Project/Workspace 身份和根目录、Session 身份和元数
 Session 内容。如果 sidecar 不可用或损坏，原生 Project/Session 视角仍然可读，插件进入
 degraded/read-only 状态；不能用空索引覆盖 DSH 原生列表。
 
-sidecar 兼容读取 v1 和 v2 snapshot。旧记录会先在内存中归一化，第一次成功 mutation 会
-以原子方式将 shard 升级为 v3。新的 v3 snapshot 使用 revision、不可逆向还原的 repository
+Session 活动仅用于信息展示，不阻断磁盘清理或移出管理；默认 Host 仍可能显示 `unknown`。
+确认磁盘清理前，请自行停止所有使用该目录的任务，插件不会核验任务是否已停止。
+原生活动变化或重新打开归档菜单会刷新所属 Workspace 并保留 ready 内容。
+
+sidecar 兼容读取 v1、v2 和 v3 snapshot。旧记录会先在内存中归一化，第一次成功 mutation 会
+以原子方式将 shard 升级为 v4。旧 removed 记录归一化为 `diskCleanup: completed`，保留 v3 revision。
+新的 v4 snapshot 使用 revision、不可逆向还原的 repository
 fingerprint，以及为 Git create/remove 保存的 durable pending-operation metadata。早期 v3
 实现可能写入的 raw repository 字段也可以读取，并会在下一次稳定写入时清理。无效 JSON、
 未知 schema version 和关系不变量错误都会报告为 corruption，不会静默重置为空索引。
@@ -388,7 +440,7 @@ Host 启动时，插件会针对已知 DSH Workspace 执行一次尽力而为的
 状态。破坏性操作还可以携带最新 Worktree projection 生成的 opaque mutation token，避免
 过期 UI 对已变化的记录执行操作。
 
-Worktree Session 流程将独立的 Worktree cwd 交给 upstream DSH runtime，并将
+Worktree Session 流程将独立的 Worktree cwd 交给 DSH Session Controller，并将
 `{ workspaceId, sessionId }` 保持为浏览器本地 membership projection，而不是持久化的 DSH
 attach。它不会修改 DSH 源码、Session metadata 或原生 Workspace 存储。native list 刷新后会
 重放 projection；binding 消失或 Client dispose 时会移除 projection。

package/lib/client/WorktreeSurface.d.ts

@@ -1,8 +1,5 @@
-import type { WorktreeSurfaceProps } from './worktree-surface-types.js';
-export type { WorktreeSurfaceInjected, WorktreeSurfaceProps } from './worktree-surface-types.js';
-/**
- * Peer Worktree navigation surface. It keeps the original DSH Workspace mode
- * intact and renders a browser-local Workspace → Worktree → Session projection.
- */
-export declare function WorktreeSurface({ useStore, actions, useSessions, useWorkspaces, t, available, expandState, sessionOrder, manager, permission, confirmFullAccess, fullAccessConfirmation, onPermissionResult, onPermissionNotice, permissionNotice, invalidateWorktreeContext, createWorkspace, createSessionForWorktree: createSessionCallback, createMainSession, renameWorkspace, deleteWorkspace, insertWorkspaceBefore, insertSessionBefore, insertWorktreeBefore, renameSession, forkSession, archiveSession, forkRecovery, retryForkSession, ensureSessionWorkspace, syncSessionWorkspaces, openSession, }: WorktreeSurfaceProps): import("react").JSX.Element | null;
+import type { WorktreeSurfaceProps } from './surface/types.js';
+export type { WorktreeSurfaceInjected, WorktreeSurfaceProps } from './surface/types.js';
+/** Composes independent surface state/action domains into the sidebar overlay. */
+export declare function WorktreeSurface(props: WorktreeSurfaceProps): import("react").JSX.Element | null;
 //# sourceMappingURL=WorktreeSurface.d.ts.map

package/lib/client/WorktreeSurface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorktreeSurface.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeSurface.tsx"],"names":[],"mappings":"AAiEA,OAAO,KAAK,EAQV,oBAAoB,EASrB,MAAM,6BAA6B,CAAC;AA6BrC,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAoEjG;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAO,EACP,WAAW,EACX,aAAa,EACb,CAAC,EACD,SAAS,EACT,WAAW,EACX,YAAY,EACZ,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,EACzB,eAAe,EACf,wBAAwB,EAAE,qBAAqB,EAC/C,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,GACZ,EAAE,oBAAoB,sCA4uDtB"}
+{"version":3,"file":"WorktreeSurface.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeSurface.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,sCAuF1D"}