@wingsky-1/dsh-worktree-sidebar 0.2.5

package/lib/server/scope/deps.d.ts

@@ -0,0 +1,110 @@
+/**
+ * scope 域依赖声明。这里全部是本插件自己的窄类型——官方 typert 的类型体操留在组合根的适配层里，
+ * 于是本域可以完全脱离 cordis 与官方类型被单测驱动。
+ */
+import type * as bindingApi from "../binding/interface.js";
+import type * as gitApi from "../git/interface.js";
+import type { LoggerPort } from "../shared/interface.js";
+/** 与官方同形的文件根解析结果。 */
+export interface FileScope {
+    readonly sessionId: string;
+    readonly workspaceRoot: string;
+}
+/**
+ * binding 域给本域的能力面。**含 `drop`**：检测到失效绑定时要摘掉它，
+ * 好让客户端的 revision 缓存随之失效（见 G5 与 `impl/resolve` 的注释）。
+ */
+export type BindingPort = Pick<typeof bindingApi, "get" | "drop">;
+/** git 域给本域的能力面：只要一个归属判定。 */
+type GitPort = Pick<typeof gitApi, "belongsTo">;
+/** typert 查找表的一个描述符。`resolve` 是「当前生效的那一个」。 */
+export interface LookupDescriptorPort {
+    readonly resolve: (sessionId: string) => Promise<FileScope | undefined>;
+}
+/** typert 查找表。键名由本域持有，官方类型只在组合根出现。 */
+export interface TypertPort {
+    /**
+     * 读**当前生效**的描述符；provider 尚未注册时返回 undefined。
+     *
+     * 调用时机是硬约束：必须在 `configure` **之前**。configure 之后 `get` 回的是我们自己的包装，
+     * 官方 resolve 从此不可达——晚一步读，捕获到的就是自己，委托会变成无限递归。
+     */
+    current(): LookupDescriptorPort | undefined;
+    /**
+     * 订阅这张查找表的变化（该键的 provider 注册与撤销都会触发）。
+     *
+     * provider 是**别人**注册的：官方 dsh-api-workspace-files 在自己的 apply 期才 `register`，
+     * 谁先谁后由宿主启动序决定。所以本域不能只在 install 那一刻读一次——读不到就等这条通知。
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * 注册我们的解析器。
+     * @throws 当该键已经被别人 configure 过时（第三方接管是全局唯一的，这里只捕获、不抢）。
+     */
+    configure(resolver: (sessionId: string) => Promise<FileScope | undefined>): () => void;
+}
+/**
+ * 会话链只读面：本域只要「父会话是谁」这一个事实，但它有**两个来源**。
+ *
+ * 子 agent 的会话与用户 fork 的会话都是**独立会话**——创建时只把父的 cwd 拷进 header
+ * （dsh-subagent 建子会话见 dsh-subagent/lib/index.js:504-510；用户 fork 走的是同一条 header 判据
+ * `parentSession`），所以「子 agent / fork 跟着父会话的 worktree」不会自动发生：
+ * 绑定记在父会话 id 上，它们自己那条永远是空的，不问父链就永远看不到。本域因此不区分两者。
+ *
+ * 而父链只在**活会话**的 header 上随时可读：官方 `ctx.sessions.get` 是 live-only
+ * （`dsh-session/lib/index.js:1550-1557`）。UI 里能点选的子会话（以及已结束的 fork）恰恰是
+ * **已结束**的那些，所以还要一条持久读面。两者的分工必须显式——用 `undefined` 同时表示「没有父」和「不在册」时，
+ * 每个普通会话都会去问一次持久面，把一次确定的「到顶」变成请求路径上的额外 IO。
+ */
+export type LiveParent = {
+    readonly kind: "parent";
+    readonly id: string;
+} | {
+    readonly kind: "root";
+} | {
+    readonly kind: "not-live";
+};
+export interface SessionChainPort {
+    /** 活会话的父链读数；不在册时回 `not-live`，由本域决定要不要回落持久面。 */
+    liveParentOf(sessionId: string): LiveParent;
+    /**
+     * 已结束会话的父 id（持久 header）。取不到回 undefined。
+     * 后端出错（找不到 / 父链成环 / 持久化失败）**可以抛**，由本域收口成「到顶」。
+     */
+    storedParentOf(sessionId: string): Promise<string | undefined>;
+    /**
+     * 活会话的身份；不在册时回 undefined。
+     *
+     * 会话身份存在的唯一理由是 id **不是**跨进程稳定键：官方 id 是实例字段计数器
+     * （`dsh-session/lib/index.js` 的 `counter = 0` 与 `session-${++this.counter}`），
+     * 只防同进程冲突，重启后新会话会重新拿到 `session-1`。没有身份核对，上一进程遗留的登记
+     * 会被一个全新的会话静默继承——那正是本插件最想避免的「看错地方」。
+     *
+     * 与父链一样**分成两个来源**：合起来变成一个 `identityOf` 会把「活 header 一下就答了」
+     * 与「要读持久面」混成同一次记账，health 的成本读数就不再是它字面上的意思。
+     */
+    liveIdentityOf(sessionId: string): SessionIdentity | undefined;
+    /** 已结束会话的身份（持久 header）。取不到回 undefined；后端出错**可以抛**，由调用方收口。 */
+    storedIdentityOf(sessionId: string): Promise<SessionIdentity | undefined>;
+}
+/**
+ * 会话身份里唯一可作凭据的那一项。`createdAt` 来自会话 header（官方类型里是必填的 epoch 毫秒），
+ * 活会话与已结束会话读到的都是同一个值，因此「真恢复的会话」仍然对得上。
+ */
+export interface SessionIdentity {
+    readonly createdAt: number;
+}
+export interface ScopeDeps {
+    readonly logger: LoggerPort;
+    readonly binding: BindingPort;
+    readonly git: GitPort;
+    readonly typert: TypertPort;
+    readonly sessions: SessionChainPort;
+    /**
+     * 目录存在性判定。缺省直连 fs（`impl/resolve` 的 `directoryExists`）。
+     * 注入点存在的理由不是「方便测试」，而是这条判据的两条分支（目录消失 / 读不了）在真实权限下无法稳定构造，
+     * 而它们的正确性直接决定用户会不会被永久摘掉绑定。
+     */
+    readonly existsDirectory?: (path: string) => boolean;
+}
+export {};

package/lib/server/scope/impl/inherit/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 继承父会话的登记：本会话没登记时沿父链向上找。
+ *
+ * 子会话是**独立会话**——dsh-subagent 建它时只把父的 cwd 拷进子 header
+ * （dsh-subagent/lib/index.js:504-510），而绑定记在父会话 id 上（工具是从会话上下文取 id 写登记的）。
+ * 不问父链，子 agent 的文件根就永远是它自己的 cwd。
+ *
+ * 用户 fork 出来的会话走的是同一条判据（header.parentSession），本域**刻意不区分** fork 与子 agent：
+ * fork 的 header 同样拷了父的 cwd，视图根跟着一起继承才与「文件根是会话 cwd 的改写」自洽。
+ *
+ * 三条边界是硬的：到顶即停（没有父就回未绑定）、父链成环时不转圈（错数据不该把请求拖死）、
+ * 父会话的登记失效时按它自己的自愈逻辑摘掉并继续向上（最终仍是未命中，也就是回退自己的 cwd）。
+ */
+import type { BindingRecord } from "../../../binding/interface.js";
+import type { ScopeDeps } from "../../deps.js";
+/**
+ * 沿父链找到的第一个有效登记，连同**持有它的那个会话 id**（不是直接父）。
+ *
+ * `ownerSessionId` 是工具面唯一能给出的「去哪个会话解绑」的答案，所以它必须是持有登记的那个祖先，
+ * 而不是只上跳一步的父——多级 fork 链上这两者并不相同。
+ */
+export declare function inheritedOrigin(deps: ScopeDeps, sessionId: string): Promise<{
+    record: BindingRecord;
+    ownerSessionId: string;
+} | undefined>;

package/lib/server/scope/impl/own/index.d.ts

@@ -0,0 +1,21 @@
+import type { BindingRecord } from "../../../binding/interface.js";
+import type { ScopeDeps } from "../../deps.js";
+/** 存在性判定看到的形状。窄到只需要一个方法，测试才能用一个字面量替身驱动。 */
+interface StatLike {
+    isDirectory(): boolean;
+}
+/**
+ * 目录是否真的在。只有 ENOENT/ENOTDIR 才算「不在」；其它错误（EACCES、EIO）按存在处理。
+ *
+ * `stat` 是可注入的：这段「读不了不等于不存在」的语义正是最容易写错、也最不该靠真实权限去构造
+ * 测试环境的地方（换成 `return false` 会把一次权限抖动变成永久摘掉用户的绑定）。
+ */
+export declare function directoryExists(path: string, stat?: (p: string) => StatLike | undefined): boolean;
+/**
+ * 只看本会话自己的登记：没有、或已失效（目录没了 / 已不是该仓库的 worktree）都回 undefined。
+ *
+ * 返回整条记录而不是根：调用方（解析器与工具面）还要用到根之外的字段（分支名、仓库根），
+ * 只回一个字符串会让它们各自再查一遍表。
+ */
+export declare function ownRecord(deps: ScopeDeps, sessionId: string): Promise<BindingRecord | undefined>;
+export {};

package/lib/server/scope/impl/resolve/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 把「绑定」翻译成「生效的文件根」。解析器与浏览器路由**共用**这一个函数，
+ * 两端因此不可能各说各话（降级预案 G7 的根治办法：不是让两边都算对，而是让只有一边在算）。
+ *
+ * 文件根的两个来源分别是 `impl/own`（本会话自己的登记）与 `impl/inherit`（沿父链继承），
+ * 本文件只负责把它们合成一个答案、并保证解析器**永不抛出**。
+ *
+ * `bindingOrigin` 是这条链条对外的**唯一事实源**：它不只回答「根在哪」，还回答「根是谁的」。
+ * 工具面要区分「本会话自己的登记」与「继承来的登记」，唯一正确的做法就是读它——让工具面
+ * 另算一遍继承，得到的就是本插件最该避免的「两个事实源各说一句话」。
+ */
+import type { BindingRecord } from "../../../binding/interface.js";
+import type { FileScope, ScopeDeps } from "../../deps.js";
+/**
+ * 绑定来源。用判别联合而不是「根 + 若干冗余字段」：`root` 恒等于 `record.worktreeRoot`，
+ * 存两份就多一个能漂移的地方；`kind` 也把「没有登记」时其余字段该取什么值这个问题整个消掉。
+ */
+export type WorktreeOrigin = {
+    readonly kind: "none";
+} | {
+    readonly kind: "own";
+    readonly record: BindingRecord;
+} | {
+    readonly kind: "inherited";
+    readonly record: BindingRecord;
+    readonly ownerSessionId: string;
+};
+/** 来源对应的 worktree 根；`none`（该会话按官方语义走）回 null。 */
+export declare function rootOf(origin: WorktreeOrigin): string | null;
+/** 本会话的绑定来源：自己的登记优先，其次沿父链继承，都没有就是 none。 */
+export declare function bindingOrigin(deps: ScopeDeps, sessionId: string): Promise<WorktreeOrigin>;
+/** 当前生效的 worktree 根；null 表示该会话按官方语义（cwd）走。 */
+export declare function effectiveWorktree(deps: ScopeDeps, sessionId: string): Promise<string | null>;
+/**
+ * 解析器的入口：命中绑定就给 worktree，否则委托。
+ *
+ * **永不抛出**是这里的核心承诺：官方 gateway 把 resolver 的异常翻成 `gateway/lookup-failed`，
+ * 那是整条文件读取链路的硬失败，不是回退。所以 catch 必须在这里，而不是指望上游。
+ */
+export declare function resolveScope(deps: ScopeDeps, delegate: (sessionId: string) => Promise<FileScope | undefined>, sessionId: string): Promise<FileScope | undefined>;

package/lib/server/scope/impl/service/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * scope 域装配：接管 `workspaceFileScope` 的解析，命中绑定就把会话的文件根指到 worktree。
+ *
+ * 接管是**全局替换**（一个键只有一个解析器），所以本域的三条纪律是硬的：
+ * 1. 捕获委托对象必须在 configure 之前；
+ * 2. configure 抛错（别人已接管）就整片放弃，不抢；
+ * 3. 解析器永不抛出，任何异常都回落官方语义。
+ *
+ * **provider 由别人注册，我们等它**：官方 dsh-api-workspace-files 在自己的 apply 期才
+ * `register("workspaceFileScope", …)`，与本插件的装配先后由宿主启动序决定。所以 provider 不在时
+ * 本域既不自己复刻官方默认语义、也不失败，而是**订阅查找表、等它出现**（先订阅再重读一次：
+ * 只重读不订阅会漏掉两者之间注册的 provider，只订阅不重读会漏掉订阅之前就已注册的那一个）。
+ * 等待期不接管——文件根按官方语义走，这是**正常启动态**而不是降级。
+ *
+ * 状态（委托对象、装配入参、两个 disposer）住在实例里；域是**进程内单例**，第二次 `install` 由
+ * 状态守卫**显式抛错**（响亮失败优于静默共享/丢数据）。
+ */
+import type { ScopeDeps } from "../../deps.js";
+import type { WorktreeOrigin } from "../resolve/index.js";
+/**
+ * 接管状态。`waiting` 与 `abandoned` 都不接管，但成因不同，故分开报：
+ * 前者是「宿主还没把 provider 装上」（正常启动态，会自动收敛），后者是「这个键被别人占了」（终态）。
+ */
+export type TakeoverState = "idle" | "waiting" | "live" | "abandoned";
+/** scope 域的服务面。 */
+export interface ScopeApi {
+    /**
+     * 当前**生效**的 worktree 根；null 表示该会话按 cwd 走。
+     * 浏览器路由读它，所以它与解析器给出的答案是同一个（G7）。
+     */
+    effectiveWorktree(sessionId: string): Promise<string | null>;
+    /**
+     * 该会话的**绑定来源**（自己的登记 / 继承来的登记 / 没有）。工具面读它，用来区分
+     * 「本会话自己的登记」与「继承自哪个会话」。
+     *
+     * 它与 `effectiveWorktree` 的**唯一差别是不设 takeover 门**（后者在 `state !== "live"` 时回 null）。
+     * 这是刻意的：工具面要的是「登记事实」，而「文件根有没有真的换根」是宿主启动期读数，
+     * 由 `/health` 的 `scopeTakeover` 报告。waiting / abandoned 期两者结论不同，不是 bug。
+     */
+    worktreeOrigin(sessionId: string): Promise<WorktreeOrigin>;
+    /** 接管状态的诊断读数：只给 health 用，判定逻辑不看它。接管与否看它是否等于 `live`。 */
+    takeoverState(): TakeoverState;
+    /** 会话链持久面的读数：查了几次、坏了几次、最后一次为什么坏。同样只给 health 用。 */
+    chainDiagnostics(): ChainDiagnostics;
+}
+/**
+ * 会话链持久面的读数。
+ *
+ * 它存在的唯一理由是**那处收口是无声的**：持久面读不出来时本域按「到顶」处理（正确的行为），
+ * 于是功能悄悄降级成 live-only，而真机上插件的 `logger.warn` 不落盘（§19.5），
+ * 排查时既没有日志也没有别的痕迹。health 是唯一一条能落地的观测面。
+ */
+export interface ChainDiagnostics {
+    /** 持久面被查了几次：父链的「会话不在册」回落，以及每次会话身份核对。 */
+    readonly storedReads: number;
+    /** 其中抛错的次数——到顶收口就是在这里发生的。 */
+    readonly storedFailures: number;
+    /** 最后一次失败的原因；没有失败时缺席。 */
+    readonly lastFailure: string | undefined;
+}
+/** `workspaceFileScope` 的接管者：唯一实例。 */
+declare class ScopeService implements ScopeApi {
+    private state;
+    private deps;
+    /** 捕获到的委托对象。释放即丢掉，不留在实例上供下一次装配复用。 */
+    private delegate;
+    /** configure 交回的释放面：调用它官方默认解析即恢复。 */
+    private dispose;
+    /** 查找表订阅的退订面。等待期需要它，进入终态后它只是空转。 */
+    private unsubscribe;
+    /** 等待期只出一次声：通知可能来很多次，每次都报会把日志淹掉。 */
+    private warnedWaiting;
+    /** 持久面读数。跨调用存活，所以只能住在这里，不能住在 `inherit`（那是无状态函数）。 */
+    private chain;
+    /** 装配 scope 域。重复装配是编程错误，当场暴露。 */
+    install(deps: ScopeDeps): void;
+    /**
+     * 卸载：把 resolver 交还官方、退订、丢掉捕获到的委托与装配入参，复位状态。重复调用无害。
+     * 此后到达的解析请求回 undefined（gateway 走它自己的 lookup-not-found），不会拿旧 deps 继续服务。
+     */
+    release(): void;
+    takeoverState(): TakeoverState;
+    /** 读数是快照：调用方拿不到本域内部那个对象，改不动它。 */
+    chainDiagnostics(): ChainDiagnostics;
+    /**
+     * 给会话链的持久面加一圈读数。失败**照原样抛回**，收口仍在调用方——
+     * 这里只负责记账，不改变任何判定。
+     *
+     * 身份核对也走同一条持久面，所以它同样计入读数：只统计父链会让「身份读不出来」这类
+     * 故障在 health 上完全不可见。
+     */
+    private observed;
+    /** 记一次持久面读取：无论成败都算一次读，抛错另计一次失败并留下最后原因。 */
+    private counted;
+    effectiveWorktree(sessionId: string): Promise<string | null>;
+    /**
+     * 绑定来源。**不设 takeover 门**：登记是否存在与「文件根是否已经换成它」是两件事，
+     * 工具面（register / create / remove）要的是前者的完整答案——它据此决定能不能摘、
+     * 该不该报「继承自哪个会话」。把工具面也卡在 `live` 上，接管冲突时连一条已确认失效的
+     * 登记都清理不掉。
+     */
+    worktreeOrigin(sessionId: string): Promise<WorktreeOrigin>;
+    /**
+     * 试一次接管。provider 没出现就退回等待态，等待由查找表的变更通知再次叫醒。
+     */
+    private attempt;
+    /**
+     * 交给官方 typert 的解析器。委托对象与装配入参都按**调用当刻**取：释放之后这个闭包只剩
+     * undefined，官方拿到的是它自己的 lookup-not-found，而不是一份过期绑定。
+     */
+    private resolve;
+}
+/** 本域唯一实例：类不外放，外面 `new` 不出第二份接管者。 */
+export declare const scopeService: ScopeService;
+export {};

package/lib/server/scope/interface.d.ts

@@ -0,0 +1,40 @@
+/**
+ * scope 域对外契约：接管 `workspaceFileScope` 的解析，命中绑定就把会话的文件根指到 worktree。
+ *
+ * 本文件只做收口——单例与它的 `ScopeApi` 形状的物理定义都在 `impl/service`（形状不从门面转出），
+ * 解析判定在 `impl/resolve`。单例本身不出这道门：它一旦被转出就成了
+ * 本域的第二张公开契约，调用方还能持有它、绕过释放。
+ */
+import type { ScopeDeps } from "./deps.js";
+import type { WorktreeOrigin } from "./impl/resolve/index.js";
+import { rootOf } from "./impl/resolve/index.js";
+import { scopeService } from "./impl/service/index.js";
+export { rootOf };
+export type { WorktreeOrigin };
+/** 装配 scope 域（组合根在 `apply` 期调用一次）。重复装配是编程错误，当场抛错。 */
+export declare function installScope(deps: ScopeDeps): void;
+/** 卸载 scope 域，与 `installScope` 配对：把 resolver 交还官方。此后能力面当场失败。 */
+export declare function releaseScope(): void;
+/** 当前**生效**的 worktree 根；null 表示该会话按 cwd 走。 */
+export declare function effectiveWorktree(sessionId: string): Promise<string | null>;
+/**
+ * 该会话的**绑定来源**（自己的登记 / 继承来的登记 / 没有）。
+ *
+ * 与 `effectiveWorktree` 的唯一差别是**不设 takeover 门**：工具面要的是「登记事实」，
+ * 而文件根有没有真的换成它由 `/health` 的 `scopeTakeover` 报告。waiting / abandoned 期
+ * 两者结论不同（工具面照旧给出登记，浏览器面仍按 cwd），这是刻意设计，不是 bug。
+ */
+export declare function worktreeOrigin(sessionId: string): Promise<WorktreeOrigin>;
+/**
+ * 接管状态的诊断读数（`idle` / `waiting` / `live` / `abandoned`）。
+ *
+ * 只给 health 端点用：真实启动序里「provider 与插件谁先到」没有稳定保证，这个读数让
+ * 「文件根没换根」当场可分辨成「还没等到 provider」「被别人占了」「接管了但没命中绑定」三种。
+ */
+export declare function takeoverState(): ReturnType<typeof scopeService.takeoverState>;
+/**
+ * 会话链持久面的读数（查了几次 / 坏了几次 / 最后一次的原因）。
+ *
+ * 只给 health 端点用：持久面读失败被收口成「到顶」是一处**静默降级**，这条读数是它唯一落地的痕迹。
+ */
+export declare function chainDiagnostics(): ReturnType<typeof scopeService.chainDiagnostics>;

package/lib/server/shared/file-io.d.ts

@@ -0,0 +1,19 @@
+/** 读取结果：「不存在」「不可读」「是目录」归为同一类——调用方对三者的处置都是回落空值。 */
+type FileRead = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+};
+/** 写入结果。 `reason` 是给日志用的原因文本，不含路径之外的额外事实。 */
+export type FileWrite = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** 同步读全文。只给装配路径用：装配返回时必须已拿到最终值，否则会开一个「读面已可用、文件还没加载」的窗口。 */
+export declare function readTextFileSync(file: string): FileRead;
+/** 原子写全文：补齐父目录 → 写临时文件 → `rename` 覆盖。父目录在这里补齐，谁给出路径谁负责让它可写。 */
+export declare function writeTextAtomic(file: string, text: string): Promise<FileWrite>;
+export {};

package/lib/server/shared/interface.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 共享层门面：包内跨域引用共享设施的唯一入口。
+ *
+ * 共享层是叶子——它不依赖任何域，域依赖它。收口到一处，「共享层提供了什么」
+ * 才有可被门禁校验的答案，而不是散在各域对若干实现文件的直引里
+ * （verify-dir-imports 的规则 1/2 判据）。
+ */
+export type { FileWrite } from "./file-io.js";
+export { readTextFileSync, writeTextAtomic } from "./file-io.js";
+export type { LoggerPort } from "./type.js";
+export { bindingsFile } from "./paths.js";

package/lib/server/shared/paths.d.ts

@@ -0,0 +1,2 @@
+/** 绑定表完整路径。目录是否存在由写入方按需创建。 */
+export declare function bindingsFile(): string;

package/lib/server/shared/type.d.ts

@@ -0,0 +1,6 @@
+/** 包内共享的窄类型。这里不出现宿主上下文：域拿到的是能力，不是 `ctx`。 */
+/** 日志出口。只有 warn 是必需的——本插件的所有失败路径都以「降级 + 出声」收场。 */
+export interface LoggerPort {
+    /** 记一条警告。实现方不得抛出。 */
+    warn(message: string): void;
+}

package/lib/server/tools/deps.d.ts

@@ -0,0 +1,52 @@
+/** tools 域依赖声明：只声明「我需要外部什么」，声明面只有类型。 */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type * as bindingApi from "../binding/interface.js";
+import type * as gitApi from "../git/interface.js";
+import type * as scopeApi from "../scope/interface.js";
+import type { LoggerPort } from "../shared/interface.js";
+/**
+ * binding 域给工具的能力面。**工具是唯一的写入口**——api 域拿不到这三个方法，
+ * 所以浏览器侧不存在任何写绑定的授权路径。
+ */
+export type BindingPort = Pick<typeof bindingApi, "get" | "put" | "drop">;
+/** git 域给工具的能力面。只列本域真正要用的方法，域内不认识 git 的其余能力。 */
+type GitPort = Pick<typeof gitApi, "commonDir" | "belongsTo" | "headBranch" | "checkRefFormat" | "resolveCommit" | "addWorktree" | "removeWorktree" | "listWorktrees">;
+/**
+ * scope 域给工具的能力面。只要「绑定来源」这一个读数——工具据此区分「本会话自己的登记」与
+ * 「继承自哪个会话的登记」，这正是它必须与浏览器面同源的那件事。
+ *
+ * **刻意不取 `effectiveWorktree`**：那是浏览器面的生效根，带 takeover 门（provider 未就绪时回 null）。
+ * 工具面要的是稳定的登记事实，否则接管冲突期连一条已确认失效的登记都清理不掉。
+ */
+type ScopePort = Pick<typeof scopeApi, "worktreeOrigin">;
+/** 一条 agent 的窄面。 */
+export interface AgentFace {
+    readonly id: string;
+    /**
+     * 会话工作目录。判定「是否在 git 仓库里」与解析相对路径都用它。
+     * 缺省时不注册工具——没有 cwd 就无法回答「这个会话在不在仓库里」，猜一个会给出错的工具。
+     */
+    readonly cwd: string | undefined;
+}
+/**
+ * agent 注册面。三个方法各自对应一件事，域内不出现 `ctx`：
+ * 谁订事件、从哪枚举、怎么把工具装进某个 agent 的作用域，都是组合根的知识。
+ */
+export interface AgentPort {
+    /** 订阅「新 agent 发布」。返回退订函数。 */
+    subscribe(handler: (agent: AgentFace) => void): () => void;
+    /** 当前存活的所有 agent 快照（含子 agent；插件加载前就存在的那些都在里面）。 */
+    list(): readonly AgentFace[];
+    /** 把工具装进该 agent 的作用域，返回释放函数。 */
+    publish(agent: AgentFace, definitions: readonly ToolDefinition[]): () => void;
+}
+export interface ToolsDeps {
+    readonly logger: LoggerPort;
+    readonly binding: BindingPort;
+    readonly git: GitPort;
+    readonly scope: ScopePort;
+    readonly agents: AgentPort;
+    /** 登记时间戳。由组合根注入，与 binding 域共用同一个时钟实现。 */
+    readonly now: () => string;
+}
+export {};

package/lib/server/tools/impl/bind/index.d.ts

@@ -0,0 +1,62 @@
+import type { WorktreeOrigin } from "../../../scope/interface.js";
+import type { AgentFace, ToolsDeps } from "../../deps.js";
+import type { SessionFace } from "../session/index.js";
+import type { ToolResultValue } from "../protocol/index.js";
+/** 当前的绑定状态（三个工具的返回信封都要它）。 */
+export interface BindingState {
+    readonly bound: boolean;
+    readonly worktree: string;
+    readonly branch: string;
+}
+/**
+ * 还没解析出来源时用的中性读数。早退路径（缺会话、缺 cwd、不在仓库、缺必填参数）用它：
+ * 为一句「没有 cwd」白付一趟 git 与持久面读不值得，那些失败的成因也和「绑在哪」无关。
+ */
+export declare const NO_ORIGIN: WorktreeOrigin;
+/**
+ * 读来源的结果：`problem` 非空时 `origin` 是中性读数，调用方应直接把 `problem` 当作失败原因报出去。
+ */
+export interface OriginRead {
+    readonly origin: WorktreeOrigin;
+    readonly problem: string | undefined;
+}
+/**
+ * 读某个会话的绑定来源（自己的登记 / 继承来的登记 / 没有）。
+ *
+ * 解析异常在这里收口。scope 域未装配或已释放时它抛的是**插件自己的装配状态**（内部文案是
+ * 「scope 域尚未装配」）：那句话与调用者正在做的事毫无关系，透给模型只会让它照着一句无法行动的
+ * 话去猜。所以对外只说「读不到绑定状态、稍后重试」，原因留给 logger —— 现场痕迹不丢，
+ * 模型也不会拿到内部装配文案。
+ *
+ * 不静默翻成「没有绑定」：那会把一次真实故障说成事实，而「看错地方」正是本插件最该避免的事。
+ */
+export declare function readOrigin(deps: ToolsDeps, sessionId: string): Promise<OriginRead>;
+/** 把来源翻成信封里的状态读数：继承态下 worktree / branch 取的是继承到的那条登记。 */
+export declare function stateOf(origin: WorktreeOrigin): BindingState;
+/**
+ * 组装结果信封。**继承来源说明只在这里加一次**：三个工具、每条成功与失败路径都经过它。
+ * 各调用点自己拼就一定会漏——漏掉之后模型读到的是「本会话没有绑定」，它会去重建一条
+ * 本已存在的登记（#847 的现场就是这样）。
+ */
+export declare function resultOf(origin: WorktreeOrigin, ok: boolean, detail: string): ToolResultValue;
+/**
+ * 把调用方给的路径解析成绝对路径。相对路径按**会话 cwd** 解析（那是调用者心里的基准），不是进程 cwd。
+ *
+ * 参数是 `string` 而不是 `string | undefined`：两个调用方都在更早的分支上把「没有 cwd」判失败并返回了，
+ * 这里再留一条 undefined 分支就是一段**不可达代码**（覆盖率替一段永远到不了的代码记账没有意义）。
+ */
+export declare function resolveTarget(cwd: string, raw: string): string;
+/** 是目录才继续。不是就给一句能照着做的失败。 */
+export declare function directoryProblem(target: string): string | undefined;
+/** 会话所属仓库的可用 worktree 清单，用于失败时的可操作提示。 */
+export declare function availableWorktrees(deps: ToolsDeps, repo: string): Promise<string>;
+/**
+ * 落一条绑定。归属校验在这里做唯一一次——三个工具都经过它，
+ * 所以「只允许绑定同一仓库的 worktree」这条不变量不会因为某条路径漏写而破。
+ *
+ * `before` 由调用方先解析好再递进来：调用方在更早的分支上就要用它（那几处失败路径也要报现状），
+ * 在这里重算一遍等于白付一趟 git 与持久面读。
+ */
+export declare function bindWorktree(deps: ToolsDeps, session: SessionFace, repo: string, target: string, registeredAt: string, before: WorktreeOrigin): Promise<ToolResultValue>;
+/** 会话是否在一个 git 仓库里。不在就没有工具可言。 */
+export declare function repoOf(deps: ToolsDeps, agent: AgentFace): Promise<string | undefined>;

package/lib/server/tools/impl/create/index.d.ts

@@ -0,0 +1,4 @@
+/** `ws_worktree_create`：先 `git worktree add` 建出来，再登记给当前会话。 */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { ToolsDeps } from "../../deps.js";
+export declare function buildCreateTool(deps: ToolsDeps): ToolDefinition;

package/lib/server/tools/impl/protocol/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 工具的输入读取与结果信封。
+ *
+ * 三个工具共用同一个结果形状，是为了让「当前指向哪个 worktree」这件事永远出现在返回文本里：
+ * 失败路径也要说清现状，否则模型在错误之后只知道「失败了」，不知道自己现在到底绑在哪。
+ *
+ * 输出 schema 只用 enforced subset 支持的键（单一 `type`、无 type 数组），
+ * 「没有值」一律用空串表达而不是 null——该子集不接受可空类型。
+ */
+import type { JsonSchemaNode } from "@deepseek-ai/dsh-tools";
+/** 三个工具的统一返回值。 */
+export interface ToolResultValue {
+    /** 本次请求的操作是否成功。 */
+    readonly ok: boolean;
+    /** 调用之后该会话是否仍有绑定（含沿父链继承来的那条）。 */
+    readonly bound: boolean;
+    /** 绑定指向的 worktree 绝对路径；`bound` 为 false 时是空串。 */
+    readonly worktree: string;
+    /** 绑定的分支名；无绑定或 detached 时是空串。 */
+    readonly branch: string;
+    /** 面向模型的结果说明：成功是事实陈述，失败是原因加可操作的下一步。 */
+    readonly detail: string;
+}
+/** 结果信封的 schema（`output.schema`）。 */
+export declare const RESULT_SCHEMA: JsonSchemaNode;
+/**
+ * 结果渲染。**状态行永远在前**：模型据此知道调用后的真实状态，不必再调一次工具确认。
+ */
+export declare function renderResult(value: ToolResultValue): Array<{
+    type: "text";
+    text: string;
+}>;
+/** 读一个非空字符串参数。空白串视同缺席（模型偶尔会给空串表示「没填」）。 */
+export declare function argString(args: unknown, key: string): string | undefined;
+/** 读一个布尔参数。只有显式 `true` 为真——缺席、非布尔、字符串 "true" 都不算。 */
+export declare function argBool(args: unknown, key: string): boolean;

package/lib/server/tools/impl/register/index.d.ts

@@ -0,0 +1,4 @@
+/** `ws_worktree_register`：把一个**已存在**的 worktree 登记给当前会话。 */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { ToolsDeps } from "../../deps.js";
+export declare function buildRegisterTool(deps: ToolsDeps): ToolDefinition;

package/lib/server/tools/impl/remove/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `ws_worktree_remove`：摘掉登记；只有显式 `removeDirectory` 才连带 `git worktree remove`。
+ *
+ * 默认不删目录是刻意的：删除可能丢掉未提交改动，而「我只是想换个根」与「我要销毁这个工作区」
+ * 是两件事，不该由同一个默认值承担。
+ *
+ * **继承态不摘任何东西**：本会话没有自己的登记时，右栏的根属于父会话——摘它是改别人的状态，
+ * 删目录更是销毁别人的工作区。这一态只如实说明并给出路。
+ */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { ToolsDeps } from "../../deps.js";
+export declare function buildRemoveTool(deps: ToolsDeps): ToolDefinition;

package/lib/server/tools/impl/service/index.d.ts

@@ -0,0 +1,28 @@
+import type { ToolsDeps } from "../../deps.js";
+/** 三个工具的注册者：唯一实例。 */
+declare class ToolsService {
+    /** 是否已装配；单例实例重复装配是编程错误，当场暴露。 */
+    private installed;
+    private deps;
+    /** 每个 agent 的工具摘除器。释放时逐个调用并清空，下一次装配才装得进同一个 agent。 */
+    private readonly perAgent;
+    private unsubscribe;
+    private chain;
+    /**
+     * 装配代数。在飞的异步判定跨过一次 release 就作废——否则它会把上一代的 deps 装进新一代，
+     * 而那种串味的症状是「工具装了但绑的是上一个装配体的表」。
+     */
+    private generation;
+    /** 装配工具域。重复装配是编程错误，当场暴露。 */
+    install(deps: ToolsDeps): void;
+    /**
+     * 卸载：退订、逐个摘掉每个 agent 的工具、丢掉映射与在飞的异步链，复位装配标记。重复调用无害。
+     * 映射必须清空——留着它下一次装配会把同一个 agent 当成「已装过」直接跳过，工具永远装不上。
+     */
+    release(): void;
+    /** 判定一个 agent 是否该装工具，该装就装。同一个 agent 只处理一次。 */
+    private consider;
+}
+/** 本域唯一实例：类不外放，外面 `new` 不出第二份注册表。 */
+export declare const toolsService: ToolsService;
+export {};

package/lib/server/tools/impl/session/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 执行期身份解析：从 `exec` 取会话身份与工作目录。
+ *
+ * `exec.agent` 在类型上是可选的（子派发、非 agent 调用都没有它），所以这里返回
+ * `undefined` 而不是抛错；调用方必须把它翻成一句明确的失败，而不是回落到 `process.cwd()`
+ * ——后者会把绑定挂到一个与调用者无关的目录上。
+ */
+export interface SessionFace {
+    readonly id: string;
+    readonly cwd: string | undefined;
+    /**
+     * 会话 header 的创建时间。登记要把它一起落盘：id 是进程内计数器，重启后会被新会话复用，
+     * 没有它就分不清「同一个会话」与「另一个会话拿到了同一个 id」。
+     */
+    readonly createdAt: number | undefined;
+}
+/** 解析会话身份。形状不符即 undefined，不猜。 */
+export declare function sessionOf(exec: unknown): SessionFace | undefined;

package/lib/server/tools/interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * tools 域对外契约：三个 agent 工具的注册与释放。
+ *
+ * 工具按 **agent 作用域**注册（每个 agent 自己的 `ctx.tools`），只在会话位于 git 仓库里时才装；
+ * 会话不在仓库里就一个工具都不给——给了也只会每次都失败。
+ *
+ * 本文件只做收口：门面的物理定义在 `impl/service`。本域不对外提供能力（工具就是它的产物），
+ * 门面因此只有装配与释放。
+ */
+import type { ToolsDeps } from "./deps.js";
+/** 装配工具域（组合根在 `apply` 期调用一次）。重复装配是编程错误，当场抛错。 */
+export declare function installTools(deps: ToolsDeps): void;
+/** 卸载工具域，与 `installTools` 配对：退订 + 摘掉每个 agent 的工具（重复调用无害）。 */
+export declare function releaseTools(): void;