@wingsky-1/dsh-worktree-sidebar 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wingsky-1
+
+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.en.md

@@ -0,0 +1,186 @@
+# @wingsky-1/dsh-worktree-sidebar
+[![npm](https://img.shields.io/npm/v/@wingsky-1/dsh-worktree-sidebar)](https://www.npmjs.com/package/@wingsky-1/dsh-worktree-sidebar)
+[![GitHub Releases](https://img.shields.io/github/v/release/wingsky-1/dsh-plugin-hub)](https://github.com/wingsky-1/dsh-plugin-hub/releases)
+
+Three tools that let the agent bind a **git worktree** to the current session, so that session's right-sidebar file tree is rooted at that worktree — **without changing the session cwd**.
+
+This is a **transitional adapter**: if the official product ships native worktree sessions, this plugin retires.
+How it works (five host domains, host/client chains, self-healing rules, the six things to remember) is documented in [docs/architecture/dsh-worktree-sidebar.md](../../docs/architecture/dsh-worktree-sidebar.md).
+
+## What it does
+
+The right sidebar's file tree is always rooted at `session.header.cwd`, and that field is immutable once the session is created (adopting a session with a different cwd throws `ApiSessionCwdConflict`). So when a session runs in the main checkout while the actual work happens in a worktree, the tree shows the wrong place.
+
+The plugin exposes three tools to the agent:
+
+| Tool | Effect |
+|---|---|
+| `ws_worktree_register` | Bind an **existing** worktree to the current session |
+| `ws_worktree_create` | Run `git worktree add` first, then bind (path and branch come from the caller; the plugin imposes no layout convention); an optional `base` picks the start point, defaulting to the current HEAD of the repository the session working directory is in |
+| `ws_worktree_remove` | Drop the binding; only removes the directory via `git worktree remove` when explicitly asked |
+
+Once bound, **open or refresh** the Files tab and it lists the worktree; opening a file previews the worktree's copy.
+The tab does **not** follow automatically: the plugin does not poll the host, and re-reads the binding only when you open the tab, hit the built-in refresh, or the window becomes visible/focused again.
+
+Subagent sessions **and user-forked sessions** inherit their parent's binding: a session without a binding of its own roots its Files tab at the worktree of the **first session up the parent chain that holds a registration** (the walk stops at the top, and falls back to the session's own cwd once that registration is dropped). The criterion is the header's `parentSession`, and the plugin deliberately does not tell the two shapes apart — a fork copies the parent's cwd, so inheriting the view root keeps it consistent with "the file root is a rewrite of the session cwd".
+
+Tools are exposed to **every agent inside a git repository, subagents included**, decided per agent when it is created; a second check at execution time covers environments that changed in between. Each tool's result text states which worktree is bound and on which branch, so the model need not call another tool to confirm.
+
+`ws_worktree_create`'s `base` is a commit-ish (branch, tag, SHA — e.g. `origin/main`). Its shape is checked first (a value starting with `-` is rejected), then it is normalized to a SHA before git sees it: after `<path>`, git **restarts option parsing** (measured: `base: "-f"` / `"--force"` reports success yet checks out HEAD), and a normalized SHA gives that parsing nothing to latch onto.
+
+## Explicit non-goals (known inconsistencies)
+
+These are deliberate trade-offs of "change only the view root", not a backlog:
+
+- `@` file references, `present` targets and the skill catalog **still anchor `session.header.cwd`**. The tree points at the worktree while `@` lists the main checkout — the most easily misunderstood part of this plugin.
+- **Under the `workspace-write` file policy the agent cannot write into the worktree**: the write fence's `sandboxPolicy.workspaceRoot` also derives from `header.cwd`, and that service cannot be replaced by a third-party plugin. Use `danger-full-access`, or open the session inside the worktree.
+- **No diff marker** for same-named files between the main checkout and the worktree.
+- "Tree root = worktree, execution cwd = original directory" is this design's premise. The agent's commands still run in the original cwd.
+- The rewritten session view **affects only the single entry this plugin registers**: the client attaches the rewrite to `hooks.sessions` of the official entry inject face, so only that one entry's inject face is affected; every other `useSessions` consumer (preview, command palette, `@`, ...) still sees the session's real cwd. That is a direct consequence of "change only the view root", not a backlog item.
+
+## Install
+
+Requires DeepSeek Harness with a working `dsh web` (see "dsh not installed globally" otherwise).
+
+### Install the plugin (add)
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+```
+
+### Remove the plugin (remove)
+
+```sh
+dsh plugin --profile web remove @wingsky-1/dsh-worktree-sidebar
+```
+
+After removal the binding table remains at `<DSH_HOME>/@wingsky-1/dsh-worktree-sidebar/bindings.json` but has no effect. Worktrees you created are **not** deleted; clean up yourself if needed:
+
+```sh
+git worktree list          # see what is left
+git worktree prune         # drop registrations whose directory was deleted by hand
+```
+
+### Update the plugin (update)
+
+```sh
+dsh plugin --profile web update @wingsky-1/dsh-worktree-sidebar
+```
+
+> Install / remove / update each require **one restart** of `dsh web` (bundles are composed at startup only).
+
+### Pin a version (@version)
+
+Omit `@version` to install latest (recommended). Append it only when the registry lags or a specific release misbehaves in your environment:
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar@<version>
+```
+
+### dsh not installed globally
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+npx @deepseek-ai/dsh plugin --profile web remove @wingsky-1/dsh-worktree-sidebar
+npx @deepseek-ai/dsh plugin --profile web update @wingsky-1/dsh-worktree-sidebar
+```
+
+## Configuration
+
+- A single master switch `enabled` comes in via the plugin config (`WorktreeSidebarConfig`, `src/index.ts:41-45`): with `enabled === false` nothing is taken over, no tools are registered, no routes are mounted (`src/index.ts:98`); omitting it enables the plugin.
+- The plugin never reads a user config file from disk; it owns its binding table at `<DSH_HOME>/@wingsky-1/dsh-worktree-sidebar/bindings.json`, derived from the single variable `DSH_HOME` (`src/server/shared/paths.ts:9-17`).
+- `ws_worktree_create`'s `base` defaults to the current HEAD of the repository the session working directory is in; an explicit `base` is shape-checked (a leading `-` is rejected) and normalized to a SHA before reaching git, so the start point cannot be silently dropped.
+- `base` is a commit-ish (branch, tag, SHA, e.g. `origin/main`); an omitted branch adds an explicit `--detach`, checking out the start point detached without creating a branch.
+- With `enabled === false` the binding table is not even read; existing registrations stay on disk with no effect.
+
+## Contract
+
+- Only two things must agree on both ends, defined once in `src/shared/contract.ts:12-28`: route paths (`ROUTES`) and the binding-query response shape (`BindingResponse`); routes are additionally injected into the client at build time via `__DSH_ROUTES__`, keeping both ends consistent. See §2.4 of the architecture doc.
+- Both routes are GET and read-only: `GET /api/dsh-worktree-sidebar/bindings?session=<id>` answers `{ revision, worktreePath | null }`; `GET /api/dsh-worktree-sidebar/health` answers `{ ok, revision, scopeTakeover, scopeChain }` (`src/server/api/impl/handlers/index.ts:24-67`).
+- Minimal exposure: the binding query never returns `repoRoot` — the client only needs the directory root; a missing `session` parameter is a 400, never an empty answer that could be misread as "unbound" (`handlers/index.ts:1-8`, `30-34`).
+- `revision` is a content version, not a write counter: an empty table starts at 0, storing one binding bumps it by one; dropping a nonexistent target returns the table unchanged without bumping (`src/server/binding/impl/model/index.ts:10-13`, `67-86`).
+- The client only compares for equality and guards monotonicity: no notification when revision and path are unchanged, and a smaller revision arriving out of order is discarded (`src/client/bindings.ts:40-48`).
+- The query endpoint carries a self-healing side effect: it resolves the effective root first and reads the revision second, dropping registrations positively confirmed as stale; merely ignoring them would leave the revision unchanged and the tree pointing at a dead root (`handlers/index.ts:35-37`).
+
+## Verification
+
+```sh
+pnpm build && pnpm test      # unit + integration, including real git repos and real worktree add/remove
+pnpm gate:pr                 # before opening a PR; a new package and catalog entry also need pnpm gate:full
+```
+
+Four **UI semantics** cannot be covered by any automated gate (there is no browser in `gate:*`) and are pre-release manual evidence, verified in an isolated live environment:
+
+1. the file tree lists the worktree's contents;
+2. opening a file previews the worktree's copy;
+3. an unbound session — and an install without this plugin — behaves identically (no regression);
+4. a subagent or forked session's tree follows the binding held by the session that owns it up the parent chain, and the three tools report the same root.
+
+## Test strategy
+
+- Two layers: `test/unit` drives `src` modules directly (pure logic, domain assembly, client contract assertions); `test/integration` goes through the composition root with real git repositories and real temp directories; all on-disk output goes to `mkdtempSync` isolation directories (see §12 of the proposal).
+- Zero file exclusions in the mutation surface: `mutate` covers `src/**/*.ts`, the package config revokes the four shared-default literal exclusions, leaving the effective operator exclusion set empty (`scripts/data/gauntlet.config.json:51`, #847).
+- Inheritance criterion: forked and subagent sessions resolve bindings up the parent chain; in the inherited state the tool surface never drops the parent record and never calls git, reporting only the owning session and the three ways out (`test/unit/tools.test.ts:587`, "tool surface in the inherited state (#847)").
+- Routes always carry 403/405 fence cases plus a two-end route-consistency assertion (proposal §12; `src/server/api/impl/route/index.ts:41`, 403 before 405).
+- This section is read-only description: commands and gate wording follow the "Verification" section and the repository-root AGENTS.md; no commands are promised here.
+
+## Troubleshooting
+
+- Tools say bound while the sidebar still follows the cwd: check `scopeTakeover` in `/health` first — the two readings differ deliberately: the tool surface reports the registration fact (no takeover gate), and only `live` means the file root really switched (`src/server/scope/interface.ts:31-40`).
+- Liveness and state queries (use the port your local `dsh web` actually listens on; the example uses the default 3080):
+
+  ```sh
+  curl 'http://127.0.0.1:3080/api/dsh-worktree-sidebar/health'
+  curl 'http://127.0.0.1:3080/api/dsh-worktree-sidebar/bindings?session=session-1'
+  ```
+
+- Two common causes for a non-`live` `scopeTakeover`: `waiting` (provider not registered yet; startup order is not stable) and `abandoned` (the lookup table is held by a third party); `scopeChain` records the one silent degradation where the persistence read failed (`src/server/api/impl/handlers/index.ts:44-53`).
+- A failed client fetch keeps the last good state (G6): every failure yields undefined, never null, so a first-ever failure falls back to the real cwd (`src/client/index.ts:37-56`, `src/client/bindings.ts:30-39`); both ends read the revision from the same in-memory snapshot, and the client never moves the root on mismatch (G7, see "Contract").
+- Mount or takeover entry failures only speak through `console.warn`: nothing is registered and the right column keeps official behaviour (`src/client/index.ts:121-124`, `src/client/takeover.ts:226-233`).
+
+## Compatibility (read-only coupling)
+
+The plugin does not modify official sources, but it **reads** these contracts (baseline `@deepseek-ai/dsh 0.1.5-rc.1`):
+
+- the host's `typert` `workspaceFileScope` lookup: the plugin registers its resolver via `lookups.configure` and delegates to the **official resolve captured before configuring** on a miss;
+- the client `sidebarRightTabs` type registry and the keyed seat `sidebar.right.pane.tab` (including the `StoredEntry` shape: `component/inject/store/locale`);
+- the session hook source contract `{ getSnapshot(), subscribe(fn) }`, where `getSnapshot` must return a **reference-stable** snapshot;
+- the official client package `@deepseek-ai/dsh-client-ui-sidebar-right` must be present.
+
+On any of these failing the behaviour is **zero registration / fall back to official**: if the official tab implementation cannot be captured, no tab is registered at all and the tree shows the cwd exactly as before. **Visibly doing nothing beats silently showing the wrong place.**
+
+## Security model
+
+- **Loopback-only routes**: non-loopback requests to `/api/dsh-worktree-sidebar/*` get 403; unknown methods get 405 (403 before 405). No file-reading surface is exposed to the browser.
+- **The query endpoint has a self-healing side effect**: `GET /api/dsh-worktree-sidebar/bindings` may drop a binding it has positively confirmed as stale while resolving the effective root (rewriting `bindings.json` and bumping the revision). That is deliberate: the client uses the revision as its cache key, so merely ignoring a stale binding would leave the revision unchanged and the tree pointing at a root that no longer holds.
+- **The main repository path is never returned**: the binding query answers only `{ revision, worktreePath | null }`.
+- **git runs via `execFile` with argv only**, never a shell.
+- **Branch names are validated by git itself** (`git check-ref-format --branch`); every positional argument follows `--`, so a path that looks like `--force` is never read as a flag.
+- **An omitted branch adds an explicit `--detach`**: plain `git worktree add <path>` creates a **new branch named after the directory basename**, so a basename with a space (common in macOS home directories) is rejected as an invalid branch name and one starting with `-` is re-parsed as a flag — `--` only guards `worktree add`'s own option parsing. With `--detach`, "omit the branch" really means "check out the start point, detached" — the repository HEAD by default, or the `base` you passed.
+- **Removal is explicit**: `ws_worktree_remove` only drops the binding unless explicitly told otherwise, and `--force` must be asked for separately. The plugin only ever runs `git worktree remove` — never `rm -rf`.
+- **State lives under `DSH_HOME`**: `bindings.json` is written atomically (temp file + `rename`); a corrupt or future-versioned file is treated as empty rather than guessed at.
+- **No credentials, no network**: tools only write the plugin's own binding table and invoke git.
+
+## Known limitations
+
+- **Session ids are reused by new sessions after a restart, and the binding does not follow**: the official session id is an **in-process counter** (`session-1`, `session-2`, ...), so a restarted `dsh web` hands `session-1` to a brand-new session. Each binding therefore also stores the session header's `createdAt` as its identity: a mismatch (a different session) drops that binding and the tree falls back to cwd, while a genuinely restored session matches and keeps it (when the check cannot be read at all, the binding is conservatively kept — one IO hiccup must not permanently drop a user's binding).
+- **Worktree directory deleted from outside**: treated as unbound and the tree returns to the real cwd (visible, never pointing at a missing directory). But when the **ownership reading is unavailable** (permissions, failing git) the binding is kept and a warning is emitted: only two positively-read, differing common git directories count as "no longer a worktree of this repository".
+- **One worktree per session**: a second binding overwrites the first.
+- **No system-prompt injection**: the model is not told the tool exists beyond the tool list and result text. This is deliberate (no always-on prompt cost); discovery depends on the model inspecting its tools.
+- **Cannot write into the worktree under `workspace-write`** (see non-goals).
+- **One `dsh web` restart is needed after install or upgrade.**
+- **Per-session state is released with the plugin itself**: the client no longer infers liveness (per-session pruning was removed together with the polling), and uses the snapshot only to rewrite the single field `byId[sessionId].cwd`; views and subscriptions are released when the plugin unmounts (`releaseAllSeedings()` + `views.clear()` inside `ctx.effect`), and the view cache is capped at 128 entries, evicting the coldest sessions (each view is an independent reader of the same host fact, so an eviction never makes a tree read a different place).
+- **A second assembly in the same process throws**: all five domains are in-process singletons (`install` / `release` pairs with an `installed` guard), so a second instance cannot mount and the second `install` throws instead of silently sharing state. If a profile mounts this package twice you get one explicit startup error; the old "two instances do not interfere" semantics is gone.
+- **Inheritance is re-resolved along the parent chain every time**: the Files tab root comes from the first session up the chain that holds a registration; once that registration is dropped, or found invalid during resolution, descendants fall back to their own cwd (never silently pointing at a root that no longer holds).
+- **When the takeover is not in effect, tools and the Files tab disagree (deliberately)**: the `workspaceFileScope` takeover has a waiting state (provider not registered yet) and an abandoned state (taken by a third party); in both, the plugin leaves the file root alone and the Files tab still follows the cwd, while the three tools report the **registration fact**. `scopeTakeover` in `/health` is the authority (nothing but `live` switches the root).
+- **`ws_worktree_remove` in the inherited state drops nothing**: it never unbinds the parent session's registration and never removes the directory; it reports which session owns the root plus the ways out (unbind there / bind another worktree here / register this session to its own cwd).
+
+## Retirement criteria
+
+Any one of these makes the plugin unnecessary:
+
+- the official product ships native worktree sessions (a session carries its own working-area switch);
+- the official product ships a supported way to switch the file root per session;
+- `SessionHeader.cwd` becomes mutable, or `workspaceFileScope` gains a supported third-party extension point.
+
+After retiring, clean up worktrees left behind: `git worktree list` to inspect, `git worktree prune` to drop stale registrations.

package/README.md

@@ -0,0 +1,190 @@
+# @wingsky-1/dsh-worktree-sidebar
+[![npm](https://img.shields.io/npm/v/@wingsky-1/dsh-worktree-sidebar)](https://www.npmjs.com/package/@wingsky-1/dsh-worktree-sidebar)
+[![GitHub Releases](https://img.shields.io/github/v/release/wingsky-1/dsh-plugin-hub)](https://github.com/wingsky-1/dsh-plugin-hub/releases)
+
+给 agent 三个工具，把某个 **git worktree** 登记给当前会话，让该会话右侧栏的文件树根指向那个 worktree —— **会话 cwd 不变**。
+
+这是一个**过渡适配层**：官方若推出原生 worktree 会话能力，本插件即退役。
+原理与运行机制（五域装配、宿主/客户端链路、自愈判据、命门清单）见 [架构图解](../../docs/architecture/dsh-worktree-sidebar.md)。
+
+## 它做什么
+
+dsh 的右侧栏文件树根固定取 `session.header.cwd`，且该字段创建后不可变（显式收养不同 cwd 的会话会抛 `ApiSessionCwdConflict`）。于是在「会话开在主 checkout、实际改动在 worktree」这一常见工作方式下，树看的是主 checkout，看错了地方。
+
+本插件给 agent 三个工具：
+
+| 工具 | 作用 |
+|---|---|
+| `ws_worktree_register` | 把一个**已存在**的 worktree 登记给当前会话 |
+| `ws_worktree_create` | 先 `git worktree add` 建出来，再登记（路径与分支由调用方给出，插件不设目录约定）；可选 `base` 指定起点，缺省是会话工作目录所在仓库的当前 HEAD |
+| `ws_worktree_remove` | 摘掉登记；只有显式给出参数才连带 `git worktree remove` 删目录 |
+
+登记之后**打开或刷新**右侧栏的 Files 页签，列的就是该 worktree 的内容，点开的文件预览读的也是 worktree 里的那一份。
+页签**不会自动跟随**：插件不轮询宿主，只在「打开页签 / 点官方刷新 / 窗口重新可见或获得焦点」这三种时机重读登记。
+
+子 agent 的会话与**用户 fork 出来的会话**都继承父会话的登记：自己没有登记时，右侧栏的 Files 页签指向父链上**第一个持有登记**的那个会话所绑定的 worktree（父链到顶、那条登记被摘除即回退到自己的 cwd）。判据同在会话 header 的 `parentSession`，本插件刻意不区分这两种形态——fork 的 header 同样拷了父的 cwd，视图根跟着一起继承才与「文件根是会话 cwd 的改写」自洽。
+
+工具对 **git 仓库内的所有 agent（含子 agent）**暴露：每个 agent 注册时按其会话目录判断，不在 git 仓库里就不注册。执行期还有一次兜底校验，环境在两次之间变了也不会按错误前提动作。
+
+三个工具同时带一个可见的返回文本，写明当前指向哪个 worktree、分支是什么 —— 让模型不必额外调一次工具就能确认状态。
+
+`ws_worktree_create` 的 `base` 是 commit-ish（分支、tag、SHA，如 `origin/main`）。它会先做形态校验（拒绝 `-` 开头的值）再归一化成 SHA 交给 git：起点位置在 `<path>` 之后，git 会**重新开始选项解析**（实测 `base: "-f"` / `"--force"` 会报成功却从 HEAD 建），归一化成 SHA 之后无处下手。
+
+## 显式非目标（已知不一致清单）
+
+这些是**刻意的**取舍，不是待办；它们源于「只换视图根」这一决定：
+
+- `@` 文件引用、`present` 交付物落点、skill 目录**仍锚 `session.header.cwd`**，不随视图根走。树指 worktree 而 `@` 列主 checkout，这是本插件最容易被误解的一处。
+- **`workspace-write` 文件策略下 agent 写不进 worktree**：写围栏的 `sandboxPolicy.workspaceRoot` 同样取自 `header.cwd`，该服务不可被第三方插件替换。要写 worktree 请改用 `danger-full-access`，或把会话开在 worktree 里。
+- 主 checkout 与 worktree 里的**同名文件在预览里没有差异标记** —— 树换了根，文件内容就按 worktree 那一份显示。
+- 「树根 = worktree、执行 cwd = 原目录」是本方案的语义前提。agent 的命令仍在原 cwd 下执行。
+- 被改写的会话视图**只作用于本插件注册的那一个 entry**：客户端把改写挂在官方 entry inject 面的 `hooks.sessions` 上，只影响这一个 entry 的注入面；其它 `useSessions` 消费方（预览、命令面板、`@` 等）仍读到会话真实 cwd。这是「只换视图根」的直接后果，不是待办。
+
+## 安装
+
+前提：已安装 DeepSeek Harness 且 `dsh web` 可正常启动（未全局安装 dsh 见下方「未全局安装 dsh」）。
+
+### 安装插件（add）
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+```
+
+### 卸载插件（remove）
+
+```sh
+dsh plugin --profile web remove @wingsky-1/dsh-worktree-sidebar
+```
+
+卸载后登记表仍留在 `<DSH_HOME>/@wingsky-1/dsh-worktree-sidebar/bindings.json`，但不再有任何效果 —— 插件不在了，就没有人接管文件根。真正建出来的 worktree 目录**不会**被删除，需要时自行处理：
+
+```sh
+git worktree list          # 看还有哪些
+git worktree prune         # 清理已被手工删掉目录的登记项
+```
+
+### 更新插件（update）
+
+```sh
+dsh plugin --profile web update @wingsky-1/dsh-worktree-sidebar
+```
+
+> 安装 / 卸载 / 更新后都需**重启一次** `dsh web`（bundle 层只在启动时组合）生效。
+
+### 指定版本号（@version）
+
+省略 `@版本号` 即安装默认 latest（推荐）。仅当 registry 尚未同步到最新、或最新版在你的环境有问题时，在包名后追加 `@版本号`：
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar@<版本号>
+```
+
+### 未全局安装 dsh
+
+若本机没有全局 `dsh` 命令，用 `npx` 临时拉起（底层调用 `pnpm`，仍需本机装好 `pnpm` 与 `Node.js`）：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+npx @deepseek-ai/dsh plugin --profile web remove @wingsky-1/dsh-worktree-sidebar
+npx @deepseek-ai/dsh plugin --profile web update @wingsky-1/dsh-worktree-sidebar
+```
+
+## 配置
+
+- 总开关只有一个 `enabled`，经插件配置传入（`WorktreeSidebarConfig`，`src/index.ts:41-45`）：`enabled === false` 时不接管、不注册工具、不挂路由（`src/index.ts:98`）；缺省不填即启用。
+- 插件不在盘上读任何用户配置文件，绑定表由插件自持：完整路径是 `<DSH_HOME>/@wingsky-1/dsh-worktree-sidebar/bindings.json`，只认 `DSH_HOME` 一个变量（`src/server/shared/paths.ts:9-17`）。
+- `ws_worktree_create` 的 `base` 缺省是会话工作目录所在仓库的当前 HEAD；显式传 `base` 时先做形态校验（拒绝 `-` 开头），再归一化成 SHA 才交给 git，避免起点被静默忽略。
+- `base` 是 commit-ish（分支、tag、SHA，如 `origin/main`）；省略分支时显式加 `--detach`，即以 detached 形态 checkout 起点，不新建分支。
+- `enabled === false` 时连绑定表都不读，已有登记原样留在盘上但无任何效果。
+
+## 契约
+
+- 双端必须一致的只有两件事，单点定义在 `src/shared/contract.ts:12-28`：路由路径（`ROUTES`）与绑定查询的响应形状（`BindingResponse`）；路由另经构建期 `__DSH_ROUTES__` 注入客户端，两端因此强一致。原理见架构文 §2.4。
+- 两条路由都是 GET 只读：`GET /api/dsh-worktree-sidebar/bindings?session=<id>` 回 `{ revision, worktreePath | null }`；`GET /api/dsh-worktree-sidebar/health` 回 `{ ok, revision, scopeTakeover, scopeChain }`（`src/server/api/impl/handlers/index.ts:24-67`）。
+- 最小暴露：绑定查询不回 `repoRoot`，客户端只需要目录根；缺 `session` 参数判 400 而不是回空，避免被误读成「没有绑定」（`handlers/index.ts:1-8`、`30-34`）。
+- `revision` 是内容版本而非写入次数：空表从 0 起，落一条绑定加一；摘不存在的目标时原样返回、不涨 revision（`src/server/binding/impl/model/index.ts:10-13`、`67-86`）。
+- 客户端只做相等比较与单调守卫：revision 与路径都相同则不通知，乱序回来的更小 revision 直接丢弃（`src/client/bindings.ts:40-48`）。
+- 查询端点带自愈副作用：先生效根、再读 revision，顺带摘除已确认失效的登记；只忽略不摘的话 revision 不变，树会一直指向已不成立的根（`handlers/index.ts:35-37`）。
+
+## 验证
+
+```sh
+pnpm build && pnpm test      # 仓库内：构建 + 单测/集成（含真 git 仓库与真 worktree 的增删）
+pnpm gate:pr                 # 开 PR 前；新增包与 catalog 条目另需 pnpm gate:full
+```
+
+四条**界面语义**进不了任何自动门禁（`gate:*` 里没有浏览器），只能靠隔离真机验证，属发布前人工证据：
+
+1. 打开或刷新 Files 页签后，文件树列的是 worktree 内容；
+2. 点开文件预览读的是 worktree 里的文件；
+3. 未登记会话、以及未安装本插件时的行为一致（无回归）；
+4. 子 agent 会话与 fork 会话的树根跟随父链上持有登记的那个会话，且继承态下三个工具的读数与侧边栏一致。
+
+## 测试策略
+
+- 两层：`test/unit` 直连 `src` 模块（纯逻辑、域装配、客户端契约断言），`test/integration` 走组合根与真 git 仓库、真临时目录；落盘一律进 `mkdtempSync` 隔离目录（见提案 §12）。
+- 变异面零文件排除：`mutate` 覆盖 `src/**/*.ts`，包级配置撤销共享默认的四类字面量排除，有效算子排除集合为空（`scripts/data/gauntlet.config.json:51`，#847）。
+- 继承判据：fork 与子 agent 会话沿父链解析登记；工具面在继承态下不摘父记录、不调 git，只报来源会话与三条出路（`test/unit/tools.test.ts:587` 起「继承态下的工具面」）。
+- 路由必含 403/405 围栏用例与两端路由一致性断言（提案 §12；实现 `src/server/api/impl/route/index.ts:41`，403 先于 405）。
+- 本节只作只读说明：命令与门禁口径以「验证」一节与仓库根 AGENTS.md 为准，这里不另承诺命令。
+
+## 排障
+
+- 工具说已绑定、侧边栏仍按 cwd：先看 `/health` 的 `scopeTakeover`，这是刻意的两路读数——工具面读的是登记事实（不设 takeover 门），文件根有没有真换只有 `live` 才算（`src/server/scope/interface.ts:31-40`）。
+- 存活与状态查询（端口以本机 `dsh web` 实际监听为准，下例用默认 3080）：
+
+  ```sh
+  curl 'http://127.0.0.1:3080/api/dsh-worktree-sidebar/health'
+  curl 'http://127.0.0.1:3080/api/dsh-worktree-sidebar/bindings?session=session-1'
+  ```
+
+- `scopeTakeover` 非 `live` 的两种常见成因：`waiting`（provider 尚未注册，启动先后无稳定保证）与 `abandoned`（查找表已被第三方占位）；`scopeChain` 记录持久面读失败那次静默降级（`src/server/api/impl/handlers/index.ts:44-53`）。
+- 客户端拉取失败保持上次成功态（G6）：任何失败都回 undefined 而非 null，首次即失败时按真实 cwd（`src/client/index.ts:37-56`、`src/client/bindings.ts:30-39`）；双端 revision 读同一内存快照，不一致时客户端不改根（G7，见「契约」一节）。
+- 挂载或接管入口异常只经 `console.warn` 出声：不注册任何东西，右栏保持官方行为（`src/client/index.ts:121-124`、`src/client/takeover.ts:226-233`）。
+
+## 兼容性（只读耦合点）
+
+插件不改官方源码，但**读取**以下官方契约（基线 `@deepseek-ai/dsh 0.1.5-rc.1`）；官方改版时这些点是唯一的失效面：
+
+- 宿主 `typert` 的 `workspaceFileScope` 查表：本插件用 `lookups.configure` 注册自己的解析器，并在 miss 时委托**配置前捕获到的官方 resolve**；
+- 客户端 `sidebarRightTabs` 类型注册表与键控座位 `sidebar.right.pane.tab`（含 `StoredEntry` 的 `component/inject/store/locale` 形状）；
+- 会话 hook 源契约 `{ getSnapshot(), subscribe(fn) }`，且 `getSnapshot` 必须返回**引用稳定**的快照；
+- 官方客户端包 `@deepseek-ai/dsh-client-ui-sidebar-right` 必须存在（它提供 `sidebarRightTabs`）。
+
+任一点失效时的行为是**零注册 / 退回官方**：抓不到官方页签实现就一个页签都不注册，树按官方原样显示 cwd。**可感知地什么都不做，好过静默显示错的地方。**
+
+## 安全模型
+
+- **路由只回环**：`/api/dsh-worktree-sidebar/*` 非回环请求一律 403，方法不在表里 405（403 先于 405）。插件不向浏览器暴露任何文件读取面。
+- **查询端点带自愈副作用**：`GET /api/dsh-worktree-sidebar/bindings` 在解析生效根时会顺带摘除**已确认失效**的登记（写 `bindings.json` 并让 revision 自增）。这是刻意的：客户端以 revision 判定缓存有效性，只忽略不摘的话 revision 不变、树会一直指向已经不成立的根。
+- **不回主仓库路径**：绑定查询只回 `{ revision, worktreePath | null }`，不回 `repoRoot` —— 客户端只需要目录根。
+- **git 只经 `execFile` + argv**：不经 shell，路径与分支名里的空白、`;`、`$()` 不会被重新解释。
+- **分支名交给 git 自己校验**（`git check-ref-format --branch`）；所有位置参数前加 `--`，形如 `--force` 的路径不会被当成标志。
+- **省略分支时显式 `--detach`**：`git worktree add <path>` 的默认行为是**新建一个以目录 basename 命名的分支**，basename 含空格（macOS 家目录常见）会被 git 拒为非法分支名，以 `-` 开头则会被它当成开关二次解析——而 `--` 只挡得住 worktree add 自己的选项解析。补上 `--detach` 之后「省略分支」才真的是「checkout 起点（detached）」——缺省起点是仓库 HEAD，提供 `base` 时 checkout 的就是 `base` 指定的那个起点。
+- **删除是显式的**：`ws_worktree_remove` 默认只摘登记，只有显式参数才执行 `git worktree remove`，且 `--force` 需要再单独显式给出（默认不丢未提交改动）。插件只做 `git worktree remove`，不 `rm -rf`。
+- **落盘在 `DSH_HOME` 下**：`bindings.json` 以临时文件 + `rename` 原子写；文件损坏、版本不符一律当空表，不猜着读。
+- **工具不下发权限**：工具只写自己的登记表并调用 git；不读凭据、不联网。
+
+## 已知限制
+
+- **会话 id 会被重启后的新会话复用，登记不跟着走**：官方会话 id 是**进程内计数器**（`session-1`、`session-2`…），重启后新会话会重新拿到同一个 id。所以登记表里额外存了该会话 header 的 `createdAt` 作为身份凭据：凭据对不上（＝这是另一个会话）就摘掉那条登记、按未登记处理；真正的会话恢复读到的凭据一致，登记照常生效（只读受阻时保守保留，不会因一次 IO 抖动摘掉用户的登记）。
+- **worktree 目录被外部删掉**时按「未登记」处理并让树回到真实 cwd（可感知，不会指向不存在的目录）；但**归属读不出来**（权限、git 执行失败）时保留登记并出声——只有两侧都确实读到了公共 git 目录、且值不同，才判定「已不是该仓库的 worktree」。
+- **一次一个 worktree**：一个会话同时只指向一个 worktree，再次登记会覆盖前一次。
+- **不注入系统提示词**：模型不会被告知「你有这个工具」，只从工具清单与返回文本了解。这是刻意的（避免常驻提示词开销），代价是模型发现该工具依赖它主动查看工具列表。
+- **`workspace-write` 下写不进 worktree**（见「显式非目标」）。
+- **安装 / 升级后需重启一次** `dsh web`。
+- **每会话状态随插件卸载一起释放**：客户端不再做存活性推断（按会话剪枝已在去轮询换根时删除），快照只用来改写 `byId[sessionId].cwd` 这一个字段；视图与订阅在本插件卸载时被收掉（`ctx.effect` 里 `releaseAllSeedings()` + `views.clear()`），视图缓存另有 128 条上限（淘汰最冷的会话；每个视图都是同一份宿主事实的独立读数，淘汰不会让树读到另一个地方）。
+- **同进程第二次装配会显式抛错**：五个域都是进程内单例（`install` / `release` 成对 + `installed` 守卫），第二份实例挂不上并在第二次 `install` 时抛错，而不是静默共享状态。若某个 profile 把本包挂了两次，表现是启动期一条明确的报错；旧的「两份实例互不干扰」语义已不存在。
+- **继承是每次沿父链解析的**：右栏的根来自父链上第一个持有登记的会话，那条登记被摘除、或在解析时被判定失效，后代会话立即回退到自己的 cwd（不会静默指向已不成立的根）。
+- **接管未生效时工具与侧边栏会不一致（刻意）**：`workspaceFileScope` 的接管有等待态（provider 尚未注册）与让位态（被第三方占用），这两态下插件不动文件根、侧边栏仍按 cwd，而三个工具回报的是**登记事实**。以 `/health` 的 `scopeTakeover` 为准（`live` 之外都不换根）。
+- **继承态下 `ws_worktree_remove` 不会摘父会话的登记、也不会删目录**：它只说明根属于哪个会话，并给出出路（在那条会话解绑 / 在本会话绑别的 worktree / 把本会话登记到它自己的 cwd）。
+
+## 落幕判据
+
+以下任一条件满足时，本插件即可退役：
+
+- 官方提供原生的 worktree 会话能力（会话自带工作区切换）；
+- 官方提供受支持的「按会话切换文件根」能力；
+- 官方让 `SessionHeader.cwd` 可变，或让 `workspaceFileScope` 有受支持的第三方扩展点。
+
+退役后建议从使用者的仓库里清理遗留 worktree：`git worktree list` 查看、`git worktree prune` 清登记。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-worktree-sidebar bundle patch：向 web profile 名册插入 worktree 侧边栏适配层。
+# 主机端（exports "."）在宿主进程运行：注入 webServer / agents / typert / sessions，
+# 提供三个 agent 工具（登记 / 创建 / 移除 worktree）、接管 workspaceFileScope 解析，
+# 并提供 /api/dsh-worktree-sidebar/* 只读路由；
+# 浏览器端（exports "./client"）在官方封装就绪后接管 files 页签的目录根。
+# 配置走 schema 默认值（enabled），行内不带 config。
+- insert:
+    - id: ui-dsh-worktree-sidebar
+      name: "@wingsky-1/dsh-worktree-sidebar"

package/lib/client/bindings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 绑定读取：每个会话一份状态，宿主回什么就是什么。
+ *
+ * 客户端**不做**「这个根还有效吗」的判断——宿主已经把「生效值」算好了（失效绑定会被它摘掉）。
+ * 两边各判一次就是 G7 说的那种分叉：客户端认为还绑着、宿主已经按 cwd 解析，
+ * 用户看到的是持续的 outside-workspace 报错。所以这里只负责搬运与保持上次成功态。
+ */
+import type { ObservablePort, ReadBinding } from "./shared/ports.js";
+/** 一个会话的绑定状态。同块使用，故不从本模块转出（对照 source.ts 的 SessionsSource）。 */
+interface BindingState extends ObservablePort<string | null> {
+    /** 拉一次宿主；失败保持上次成功态（G6）。 */
+    refresh(): Promise<void>;
+}
+/** 造一个会话的绑定状态。 */
+export declare function createBindingState(read: ReadBinding, sessionId: string): BindingState;
+export {};

package/lib/client/index.d.ts

@@ -0,0 +1,23 @@
+import type { ClientSlotsPort, ObservablePort, SessionsSnapshotLike, TabsPort } from "./shared/ports.js";
+/**
+ * 浏览器端上下文的窄面。刻意不用 `any`：这几个面正是 `inject` 声明的那几个，
+ * 写成结构类型之后，「多用一个服务却忘了声明」会在类型层先露出来。
+ */
+interface ClientContext {
+    readonly slots: ClientSlotsPort;
+    readonly sidebarRightTabs: TabsPort;
+    /** 服务对象本身**不是**快照源：数据在 `ISessions.list` 上（真机实测见 ports.ts 的注释）。 */
+    readonly sessions: {
+        readonly list: ObservablePort<SessionsSnapshotLike>;
+    };
+    readonly effect: (execute: () => () => void, label?: string) => unknown;
+}
+export declare function apply(ctx: ClientContext): void;
+/**
+ * 客户端契约。`slots` 是接管的落点（`sidebarRightTabs` 只用来读官方类型 id，我们从不写它），
+ * `sessions.list` 是真实快照的来源，
+ * `locale` 随官方组件的完整装配面一起被继承（本包不自带文案）。漏声明会在属性访问处抛
+ * "without inject"；`sidebarRightTabs` 不存在时整体不激活——那说明官方包不在，我们无话可说。
+ */
+export declare const inject: string[];
+export {};

package/lib/client/inject.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 官方 entry inject 面的改写。本文件回答两件事：
+ * 1. `hooks.sessions` 指向按会话的改写源（官方正文读到的 cwd）；
+ * 2. **树根的播种时机**——覆盖 `start`/`load`，把「根 = 首帧读到的 cwd」改成「根 = 绑定解析后的生效根」。
+ *
+ * 为什么必须覆盖 `start`：官方只在 `state === undefined` 时用当帧的 cwd 播一次种
+ * （dsh-client-ui-sidebar-files/lib/client.js:426-428），之后 cwd 再变也不会重设根；
+ * 刷新按钮只走 `actions.reset` + 按已展开路径重新 `load`（同文件 :455-458、:659-661），
+ * 同样不重设根。所以「读到新绑定但树还指着旧根」只能在这一层堵住。
+ *
+ * 请求只在用户可感知的时机发出：挂载页签（`start` 前读一次）、点刷新（`load` 命中已播种的根时读一次）、
+ * 窗口重新可见/获得焦点（读一次）。**没有定时轮询**——轮询既改不了已挂载页签的根，也白花请求。
+ *
+ * 作用域仍是**本 entry**：只改我们注册的那条正文。探测官方 entries 与三步注册在 `takeover.ts`；
+ * 两块零互引（ESLint 块间隔离），装配根把 `viewFor` 接进来、再把产出接到那边的 `wrapInject` 上。
+ */
+import type { ViewFor, WrapInject } from "./shared/ports.js";
+/** 整体释放：装配根在卸载路径上调用。重复调用无害（释放函数自己会把自己摘掉）。 */
+export declare function releaseAllSeedings(): void;
+/** 造一个改写器：外包官方工厂、保留它产出的一切，只改 hooks 与那两个播种方法。 */
+export declare function createInjectWrapper(viewFor: ViewFor): WrapInject;

package/lib/client/shared/ports.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 客户端依赖面：全部是窄接口，浏览器对象与官方组件只出现在 `index.ts` 的适配层里。
+ *
+ * **这些窄接口必须逐条对着运行时的真实服务面写，不能对着某个类型包的声明写。**
+ * 本项目踩过两次，形态完全一样（照假设写的端口在真机上第一次求值就 TypeError，而假端口单测全绿）：
+ * 1. `ctx.slots` 的运行时实现是 `dsh-client-ui-renderer` 的 `SlotRegistry`
+ *    （registry.d.ts:46 的 `class SlotRegistry extends Service`，:84 的 `register = SlotCore[%27register%27]`），
+ *    而另一个同名类型包声明了一个 `isLive` 方法。
+ * 2. `ctx.sessions` 是 `ISessions`（客户端的会话服务），快照数据在它的 `.list` 上
+ *    （`ObservableSnapshot<SessionListState>`），服务对象自己**没有** `getSnapshot`。
+ * 两次的教训是同一条：假端口只证明「代码与我的假设一致」，不证明「假设与运行时一致」。
+ *
+ * 同一个教训的第三份副本在本文件另一类注释里：曾把「往组件 props 里塞 `hooks.sessions` 不被读」
+ * 写成事实，并据此把接缝换成 session 作用域。官方 `bindInjectSources` 恰恰会把 entry inject 面的
+ * `hooks.<name>` 变成 `use<Name>` props——被读，且覆盖框架注入。所以本包用 entry 级接缝。
+ */
+import type { BindingResponse } from "../../shared/interface.js";
+/**
+ * 官方座位上的一条已登记项（运行时形状即 `dsh-client-ui-slots` 的 `StoredEntry`）。
+ *
+ * 类型面在树内读得到：`dsh-client-ui-renderer/lib/types/client/registry.d.ts:15` 从该包 import
+ * `StoredEntry`，`:154`/`:164` 是 `entries`/`entriesOfSlot` 的返回类型（实现包本身不在安装树里，
+ * 可读副本的位置见 takeover.ts 头部注释）。
+ */
+export interface StoredEntryLike {
+    readonly component: unknown;
+    readonly options: {
+        readonly key?: string;
+        readonly id?: string;
+        readonly order?: number;
+        readonly priority?: number;
+    };
+    /** 官方组件的业务面工厂。我们整套保留它的产物，只在外面把 `hooks.sessions` 换成改写源。 */
+    readonly inject?: InjectFactory | undefined;
+    readonly store?: unknown;
+    readonly locale?: string | undefined;
+}
+/**
+ * tab 类型定义，逐字对齐官方 SidebarRightTabDefinition。
+ *
+ * 这里**必须**把所有字段都列全（尤其 `guide`）：类型表用的是官方定义的那一份（本插件只遮蔽
+ * 正文，从不改写类型表），官方注册表 refresh 后会用**在册定义**重算 guide 条目。丢掉 `guide` 的后果不是少一块文案，
+ * 而是 guide 归零、所有会话（含从未登记的）默认页签从 Files 变成空的 Guide、文件树打不开。
+ */
+export interface TabDefinitionLike {
+    readonly id: string;
+    readonly kind: string;
+    readonly patterns?: readonly string[];
+    readonly priority?: string;
+    readonly canOpen?: (address: string) => boolean;
+    readonly title: (address: string) => string;
+    readonly guide?: readonly unknown[];
+}
+/**
+ * 官方座位登记表（只声明本包用到的方法）。
+ *
+ * `isLive` 刻意**不在**这里：官方公开面没有它。存活性判据就是 `entriesOfSlot` 的返回集合本身——
+ * 它给的是「每个 cell 当前生效（非 abdicated）的那一条」，在册即存活。
+ */
+export interface ClientSlotsPort {
+    /**
+     * 某座位的**原始账**（含被遮蔽的条目），与 {@link entriesOfSlot} 同源不同视图。
+     *
+     * 遮蔽生效之后「当值」恒为我们那条，官方那条只有这里看得见——官方文档原话：
+     * the raw entries view stays the inspection surface（renderer/lib/client.js:1181-1191）。
+     * 没有它就看不见官方组件被 HMR 换掉，会一直渲染旧模块的组件。
+     */
+    entries(key: string): readonly StoredEntryLike[];
+    /** 某座位每 cell 当前当值的那一条（优先级最低的存活项）。 */
+    entriesOfSlot(key: string): readonly StoredEntryLike[];
+    register(options: Record<string, unknown>, component: unknown): () => void;
+    subscribe(key: string, listener: () => void): () => void;
+    onEntryError(listener: (key: string, entry: StoredEntryLike, error: unknown) => void): () => void;
+}
+/**
+ * tab 类型注册表。**只读**：本包以「同 key 更低 priority 遮蔽正文」接管，不碰类型表，
+ * 所以这里没有 `register`——官方定义（含 `guide`）保持原样，也就没有「搬定义搬丢了」的失败形态。
+ */
+export interface TabsPort {
+    /** 某 kind 当前生效的类型定义；`id` 恒为官方 id（我们从不改写它）。 */
+    get(kind: string): TabDefinitionLike | undefined;
+}
+/** uSES 观察源：`getSnapshot` 必须返回引用稳定的快照，否则每次渲染都会触发更新。 */
+export interface ObservablePort<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+/** 官方 entry 的 inject 面工厂：吃渲染器传的参数（首个字符串是会话 id），返回业务面。 */
+export type InjectFactory = (...args: unknown[]) => Record<string, unknown>;
+/**
+ * 一个会话的生效根读数：同步读 + 变化订阅 + 主动拉取。
+ *
+ * 与 `bindings.ts` 的 `BindingState` **同形**（那边直接当这个端口用），刻意不另造适配层：
+ * 「宿主说生效根是哪个」与「改写源看到的是哪个」必须是同一个事实，多一层包装就多一次分叉。
+ */
+export interface RootReader {
+    /** 同步读当前生效根；null 表示按真实 cwd 走。 */
+    getSnapshot(): string | null;
+    /** 变化订阅（只在实际变化时触发）。返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /** 拉一次宿主；失败保持上次成功态。 */
+    refresh(): Promise<void>;
+}
+/** 一个会话的整套视图：伪造快照源（供 `hooks.sessions`）+ 生效根读数（供树根播种）。 */
+export interface SessionView {
+    readonly source: ObservablePort<SessionsSnapshotLike>;
+    readonly root: RootReader;
+}
+/** 按会话取视图；同一 id 恒回同一对象（渲染器按源缓存订阅，换了对象就会被当成「状态一直在变」）。 */
+export type ViewFor = (sessionId: string) => SessionView;
+/**
+ * 官方 inject 面的改写器：吃官方工厂、吐同形状的新工厂。改写两件事——`hooks.sessions` 指向
+ * 改写源（树读到的 cwd），以及 `start`/`load` 换成「以生效根播种」（官方只在首帧播种一次根）。
+ *
+ * 契约放在本文件而不是 `inject.ts`：块间零互引（ESLint `no-restricted-imports`）意味着
+ * `takeover.ts` 连 `inject.ts` 的**类型**都引不到，跨块的形状只能由纯类型面承载。
+ */
+export type WrapInject = (official: InjectFactory | undefined) => InjectFactory;
+/**
+ * 一份注入面里的 hook 源表，键是 hook 名。
+ *
+ * 这正是官方 `bindInjectSources` 读的那个 `face["hooks"]`：它把每个 `hooks.<name>`
+ * 经 `standardHookPropName` 合成为 `use<Name>` props
+ * （`dsh-client-ui-renderer/lib/client.js:342-357`），而展开序 `{...kit, ...injected, ...}`
+ * （`:644-650` 与 `:653-658`）让 injected 覆盖框架注入——这就是改写 `useSessions` 的机制。
+ */
+export interface SessionContribution {
+    readonly hooks: Readonly<Record<string, ObservablePort<unknown>>>;
+}
+/** 读一次宿主绑定。失败返回 undefined（调用方保持上次成功态）。 */
+export type ReadBinding = (sessionId: string) => Promise<BindingResponse | undefined>;
+/**
+ * 会话快照的最小形状：我们只改写 `byId[sessionId].cwd` 这一个字段，其余原样透传。
+ *
+ * 只声明真正读到的那一面：`ids` / `current` 曾经是「按会话剪枝」的证据面，剪枝随
+ * 去轮询一起删掉后它们没有读取点，留着只会让人以为还有一条存活性推断。
+ * `byId` 声明成可选：形态对不上时整体放弃改写，而不是凭空造出会话条目。
+ */
+export interface SessionsSnapshotLike {
+    readonly byId?: Record<string, unknown> | undefined;
+}