@norman-else/dsh-claude 0.1.51 → 0.1.52

package/INSTALL.md

@@ -1,55 +1,120 @@
-# Agent Installation Runbook
-
-This runbook is idempotent for a local `dsh-claude` checkout and an existing DSH `web` profile.
-
-## 1. Verify the checkout
-
-```sh
-cd /path/to/dsh-claude
-export PATH="/opt/homebrew/bin:$PATH"
-pnpm install
-pnpm check
-node lib/bin.mjs doctor
-```
-
-Stop if Doctor cannot find an authenticated local Claude Code installation. Do not request, copy, or write credentials.
-
-## 2. Link the bundle into the current Web profile
-
-The bundle keeps a protected compatibility preset at `$DSH_HOME/.agent-presets/claude`, because DSH Desktop 2.0.4 does not retain third-party preset roots from bundle patches. Its route uses the active profile package source to avoid duplicate client-module Loaders. User-modified preset files are preserved.
-
-```sh
-dsh plugin --profile web add "link:$(pwd)"
-```
-
-Do not start another DSH Web server. This bundle must load in the existing app at `http://127.0.0.1:56454`.
-
-## 3. Refresh and smoke test
-
-1. Refresh the existing DSH Web page.
-2. Confirm **Claude** appears in the new-session Agent Preset picker.
-3. Run one existing native preset prompt and verify it remains native.
-4. Create a Claude session and send a read-only prompt.
-5. Send one edit prompt; verify DSH displays a permission request. Exercise reject first, then allow once with a harmless temporary file.
-6. Cancel a running prompt and confirm the cancelled session owns no child `claude` process that is still executing cancelled work or left orphaned/unowned.
-7. Refresh the browser and continue the session.
-8. Restart DSH and confirm the next prompt resumes the persisted Claude session.
-
-A live prompt can consume the user's Claude subscription. Keep it minimal.
-
-## 4. Uninstall
-
-Clean up the managed preset while the profile can still execute the package CLI, then remove the plugin:
-
-```sh
-dsh plugin --profile web exec dsh-claude remove-preset
-dsh plugin --profile web remove @norman-else/dsh-claude
-```
-
-DSH has no plugin uninstall lifecycle hook, so direct package removal can leave the compatibility preset behind. After direct removal, no source checkout is required; run the matching package version:
-
-```sh
-pnpm dlx @norman-else/dsh-claude@<version> remove-preset
-```
-
-Cleanup refuses to delete user-modified preset content.
+# Installation and removal runbook
+
+Current guidance: 2026-09-14, plugin 0.1.51, development graph DSH 0.1.5-rc.2.
+
+## 1. Identify the running installation
+
+Use the DSH CLI supplied by the installation you intend to modify. Determine
+its active profile before installing: the local Desktop setup uses `desktop`;
+a standalone Web setup may use `web`. Do not create another profile or server
+to compensate for a command aimed at the wrong one. No port is assumed here.
+
+Examples below use `desktop`; substitute the actual profile throughout.
+If `dsh` is not on PATH, use that installation's CLI entry point instead.
+
+## 2. Install from npm
+
+```sh
+dsh plugin --profile desktop add @norman-else/dsh-claude
+```
+
+Wait for the profile operation to finish, then quit Desktop completely and
+reopen it. Select **Claude** in a new session. The plugin maintains a guarded
+compatibility preset at `$DSH_HOME/.agent-presets/claude`; its route uses the
+active profile package source. User-modified preset files are preserved.
+
+## 3. Install from a source checkout
+
+Requires Node.js 20 or later and pnpm. From the checkout:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+On macOS, prepend `/opt/homebrew/bin` to PATH if that is where pnpm is installed.
+PowerShell does not use the POSIX `PATH=... command` syntax.
+
+If this checkout is already linked to a running profile, finish active turns
+before rebuilding it. A build can trigger a live client reload and interrupt
+projection subscriptions. During active work, validate in a separate source
+copy with its own dependencies; do not copy its build into the live checkout.
+After a deliberate live rebuild, fully restart Desktop to verify activation.
+
+Link from PowerShell:
+
+```powershell
+dsh plugin --profile desktop add "link:$($PWD.Path.Replace('\', '/'))"
+```
+
+Or from a POSIX shell:
+
+```sh
+dsh plugin --profile desktop add "link:$(pwd)"
+```
+
+## 4. Check the local Claude CLI
+
+Claude Code owns authentication. Use its existing login or supported settings
+configuration; never request, copy, print, or store credentials in this plugin.
+
+```sh
+node lib/bin.mjs doctor
+```
+
+If discovery fails, use `doctor --executable` with the absolute native Claude
+executable path. The standalone CLI's path search is simpler than the Host
+resolver; on Windows prefer the native executable over an npm `.cmd` shim.
+
+Read each report field. A zero exit code from the standalone Doctor establishes
+version detection, not authenticated query success; its handshake is `not-run`.
+An `unknown` authentication report is inconclusive. Use Settings/Doctor inside
+DSH and a minimal real turn to verify the installed environment.
+
+Main turns, session titles, and branch summaries load `user`, `project`, and
+`local` settings. Summary calls also inherit behavior settings and use their
+own working directory (`process.cwd()`), not a borrowed session process.
+
+## 5. Smoke test after a full Desktop restart
+
+1. Confirm **Claude** appears in the new-session preset picker.
+2. Verify an existing native preset still works.
+3. Send a minimal read-only Claude prompt; confirm streaming, final output, and title.
+4. Under an access mode that requires approval, exercise deny and allow-once
+   with a harmless temporary edit. Full access intentionally bypasses ordinary approvals.
+5. Test a user question and plan review; both must remain available under Full access.
+6. Stop a running turn, then send another prompt; confirm cleanup and continuity.
+7. Restart Desktop and continue the same conversation to verify resume.
+8. Open diff, plan, tasks, and overview tabs in the right sidebar; exercise
+   fullscreen and close. Check command completion, prompt controls, and queue UI.
+9. In a disposable repository, verify worktree creation and naming. Preserve
+   needed changes before deleting its workspace: managed-worktree reconciliation
+   can remove dirty files. Merged-branch cleanup is a separate guarded action.
+10. Read the new Host log for `dsh-claude client [boot-check]`,
+    `[slot-entry-crashed]`, and plugin refresh failures.
+
+On the current Windows Desktop, Host logs are under
+`%APPDATA%/DSH Desktop/logs/host/`; shell startup logs are one directory above.
+Record what was actually exercised. A source audit or green unit tests do not
+establish successful real authentication, approval, streaming, or resume.
+
+## 6. Remove the plugin
+
+Clean up the compatibility preset while the profile still resolves the package:
+
+```sh
+dsh plugin --profile desktop exec dsh-claude remove-preset
+dsh plugin --profile desktop remove @norman-else/dsh-claude
+```
+
+DSH has no plugin uninstall lifecycle hook. Direct package removal can leave
+the compatibility preset behind. If necessary, invoke the matching version's
+CLI with the same `DSH_HOME` and inspect its result:
+
+```sh
+pnpm dlx @norman-else/dsh-claude@<installed-version> remove-preset
+```
+
+Cleanup refuses user-modified presets; review them manually rather than forcing
+removal. Restart Desktop after uninstalling. Removing the plugin does not mean
+all Claude transcripts, sidecars, settings, or worktrees have been deleted.

package/LICENSE

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

package/README.md

@@ -10,7 +10,7 @@ Claude Code remains responsible for its agent loop, tools, `CLAUDE.md`, Skills,
 
 ### Requirements
 
-- DeepSeek Harness Desktop with compatible public plugin APIs. This package is currently developed against the DSH `0.1.5-rc.1` package line (DSH Desktop 2.0.7). Plugin 0.1.37 and later import symbols that do not exist on `0.1.1-rc.2`; a Host still on that line must pin `@norman-else/dsh-claude@0.1.36`.
+- DeepSeek Harness Desktop with compatible public plugin APIs. This package is currently developed against the DSH `0.1.5-rc.2` package line (DSH Desktop 2.0.10). Plugin 0.1.37 and later import symbols that do not exist on `0.1.1-rc.2`; a Host still on that line must pin `@norman-else/dsh-claude@0.1.36`.
 - A local Claude Code installation that is already authenticated.
 - Node.js 20 or later when installing from a source checkout.
 
@@ -18,13 +18,13 @@ The plugin never asks for or stores Claude credentials. Authenticate through the
 
 ### Install from npm
 
-Add the published package to the DSH Web profile:
+Add the published package to the profile used by your running DSH instance. The commands below use `desktop`; replace it with `web` only for an existing Web profile. Use the DSH CLI supplied by that installation:
 
 ```sh
-dsh plugin --profile web add @norman-else/dsh-claude
+dsh plugin --profile desktop add @norman-else/dsh-claude
 ```
 
-Wait for the profile rebuild to finish, then restart DSH Desktop if requested. Create a new conversation and select **Claude** from the Agent Preset picker.
+Wait for the profile rebuild to finish, then quit DSH Desktop completely and reopen it. Create a new conversation and select **Claude** from the Agent Preset picker.
 
 ### Install from source
 
@@ -35,16 +35,18 @@ pnpm install
 pnpm check
 ```
 
+For a checkout already linked to a running Desktop, run builds only after its turns have finished: rebuilding can hot-reload the plugin. Use a separate source copy for validation during active work. See [INSTALL.md](INSTALL.md).
+
 Link the checkout to DSH from PowerShell:
 
 ```powershell
-dsh plugin --profile web add "link:$PWD"
+dsh plugin --profile desktop add "link:$($PWD.Path.Replace('\', '/'))"
 ```
 
 Or from macOS/Linux:
 
 ```sh
-dsh plugin --profile web add "link:$(pwd)"
+dsh plugin --profile desktop add "link:$(pwd)"
 ```
 
 ### Remove the plugin
@@ -52,8 +54,8 @@ dsh plugin --profile web add "link:$(pwd)"
 Remove the managed compatibility preset before removing the package:
 
 ```sh
-dsh plugin --profile web exec dsh-claude remove-preset
-dsh plugin --profile web remove @norman-else/dsh-claude
+dsh plugin --profile desktop exec dsh-claude remove-preset
+dsh plugin --profile desktop remove @norman-else/dsh-claude
 ```
 
 DSH does not currently expose a plugin uninstall lifecycle hook. If the package was removed before its managed preset was cleaned up, run the matching installed version directly:
@@ -69,12 +71,12 @@ Preset cleanup removes only installer-managed content and refuses to delete user
 ### 3.1 Conversation
 
 - **Native Claude Code conversations** — Runs Claude Code as the main agent in a normal DSH conversation instead of wrapping it as a tool or secondary chat.
-- **Claude preset and model selection** — Adds a `Claude` Agent Preset and exposes Claude Code's `default`, `opus[1m]`, `fable`, `sonnet`, and `haiku` model choices.
+- **Claude preset and model selection** — Adds a `Claude` Agent Preset and reads Claude Code's model catalog. `default`, `opus[1m]`, `fable`, `sonnet`, and `haiku` are fallback choices when the catalog is unavailable.
 - **Thinking effort** — Maps DSH's per-model reasoning effort onto Claude Code's thinking modes — `off`, `low`, `medium`, `high` (Claude Code's own default), `xhigh`, `max`, and `ultracode` — so the conversation's effort control drives extended thinking directly. Models that do not support a mode downgrade silently inside Claude Code; `ultracode` additionally turns on standing dynamic-workflow orchestration and needs an `xhigh`-capable model.
 - **Local Claude environment compatibility** — Preserves the user's existing Claude Code authentication, settings, `CLAUDE.md`, Skills, Hooks, Plugins, tools, and MCP configuration.
 - **Real-time streaming and conversation continuity** — Streams Claude responses and tool activity into DSH while retaining multi-turn context and persisted Claude session resume.
 - **DSH permissions and questions** — Routes Claude tool permission requests through DSH approvals and Claude clarification prompts through DSH's native question forms.
-- **Plan review** — Under read-only access Claude works in plan mode, and the plan it hands back is read in a plugin-owned panel in the details column, rendered as Markdown under the prose palette chosen in this plugin's settings. The approval itself stays with DSH: its dialog names the decision and points at the panel instead of pasting the plan into a plain-text modal, and it is asked even under Full access — that setting waives actions, not the decision the plan was written to put in front of the user. Full access silences approvals outright (`approval/policy: never`, answered before any surface is shown), so the ask is un-silenced for as long as the plan is open and the session's own policy is put back afterwards. Approving and rejecting are the only answers the dialog has, and neither is "change this", so the panel adds the third: select a passage, write what should change, and send the plan back — the notes reach Claude as the reason it was refused, and the dialog closes itself. A session that proposes more than once keeps every plan: the panel heading becomes a picker listing each with its own decision, and a fresh proposal awaiting approval takes the panel back. The Session header carries a plan toggle, dotted while a plan is still waiting on its decision, and the turn's tool card carries the same plan.
+- **Plan review** — Under read-only access Claude works in plan mode, and the plan it hands back is read in a plugin-owned panel in a right-sidebar tab, rendered as Markdown under the prose palette chosen in this plugin's settings. The approval itself stays with DSH: its dialog names the decision and points at the panel instead of pasting the plan into a plain-text modal, and it is asked even under Full access — that setting waives actions, not the decision the plan was written to put in front of the user. Full access silences approvals outright (`approval/policy: never`, answered before any surface is shown), so the ask is un-silenced for as long as the plan is open and the session's own policy is put back afterwards. Approving and rejecting are the only answers the dialog has, and neither is "change this", so the panel adds the third: select a passage, write what should change, and send the plan back — the notes reach Claude as the reason it was refused, and the dialog closes itself. A session that proposes more than once keeps every plan: the panel heading becomes a picker listing each with its own decision, and a fresh proposal awaiting approval takes the panel back. The Session header carries a plan toggle, dotted while a plan is still waiting on its decision, and the turn's tool card carries the same plan.
 - **Claude command bridge** — Publishes Claude Code's own command catalog into the DSH command palette, retrying with backoff while a fresh CLI finishes loading Skills and Plugins.
 - **Prompt snippets** — Keeps the half-written messages a user retypes every day as ordinary Markdown files in `~/.claude/prompts`, one per file, and offers them as a second `/` group beside the Claude command catalog. Picking one drops its text into the composer instead of sending it, so the draft stays editable — a snippet is a message the user finishes, not a command that runs. A control in the composer's own tool row, beside the attach and access controls, saves the current draft as a new snippet: it offers the draft's opening line as the file name and names the file it wrote. It costs the layout nothing — a docked row would move the composer on every keystroke — and an existing name is never overwritten. The derived name is only the starting point: a Claude Haiku call names the snippet properly and replaces it when it lands, unless the user has already started typing, and a failed or slow suggestion is a non-event because a working name was there from the first frame. That call runs with extended thinking off, which is what keeps it around three seconds rather than ten.
 - **Rewrite a draft with AI** — A second control in the same tool row hands the current draft to Claude Haiku and replaces it with a version an agent can act on without asking follow-up questions, keeping every concrete detail the original carried. `SessionInput.setDraft` merges into the editor's undo history rather than adding a step to it, so Ctrl/Cmd+Z would not bring the original back: the button holds it instead, and offers it back for as long as the rewrite is still on screen unedited. The rewrite is told to leave every reference to a person as written — asked to rewrite "assign it to me", the model otherwise reaches into Claude Code's ambient context and substitutes the operator's real email address. Editing, renaming, and deleting happen in the user's own editor, and a file added there shows up in the menu without a reload.
@@ -83,24 +85,25 @@ Preset cleanup removes only installer-managed content and refuses to delete user
 - **Ask about a selection** — Answers a question about any selected text through a read-only side query limited to `Read`, `Grep`, and `Glob`, reusing the session's model and thinking mode, with the answer copyable or sendable into the main conversation.
 - **Redacted activity timeline** — Displays thinking summaries, tool calls and results, permission events, questions, status changes, usage, errors, and subagent activity without persisting credentials.
 - **Selectable AI output renderer** — Draws Claude's output either with this plugin's own transcript (interleaved prose, grouped tool cards, activity rows) or with DSH's native conversation renderer, where prose arrives as ordinary assistant text blocks, thinking as reasoning blocks, and root Claude tools as native tool cards (terminal, diff, search, read). Chosen in Settings and applied from the next turn; the plugin transcript remains the default, and turns already recorded keep the renderer that drew them.
+- **Automatic session titles and branch names** — Uses separate one-turn Haiku queries to summarize the first message or worktree intent. Both load `user`, `project`, and `local` settings like the main conversation, including settings-based authentication and behavior configuration. An error result keeps DSH's fallback title or the generated timestamped branch name. These queries do not borrow the main conversation process.
 - **Background task tracking** — Shows running and completed Claude subagents or background tasks with task status, recent tools, and expandable activity.
-- **Context usage** — Tracks how much of the context window a session has consumed and surfaces it as a percentage in the conversation and on the session board.
+- **Context usage** — Collects aggregate context-window usage from Claude Code and shows it on the session board. It does not register a separate context-meter slot beside the model selector.
 - **Turn accounting** — Closes each turn the plugin transcript drew with the footer DSH gives only its own messages: tokens, cache hit rate, wall time, time to first token, and cumulative cost. The timings are measured as the turn runs, because activity records carry no clock of their own.
 - **Managed process lifecycle** — Keeps one live Claude process per active session, serializes turns, evicts idle processes, queues user turns FIFO when every process slot is busy, converges safely after the limit is lowered, and handles Stop, cancellation, restart, and process-tree cleanup.
 - **Bilingual interface** — Ships every user-facing string in both English and Chinese.
 
 ### 3.2 Repository, worktrees, and pull requests
 
-- **Repository and worktree preparation** — Lets a user choose a branch before submitting, switch an eligible local branch, or create a dedicated Git worktree and DSH workspace while transferring the current draft and attachments, and removes a worktree's directory automatically once its workspace is deleted and the tree is clean.
+- **Repository and worktree preparation** — Lets a user choose a branch before submitting, switch an eligible local branch, or create a dedicated Git worktree and DSH workspace while transferring the current draft and attachments, and reconciles plugin-managed worktrees after their workspace is deleted. That deletion can remove a dirty worktree with `--force`; commit or preserve needed files before deleting the workspace. The separate merged-branch cleanup action requires a clean tree and checks for unpushed commits.
 - **Branch picker** — Lists the repository's local and remote-tracking branches, filters them as the user types, and refreshes from the remote on demand so a branch created elsewhere becomes selectable without leaving DSH.
 - **Jira-driven sessions** — Connects to Jira Cloud and starts work from a ticket: the branch is named after the ticket key, the composer is seeded with the ticket brief, the ticket is assigned to the user once the worktree exists, and several tickets can be kicked off at once, each in its own worktree session.
 - **Repository and pull request status** — Shows the current repository, branch, worktree state, changed-line counts, unpushed commits, GitHub pull request, checks, review state, merge state, and blocking Claude rate limits near the composer.
 - **Session board** — Summarizes every Claude session in one place with its run state, branch, pull request, context usage, auto-fix state, and whether it is waiting on an approval or an answer.
 - **Session alerts** — Raises a desktop notification when a session the user is not looking at starts waiting on an approval or an answer, or finishes its turn; clicking it brings that session up. The session on screen never raises one, a prompt is announced once, and the whole thing is switched off from Settings.
-- **Branch diff viewer** — Provides an expandable or maximized branch diff with file statistics, expand-all and collapse-all, on-demand unmodified context, and comment-to-comment navigation.
+- **Branch diff viewer** — Provides a branch diff in a right-sidebar tab, with Host-managed fullscreen with file statistics, expand-all and collapse-all, on-demand unmodified context, and comment-to-comment navigation.
 - **Line-level review comments** — Records the user's own line or range comments against the diff and attaches them to the next Claude message.
 - **GitHub review threads** — Reads, replies to, resolves, and unresolves pull request review threads inline, with `@` completion for repository members, bot authors marked as such, and a link back to the thread on GitHub.
-- **Commit, push, merge, and pull request actions** — Supports Commit, Commit & Push, Push, draft pull request creation, and merging a pull request as a merge commit, squash, or rebase, with repository snapshot validation and optional Claude-generated commit messages.
+- **Commit, push, merge, and pull request actions** — Supports Commit, Commit & Push, Push, draft pull request creation, and merging a pull request as a merge commit, squash, or rebase, with repository snapshot validation and Claude-written text. The commit message is written from the diff it commits: a subject line, and when the diff carries more than one independent change, a bullet per change under it; the repository's recent subjects are shown for style only, and a diff too long to send is marked as cut short rather than passed off as whole. The pull request is described from the branch rather than the tree: its commits and diff against the base branch (the one named in the dialog, else origin's default), plus whatever the commit before it adds, produce their own title and a Summary and Changes body with one bullet per independent change, so a pull request opened from already committed work is no longer described from an empty diff.
 - **Branch updates** — Updates the current branch from its base by rebase (pushed with `--force-with-lease`) or merge, and hands any resulting conflicts to Claude to resolve.
 - **Pull request feedback handoff** — Expands failing check details and GitHub pull request comments and hands either of them to Claude as a fix request.
 - **Auto fix** — Watches an open pull request for new review comments and failing checks, hands each new batch to Claude to fix, commit, and push, and keeps going until everything passes or the watcher is switched off.
@@ -112,7 +115,7 @@ Preset cleanup removes only installer-managed content and refuses to delete user
 - **Plan usage** — Reports the signed-in subscription's utilization windows — five-hour, weekly across all models, and weekly per model — with reset countdowns, degrading to unavailable rather than failing on API-key, Bedrock, and Vertex sessions.
 - **Bounded requests and a rationed connection pool** — Caps the plugin's share of the browser's per-origin connections so its own panels can never starve each other or the Host, and gives every route a declared time budget — answers from memory, local Git work, and calls that reach the network each get their own — with the client waiting one round trip longer than the server, so a slow operation reports which budget elapsed instead of hanging in the browser's queue.
 - **Plugin updates** — Checks npm for new releases and updates in place, only when the installation is uniquely identified; local development links are never replaced.
-- **Managed preset compatibility** — Installs a guarded Claude preset whose route reuses the active profile package source, preserving discovery on DSH Desktop 2.0.4 without duplicate client-module Loaders or overwriting user changes.
+- **Managed preset compatibility** — Installs a guarded Claude preset whose route reuses the active profile package source, preserving discovery on Desktop versions that do not retain third-party preset roots without duplicate client-module Loaders or overwriting user changes.
 
 ## 4. Contributing
 
@@ -197,3 +200,10 @@ The type is declared through the label and the `Type:` line rather than a title
 - A failing or unrun `pnpm check`.
 - Anything that logs, persists, or renders credentials, including in tests and fixtures.
 - Version bumps, release script edits, or publish attempts from a contribution branch.
+
+## 5. Documentation
+
+- [Installation and removal](INSTALL.md): profile selection, safe source builds, Doctor, and smoke checks.
+- [Current architecture](docs/aegis/spec/2026-08-15-dsh-claude-spec.md): behavior and ownership boundaries, maintained despite the original filename.
+- [Desktop upgrades](docs/upgrading-dsh-desktop.md): installed-Host audit and verification procedure.
+- [Documentation index](docs/aegis/INDEX.md): distinguishes current guidance from historical plans and evidence.

package/cordis.patch.yml

@@ -1,12 +1,12 @@
-# dsh-claude host bundle. The preset stays inside this package as a system
-# preset, so removing the profile dependency removes the complete integration.
-- id: agent-presets
-  config:
-    default: standard
-    roots:
-      - path: !!js "process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(ctx.baseUrl).resolve('@norman-else/dsh-claude/package.json')), 'preset')"
-        trust: system
-
-- insert:
-    - id: llm-claude
-      name: '@norman-else/dsh-claude'
+# dsh-claude host bundle. The preset stays inside this package as a system
+# preset, so removing the profile dependency removes the complete integration.
+- id: agent-presets
+  config:
+    default: standard
+    roots:
+      - path: !!js "process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(ctx.baseUrl).resolve('@norman-else/dsh-claude/package.json')), 'preset')"
+        trust: system
+
+- insert:
+    - id: llm-claude
+      name: '@norman-else/dsh-claude'

package/legacy-preset/agent.cordis.yml

@@ -1,11 +1,11 @@
-# Shipped by dsh-claude. Claude Code owns the inner agent loop and tools;
-# this system preset contributes only the request-route override. DSH resolves
-# the bare package specifier from the host profile when mounting system roots.
-- id: claude-code-route
-  name: '@norman-else/dsh-claude/preset-route'
-  # Entry-local isolate realm: each session's preset mount gets its own
-  # claudeCommands service instance (keeps mountPreset's leaked-service check
-  # happy and prevents cross-session collisions). The host reads it through
-  # dsh-agent-presets' serviceForAgent().
-  isolate:
-    claudeCommands: true
+# Shipped by dsh-claude. Claude Code owns the inner agent loop and tools;
+# this system preset contributes only the request-route override. DSH resolves
+# the bare package specifier from the host profile when mounting system roots.
+- id: claude-code-route
+  name: '@norman-else/dsh-claude/preset-route'
+  # Entry-local isolate realm: each session's preset mount gets its own
+  # claudeCommands service instance (keeps mountPreset's leaked-service check
+  # happy and prevents cross-session collisions). The host reads it through
+  # dsh-agent-presets' serviceForAgent().
+  isolate:
+    claudeCommands: true

package/legacy-preset/preset.yml

@@ -1,4 +1,4 @@
-# Shipped by dsh-claude. Copy this system preset under a new id to customize it.
-name: Claude
-description: Use the local Claude Code as the complete agent runtime inside DSH.
-order: 10
+# Shipped by dsh-claude. Copy this system preset under a new id to customize it.
+name: Claude
+description: Use the local Claude Code as the complete agent runtime inside DSH.
+order: 10

package/lib/bin.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bin.mjs","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { access } from 'node:fs/promises'\nimport { constants } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { delimiter, isAbsolute, join } from 'node:path'\nimport { spawnSync } from 'node:child_process'\nimport { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'\nimport { parseClaudeVersion } from './executable.ts'\nimport { ensureManagedPreset, removeManagedPreset } from './preset-installer.ts'\n\nfunction option(name: string): string | undefined {\n  const index = process.argv.indexOf(name)\n  return index < 0 ? undefined : process.argv[index + 1]\n}\n\nasync function executable(configured?: string): Promise<string | undefined> {\n  const candidates: string[] = []\n  if (configured !== undefined) candidates.push(configured)\n  else {\n    for (const directory of (process.env.PATH ?? '').split(delimiter)) {\n      if (directory.length > 0) candidates.push(join(directory, 'claude'))\n    }\n    candidates.push(join(homedir(), '.local', 'bin', 'claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude')\n  }\n  for (const candidate of [...new Set(candidates)]) {\n    if (!isAbsolute(candidate)) continue\n    try {\n      await access(candidate, constants.X_OK)\n      return candidate\n    } catch {\n      // Continue to the next documented candidate.\n    }\n  }\n  return undefined\n}\n\nfunction run(executablePath: string, args: string[]) {\n  return spawnSync(executablePath, args, {\n    encoding: 'utf8',\n    env: scrubbedParentEnv(),\n    timeout: 15_000,\n    windowsHide: true,\n  })\n}\n\nasync function doctor(): Promise<number> {\n  const configured = option('--executable') ?? process.env.DSH_CLAUDE_CODE_EXECUTABLE\n  const path = await executable(configured)\n  if (path === undefined) {\n    process.stdout.write(`${JSON.stringify({\n      executable: { status: 'missing', searched: configured === undefined ? ['claude', '~/.local/bin/claude', '/opt/homebrew/bin/claude', '/usr/local/bin/claude'] : [configured] },\n      version: { status: 'not-run' },\n      authentication: { status: 'not-run' },\n      message: 'Set executablePath to an absolute Claude Code CLI path',\n    }, null, 2)}\\n`)\n    return 1\n  }\n  const versionProbe = run(path, ['--version'])\n  const version = parseClaudeVersion(`${versionProbe.stdout ?? ''}\\n${versionProbe.stderr ?? ''}`)\n  const authProbe = run(path, ['auth', 'status', '--json'])\n  let authentication: Record<string, unknown> = { status: 'unknown' }\n  if (authProbe.status === 0) {\n    try {\n      const value = JSON.parse(authProbe.stdout) as Record<string, unknown>\n      authentication = {\n        status: value.loggedIn === true ? 'signed-in' : 'signed-out',\n        ...(typeof value.authMethod === 'string' ? { method: value.authMethod } : {}),\n        ...(typeof value.apiProvider === 'string' ? { provider: value.apiProvider } : {}),\n        ...(typeof value.subscriptionType === 'string' ? { subscription: value.subscriptionType } : {}),\n      }\n    } catch {\n      authentication = { status: 'unknown', message: 'Authentication status was not valid JSON' }\n    }\n  }\n  process.stdout.write(`${JSON.stringify({\n    executable: { status: 'found', path },\n    version: version === undefined ? { status: 'error' } : { status: 'ok', value: version },\n    authentication,\n    handshake: 'not-run',\n  }, null, 2)}\\n`)\n  return version === undefined ? 1 : 0\n}\n\nasync function main(): Promise<number> {\n  const command = process.argv[2] ?? 'doctor'\n  if (command === 'doctor') return doctor()\n  if (command === 'install-preset') {\n    process.stdout.write(`${await ensureManagedPreset()}\\n`)\n    return 0\n  }\n  if (command === 'remove-preset') {\n    process.stdout.write(`${await removeManagedPreset()}\\n`)\n    return 0\n  }\n  process.stderr.write(`Usage: dsh-claude [doctor [--executable PATH] | install-preset | remove-preset]\\n`)\n  return 2\n}\n\ntry {\n  process.exitCode = await main()\n} catch (error) {\n  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`)\n  process.exitCode = 1\n}\n"],"mappings":"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"}
+{"version":3,"file":"bin.mjs","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\r\n\r\nimport { access } from 'node:fs/promises'\r\nimport { constants } from 'node:fs'\r\nimport { homedir } from 'node:os'\r\nimport { delimiter, isAbsolute, join } from 'node:path'\r\nimport { spawnSync } from 'node:child_process'\r\nimport { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'\r\nimport { parseClaudeVersion } from './executable.ts'\r\nimport { ensureManagedPreset, removeManagedPreset } from './preset-installer.ts'\r\n\r\nfunction option(name: string): string | undefined {\r\n  const index = process.argv.indexOf(name)\r\n  return index < 0 ? undefined : process.argv[index + 1]\r\n}\r\n\r\nasync function executable(configured?: string): Promise<string | undefined> {\r\n  const candidates: string[] = []\r\n  if (configured !== undefined) candidates.push(configured)\r\n  else {\r\n    for (const directory of (process.env.PATH ?? '').split(delimiter)) {\r\n      if (directory.length > 0) candidates.push(join(directory, 'claude'))\r\n    }\r\n    candidates.push(join(homedir(), '.local', 'bin', 'claude'), '/opt/homebrew/bin/claude', '/usr/local/bin/claude')\r\n  }\r\n  for (const candidate of [...new Set(candidates)]) {\r\n    if (!isAbsolute(candidate)) continue\r\n    try {\r\n      await access(candidate, constants.X_OK)\r\n      return candidate\r\n    } catch {\r\n      // Continue to the next documented candidate.\r\n    }\r\n  }\r\n  return undefined\r\n}\r\n\r\nfunction run(executablePath: string, args: string[]) {\r\n  return spawnSync(executablePath, args, {\r\n    encoding: 'utf8',\r\n    env: scrubbedParentEnv(),\r\n    timeout: 15_000,\r\n    windowsHide: true,\r\n  })\r\n}\r\n\r\nasync function doctor(): Promise<number> {\r\n  const configured = option('--executable') ?? process.env.DSH_CLAUDE_CODE_EXECUTABLE\r\n  const path = await executable(configured)\r\n  if (path === undefined) {\r\n    process.stdout.write(`${JSON.stringify({\r\n      executable: { status: 'missing', searched: configured === undefined ? ['claude', '~/.local/bin/claude', '/opt/homebrew/bin/claude', '/usr/local/bin/claude'] : [configured] },\r\n      version: { status: 'not-run' },\r\n      authentication: { status: 'not-run' },\r\n      message: 'Set executablePath to an absolute Claude Code CLI path',\r\n    }, null, 2)}\\n`)\r\n    return 1\r\n  }\r\n  const versionProbe = run(path, ['--version'])\r\n  const version = parseClaudeVersion(`${versionProbe.stdout ?? ''}\\n${versionProbe.stderr ?? ''}`)\r\n  const authProbe = run(path, ['auth', 'status', '--json'])\r\n  let authentication: Record<string, unknown> = { status: 'unknown' }\r\n  if (authProbe.status === 0) {\r\n    try {\r\n      const value = JSON.parse(authProbe.stdout) as Record<string, unknown>\r\n      authentication = {\r\n        status: value.loggedIn === true ? 'signed-in' : 'signed-out',\r\n        ...(typeof value.authMethod === 'string' ? { method: value.authMethod } : {}),\r\n        ...(typeof value.apiProvider === 'string' ? { provider: value.apiProvider } : {}),\r\n        ...(typeof value.subscriptionType === 'string' ? { subscription: value.subscriptionType } : {}),\r\n      }\r\n    } catch {\r\n      authentication = { status: 'unknown', message: 'Authentication status was not valid JSON' }\r\n    }\r\n  }\r\n  process.stdout.write(`${JSON.stringify({\r\n    executable: { status: 'found', path },\r\n    version: version === undefined ? { status: 'error' } : { status: 'ok', value: version },\r\n    authentication,\r\n    handshake: 'not-run',\r\n  }, null, 2)}\\n`)\r\n  return version === undefined ? 1 : 0\r\n}\r\n\r\nasync function main(): Promise<number> {\r\n  const command = process.argv[2] ?? 'doctor'\r\n  if (command === 'doctor') return doctor()\r\n  if (command === 'install-preset') {\r\n    process.stdout.write(`${await ensureManagedPreset()}\\n`)\r\n    return 0\r\n  }\r\n  if (command === 'remove-preset') {\r\n    process.stdout.write(`${await removeManagedPreset()}\\n`)\r\n    return 0\r\n  }\r\n  process.stderr.write(`Usage: dsh-claude [doctor [--executable PATH] | install-preset | remove-preset]\\n`)\r\n  return 2\r\n}\r\n\r\ntry {\r\n  process.exitCode = await main()\r\n} catch (error) {\r\n  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`)\r\n  process.exitCode = 1\r\n}\r\n"],"mappings":"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"}

package/lib/client.d.ts

@@ -229,9 +229,6 @@ declare const en: {
   readonly presetHeaderHint: "The agent preset this session runs";
   readonly diffRepository: "Repository";
   readonly repositoryLinked: "Linked repository: changed by this session";
-  readonly linkedMore: "{count} more linked repositories";
-  readonly linkedShowAll: "Show all";
-  readonly linkedCollapse: "Collapse linked repositories";
   readonly linkedRepositoryPrompt: "The following concerns the linked repository at {root} (branch {branch}), not this session's own checkout.";
   readonly diffFiles: "{count} modified file(s)";
   readonly diffFilesShort: "{count} files";