@cerbur/clutch-dsh-worktree 0.1.16 → 0.1.18

package/README.md

@@ -6,21 +6,28 @@
 Sessions as Workspace → Worktree → Session while keeping DSH as the source of truth for
 Workspace identity, Session metadata, native lists, messages, and conversation history.
 
-The plugin stores Worktree relationships, acquisition facts, shared Worktree instructions, and Workspace-root
-Main instructions in its own sidecar. Managed Worktrees expose a read-only baseline-relative Git & Changes dashboard, while Main exposes
-its Workspace-root HEAD history; the plugin does not copy transcripts or rewrite DSH Sessions.
+Tool preferences are stored in separate Host-owned files, outside relationship indexes and native
+Session metadata. The plugin stores Worktree relationships, acquisition facts, shared Worktree instructions, and Workspace-root
+Main instructions in its own sidecar. Managed Worktrees expose a read-only baseline-relative Git & Changes dashboard, while Local/Main exposes
+its Workspace-root HEAD history with an optional comparison branch; the plugin does not copy transcripts or rewrite DSH Sessions.
 
 > **Preview:** Worktree Dashboard is an early, plugin-only MVP preview. Worktree navigation, lifecycle actions,
 > Session actions, Worktree/Main instructions, and the managed Worktree or Main Git & Changes view are connected.
-> Derived Worktrees, Settings, and other unfinished actions remain marked
+> Derived Worktrees and other unfinished actions remain marked
 > **Coming soon**.
 
 ## Installation
 
 After installing into a running DSH instance, restart DSH Desktop, or restart the DSH Web
-server and refresh the page, to load the plugin Host. If the Client loads while the Host is
-still unavailable, a native toast reminds you once per Client load. Network failures and
-Workspace errors do not trigger the reminder.
+server and refresh the page, to load the plugin Host and permission configuration. Finish
+active tasks before restarting. If the Client loads while the Host is still unavailable, a
+native toast reminds you once per Client load. If a Worktree Session permission check reports
+that **Worktree Full Access** is unavailable and falls back to `workspace-write`, a separate
+once-per-load toast gives the same restart guidance for a recent install or update. The
+permission recovery message retains this guidance after the toast closes. Network failures,
+Workspace errors, unverified permissions, and explicit user restrictions do not trigger the
+missing-preset reminder. The reminder does not reload services or grant Full Access; if the
+preset remains unavailable after restarting, check the DSH plugin and permission configuration.
 
 ### Install from npm
 
@@ -53,6 +60,17 @@ pnpm dsh web
 The DSH Web profile must be able to start before this plugin is added. Re-run the absolute-path
 install command after changing `package.json` or `cordis.patch.yml`.
 
+For Desktop, fully quit DeepSeek Harness after active tasks finish, then use the installed DSH CLI:
+
+```bash
+dsh plugin --profile desktop add /absolute/path/to/clutch-dsh/packages/clutch-dsh-worktree
+```
+
+Reopen Desktop after installation. Keep the local checkout and its installed `node_modules`
+available while it is linked; copying only `lib/` or removing the checkout's dependencies can
+cause the Host and permission-preset entries to fail to import. Client implementation dependencies
+are bundled during the build, so Desktop does not need separate Zustand or Immer modules.
+
 ### Install from GitHub source (optional)
 
 The package also supports the source dependency form used by the DSH plugin market:
@@ -69,13 +87,21 @@ development details, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 | Feature                         | Preview                                                                                                                                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **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. |
-| **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.                                                                                                                                                                                                                                                                                                       |
-| **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, Settings, and other unfinished cards remain **Coming soon**.                                                                                                                                                                 |
+| **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.                                                                                                                                                                                                                                                                                                       |
+| **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**.                                                                                                                                                                 |
+| **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. |
 
 ## Usage
 
 ### Open Worktree mode
 
+The Sidebar scrollbar floats over the edge without shifting row spacing. Workspace folders
+and rotating disclosure triangles match native DSH. An expanded Workspace containing the current
+Session uses the native blue folder; other Workspace folders use the native gray. Hover over a long
+Session title or Worktree
+name to reveal its tail at native speed; leaving restores the start. Reduced motion reveals the
+tail immediately.
+
 1. Start DSH Web and select **Worktree** from the DSH Sidebar footer.
 2. Search or expand a Workspace in the Worktree tree.
 3. Select Local/Main or a Worktree to browse its Sessions. The view is additive; DSH's native
@@ -89,30 +115,223 @@ keeps no collapsed rail; use the native titlebar control to reopen it. Row anima
 reduced motion and settles immediately during search, drag, and initial loading.
 On Web, Worktree navigation starts below the native DSH brand row, leaving its Sidebar toggle
 visible and clickable even when the New Session action displays keyboard shortcuts.
+If the native Sidebar layout cannot be safely recognized, the plugin leaves native navigation
+visible rather than covering its controls. It retries when the layout changes.
+Worktree navigation and Dashboard support AppFrame layouts with extra titlebar or shell controls
+before, between, or after the native columns, while keeping those controls accessible.
 
 ### Create a Worktree
 
+You can also enable Agent tools with `/cluworktree`; see the next section.
+
+New Worktree actions use the same branch icon as Worktree rows. The Workspace row button appears
+on hover, keyboard focus, or while its options menu is open, matching the menu button.
+
 1. Open the options menu for Local/Main or an active Worktree and choose **Create Worktree**.
-2. Choose the local base branch. You can also provide a new branch name.
+2. Choose a local or fetched remote base branch and a new local branch name. The dialog suggests an available name.
 3. Confirm the dialog. The plugin creates the Git Worktree, records its acquisition facts, and
    continues through the normal Session and binding flow when you open a Session from that Worktree.
 
-Git must have a usable repository, local branch, and initial commit. If setup is incomplete, DSH
+The Create and Import tabs share aligned, full-width controls and consistent spacing between fields.
+
+Creation, saved baselines, and Git comparison use the same searchable selector, grouped into **Local branches**
+and **Remote branches**, with current/checked-out markers and filters for all, local, or remote branches.
+Dropdowns use DSH’s native menu material in light and dark themes.
+Dropdown lists are compact and prefer opening below the field, shrinking to available space with internal scrolling;
+they open above only when there is too little useful space below.
+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,
+empty space, search, filters, and fetch controls; selecting an option or clicking outside closes it.
+Branch and import selectors open immediately while candidates load, show a loading indicator inside,
+and update in place when data arrives. Search and filters stay intact; refreshes keep existing rows visible.
+Closing and reopening the baseline editor discards pending results from the previous dialog.
+Only the latest branch read or Fetch can update its candidates and loading state.
+Even with cached candidates, the dropdown paints its compact loading shell before preparing the list.
+The initial shell and loading state keep the same height; ready results size to their content within the scrolling limit.
+Large lists render only rows near the viewport; search, filters, and keyboard selection still cover every candidate.
+Switching between **Create** and **Import** replaces the form content in the same dialog without replaying its opening animation.
+Opening any branch selector rereads local Git refs, including changes made in a terminal. Returning to
+the browser does not reload candidates. Fetch reads the updated list once and supplies it directly to the selector.
+Opening the New Worktree dialog does not preload branches; its default comes from the current branch or HEAD.
+The full branch list is loaded only when a picker opens or Fetch completes. Workspace navigation
+reads Git readiness and the current root-checkout branch separately; entering Git & Changes loads history without preloading branches.
+The current local branch is preferred by default. Remote refs are read
+from the local repository. Use the download-arrow button beside **Remote branches** to fetch all configured
+remotes, including when the remote list is empty. Fetch updates remote branch refs and refreshes this Workspace;
+it preserves your current selection, local branches, tags and working files, and does not prune deleted refs.
+The button shows a loading icon during fetch, then displays **Remote branches updated** in place for two
+seconds before restoring the download icon. Failures retain the list and show a retry on the same button;
+the button details retain the error code, message, and diagnostics, also available in **Errors & Repair**.
+no extra status row is added beneath the list.
+Listing branches never contacts a remote automatically.
+Remote baselines require a new local branch when creating a Worktree; its short name may match the remote baseline
+when that local branch does not exist. Symbolic remote HEAD entries are excluded.
+
+Git must have a usable repository and initial commit. Choose a local branch, or choose **HEAD** to
+create a new branch from Main's current checkout, including an exact Tag or detached Commit.
+The localized HEAD option includes the current reference name, for example **HEAD (v1.0.0)**.
+Creation uses the commit shown when selected. If HEAD changes before submission, creation is rejected
+with `WORKTREE_STATE_CONFLICT`; refresh the dialog and select the source again.
+Main displays the current branch, exact Tag, or short Commit and retains its creation action when detached.
+If setup is incomplete, DSH
 shows the relevant readiness message and copyable setup guidance.
 
+When the Workspace is a repository subdirectory, its Worktrees preserve that relative directory.
+For example, a Workspace at `/repo/packages/app` uses `<worktree-root>/packages/app` for new
+Sessions, the Dashboard path, Copy Path, and Open In. Git operations still use the entire checkout.
+If that directory is missing or resolves outside the checkout, the Worktree needs repair; it does
+not fall back to the Git root or create the missing directory.
+
+Already-bound Sessions with a legacy Git-root cwd remain usable after a subdirectory upgrade,
+including automatic tool injection, Session discovery, follow-ups, result reports and default
+Worktree creation from their own checkout's HEAD. Their original cwd and history remain unchanged;
+new Session bindings still require the Workspace directory inside the checkout. Git file previews use
+relative addresses inside the target Session cwd. Files outside that cwd show a prompt to use an IDE
+or a Session at the repository root; already-bound Git-root Sessions keep their original preview scope.
+
+### Enable Agent Worktree tools
+
+Open **Settings → Worktree → General** and turn on **Worktree tools**, then select the
+capabilities you want. Both tool switches start off. Run `/cluworktree` in a Session belonging to a
+Workspace or an active managed Worktree to enable your selected capabilities. Turning the general
+switch off removes the command; deselecting every capability turns the switch off automatically.
+
+For automatic injection, open **Dashboard → Settings** for Local/Main or a managed Worktree and select
+capabilities under **Automatically inject Worktree tools**. Local/Main settings apply only to unbound
+Sessions in that Workspace root; Worktree settings apply only to Sessions bound to that Worktree.
+Each configuration is stored separately. Selected tools are assembled before the first model request,
+including after an Agent restart; ordinary prompt presets also include delegation guidance and,
+in PTC mode, their SDK.
+These selections are independent of General:
+if General selects capabilities 1, 2, 3 and automatic injection selects 2, 3, 4, running
+`/cluworktree` adds only capability 1. Already enabled tools remain until that Agent ends; changing
+preferences affects future injection.
+
+The Worktree entry in Settings uses the same branch icon as the sidebar.
+Both settings use a card with the main switch at the top. Turning it on reveals tool selections
+and their descriptions below a divider; turning it off collapses them and retains your selection.
+Injection and reporting notes sit directly under the tool-selection explanation.
+The command and automatic-injection settings carry DSH's native **Experimental** badge.
+The settings explain each capability in plain language. Command results use DSH's native command
+presentation and report how many capabilities were added or already available.
+In a new Session, running `/cluworktree` immediately opens the conversation page and shows
+the command outcome, without first sending a message to the model.
+
+With delegation enabled, a request to create a feature Worktree and implement or fix something
+defaults to creating the Worktree and assigning the work to its own Session. That Session handles
+code edits, dependency setup and verification; creating the directory alone does not start the task.
+Guidance prefers the enabled plugin tools over other Worktree/Session tools, while respecting
+explicit requests to only create a Worktree, work in the current Session or use a different tool.
+
+The six selectable capabilities correspond to these tools:
+
+| Tool                    | Parameters                                                         | Behavior                                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`. |
+| `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.                                                                                          |
+| `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.                                                                                       |
+| `clutch_list_models`    | optional `provider`                                                | Lists native provider/model routes, reasoning efforts and provider failures, alongside the current Session model and deployment default.                                                                                           |
+| `clutch_list_sessions`  | optional `workspaceId`, `worktreeId`                               | Finds existing Sessions, binding state, status and title. Unavailable relations return a diagnostic without reading their history.                                                                                                 |
+| `clutch_send_message`   | `sessionId`, `prompt`, optional `mode`, `requestId`                | Continues an existing Session. `queue` is the default; `steer` corrects at a native step boundary. Returns admission, not a reply.                                                                                                 |
+
+For example, ask the Agent to call `clutch_new_worktree({ name: "feature/demo", instructions: "Run tests before finishing." })`,
+then `clutch_span_worktree({ worktreeId: created.worktreeId, prompt: "Implement the feature and report the result." })` using the returned Worktree id.
+The tool name is intentionally `clutch_span_worktree`. Worktree names are exact Git branch names
+within the calling Workspace; prefer stable `worktreeId` for dispatch. Creating a Worktree alone does not create a Session.
+Only committed state is inherited; staged, unstaged and untracked files are not copied.
+An unhealthy binding never silently falls back to Main. The default captures the calling checkout's
+committed HEAD, including a detached root HEAD. Detached sources return `baseCommit` without inventing
+a `baseBranch`; an explicit local or fetched remote `baseBranch` remains available as an override.
+
+Newly delegated Sessions automatically receive only
+`clutch_report_result({ status, summary, evidence?, requestId? })`. The Host fixes the destination
+to the delegating Session. `status` is `completed`, `blocked`, or `failed`; `summary` and `evidence`
+are each limited to 2,000 characters. The other six capabilities require `/cluworktree` or the
+Worktree's explicit automatic-injection selection. Reports arrive as ordinary queued native messages;
+verify their claims and evidence before accepting completion. Reports are model-driven:
+a crash, stopped Agent or unanswered human approval may prevent reporting. `idle` is not success.
+
+Reporting is limited to the active delegated task. One successfully admitted `completed`, `blocked`,
+or `failed` report consumes and clears its in-memory token. The reporting tool, SDK and guidance
+stay stable; calls without a token are rejected. Later user input clears any remaining token;
+it does not report to the former parent. An explicit new `clutch_send_message`
+dispatch from that parent opens reporting again after its prompt is consumed. Uncertain report
+admission permits only an identical retry with the returned `requestId`.
+Tokens are never persisted and are lost on Agent/plugin restart. Dispatch retry identities are
+retained in a bounded in-memory cache; expired retries fail explicitly instead of reopening reporting.
+The plugin rejects self/ancestor messages and blocks further message/task dispatch from turns
+triggered solely by reports or ordinary plugin messages. New human input permits dispatch again;
+these guards apply to this plugin's tools in both native and PTC modes.
+
+`clutch_read_session` and `clutch_wait_sessions` are removed from the model catalog. Do not
+poll lists or read raw Session logs for progress. After successful dispatch or follow-up admission,
+acknowledge dispatch and end the turn, waiting for the executing Session's pushed report.
+Continue only separate independent work already requested by the user. Do not check the delegated
+task through agent lists, terminal commands, Git, files or tests, and do not edit or commit it yourself.
+An explicit user progress/investigation request or a concrete admission failure permits a targeted action.
+Evaluate a report's supplied evidence rather than automatically rerunning checks; investigate only
+when requested or when the evidence has a concrete gap or inconsistency.
+Complete prompt presets such as **minimal** omit extra prompt sections; critical handoff and
+model-selection rules also appear in native tool descriptions, preserving that preset's complete prompt.
+Activation adds Agent-scoped guidance for choosing delegation from ordinary task descriptions,
+so users need not specify tool names. Schemas describe exact ids, defaults and target alternatives
+without `$schema`; errors explain the cause, correction and a valid invocation. A bad Session
+history returns one `unavailable` diagnostic while keeping healthy list entries available.
+
+In PTC mode, the generated SDK exposes concrete argument types, including required report
+`status` and `summary`. Length limits remain in field descriptions and are enforced at execution;
+mutually exclusive dispatch targets use `oneOf` compatible with DSH's schema subset.
+
+`model` is `{ provider, model, reasoningEffort? }`. Omission inherits the calling Session's
+effective selection, including reasoning effort; no catalog lookup is required for that default.
+When the user specifies a different model or asks to choose one for the task, discover supported
+routes with `clutch_list_models` if enabled and pass the selected object explicitly.
+Unknown routes require discovery or user clarification, never invented ids or a deployment-default fallback.
+An unavailable model or effort fails before creating a Session. Initial
+model routing does not save the deployment default. It is runtime-only until DSH records the
+first request header; after that, DSH restores the model from its own history. Restarting before
+that first request discards the initial routing override. Native Session model changes take precedence.
+
+Tool changes refresh the owning Workspace's Worktree list and bindings while preserving ready
+content. Dispatch keeps the current conversation open and uses DSH's normal new-Session
+preset and permission defaults; it does not automatically grant Worktree Full Access. Run `/cluworktree` again after the Agent or plugin restarts for capabilities not automatically injected.
+No extra command arguments are accepted. All discovery, reports and follow-ups are restricted
+to the calling Workspace; passing another `workspaceId` grants no additional access. Sessions
+are ordinary native Sessions, not native subagent children or a persistent delegation catalog.
+Detached bindings must be repaired before sending or reporting through these tools.
+Healthy archived Worktrees retain their active bindings and allow Session follow-ups;
+a missing Workspace root still blocks message admission.
+
+If saving instructions, binding, or prompt admission fails after creation, the tool returns the
+created identity and an error (`instructionsSaved: false`, `binding-failed`, `model-failed`,
+`title-failed`, `reporting-failed`, or `prompt-failed`).
+The Worktree and native Session are retained. Repair or open the returned Session before retrying;
+another dispatch creates another Session. After a successful binding/model setup, retry a failed
+prompt with `clutch_send_message` and the returned `requestId`. Reuse a request id only for the
+same message retry; new follow-ups get fresh ids. `clutch_send_message` also returns `prompt-failed`
+with that id when native admission throws, including when acceptance is uncertain.
+Reporting destinations and activation are runtime-only. Restart discards the destination;
+a resumed Session can enable `/cluworktree` and use `clutch_send_message` with a known delegator id. There are no automatic merge, publish or disk-cleanup tools.
+
 ### Import an existing Worktree
 
-1. Select a Workspace, open its `+` action, and switch to **Import**.
-2. Choose a candidate from the branch-and-path list.
+1. Select a Workspace, open its branch-icon **New Worktree** action, and switch to **Import**.
+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.
 3. Select **Import Worktree**. The plugin registers the existing directory without moving,
    copying, or changing its files, then uses the same Session flow as a created Worktree.
 
 The first version lists only ready, branch-attached, non-root Git Worktrees that are not already
 managed by the plugin. Detached, bare, prunable, missing, and invalid entries are omitted. Imported
-Worktrees can still use Git & Changes after you choose a local baseline branch.
+Worktrees can still use Git & Changes after you choose a local or fetched remote baseline branch.
+
+Import uses the same Workspace-relative directory rule and offers only candidates where that
+directory is available. Existing records are projected with the corrected path when the original
+Workspace is available. Existing DSH Sessions keep their original metadata; create a new Session
+to run from the corrected directory.
 
 ### Create and open Sessions
 
+The new Session buttons on Local/Main and Worktree rows use DSH's native chat-bubble-plus icon.
+
 - Use **+** on Local/Main for a normal DSH Session whose runtime directory is the Workspace root.
 - Use **+** on a Worktree for a Session whose runtime directory is that Worktree.
 - When possible, the plugin reuses an unarchived blank Session with the exact target directory.
@@ -127,7 +346,7 @@ or open recovery actions; the plugin does not delete or rewrite the DSH Session.
 Open **Dashboard** from a Local/Main or Worktree row menu, its hover action, or the Dashboard icon
 beside the native Session-header actions. The header icon opens it in one click even when the Sidebar
 is collapsed, without expanding the Sidebar. If the target is still loading, the request stays open
-and shows loading or a retryable error in the center area. The Dashboard is a peer page to the native Session content: it
+and shows loading in the center area, with failures announced by toast and retries available in Worktree settings. The Dashboard is a peer page to the native Session content: it
 occupies the center area beside the Sidebar while leaving an already-open right sidebar visible for a
 session-bound target. When the target Worktree has Sessions, opening its Dashboard waits for an initial pending
 Session list to become ready, then keeps the current Session if it belongs to that Worktree; otherwise it
@@ -146,7 +365,7 @@ Use **Back to session**, Escape, a Sidebar Session, or Worktree mode exit to clo
 Sessions, the top-right action becomes **New Session** and starts one in that Worktree. The connected MVP surface
 can show Overview and Sessions, create a Session or Worktree, archive a Worktree, edit instructions, copy a
 path, open the recorded directory in VS Code, and inspect Git & Changes.
-Derived Worktrees, Settings, and other marked quick actions remain placeholders. VS Code must be
+Derived Worktrees and other marked quick actions remain placeholders. VS Code must be
 installed on the browser's machine and able to access the recorded path; the link does not verify
 launch success.
 
@@ -168,18 +387,22 @@ existing VS Code protocol-link fallback.
 
 Open the **Git & Changes** tab from a managed Worktree or Main Dashboard. Main reads the current Workspace-root
 commit history directly and prepends an **Uncommitted changes** entry when the root has tracked, staged, unstaged, or
-untracked changes. It shows at most the first 200 committed commits, selects the first visible target, and uses the same
+untracked changes. Its baseline selector defaults to **None**, showing HEAD history without a total commit count.
+Choose a local or fetched remote comparison branch to show Baseline summary, the full comparison commit count,
+and ahead/behind facts. Selecting **None** returns to direct history. These choices stay in page memory.
+Direct history selects the first visible target and uses the same
 changed-file and diff panes for either a live working-tree target or a committed history entry. For a managed Worktree with a
 persisted `baseBranch` that differs from the current branch, or with a captured acquisition commit that
 supplies the implicit baseline, the Overview performs one compact, on-demand Git status read through the
 existing `/api` Connection. It shows ahead/behind commit counts plus separate
 committed (baseline-to-HEAD) and uncommitted (live working-tree) line totals; this is an ephemeral
-projection, not a watcher or a Worktree-record field. Main has no Worktree baseline comparison, so Overview remains
+projection, not a watcher or a Worktree-record field. Local/Main's comparison is a transient Git-tab choice, so Overview remains
 **Not connected** for ahead/behind facts while its Git tab still exposes Main history. Unavailable or baseline-unselected
-managed views honestly remain **Not connected**. Opening Overview does not load the branch list; the first Git tab
-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
+managed views honestly remain **Not connected**. Opening Overview does not load the branch list; mounting the Git tab
+reads history against the saved branch or captured acquisition commit. Branch candidates load only when a
+selector opens; Fetch supplies its returned candidates directly. To replace that baseline, click the pencil icon beside the Base fact to open the branch
 picker: its search field sits permanently above a bounded branch list that shows roughly seven rows and
-scrolls internally, so the dialog keeps one size while you filter. Choose any local branch except the
+scrolls internally, so the dialog keeps one size while you filter. Choose any local or fetched remote branch except the
 current Worktree branch and save.
 The save replaces the persisted `baseBranch` in the plugin sidecar; the saved value becomes the default for
 the Git selector. Once the Git tab is open, changing its selector remains a transient view choice and reloads
@@ -188,19 +411,22 @@ history, changed files, and diffs without another Worktree-record write. If no u
 immutable captured acquisition commit and show that resolved commit as the Base fact; only a Worktree with
 neither a usable saved baseline nor a captured commit stays baseline-unselected and prompts you to choose
 one. When the selected branch has diverged, Git resolves the two heads' common ancestor. The
-Git & Changes view reports Worktree commits after that ancestor as `+N` ahead and base-branch commits after it
-as `-N` behind; history and file reads remain available. If the two heads have no common ancestor, the
+Git & Changes view reports Worktree commits after that ancestor as `↑ N` ahead and base-branch commits after it
+as `↓ N` behind; history and file reads remain available. If the two heads have no common ancestor, the
 committed summary falls back to the full tree diff between the base branch tip and Worktree `HEAD`, while
 history uses the Worktree commits not reachable from that base tip.
 With a valid managed Worktree baseline loaded, the Git & Changes tab initially selects **Baseline summary** rather than the
 first commit; changing the baseline branch also returns to that summary. Choose a commit or **Uncommitted
-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
+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
 Workspace root has changes. Selecting **Uncommitted changes** compares the current Workspace root with `HEAD`; it does not
 create a baseline or write any Git state.
 
-The selected local branch is resolved again for each read. The browser can choose only a plain local branch
-name, not a raw commit SHA or arbitrary Git ref: a full ref path, tag, or remote-tracking ref is rejected
-outright, while a selected branch that no longer exists shows the honest unavailable state instead of a
+The selected local or fetched remote branch is resolved again for each read. Selectors display short names and
+use the enumerated `refs/heads/...` or `refs/remotes/...` as stable identities. New remote baseline saves retain
+the exact remote ref, so adding or removing a same-named local branch cannot change the baseline.
+Legacy short names are accepted only when unambiguous; an ambiguous saved value reports
+`WORKTREE_STATE_CONFLICT` and requires selecting the intended branch again. Raw commit SHAs, tags, and
+arbitrary revision expressions remain rejected. A selected exact branch that no longer exists shows the honest unavailable state instead of a
 generic Git failure. `baseCommit` is immutable acquisition metadata, is never user-selectable directly, and
 is the implicit baseline whenever no saved branch baseline is usable; creation recovery never overwrites
 it. When a managed Worktree or Main Workspace root has staged, unstaged, or untracked files, the list prepends an
@@ -214,18 +440,32 @@ one net diff from the same comparison boundary to the current working tree, incl
 unstaged, untracked, deleted, and renamed changes. This is a
 fresh on-demand projection rather than a concatenation of two diffs. Clicking a commit shows that
 commit's own diff. For managed Worktrees and Main, turn on **Multi-select commits** in the commits header to pick several committed rows
-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
+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
 collapses the selection back to the focused commit. The changed-file list
 records the contributing commits, and each selected commit is rendered as its own diff segment; this is
 not an implicit range and does not include unselected commits. The changed-files column header shows the
 aggregate green `+N` and red `-N` totals for the current target, including the Baseline summary, selected
 commits, or Uncommitted changes; binary-only totals show Unknown. The working-tree entry remains mutually
-exclusive with committed multi-selection. The **Open in Sidebar** action in the summary diff toolbar
-reveals the current file in the native right sidebar using the current Session, only when that Session
-belongs to the Dashboard Worktree. An empty Worktree
-or an unrelated current Session cannot open a file through this action.
-
-Managed Worktree and Main history are each capped at 200 commits and mark longer histories as truncated. A changed-file list larger
+exclusive with committed multi-selection. **Open in Sidebar** is available in the diff toolbar and on
+existing changed-file rows. It uses the current Session when it belongs to the Dashboard group,
+otherwise the group's first visible Session, and explicitly expands the native right sidebar.
+With no target Session it prompts you to create one; the Overview's empty Session card includes **New Session**.
+File-tree paths, Diff titles and file requests are relative to the Workspace directory, for both Main and
+managed Worktrees. At `/repo/packages/app`, `src/index.ts` names `/repo/packages/app/src/index.ts`;
+repository-root `README.md` appears as `../../README.md`. The view retains changes across the checkout.
+Files outside the target Session cwd show a prompt instead of an invalid resource address.
+
+Main shows a local checkout status and omits derived Worktree creation-time and baseline facts.
+Ahead/Behind uses neutral commit counts (`↑ N` / `↓ N`), while added/deleted code lines keep their green/red counts.
+The sticky top bar truncates long references on one line, and only the reference text copies to the clipboard.
+
+Managed Worktree and Local/Main history load the newest 50 commits first. Scrolling to the bottom appends
+the next 50 without replacing the current selection or diff; the load-more button also supports keyboard use.
+Comparison views show the full committed total from ahead counts, independent of loaded pages.
+If HEAD or the baseline moves between pages, refresh before continuing; existing rows remain visible.
+The load-more button becomes **Refresh** after this conflict. Commit file and Diff reads also require
+a stable HEAD throughout authorization and reading.
+Multi-selection supports up to 200 selected commits. A changed-file list larger
 than the Git adapter's output bound reports an explicit truncated state instead of a generic error.
 Commit details use
 first-parent comparisons; root commits compare against the empty tree; rename and copy rows retain
@@ -251,7 +491,7 @@ and refresh behavior remains unchanged.
 
 The view is read-only and does not provide commit or staging controls. For managed Worktrees, the plugin validates committed
 entries against the selected branch-to-`HEAD` projection and re-reads working-tree paths against a fresh status projection;
-Main validates committed entries against its bounded HEAD-history projection. These endpoints are not generic Git object or file readers. Refresh keeps ready
+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
 content visible while replacement data loads, and late responses for an older commit or file selection
 are ignored.
 
@@ -265,6 +505,25 @@ Instructions stay in the plugin's own data. They are not written to the project
 `AGENTS.md` file. Clearing, detaching, cleaning, or forgetting a Worktree stops future injection; archiving
 keeps an active binding and therefore keeps its Worktree instruction effective. Unchanged instruction text is not repeatedly added while its message remains visible.
 
+### Resolve errors
+
+Failures in the Worktree list, dialogs, and Dashboard appear as native toasts in the current DSH
+language (English or Chinese). Each message explains the problem and how to recover. The list
+keeps its existing content and has no error banner or diagnostics drawer at the top.
+
+Use **Errors & recovery** in the toast, or open **Settings → Worktree → Errors & recovery**,
+to read each failure and expand its original
+diagnostics (including Git stderr). Retry reads, recover interrupted Worktree operations, retry
+Session bindings, or open retained Sessions from the same tab. Records remain after the toast
+fades; the list and Git panels have no inline error or retry controls. Closed operation views
+disable their recovery actions; reopen the corresponding view to load its current state.
+Records stay in page memory and clear on reload. **Clear history** keeps active recoveries.
+Dialogs keep input; failed instruction and baseline saves retain drafts. Git setup guidance
+stays in the creation dialog. Matching Git failures share one toast while keeping separate records.
+
+The Worktree settings section uses DSH's native tabs, status tags and compact controls. Its
+text, actions and diagnostic details follow the font size selected in **Settings → General**.
+
 ### Archive or remove a Worktree
 
 - **Archive Worktree** is non-destructive. It keeps the directory, bindings, instructions, and
@@ -293,7 +552,7 @@ keeps an active binding and therefore keeps its Worktree instruction effective.
   messages, prompts, transcripts, and history. The plugin never copies or rewrites those values.
 - The plugin's external index stores Worktree paths, branches, sources, lifecycle state, bindings,
   ordering, instructions, acquisition facts, and related metadata. For managed Worktrees, the
-  Dashboard Base fact is the persisted `baseBranch`; users can replace it with a local branch other
+  Dashboard Base fact is the persisted `baseBranch`; users can replace it with a local or fetched remote branch other
   than the current Worktree branch, and the saved value becomes the Git-tab selector default. The
   immutable acquisition `baseCommit` remains separate and is not rewritten by that edit. The index is
   kept in the DSH host plugin data directory, not in a project directory or DSH's raw data store. It
@@ -320,9 +579,13 @@ keeps an active binding and therefore keeps its Worktree instruction effective.
   (optionally including one fresh baseline-to-working-tree projection), one **Uncommitted changes**
   snapshot, changed files, and one unified diff at a time. These projections combine staged, unstaged,
   and untracked files when requested but are never written back to Git. The Dashboard does not provide
-  commit, staging, reset, revert, cherry-pick, fetch, push, pull, pull requests, graph lanes, pagination,
+  commit, staging, reset, revert, cherry-pick, push, pull, pull requests, graph lanes,
   or syntax highlighting.
-- Session rows use DSH's native status and relative-time presentation. Collapsed Workspace, Main,
+- Session rows and Dashboard cards use DSH's native status and relative-time presentation. The green
+  completion dot is DSH's unread reminder for a Session that stops outside the current main view;
+  opening that Session or running it again clears the reminder. A cold-start idle Session does not
+  count as completed. The reminder remains DSH-owned and is not persisted by this plugin.
+  Collapsed Workspace, Main,
   and Worktree groups derive one aggregate `StateDot` from their complete eligible membership (after native blank/archive filtering): waiting
   approval (and other pending-interaction warnings) takes priority over running, and running
   takes priority over completed. Idle Sessions do not contribute a group dot; Worktree health
@@ -330,10 +593,13 @@ keeps an active binding and therefore keeps its Worktree instruction effective.
   remains browser-local; Main remains fixed first, Worktree drag updates only this local order projection,
   and Main drag updates native Workspace order only after DSH accepts it.
 - Active Worktree Sessions may request the named `worktree-full-access` preset after an explicit
-  confirmation. It combines DSH `danger-full-access` with `ask`, keeps approval prompts enabled,
-  and does not change network or process policy. If unavailable, the plugin falls back to
-  `workspace-write + ask` when possible or reports an unverified, retryable state. It cannot
-  exceed the sandbox imposed by the host running DSH.
+  confirmation. The plugin appends this preset while preserving DSH's existing presets, default
+  selection, and official Auto review integration. It combines DSH `danger-full-access` with `ask`,
+  keeps approval prompts enabled, and does not change network or process policy. If unavailable, the plugin falls back to
+  `workspace-write + ask` when possible or reports an unverified, retryable state. Permission
+  services may mount late or be replaced: retry uses the currently available capabilities without
+  restarting the Worktree Host. A temporarily missing service never grants Full Access, and an
+  explicit user restriction is preserved. It cannot exceed the sandbox imposed by the host running DSH.
 - Session-to-Worktree bindings and permission checks compare physical filesystem identity on the Host (`stat`/`realpath`) rather than relying on lexical path equality. This ensures robust compatibility across Windows and macOS path variations (including drive-letter casing, forward/backward slashes, UNC paths, and extended-length prefixes like `\\?\\`). On Windows, sidecar atomic persistence uses file-handle synchronization with best-effort directory sync, and Git CLI integration cleanly handles `NUL` null-device paths and CRLF line endings.
 - Git must be installed and available on `PATH`. A missing Git executable shows install guidance
   and no command block; the plugin does not run setup or installation commands.
@@ -349,7 +615,9 @@ keeps an active binding and therefore keeps its Worktree instruction effective.
 
 Worktree mode follows DSH's current interface language. The entry point, tree, menus, dialogs,
 statuses, Dashboard labels, and retry messages are localized in English and Chinese. Workspace
-names, Session titles, branch names, paths, and raw DSH or Git errors keep their original values.
+names, Session titles, branch names, and paths keep their original values. Errors use localized
+problem and recovery guidance; unknown errors include a support code. Original diagnostics are available in Worktree settings. The plugin
+does not write them to DSH logs.
 
 ## Development
 
@@ -364,11 +632,14 @@ For architecture, local DSH integration, testing, and contribution details, see:
 The focused package commands are:
 
 ```bash
+pnpm --filter @cerbur/clutch-dsh-worktree lint
 pnpm --filter @cerbur/clutch-dsh-worktree typecheck
 pnpm --filter @cerbur/clutch-dsh-worktree build
 pnpm --filter @cerbur/clutch-dsh-worktree test
 ```
 
+Lint checks both source and test files. Resolve ESLint errors before committing.
+
 The bilingual README structure is checked with:
 
 ```bash