@cerbur/clutch-dsh-worktree 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (177) hide show
  1. package/README.md +105 -33
  2. package/README.zh.md +92 -29
  3. package/lib/client/WorktreeSurface.d.ts.map +1 -1
  4. package/lib/client/WorktreeSurface.js +37 -10
  5. package/lib/client/WorktreeSurface.js.map +1 -1
  6. package/lib/client/branch/GitBranchSelector.d.ts +23 -0
  7. package/lib/client/branch/GitBranchSelector.d.ts.map +1 -0
  8. package/lib/client/branch/GitBranchSelector.js +142 -0
  9. package/lib/client/branch/GitBranchSelector.js.map +1 -0
  10. package/lib/client/context/worktree-context-store.d.ts.map +1 -1
  11. package/lib/client/context/worktree-context-store.js +1 -0
  12. package/lib/client/context/worktree-context-store.js.map +1 -1
  13. package/lib/client/context/worktree-context.d.ts +3 -2
  14. package/lib/client/context/worktree-context.d.ts.map +1 -1
  15. package/lib/client/context/worktree-context.js +5 -3
  16. package/lib/client/context/worktree-context.js.map +1 -1
  17. package/lib/client/dashboard/WorktreeDashboard.d.ts +4 -1
  18. package/lib/client/dashboard/WorktreeDashboard.d.ts.map +1 -1
  19. package/lib/client/dashboard/WorktreeDashboard.js +67 -69
  20. package/lib/client/dashboard/WorktreeDashboard.js.map +1 -1
  21. package/lib/client/dashboard/dashboard-selection.d.ts +4 -3
  22. package/lib/client/dashboard/dashboard-selection.d.ts.map +1 -1
  23. package/lib/client/dashboard/dashboard-selection.js +6 -4
  24. package/lib/client/dashboard/dashboard-selection.js.map +1 -1
  25. package/lib/client/dashboard/git/GitChangedFiles.d.ts +2 -1
  26. package/lib/client/dashboard/git/GitChangedFiles.d.ts.map +1 -1
  27. package/lib/client/dashboard/git/GitChangedFiles.js +8 -6
  28. package/lib/client/dashboard/git/GitChangedFiles.js.map +1 -1
  29. package/lib/client/dashboard/git/GitCommitList.d.ts +6 -1
  30. package/lib/client/dashboard/git/GitCommitList.d.ts.map +1 -1
  31. package/lib/client/dashboard/git/GitCommitList.js +34 -29
  32. package/lib/client/dashboard/git/GitCommitList.js.map +1 -1
  33. package/lib/client/dashboard/git/GitCommitStats.d.ts +8 -0
  34. package/lib/client/dashboard/git/GitCommitStats.d.ts.map +1 -0
  35. package/lib/client/dashboard/git/GitCommitStats.js +7 -0
  36. package/lib/client/dashboard/git/GitCommitStats.js.map +1 -0
  37. package/lib/client/dashboard/git/WorktreeGitOverview.d.ts.map +1 -1
  38. package/lib/client/dashboard/git/WorktreeGitOverview.js +2 -1
  39. package/lib/client/dashboard/git/WorktreeGitOverview.js.map +1 -1
  40. package/lib/client/dashboard/git/WorktreeGitPanel.d.ts +1 -1
  41. package/lib/client/dashboard/git/WorktreeGitPanel.d.ts.map +1 -1
  42. package/lib/client/dashboard/git/WorktreeGitPanel.js +28 -9
  43. package/lib/client/dashboard/git/WorktreeGitPanel.js.map +1 -1
  44. package/lib/client/dashboard/git/file-address.d.ts +5 -2
  45. package/lib/client/dashboard/git/file-address.d.ts.map +1 -1
  46. package/lib/client/dashboard/git/file-address.js +50 -7
  47. package/lib/client/dashboard/git/file-address.js.map +1 -1
  48. package/lib/client/dashboard/git/git-facts.js +1 -1
  49. package/lib/client/dashboard/git/git-facts.js.map +1 -1
  50. package/lib/client/dashboard/git/useWorktreeGitState.d.ts +7 -2
  51. package/lib/client/dashboard/git/useWorktreeGitState.d.ts.map +1 -1
  52. package/lib/client/dashboard/git/useWorktreeGitState.js +84 -21
  53. package/lib/client/dashboard/git/useWorktreeGitState.js.map +1 -1
  54. package/lib/client/dsh-icons.d.ts +2 -0
  55. package/lib/client/dsh-icons.d.ts.map +1 -1
  56. package/lib/client/dsh-icons.js +2 -0
  57. package/lib/client/dsh-icons.js.map +1 -1
  58. package/lib/client/locales.d.ts +40 -2
  59. package/lib/client/locales.d.ts.map +1 -1
  60. package/lib/client/locales.js +46 -8
  61. package/lib/client/locales.js.map +1 -1
  62. package/lib/client/select/SearchableSingleSelect.d.ts +44 -0
  63. package/lib/client/select/SearchableSingleSelect.d.ts.map +1 -0
  64. package/lib/client/select/SearchableSingleSelect.js +180 -0
  65. package/lib/client/select/SearchableSingleSelect.js.map +1 -0
  66. package/lib/client/select/WorktreeSelector.d.ts +14 -0
  67. package/lib/client/select/WorktreeSelector.d.ts.map +1 -0
  68. package/lib/client/select/WorktreeSelector.js +11 -0
  69. package/lib/client/select/WorktreeSelector.js.map +1 -0
  70. package/lib/client/surface/actions/useLifecycleActions.js +1 -1
  71. package/lib/client/surface/actions/useLifecycleActions.js.map +1 -1
  72. package/lib/client/surface/actions/useWorktreeRegistration.d.ts +1 -1
  73. package/lib/client/surface/actions/useWorktreeRegistration.d.ts.map +1 -1
  74. package/lib/client/surface/actions/useWorktreeRegistration.js +32 -11
  75. package/lib/client/surface/actions/useWorktreeRegistration.js.map +1 -1
  76. package/lib/client/surface/components/RegistrationDialog.d.ts +3 -3
  77. package/lib/client/surface/components/RegistrationDialog.d.ts.map +1 -1
  78. package/lib/client/surface/components/RegistrationDialog.js +70 -5
  79. package/lib/client/surface/components/RegistrationDialog.js.map +1 -1
  80. package/lib/client/surface/components/WorkspaceTree.d.ts.map +1 -1
  81. package/lib/client/surface/components/WorkspaceTree.js +11 -8
  82. package/lib/client/surface/components/WorkspaceTree.js.map +1 -1
  83. package/lib/client/surface/components/dialogs.d.ts +1 -1
  84. package/lib/client/surface/components/dialogs.d.ts.map +1 -1
  85. package/lib/client/surface/components/dialogs.js +24 -15
  86. package/lib/client/surface/components/dialogs.js.map +1 -1
  87. package/lib/client/surface/state/useRegistrationState.d.ts +6 -1
  88. package/lib/client/surface/state/useRegistrationState.d.ts.map +1 -1
  89. package/lib/client/surface/state/useRegistrationState.js +7 -0
  90. package/lib/client/surface/state/useRegistrationState.js.map +1 -1
  91. package/lib/client/surface/types.d.ts +5 -1
  92. package/lib/client/surface/types.d.ts.map +1 -1
  93. package/lib/client/view/worktree-error-copy.d.ts.map +1 -1
  94. package/lib/client/view/worktree-error-copy.js +4 -0
  95. package/lib/client/view/worktree-error-copy.js.map +1 -1
  96. package/lib/client/view/worktree-view-read.d.ts +4 -2
  97. package/lib/client/view/worktree-view-read.d.ts.map +1 -1
  98. package/lib/client/view/worktree-view-read.js +34 -17
  99. package/lib/client/view/worktree-view-read.js.map +1 -1
  100. package/lib/client/worktree-connection.d.ts +3 -0
  101. package/lib/client/worktree-connection.d.ts.map +1 -1
  102. package/lib/client/worktree-connection.js +18 -1
  103. package/lib/client/worktree-connection.js.map +1 -1
  104. package/lib/client.js +1386 -434
  105. package/lib/client.js.map +1 -1
  106. package/lib/contract/index.contract.js +15 -0
  107. package/lib/contract/index.contract.js.map +1 -1
  108. package/lib/contract/index.d.ts +69 -12
  109. package/lib/contract/index.d.ts.map +1 -1
  110. package/lib/contract/index.js +3 -0
  111. package/lib/contract/index.js.map +1 -1
  112. package/lib/host/remote.d.ts.map +1 -1
  113. package/lib/host/remote.js +7 -0
  114. package/lib/host/remote.js.map +1 -1
  115. package/lib/host/service.d.ts +13 -6
  116. package/lib/host/service.d.ts.map +1 -1
  117. package/lib/host/service.js +18 -0
  118. package/lib/host/service.js.map +1 -1
  119. package/lib/manage/manager-git-history.d.ts +5 -7
  120. package/lib/manage/manager-git-history.d.ts.map +1 -1
  121. package/lib/manage/manager-git-history.js +158 -65
  122. package/lib/manage/manager-git-history.js.map +1 -1
  123. package/lib/manage/manager-git-paths.d.ts +7 -0
  124. package/lib/manage/manager-git-paths.d.ts.map +1 -0
  125. package/lib/manage/manager-git-paths.js +62 -0
  126. package/lib/manage/manager-git-paths.js.map +1 -0
  127. package/lib/manage/manager-worktrees.d.ts +9 -1
  128. package/lib/manage/manager-worktrees.d.ts.map +1 -1
  129. package/lib/manage/manager-worktrees.js +69 -14
  130. package/lib/manage/manager-worktrees.js.map +1 -1
  131. package/lib/manage/manager.d.ts +12 -5
  132. package/lib/manage/manager.d.ts.map +1 -1
  133. package/lib/manage/manager.js +64 -3
  134. package/lib/manage/manager.js.map +1 -1
  135. package/lib/provider/git/adapter.d.ts +13 -12
  136. package/lib/provider/git/adapter.d.ts.map +1 -1
  137. package/lib/provider/git/adapter.js +152 -29
  138. package/lib/provider/git/adapter.js.map +1 -1
  139. package/lib/provider/git/branch-name.d.ts +5 -0
  140. package/lib/provider/git/branch-name.d.ts.map +1 -0
  141. package/lib/provider/git/branch-name.js +16 -0
  142. package/lib/provider/git/branch-name.js.map +1 -0
  143. package/lib/provider/git/branches.d.ts +11 -0
  144. package/lib/provider/git/branches.d.ts.map +1 -0
  145. package/lib/provider/git/branches.js +37 -0
  146. package/lib/provider/git/branches.js.map +1 -0
  147. package/lib/provider/sidecar/repository.d.ts.map +1 -1
  148. package/lib/provider/sidecar/repository.js +2 -1
  149. package/lib/provider/sidecar/repository.js.map +1 -1
  150. package/lib/provider/sidecar/sidecar-schema.d.ts.map +1 -1
  151. package/lib/provider/sidecar/sidecar-schema.js +2 -0
  152. package/lib/provider/sidecar/sidecar-schema.js.map +1 -1
  153. package/lib/provider/transaction/operations/create.d.ts.map +1 -1
  154. package/lib/provider/transaction/operations/create.js +18 -6
  155. package/lib/provider/transaction/operations/create.js.map +1 -1
  156. package/lib/provider/transaction/recovery/failure-recovery.d.ts.map +1 -1
  157. package/lib/provider/transaction/recovery/failure-recovery.js +3 -2
  158. package/lib/provider/transaction/recovery/failure-recovery.js.map +1 -1
  159. package/lib/provider/transaction/recovery/recover.d.ts.map +1 -1
  160. package/lib/provider/transaction/recovery/recover.js +8 -5
  161. package/lib/provider/transaction/recovery/recover.js.map +1 -1
  162. package/lib/provider/transaction/support/journal.d.ts.map +1 -1
  163. package/lib/provider/transaction/support/journal.js +1 -0
  164. package/lib/provider/transaction/support/journal.js.map +1 -1
  165. package/lib/provider/types.d.ts +24 -4
  166. package/lib/provider/types.d.ts.map +1 -1
  167. package/lib/provider/types.js.map +1 -1
  168. package/lib/tool/list-worktrees.d.ts.map +1 -1
  169. package/lib/tool/list-worktrees.js +9 -2
  170. package/lib/tool/list-worktrees.js.map +1 -1
  171. package/lib/tool/new-worktree.js +2 -2
  172. package/lib/tool/new-worktree.js.map +1 -1
  173. package/lib/typert.host.js +216 -46
  174. package/lib/typert.remote-client.d.ts +11 -5
  175. package/lib/typert.remote-client.d.ts.map +1 -1
  176. package/lib/typert.remote-client.js +216 -46
  177. package/package.json +4 -2
package/README.md CHANGED
@@ -8,8 +8,8 @@ Workspace identity, Session metadata, native lists, messages, and conversation h
8
8
 
9
9
  Tool preferences are stored in separate Host-owned files, outside relationship indexes and native
10
10
  Session metadata. The plugin stores Worktree relationships, acquisition facts, shared Worktree instructions, and Workspace-root
11
- Main instructions in its own sidecar. Managed Worktrees expose a read-only baseline-relative Git & Changes dashboard, while Main exposes
12
- its Workspace-root HEAD history; the plugin does not copy transcripts or rewrite DSH Sessions.
11
+ Main instructions in its own sidecar. Managed Worktrees expose a read-only baseline-relative Git & Changes dashboard, while Local/Main exposes
12
+ its Workspace-root HEAD history with an optional comparison branch; the plugin does not copy transcripts or rewrite DSH Sessions.
13
13
 
14
14
  > **Preview:** Worktree Dashboard is an early, plugin-only MVP preview. Worktree navigation, lifecycle actions,
15
15
  > Session actions, Worktree/Main instructions, and the managed Worktree or Main Git & Changes view are connected.
@@ -60,6 +60,17 @@ pnpm dsh web
60
60
  The DSH Web profile must be able to start before this plugin is added. Re-run the absolute-path
61
61
  install command after changing `package.json` or `cordis.patch.yml`.
62
62
 
63
+ For Desktop, fully quit DeepSeek Harness after active tasks finish, then use the installed DSH CLI:
64
+
65
+ ```bash
66
+ dsh plugin --profile desktop add /absolute/path/to/clutch-dsh/packages/clutch-dsh-worktree
67
+ ```
68
+
69
+ Reopen Desktop after installation. Keep the local checkout and its installed `node_modules`
70
+ available while it is linked; copying only `lib/` or removing the checkout's dependencies can
71
+ cause the Host and permission-preset entries to fail to import. Client implementation dependencies
72
+ are bundled during the build, so Desktop does not need separate Zustand or Immer modules.
73
+
63
74
  ### Install from GitHub source (optional)
64
75
 
65
76
  The package also supports the source dependency form used by the DSH plugin market:
@@ -76,7 +87,7 @@ development details, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
76
87
  | Feature | Preview | What it does |
77
88
  | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
89
  | **Worktree navigation** | <img src="assets/screenshots/screenshots-en.png" width="420" alt="DSH Worktree navigation with Workspace, Main, Worktree, and Session rows"> | Adds a Worktree mode to the native DSH Sidebar. On macOS desktop, the panel shares DSH's native glass material without a second background layer or duplicate navigation showing through. Other platforms retain the theme fill; reduced transparency uses a stronger fill. Workspace expansion and new Session rows use native-style fades and movement. Browse each Workspace through Local/Main and Git Worktree rows, then open the Sessions bound to each row. |
79
- | **Create and import Worktrees** | <img src="assets/screenshots/screenshots-import.png" width="420" alt="Worktree create and import dialog"> | Create a Worktree from a local branch, or register an existing branch-attached Worktree in place. Import does not move, copy, or edit the existing directory. |
90
+ | **Create and import Worktrees** | <img src="assets/screenshots/screenshots-import.png" width="420" alt="Worktree create and import dialog"> | Create a Worktree from a local or fetched remote branch, or register an existing branch-attached Worktree in place. Import does not move, copy, or edit the existing directory. |
80
91
  | **Worktree Dashboard** | <img src="assets/screenshots/screenshots-dashboard.png" width="420" alt="Worktree Dashboard preview with Sessions and Worktree actions"> | The preview Dashboard shows Worktree identity, path, Sessions, Worktree/Main instructions, connected actions, the host-provided Open In action, and the read-only Git & Changes view for managed Worktrees or Main. Derived Worktrees and other unfinished cards remain **Coming soon**. |
81
92
  | **Agent tool settings (Experimental)** | <img src="assets/screenshots/screenshots-worktree-tool.png" width="420" alt="Worktree tool settings preview"> | Choose capabilities for `/cluworktree` in General, and independently configure automatic injection in Local/Main and managed Worktree Dashboards. Delegated Sessions receive result reporting only by default. |
82
93
 
@@ -117,11 +128,51 @@ New Worktree actions use the same branch icon as Worktree rows. The Workspace ro
117
128
  on hover, keyboard focus, or while its options menu is open, matching the menu button.
118
129
 
119
130
  1. Open the options menu for Local/Main or an active Worktree and choose **Create Worktree**.
120
- 2. Choose the local base branch. You can also provide a new branch name.
131
+ 2. Choose a local or fetched remote base branch and a new local branch name. The dialog suggests an available name.
121
132
  3. Confirm the dialog. The plugin creates the Git Worktree, records its acquisition facts, and
122
133
  continues through the normal Session and binding flow when you open a Session from that Worktree.
123
134
 
124
- Git must have a usable repository, local branch, and initial commit. If setup is incomplete, DSH
135
+ The Create and Import tabs share aligned, full-width controls and consistent spacing between fields.
136
+
137
+ Creation, saved baselines, and Git comparison use the same searchable selector, grouped into **Local branches**
138
+ and **Remote branches**, with current/checked-out markers and filters for all, local, or remote branches.
139
+ Dropdowns use DSH’s native menu material in light and dark themes.
140
+ Dropdown lists are compact and prefer opening below the field, shrinking to available space with internal scrolling;
141
+ they open above only when there is too little useful space below.
142
+ Search ignores case; use Arrow Up/Down to move, Enter to choose, and Escape to close. Clicking within the dropdown keeps it open, including headings,
143
+ empty space, search, filters, and fetch controls; selecting an option or clicking outside closes it.
144
+ Branch and import selectors open immediately while candidates load, show a loading indicator inside,
145
+ and update in place when data arrives. Search and filters stay intact; refreshes keep existing rows visible.
146
+ Closing and reopening the baseline editor discards pending results from the previous dialog.
147
+ Only the latest branch read or Fetch can update its candidates and loading state.
148
+ Even with cached candidates, the dropdown paints its compact loading shell before preparing the list.
149
+ The initial shell and loading state keep the same height; ready results size to their content within the scrolling limit.
150
+ Large lists render only rows near the viewport; search, filters, and keyboard selection still cover every candidate.
151
+ Switching between **Create** and **Import** replaces the form content in the same dialog without replaying its opening animation.
152
+ Opening any branch selector rereads local Git refs, including changes made in a terminal. Returning to
153
+ the browser does not reload candidates. Fetch reads the updated list once and supplies it directly to the selector.
154
+ Opening the New Worktree dialog does not preload branches; its default comes from the current branch or HEAD.
155
+ The full branch list is loaded only when a picker opens or Fetch completes. Workspace navigation
156
+ reads Git readiness and the current root-checkout branch separately; entering Git & Changes loads history without preloading branches.
157
+ The current local branch is preferred by default. Remote refs are read
158
+ from the local repository. Use the download-arrow button beside **Remote branches** to fetch all configured
159
+ remotes, including when the remote list is empty. Fetch updates remote branch refs and refreshes this Workspace;
160
+ it preserves your current selection, local branches, tags and working files, and does not prune deleted refs.
161
+ The button shows a loading icon during fetch, then displays **Remote branches updated** in place for two
162
+ seconds before restoring the download icon. Failures retain the list and show a retry on the same button;
163
+ the button details retain the error code, message, and diagnostics, also available in **Errors & Repair**.
164
+ no extra status row is added beneath the list.
165
+ Listing branches never contacts a remote automatically.
166
+ Remote baselines require a new local branch when creating a Worktree; its short name may match the remote baseline
167
+ when that local branch does not exist. Symbolic remote HEAD entries are excluded.
168
+
169
+ Git must have a usable repository and initial commit. Choose a local branch, or choose **HEAD** to
170
+ create a new branch from Main's current checkout, including an exact Tag or detached Commit.
171
+ The localized HEAD option includes the current reference name, for example **HEAD (v1.0.0)**.
172
+ Creation uses the commit shown when selected. If HEAD changes before submission, creation is rejected
173
+ with `WORKTREE_STATE_CONFLICT`; refresh the dialog and select the source again.
174
+ Main displays the current branch, exact Tag, or short Commit and retains its creation action when detached.
175
+ If setup is incomplete, DSH
125
176
  shows the relevant readiness message and copyable setup guidance.
126
177
 
127
178
  When the Workspace is a repository subdirectory, its Worktrees preserve that relative directory.
@@ -134,8 +185,8 @@ Already-bound Sessions with a legacy Git-root cwd remain usable after a subdirec
134
185
  including automatic tool injection, Session discovery, follow-ups, result reports and default
135
186
  Worktree creation from their own checkout's HEAD. Their original cwd and history remain unchanged;
136
187
  new Session bindings still require the Workspace directory inside the checkout. Git file previews use
137
- relative addresses inside the current Session cwd and absolute addresses for other checkout files,
138
- subject to DSH's native file-access checks.
188
+ relative addresses inside the target Session cwd. Files outside that cwd show a prompt to use an IDE
189
+ or a Session at the repository root; already-bound Git-root Sessions keep their original preview scope.
139
190
 
140
191
  ### Enable Agent Worktree tools
141
192
 
@@ -175,8 +226,8 @@ The six selectable capabilities correspond to these tools:
175
226
 
176
227
  | Tool | Parameters | Behavior |
177
228
  | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
178
- | `clutch_new_worktree` | `name`, optional `baseBranch`, `instructions` | Creates a new branch from the calling Session's healthy Worktree branch; Local/Main uses the root checkout's current branch. An explicit local `baseBranch` overrides this. Returns the acquisition `baseBranch` and `baseCommit`. |
179
- | `clutch_list_worktrees` | optional `workspaceId` | Lists managed Worktree ids, branches, paths, lifecycle and health, plus available local base branches. Defaults to the calling Workspace. |
229
+ | `clutch_new_worktree` | `name`, optional `baseBranch`, `instructions` | Creates a new branch from the calling Session's healthy Worktree branch; Local/Main uses the root checkout's current branch. An explicit local or fetched remote `baseBranch` overrides this. Returns the acquisition `baseBranch` and `baseCommit`. |
230
+ | `clutch_list_worktrees` | optional `workspaceId` | Lists managed Worktree ids, branches, paths, lifecycle and health, plus available local and fetched remote base branches. Defaults to the calling Workspace. |
180
231
  | `clutch_span_worktree` | `worktreeId` or legacy `name`, `prompt`, optional `model`, `title` | Creates a fresh native Session, binds it, configures its initial model and submits the prompt. Returns its `sessionId` and admission status. |
181
232
  | `clutch_list_models` | optional `provider` | Lists native provider/model routes, reasoning efforts and provider failures, alongside the current Session model and deployment default. |
182
233
  | `clutch_list_sessions` | optional `workspaceId`, `worktreeId` | Finds existing Sessions, binding state, status and title. Unavailable relations return a diagnostic without reading their history. |
@@ -189,7 +240,7 @@ within the calling Workspace; prefer stable `worktreeId` for dispatch. Creating
189
240
  Only committed state is inherited; staged, unstaged and untracked files are not copied.
190
241
  An unhealthy binding never silently falls back to Main. The default captures the calling checkout's
191
242
  committed HEAD, including a detached root HEAD. Detached sources return `baseCommit` without inventing
192
- a `baseBranch`; an explicit local `baseBranch` remains available as an override.
243
+ a `baseBranch`; an explicit local or fetched remote `baseBranch` remains available as an override.
193
244
 
194
245
  Newly delegated Sessions automatically receive only
195
246
  `clutch_report_result({ status, summary, evidence?, requestId? })`. The Host fixes the destination
@@ -264,13 +315,13 @@ a resumed Session can enable `/cluworktree` and use `clutch_send_message` with a
264
315
  ### Import an existing Worktree
265
316
 
266
317
  1. Select a Workspace, open its branch-icon **New Worktree** action, and switch to **Import**.
267
- 2. Choose a candidate from the branch-and-path list.
318
+ 2. Open the searchable Worktree selector and filter by branch name or path. Each candidate shows its branch and directory; choose the Worktree to import.
268
319
  3. Select **Import Worktree**. The plugin registers the existing directory without moving,
269
320
  copying, or changing its files, then uses the same Session flow as a created Worktree.
270
321
 
271
322
  The first version lists only ready, branch-attached, non-root Git Worktrees that are not already
272
323
  managed by the plugin. Detached, bare, prunable, missing, and invalid entries are omitted. Imported
273
- Worktrees can still use Git & Changes after you choose a local baseline branch.
324
+ Worktrees can still use Git & Changes after you choose a local or fetched remote baseline branch.
274
325
 
275
326
  Import uses the same Workspace-relative directory rule and offers only candidates where that
276
327
  directory is available. Existing records are projected with the corrected path when the original
@@ -336,18 +387,22 @@ existing VS Code protocol-link fallback.
336
387
 
337
388
  Open the **Git & Changes** tab from a managed Worktree or Main Dashboard. Main reads the current Workspace-root
338
389
  commit history directly and prepends an **Uncommitted changes** entry when the root has tracked, staged, unstaged, or
339
- untracked changes. It shows at most the first 200 committed commits, selects the first visible target, and uses the same
390
+ untracked changes. Its baseline selector defaults to **None**, showing HEAD history without a total commit count.
391
+ Choose a local or fetched remote comparison branch to show Baseline summary, the full comparison commit count,
392
+ and ahead/behind facts. Selecting **None** returns to direct history. These choices stay in page memory.
393
+ Direct history selects the first visible target and uses the same
340
394
  changed-file and diff panes for either a live working-tree target or a committed history entry. For a managed Worktree with a
341
395
  persisted `baseBranch` that differs from the current branch, or with a captured acquisition commit that
342
396
  supplies the implicit baseline, the Overview performs one compact, on-demand Git status read through the
343
397
  existing `/api` Connection. It shows ahead/behind commit counts plus separate
344
398
  committed (baseline-to-HEAD) and uncommitted (live working-tree) line totals; this is an ephemeral
345
- projection, not a watcher or a Worktree-record field. Main has no Worktree baseline comparison, so Overview remains
399
+ projection, not a watcher or a Worktree-record field. Local/Main's comparison is a transient Git-tab choice, so Overview remains
346
400
  **Not connected** for ahead/behind facts while its Git tab still exposes Main history. Unavailable or baseline-unselected
347
- managed views honestly remain **Not connected**. Opening Overview does not load the branch list; the first Git tab
348
- activation loads local branches and, once a baseline is resolved, managed Worktree commit history. To replace that baseline, click the pencil icon beside the Base fact to open the branch
401
+ managed views honestly remain **Not connected**. Opening Overview does not load the branch list; mounting the Git tab
402
+ reads history against the saved branch or captured acquisition commit. Branch candidates load only when a
403
+ selector opens; Fetch supplies its returned candidates directly. To replace that baseline, click the pencil icon beside the Base fact to open the branch
349
404
  picker: its search field sits permanently above a bounded branch list that shows roughly seven rows and
350
- scrolls internally, so the dialog keeps one size while you filter. Choose any local branch except the
405
+ scrolls internally, so the dialog keeps one size while you filter. Choose any local or fetched remote branch except the
351
406
  current Worktree branch and save.
352
407
  The save replaces the persisted `baseBranch` in the plugin sidecar; the saved value becomes the default for
353
408
  the Git selector. Once the Git tab is open, changing its selector remains a transient view choice and reloads
@@ -356,19 +411,22 @@ history, changed files, and diffs without another Worktree-record write. If no u
356
411
  immutable captured acquisition commit and show that resolved commit as the Base fact; only a Worktree with
357
412
  neither a usable saved baseline nor a captured commit stays baseline-unselected and prompts you to choose
358
413
  one. When the selected branch has diverged, Git resolves the two heads' common ancestor. The
359
- Git & Changes view reports Worktree commits after that ancestor as `+N` ahead and base-branch commits after it
360
- as `-N` behind; history and file reads remain available. If the two heads have no common ancestor, the
414
+ Git & Changes view reports Worktree commits after that ancestor as `↑ N` ahead and base-branch commits after it
415
+ as `↓ N` behind; history and file reads remain available. If the two heads have no common ancestor, the
361
416
  committed summary falls back to the full tree diff between the base branch tip and Worktree `HEAD`, while
362
417
  history uses the Worktree commits not reachable from that base tip.
363
418
  With a valid managed Worktree baseline loaded, the Git & Changes tab initially selects **Baseline summary** rather than the
364
419
  first commit; changing the baseline branch also returns to that summary. Choose a commit or **Uncommitted
365
- changes** when you need a narrower target. Main skips this comparison-only summary but presents the same committed history and multi-commit selection behavior, plus a live working-tree target when the
420
+ changes** when you need a narrower target. Local/Main with **None** skips this comparison-only summary but presents the same committed history and multi-commit selection behavior, plus a live working-tree target when the
366
421
  Workspace root has changes. Selecting **Uncommitted changes** compares the current Workspace root with `HEAD`; it does not
367
422
  create a baseline or write any Git state.
368
423
 
369
- The selected local branch is resolved again for each read. The browser can choose only a plain local branch
370
- name, not a raw commit SHA or arbitrary Git ref: a full ref path, tag, or remote-tracking ref is rejected
371
- outright, while a selected branch that no longer exists shows the honest unavailable state instead of a
424
+ The selected local or fetched remote branch is resolved again for each read. Selectors display short names and
425
+ use the enumerated `refs/heads/...` or `refs/remotes/...` as stable identities. New remote baseline saves retain
426
+ the exact remote ref, so adding or removing a same-named local branch cannot change the baseline.
427
+ Legacy short names are accepted only when unambiguous; an ambiguous saved value reports
428
+ `WORKTREE_STATE_CONFLICT` and requires selecting the intended branch again. Raw commit SHAs, tags, and
429
+ arbitrary revision expressions remain rejected. A selected exact branch that no longer exists shows the honest unavailable state instead of a
372
430
  generic Git failure. `baseCommit` is immutable acquisition metadata, is never user-selectable directly, and
373
431
  is the implicit baseline whenever no saved branch baseline is usable; creation recovery never overwrites
374
432
  it. When a managed Worktree or Main Workspace root has staged, unstaged, or untracked files, the list prepends an
@@ -382,18 +440,32 @@ one net diff from the same comparison boundary to the current working tree, incl
382
440
  unstaged, untracked, deleted, and renamed changes. This is a
383
441
  fresh on-demand projection rather than a concatenation of two diffs. Clicking a commit shows that
384
442
  commit's own diff. For managed Worktrees and Main, turn on **Multi-select commits** in the commits header to pick several committed rows
385
- and view the exact union of their first-parent deltas; Main has no baseline-summary or working-tree-inclusion controls, and the switch is off by default; turning it off
443
+ and view the exact union of their first-parent deltas; Local/Main with **None** has no baseline-summary or working-tree-inclusion controls, and the switch is off by default; turning it off
386
444
  collapses the selection back to the focused commit. The changed-file list
387
445
  records the contributing commits, and each selected commit is rendered as its own diff segment; this is
388
446
  not an implicit range and does not include unselected commits. The changed-files column header shows the
389
447
  aggregate green `+N` and red `-N` totals for the current target, including the Baseline summary, selected
390
448
  commits, or Uncommitted changes; binary-only totals show Unknown. The working-tree entry remains mutually
391
- exclusive with committed multi-selection. The **Open in Sidebar** action in the summary diff toolbar
392
- reveals the current file in the native right sidebar using the current Session, only when that Session
393
- belongs to the Dashboard Worktree. An empty Worktree
394
- or an unrelated current Session cannot open a file through this action.
395
-
396
- Managed Worktree and Main history are each capped at 200 commits and mark longer histories as truncated. A changed-file list larger
449
+ exclusive with committed multi-selection. **Open in Sidebar** is available in the diff toolbar and on
450
+ existing changed-file rows. It uses the current Session when it belongs to the Dashboard group,
451
+ otherwise the group's first visible Session, and explicitly expands the native right sidebar.
452
+ With no target Session it prompts you to create one; the Overview's empty Session card includes **New Session**.
453
+ File-tree paths, Diff titles and file requests are relative to the Workspace directory, for both Main and
454
+ managed Worktrees. At `/repo/packages/app`, `src/index.ts` names `/repo/packages/app/src/index.ts`;
455
+ repository-root `README.md` appears as `../../README.md`. The view retains changes across the checkout.
456
+ Files outside the target Session cwd show a prompt instead of an invalid resource address.
457
+
458
+ Main shows a local checkout status and omits derived Worktree creation-time and baseline facts.
459
+ Ahead/Behind uses neutral commit counts (`↑ N` / `↓ N`), while added/deleted code lines keep their green/red counts.
460
+ The sticky top bar truncates long references on one line, and only the reference text copies to the clipboard.
461
+
462
+ Managed Worktree and Local/Main history load the newest 50 commits first. Scrolling to the bottom appends
463
+ the next 50 without replacing the current selection or diff; the load-more button also supports keyboard use.
464
+ Comparison views show the full committed total from ahead counts, independent of loaded pages.
465
+ If HEAD or the baseline moves between pages, refresh before continuing; existing rows remain visible.
466
+ The load-more button becomes **Refresh** after this conflict. Commit file and Diff reads also require
467
+ a stable HEAD throughout authorization and reading.
468
+ Multi-selection supports up to 200 selected commits. A changed-file list larger
397
469
  than the Git adapter's output bound reports an explicit truncated state instead of a generic error.
398
470
  Commit details use
399
471
  first-parent comparisons; root commits compare against the empty tree; rename and copy rows retain
@@ -419,7 +491,7 @@ and refresh behavior remains unchanged.
419
491
 
420
492
  The view is read-only and does not provide commit or staging controls. For managed Worktrees, the plugin validates committed
421
493
  entries against the selected branch-to-`HEAD` projection and re-reads working-tree paths against a fresh status projection;
422
- Main validates committed entries against its bounded HEAD-history projection. These endpoints are not generic Git object or file readers. Refresh keeps ready
494
+ Local/Main validates committed entries against HEAD reachability, excluding baseline ancestors when comparing. These endpoints are not generic Git object or file readers. Refresh keeps ready
423
495
  content visible while replacement data loads, and late responses for an older commit or file selection
424
496
  are ignored.
425
497
 
@@ -480,7 +552,7 @@ text, actions and diagnostic details follow the font size selected in **Settings
480
552
  messages, prompts, transcripts, and history. The plugin never copies or rewrites those values.
481
553
  - The plugin's external index stores Worktree paths, branches, sources, lifecycle state, bindings,
482
554
  ordering, instructions, acquisition facts, and related metadata. For managed Worktrees, the
483
- Dashboard Base fact is the persisted `baseBranch`; users can replace it with a local branch other
555
+ Dashboard Base fact is the persisted `baseBranch`; users can replace it with a local or fetched remote branch other
484
556
  than the current Worktree branch, and the saved value becomes the Git-tab selector default. The
485
557
  immutable acquisition `baseCommit` remains separate and is not rewritten by that edit. The index is
486
558
  kept in the DSH host plugin data directory, not in a project directory or DSH's raw data store. It
@@ -507,7 +579,7 @@ text, actions and diagnostic details follow the font size selected in **Settings
507
579
  (optionally including one fresh baseline-to-working-tree projection), one **Uncommitted changes**
508
580
  snapshot, changed files, and one unified diff at a time. These projections combine staged, unstaged,
509
581
  and untracked files when requested but are never written back to Git. The Dashboard does not provide
510
- commit, staging, reset, revert, cherry-pick, fetch, push, pull, pull requests, graph lanes, pagination,
582
+ commit, staging, reset, revert, cherry-pick, push, pull, pull requests, graph lanes,
511
583
  or syntax highlighting.
512
584
  - Session rows and Dashboard cards use DSH's native status and relative-time presentation. The green
513
585
  completion dot is DSH's unread reminder for a Session that stops outside the current main view;
package/README.zh.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  工具偏好存储在 Host 自有的独立配置文件中,与关系索引和原生 Session 元数据隔离。
10
10
  插件只在自己的 sidecar 中保存 Worktree 关系、获取事实、共享 Worktree 指令以及 Workspace 根目录的
11
- Main 指令。受管理的 Worktree 提供可选择本地 branch 基线的只读 Git 与变更 Dashboard,Main 提供 Workspace 根目录 HEAD history;
11
+ Main 指令。受管理的 Worktree 提供可选择本地或已获取的远端 branch 基线的只读 Git 与变更 Dashboard,Local/Main 提供 Workspace 根目录 HEAD history 和可选对比分支;
12
12
  不会复制 transcript 或改写 DSH Session。
13
13
 
14
14
  > **预览:** Worktree Dashboard 是仅 plugin 提供的早期 MVP 预览版。Worktree 导航、生命周期操作、
@@ -56,6 +56,16 @@ pnpm dsh web
56
56
  DSH Web profile 必须已经能够正常启动。修改 `package.json` 或 `cordis.patch.yml` 后,需要重新
57
57
  执行绝对路径安装命令。
58
58
 
59
+ 安装到 Desktop 时,先结束活跃任务并完全退出 DeepSeek Harness,再使用已安装的 DSH CLI:
60
+
61
+ ```bash
62
+ dsh plugin --profile desktop add /absolute/path/to/clutch-dsh/packages/clutch-dsh-worktree
63
+ ```
64
+
65
+ 安装完成后重新打开 Desktop。本地链接生效期间,需要保留 checkout 及其已安装的 `node_modules`;
66
+ 只复制 `lib/` 或移除 checkout 的依赖可能导致 Host 和权限 preset 入口导入失败。
67
+ Client 的实现依赖在构建时打包,Desktop 无需另外提供 Zustand 或 Immer 模块。
68
+
59
69
  ### 从 GitHub 源码安装(可选)
60
70
 
61
71
  DSH plugin market 使用的源码依赖形式也可以直接安装:
@@ -72,7 +82,7 @@ dsh plugin --profile web add "github:Cerbur/clutch-dsh#path:/packages/clutch-dsh
72
82
  | 功能 | 预览 | 作用 |
73
83
  | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
74
84
  | **Worktree 导航** | <img src="assets/screenshots/screenshots-en.png" width="420" alt="包含 Workspace、Main、Worktree 和 Session 行的 DSH Worktree 导航"> | 在 DSH 原生 Sidebar 中增加 Worktree 模式。macOS desktop 下,面板共享 DSH 原生玻璃材质,避免叠加第二层底色或透出重复导航。其他平台保留主题底色;降低透明度时使用更强的底色。Workspace 展开与新 Session 行使用原生节奏的淡入和位移动画。每个 Workspace 下可以浏览 Local/Main 和 Git Worktree,再打开对应行绑定的 Session。 |
75
- | **创建和导入 Worktree** | <img src="assets/screenshots/screenshots-import.png" width="420" alt="Worktree 创建与导入弹窗"> | 从本地 branch 创建 Worktree,或原地登记已有的 branch-attached Worktree。导入不会移动、复制或编辑已有目录。 |
85
+ | **创建和导入 Worktree** | <img src="assets/screenshots/screenshots-import.png" width="420" alt="Worktree 创建与导入弹窗"> | 从本地或已获取的远端 branch 创建 Worktree,或原地登记已有的 branch-attached Worktree。导入不会移动、复制或编辑已有目录。 |
76
86
  | **Worktree Dashboard** | <img src="assets/screenshots/screenshots-dashboard.png" width="420" alt="显示 Session 和 Worktree 操作的 Worktree Dashboard 预览"> | 预览版 Dashboard 显示 Worktree 身份、路径、Session、Worktree/Main 指令、已连接操作、由 Host 提供的在应用中打开入口,以及受管理 Worktree 或 Main 的只读 Git 与变更视图。派生 Worktree 和其他未完成卡片仍标记为**即将推出**。 |
77
87
  | **Agent 工具设置(实验性)** | <img src="assets/screenshots/screenshots-worktree-tool.png" width="420" alt="Worktree 工具设置预览"> | 在通用设置中选择 `/cluworktree` 启用的能力,在 Local/Main 与各受管 Worktree 的 Dashboard 中独立配置自动注入。委派创建的 Session 默认仅获得结果回报。 |
78
88
 
@@ -109,11 +119,46 @@ Worktree 导航与 Dashboard 支持在原生栏目之前、之间或之后插入
109
119
  或选项菜单打开时显示,与菜单按钮保持一致。
110
120
 
111
121
  1. 打开 Local/Main 或 active Worktree 的选项菜单,选择 **Create Worktree**。
112
- 2. 选择本地 base branch,也可以填写新的 branch 名称。
122
+ 2. 选择本地或已获取的远端 base branch,并填写新的本地 branch 名称。弹窗会推荐一个可用名称。
113
123
  3. 确认弹窗。插件会创建 Git Worktree,记录获取事实;从该 Worktree 打开 Session 时继续执行
114
124
  正常的 Session 和 binding 流程。
115
125
 
116
- Git repository、本地 branch 和 initial commit 必须可用。如果仓库尚未准备好,DSH 会显示对应
126
+ 创建和导入页签使用左右对齐、占满内容宽度的控件,并保持一致的字段间距。
127
+
128
+ 创建、保存基线和 Git 对比共用同一个可搜索选择器,按**本地分支**和**远端分支**分组,
129
+ 并标注当前与已检出状态,支持全部、本地、远端分支过滤。
130
+ 下拉框在亮色与暗色主题下均使用 DSH 原生菜单材质。搜索不区分大小写;方向键移动、Enter 选择、Escape 关闭。
131
+ 点击浮窗内的标题、空白、搜索、筛选或获取区域会保持打开;选中选项或点击外部区域才收起浮窗。
132
+ 分支与导入选择器在候选数据加载期间也能立即打开,浮窗内显示加载状态,数据返回后原位更新。
133
+ 搜索和筛选条件保持不变,刷新时保留已有候选列表。
134
+ 关闭并重新打开基线编辑器后,旧弹窗的待完成结果会被忽略。
135
+ 只有最新的分支读取或 Fetch 可以更新候选与加载状态。
136
+ 下拉列表采用紧凑高度,优先在字段下方展开,空间不足时缩短列表并在内部滚动;仅下方可用空间过小时向上展开。
137
+ 即使候选数据已经缓存,也先绘制紧凑的加载浮窗,再准备列表。
138
+ 首次浮窗与加载阶段保持同一高度,数据就绪后按内容调整高度,并受滚动上限约束。大量候选只渲染可视区域附近的选项;
139
+ 搜索、筛选和键盘选择仍覆盖全部候选。
140
+ 切换**创建**和**导入**时,在同一弹窗内替换表单内容,不重新播放弹窗的打开动画。
141
+ 每次打开分支选择器都会重新读取本地 Git 引用,包含 terminal 中的变更;切回浏览器不重新加载候选。
142
+ Fetch 完成后读取一次更新后的分支列表,并直接提供给选择器。
143
+ 打开新建 Worktree 弹窗不预加载分支,默认基线来自当前分支或 HEAD。
144
+ 完整分支列表仅在打开选择器或 Fetch 完成后读取。工作区导航单独读取 Git 就绪状态和根 checkout 当前分支;
145
+ 进入 Git 与变更只加载历史,不预加载分支列表。
146
+ 默认优先选择当前本地分支。远端列表来自本地仓库已有的引用;点击**远端分支**标题旁的
147
+ 下载箭头可获取全部已配置远端的分支,即使远端列表为空也能使用。Fetch 更新远端分支引用并刷新
148
+ 当前 Workspace,保留已选值、本地分支、tag 和工作区文件,不清理已删除的引用。
149
+ 获取期间按钮显示加载图标并禁止重复点击;成功后原位显示**远端分支已更新**,2 秒后恢复下载图标。
150
+ 失败保留列表,在同一按钮上显示重试入口;按钮详情保留错误码、message 与诊断信息,
151
+ 并可在**报错与修复**中查看,列表底部不额外添加提示行。
152
+ 分支列表读取不会自动连接远端。基于远端创建 Worktree 必须使用新的本地分支;
153
+ 若该本地分支不存在,其短名可以与远端基线同名。远端 HEAD 条目不会列出。
154
+
155
+ Git repository 和 initial commit 必须可用。可选择本地 branch,或选择 **HEAD**,从 Main 当前
156
+ checkout(包括精确 Tag 或游离 Commit)创建新分支。Main 会显示当前 branch、精确 Tag 或短 Commit,
157
+ 游离时仍保留创建入口。
158
+ 本地化的 HEAD 选项会包含当前引用名称,例如**当前 HEAD (v1.0.0)**。
159
+ 创建使用选择时显示的 commit;提交前 HEAD 已变化时,以 `WORKTREE_STATE_CONFLICT` 拒绝创建,
160
+ 请刷新弹窗并重新选择来源。
161
+ 如果仓库尚未准备好,DSH 会显示对应
117
162
  的 readiness 提示和可复制的 setup 指引。
118
163
 
119
164
  如果 Workspace 位于仓库子目录,其 Worktree 会保留相同的相对目录。例如,位于
@@ -125,7 +170,8 @@ Git repository、本地 branch 和 initial commit 必须可用。如果仓库尚
125
170
  子目录机制升级后,已绑定且仍使用旧 Git 根目录 cwd 的 Session 可以继续使用,包括自动工具注入、
126
171
  会话发现、继续投递、结果回报,以及默认从自身 checkout 的 HEAD 创建 Worktree。原始 cwd 和历史保持不变;
127
172
  新的 Session 绑定仍必须匹配 checkout 内的 Workspace 工作目录。Git 文件预览对当前 Session
128
- cwd 内的文件使用相对地址,对其余 checkout 文件使用绝对地址,并遵循 DSH 原生文件访问校验。
173
+ cwd 内的文件使用相对地址。cwd 外的文件会提示使用 IDE 或仓库根目录的 Session;已绑定的旧
174
+ Git-root Session 保留原有预览范围。
129
175
 
130
176
  ### 启用 Agent Worktree 工具
131
177
 
@@ -156,8 +202,8 @@ cwd 内的文件使用相对地址,对其余 checkout 文件使用绝对地址
156
202
 
157
203
  | 工具 | 参数 | 行为 |
158
204
  | ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
159
- | `clutch_new_worktree` | `name`、可选 `baseBranch`、`instructions` | 默认从调用 Session 所在的健康 Worktree 分支创建新分支;Local/Main 使用根 checkout 当前分支。显式本地 `baseBranch` 覆盖默认值。返回获取事实 `baseBranch` 与 `baseCommit`。 |
160
- | `clutch_list_worktrees` | 可选 `workspaceId` | 列出受管 Worktree 的 id、分支、路径、生命周期和健康状态,以及可用的本地基线分支。默认查询调用方 Workspace。 |
205
+ | `clutch_new_worktree` | `name`、可选 `baseBranch`、`instructions` | 默认从调用 Session 所在的健康 Worktree 分支创建新分支;Local/Main 使用根 checkout 当前分支。显式本地或已获取的远端 `baseBranch` 覆盖默认值。返回获取事实 `baseBranch` 与 `baseCommit`。 |
206
+ | `clutch_list_worktrees` | 可选 `workspaceId` | 列出受管 Worktree 的 id、分支、路径、生命周期和健康状态,以及可用的本地和已获取的远端基线分支。默认查询调用方 Workspace。 |
161
207
  | `clutch_span_worktree` | `worktreeId` 或旧参数 `name`、`prompt`、可选 `model`、`title` | 创建新的原生 Session、建立绑定、配置初始模型并提交 prompt。返回 `sessionId` 和投递阶段状态。 |
162
208
  | `clutch_list_models` | 可选 `provider` | 列出原生 provider/model、推理强度和 provider 错误,同时返回当前 Session 模型及部署默认模型。 |
163
209
  | `clutch_list_sessions` | 可选 `workspaceId`、`worktreeId` | 查找已有 Session、绑定状态、运行状态和标题。不可用关系仅返回诊断,不读取其历史。 |
@@ -170,7 +216,7 @@ Git 分支名;指派时优先使用稳定的 `worktreeId`。单独创建 Workt
170
216
  仅继承已提交状态;不会复制 staged、unstaged 或 untracked 文件。
171
217
  绑定不健康时不会悄悄退回 Main。默认固定调用 checkout 的已提交 HEAD,包括根目录的
172
218
  detached HEAD。Detached 来源返回 `baseCommit`,不虚构 `baseBranch`;
173
- 仍可显式指定本地 `baseBranch` 覆盖默认值。
219
+ 仍可显式指定本地或已获取的远端 `baseBranch` 覆盖默认值。
174
220
 
175
221
  新委派的 Session 默认仅自动获得
176
222
  `clutch_report_result({ status, summary, evidence?, requestId? })`。Host 将回报目标固定为
@@ -234,12 +280,12 @@ Workspace 根目录缺失时仍拒绝消息投递。
234
280
  ### 导入已有 Worktree
235
281
 
236
282
  1. 选择 Workspace,打开分支图标的 **新建 Worktree** 操作,然后切换到 **Import**。
237
- 2. 从 branch 和 path 列表中选择候选项。
283
+ 2. 打开可搜索的 Worktree 选择器,按分支名或路径过滤。每项展示分支和目录,选择要导入的 Worktree。
238
284
  3. 选择 **Import Worktree**。插件会原地登记已有目录,不移动、复制或修改其中的文件,随后
239
285
  使用与新建 Worktree 相同的 Session 流程。
240
286
 
241
287
  第一版只列出尚未被插件管理、状态 ready、绑定 branch 且不是 repository root 的 Git Worktree。
242
- Detached、bare、prunable、缺失或无效条目会被省略。导入的 Worktree 仍可在选择本地基线 branch 后
288
+ Detached、bare、prunable、缺失或无效条目会被省略。导入的 Worktree 仍可在选择本地或已获取的远端基线 branch 后
243
289
  使用 Git 与变更。
244
290
 
245
291
  导入遵循同样的 Workspace 相对目录规则,只提供该目录可用的候选项。原 Workspace 可用时,
@@ -298,31 +344,36 @@ Dashboard 的 **Open in ...** 分割按钮保留插件自己的按钮 UI,但
298
344
 
299
345
  从受管理 Worktree 或 Main Dashboard 打开 **Git 与变更** Tab。Main 直接读取当前 Workspace 根目录 HEAD 的
300
346
  commit history;当根目录存在 tracked、staged、unstaged 或 untracked 改动时,顶部会加入**未提交的改动** entry。
301
- 默认最多展示 200 个已提交 commit,选中第一个可见目标,并对工作区目标和已提交 history 使用相同的变更文件与 Diff 面板。对于持久化 `baseBranch` 存在且不同于当前
347
+ 基线选择器默认**无**,展示 HEAD history,不显示总提交数。选择本地或已获取的远端对比分支后,
348
+ 展示基线汇总、完整对比提交总数和 ahead/behind 事实;选择**无**会返回直接历史。这些选择只保留在页面内存。
349
+ 直接历史选中第一个可见目标,并对工作区目标和已提交 history 使用相同的变更文件与 Diff 面板。对于持久化 `baseBranch` 存在且不同于当前
302
350
  branch,或带有作为隐式基线的获取 commit 的 managed Worktree,Overview 会通过现有 `/api` Connection
303
351
  做一次轻量、按需的 Git 状态读取,分别展示 ahead/behind commit 数量、已提交(基线到 HEAD)和未提交
304
- (当前工作区)的文件行数。这是临时 projection,不是 watcher,也不会写入 Worktree 记录。Main 没有 Worktree 基线
305
- 比较,因此 Overview 对 ahead/behind 事实仍显示 **待接入**,但 Git Tab 可以展示 Main history。不可用或未选择基线的
352
+ (当前工作区)的文件行数。这是临时 projection,不是 watcher,也不会写入 Worktree 记录。Local/Main 对比只是 Git Tab 的临时选择,
353
+ 因此 Overview 对 ahead/behind 事实仍显示 **待接入**,但 Git Tab 可以展示 Main history。不可用或未选择基线的
306
354
  managed 视图会诚实显示 **待接入**。打开 Overview 不会加载 branch 列表;
307
- 第一次进入 Git Tab 时才加载本地 branch,并在基线解析后加载 commit history。要替换基线,可以点击
355
+ Git Tab 挂载时直接按已保存分支或获取 commit 读取 history。只有打开选择器才加载分支候选,
356
+ Fetch 直接消费返回的候选列表。要替换基线,可以点击
308
357
  Base fact 旁的铅笔图标打开 branch 选择器:搜索框固定在选择器顶部,下方是有固定高度的 branch 列表
309
358
  (默认展示约七条),超出部分在列表内滚动,因此过滤 branch 时整个弹窗尺寸保持不变。选择除当前
310
- Worktree branch 之外的任一本地 branch,再保存。
359
+ Worktree branch 之外的任一本地或已获取的远端 branch,再保存。
311
360
  保存会替换 plugin sidecar 中持久化的 `baseBranch`;下次打开 Git Tab 时,选择器会以保存后的值作为默认值。
312
361
  Git Tab 打开后,直接修改其中的选择器仍只是临时查看选择,会重新加载 history、changed files 和 Diff,
313
362
  不会再次写入 Worktree 记录。如果不存在可用的已保存基线(缺失或等于当前 Worktree branch),Git Tab
314
363
  和 Overview 会改用 Worktree 不可变的获取 commit 读取,并将该解析出的 commit 显示为 Base fact;只有
315
364
  既无可用已保存基线、也无获取 commit 的 Worktree 才会保持未选择状态并提示用户选择。当所选 branch
316
365
  已分叉时,Git 会解析两个 branch head 的共同先祖;
317
- Worktree 在共同先祖之后的 commit 计为 `+N` 领先,base branch 在共同先祖之后的 commit 计为 `-N` 落后,
366
+ Worktree 在共同先祖之后的 commit 计为 `↑ N` 领先,base branch 在共同先祖之后的 commit 计为 `↓ N` 落后,
318
367
  history 和文件读取仍然可用。如果两个 head 没有共同先祖,则基线汇总退化为 base branch head 与
319
368
  Worktree `HEAD` 之间的完整 tree diff,history 展示 Worktree 相对 base head 独有的 commit。
320
369
  在有效的 managed Worktree 基线加载后,Git 与变更 Tab 初始会选择**基线汇总**,而不是第一个 commit;切换基线 branch
321
- 也会回到该汇总。需要更窄的查看范围时,再选择 commit 或**未提交的改动**。Main 跳过这个仅用于比较的汇总,但使用相同的已提交 history 与多选行为;Workspace 根目录有改动时也展示实时工作区目标。
370
+ 也会回到该汇总。需要更窄的查看范围时,再选择 commit 或**未提交的改动**。Local/Main 选择**无**时跳过这个仅用于比较的汇总,但使用相同的已提交 history 与多选行为;Workspace 根目录有改动时也展示实时工作区目标。
322
371
  选择**未提交的改动**会比较当前 Workspace 根目录与 `HEAD`,不会创建基线或写入 Git 状态。
323
372
 
324
- 所选 branch 每次读取都会重新解析。浏览器只能选择普通的本地 branch 名,不能直接选择 commit SHA 或
325
- 任意 Git ref:完整 ref 路径、tag 或 remote-tracking ref 会被直接拒绝,而已选 branch 不复存在时会显示
373
+ 所选 branch 每次读取都会重新解析。选择器展示短名,以枚举出的 `refs/heads/...` 或
374
+ `refs/remotes/...` 作为稳定身份。新保存的远端基线保留精确远端 ref,新增或删除同名本地分支不会改变基线。
375
+ 旧短名仅在无歧义时兼容;有歧义的已保存值返回 `WORKTREE_STATE_CONFLICT`,需要重新选择目标分支。
376
+ commit SHA、tag 和任意 revision expression 仍被拒绝。已选精确分支不复存在时会显示
326
377
  诚实的不可用状态,而不是泛化的 Git 失败。`baseCommit` 是不可变的获取元数据,永远不能由用户直接选择,
327
378
  并在没有可用已保存 branch 基线时作为隐式基线;创建恢复也绝不会改写它。当 managed Worktree 或 Main Workspace 根目录存在 staged、unstaged 或 untracked 文件时,列表顶部会加入**未提交的改动**;
328
379
  选择它会将对应的当前工作区与 `HEAD` 比较,并使用相同的变更文件和 Diff 视图。
@@ -332,15 +383,27 @@ Worktree `HEAD` 之间的完整 tree diff,history 展示 Worktree 相对 base
332
383
  打开 **包含工作区改动** 后,该目标会改为展示从同一比较边界到当前工作区的一次净差异,其中包含已提交、
333
384
  staged、unstaged、untracked、删除和重命名改动。这是按需读取的新鲜 projection,而不是简单拼接两段
334
385
  Diff。点击 commit 会展示该 commit 自己的 Diff;对于 managed Worktree 和 Main,打开提交栏标题中的**多选提交**开关后,可以同时选择
335
- 多个已提交行,查看这些 commit 各自 first-parent delta 的精确并集。Main 不提供基线汇总或工作区包含开关;该开关默认关闭,关闭时会把已选
386
+ 多个已提交行,查看这些 commit 各自 first-parent delta 的精确并集。Local/Main 选择**无**时不提供基线汇总或工作区包含开关;多选开关默认关闭,关闭时会把已选
336
387
  集合收敛回当前聚焦的 commit。变更文件会记录贡献它的
337
388
  commit;每个所选 commit 会作为独立 Diff segment 展示,不会隐式扩展成范围,也不会包含未选择的
338
389
  commit。变更文件栏标题会展示当前目标(基线汇总、所选 commit 或未提交改动)对应的绿色 `+N` 和红色
339
- `-N` 总行数;仅包含 binary 时显示未知。未提交改动 entry 与已提交的多选互斥。汇总 Diff 工具栏中的
340
- **在侧栏打开**会使用当前 Session 在原生右侧栏中显示当前文件,但前提是该 Session 属于 Dashboard
341
- 对应的 Worktree。空 Worktree 或无关的当前 Session 不会通过此操作打开文件。
342
-
343
- managed Worktree 和 Main history 都最多展示 200 个 commit,更多内容会标记为 truncated;超过 Git adapter 输出上限的变更文件列表
390
+ `-N` 总行数;仅包含 binary 时显示未知。未提交改动 entry 与已提交的多选互斥。Diff 工具栏和仍存在的
391
+ 变更文件行均提供 **在侧栏打开**。当前 Session 属于 Dashboard 分组时优先使用,否则回退到该分组
392
+ 首个可见 Session,并显式展开原生右侧栏。没有目标 Session 时提示先创建会话,概览的空会话卡片
393
+ 也提供 **新建会话**。Main 和托管 Worktree 的文件树路径、Diff 标题和文件请求均相对 Workspace
394
+ 工作目录。在 `/repo/packages/app` 中,`src/index.ts` 指向 `/repo/packages/app/src/index.ts`;
395
+ 仓库根目录的 `README.md` 显示为 `../../README.md`。视图保留整个 checkout 范围的变更。
396
+ 目标 Session cwd 外的文件会显示提示,不会生成无效资源地址。
397
+
398
+ Main 显示本地 checkout 状态,省略派生 Worktree 的创建时间与基线事实。
399
+ Ahead/Behind 使用中性的提交计数(`↑ N` / `↓ N`),代码增删行数保留绿色/红色计数。
400
+ 粘性顶栏将长引用名称截断为单行,只有引用文本本身触发复制。
401
+
402
+ managed Worktree 和 Local/Main history 首次加载最近 50 个 commit,滚动到底部继续追加后续 50 个,
403
+ 保留当前选择和 Diff;也可以用键盘操作加载更多按钮。对比视图使用 ahead 数量展示完整已提交总数,
404
+ 与已加载页数无关。HEAD 或基线在分页间移动时,需要刷新后继续,已有行保持可见。
405
+ 发生该冲突后,加载后续提交按钮改为**刷新**。提交文件和 Diff 读取也要求 HEAD 在授权及读取期间保持一致。
406
+ 多选最多支持 200 个所选 commit。超过 Git adapter 输出上限的变更文件列表
344
407
  也会显式标记为 truncated,而不是报泛化错误。commit 详情使用 first-parent 比较,root
345
408
  commit 与空 tree 比较,rename/copy 行保留两个路径;binary 或过大的 diff 会显示明确的安全状态。变更
346
409
  文件行会用绿色 `+N` 表示新增、红色 `-N` 表示删除;binary 文件不显示这些数量。文件名会用绿色表示新增、红色表示删除、蓝色表示其他变更,每一行的标题与无障碍标签也会写出对应状态。文件夹 icon 会直接表示文件夹当前是展开还是折叠。
@@ -356,7 +419,7 @@ Git 与变更使用受页面 viewport 限制的固定尺寸布局。宽度足够
356
419
  固定尺寸的 Diff 栏内滚动;只读选择和刷新行为保持不变。
357
420
 
358
421
  视图是只读的,不提供 commit 或 staging 控件。managed Worktree 会依据所选 branch 到 `HEAD` 的 projection 验证
359
- commit;Main 会依据有界的 HEAD history projection 验证 commit。插件随后依据最新状态重新读取和授权工作区 path,因此这些 endpoint 不是通用 Git object 或文件读取器。
422
+ commit;Local/Main 根据 HEAD 可达性验证 commit,对比时排除基线先祖。插件随后依据最新状态重新读取和授权工作区 path,因此这些 endpoint 不是通用 Git object 或文件读取器。
360
423
  刷新会在替换数据加载期间保留 ready 内容;旧 commit 或文件选择的迟到响应会被忽略。
361
424
 
362
425
  ### 添加 Worktree 或 Main 指令
@@ -409,7 +472,7 @@ Worktree 设置采用 DSH 原生 Tab、状态标签和紧凑按钮。说明文
409
472
  和历史。插件不会复制或改写这些数据。
410
473
  - 插件外部索引保存 Worktree 路径、branch、来源、生命周期状态、binding、排序、指令、获取事实
411
474
  及相关元数据。对于受管理 Worktree,Dashboard Base fact 是持久化的 `baseBranch`;用户可以将其
412
- 替换为除当前 Worktree branch 之外的本地 branch,保存后的值会成为 Git Tab 选择器的默认值。
475
+ 替换为除当前 Worktree branch 之外的本地或已获取的远端 branch,保存后的值会成为 Git Tab 选择器的默认值。
413
476
  不可变的获取 `baseCommit` 与它分开保存,不会因该编辑被重写。索引位于 DSH host 的 plugin data
414
477
  directory,不写入项目目录或 DSH raw data,也不保存 Session 内容或 Workspace 根目录副本。
415
478
  - runtime `cwd` 在每次执行时派生。无 binding、Main 或 detached binding 使用 Workspace root;
@@ -431,8 +494,8 @@ Worktree 设置采用 DSH 原生 Tab、状态标签和紧凑按钮。说明文
431
494
  - Git Dashboard 只实现 commit history、只读的**基线汇总**(可选包含一次从基线到工作区的
432
495
  新鲜 projection)、顶部的只读**未提交的改动**快照、changed files 和一次一个 unified diff。
433
496
  按请求启用时,这些 projection 会合并 staged、unstaged 和 untracked 文件,但不会写回 Git。
434
- Dashboard 不提供 commit、staging、reset、revert、cherry-pick、fetch、push、pull、pull request、
435
- graph lanes、pagination 或 syntax highlighting。
497
+ Dashboard 不提供 commit、staging、reset、revert、cherry-pick、push、pull、pull request、
498
+ graph lanes 或 syntax highlighting。
436
499
  - Session 行和 Dashboard 卡片使用 DSH 原生的状态和相对时间展示。绿色完成 dot 是 DSH 对非当前
437
500
  主视图中停止的 Session 的未读提醒;打开该 Session 或再次运行时清除。冷启动时的 idle Session
438
501
  不视为已完成。提醒仍由 DSH 拥有,插件不会持久化该状态。折叠的 Workspace、Main 和 Worktree 分组会
@@ -1 +1 @@
1
- {"version":3,"file":"WorktreeSurface.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeSurface.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAsB/D,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,UAAU,EAAE,oBAAoB,sCAme/D"}
1
+ {"version":3,"file":"WorktreeSurface.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeSurface.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAsB/D,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxF,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,UAAU,EAAE,oBAAoB,sCAigB/D"}