@xrn1997/dsh-session-delete 0.5.0 → 0.6.1

package/lib/types/api/attachment-orphans.d.ts

@@ -2,10 +2,16 @@
  * 孤儿附件的报告段：`GET /attachment-orphans`。
  *
  * 报告把扫描计划折成数量/字节 + 对象清单（`id`/`bytes`，供设置页预览缩略图；最多
- * `ORPHAN_PREVIEW_LIMIT` 条，清理不受预览条数限制）。扫描跳过（引用源或对象列表读不出）时
- * **报告必须失败**——回一份 0 会让界面说"没有孤儿"，而这类失败恰恰是"不知道"，不是"没有"。
+ * `src/config.ts` 的 `orphanPreviewLimit`（默认 200，ADR-0037），清理不受预览条数限制）。
+ * 扫描跳过（引用源或对象列表读不出）时**报告必须失败**——回一份 0 会让界面说"没有孤儿"，
+ * 而这类失败恰恰是"不知道"，不是"没有"。
  * 清理是 `POST /attachment-clean`，由路由直接接到 `cleanOrphanImageAttachments`。
  */
 import { type AttachmentReadDeps } from '../trash/attachments.js';
+import type { SessionDeleteConfig } from '../config.js';
 import type { AttachmentOrphanReportWire } from '../shared/wire.js';
-export declare function reportAttachmentOrphans(deps: AttachmentReadDeps): Promise<AttachmentOrphanReportWire>;
+/** 报告比扫描多读一只旋钮（预览条数）；扫描本体仍只认 `maxJsonRefBytes`。 */
+export interface AttachmentOrphanReportDeps extends AttachmentReadDeps {
+    config: AttachmentReadDeps['config'] & Pick<SessionDeleteConfig, 'orphanPreviewLimit'>;
+}
+export declare function reportAttachmentOrphans(deps: AttachmentOrphanReportDeps): Promise<AttachmentOrphanReportWire>;

package/lib/types/api/attachment.d.ts

@@ -2,22 +2,32 @@
  * 附件原始字节（`GET /attachment`，全仓唯一的二进制响应段）。
  *
  * 四条硬口径：
- * ① **寻址只认 sha256 id**：`id` 必须 `sha256:<64 位小写 hex>`，路径由 `attachmentPathOf(home, kind, id)`
- *    自己推导——请求里的任何一截都不参与路径拼接（`name` 只做下载名）。
+ * ① **寻址只认 sha256 id**：`id` 必须 `sha256:<64 位小写 hex>`，路径不来自请求里的任何一截
+ *    （`name` 只做下载名；媒体元数据只给宿主 `attachments` 服务做引用校验）。
  * ② **kind 只认 image / file**：分别对应宿主附件库的 `objects`（图片）与 `file-objects`（普通文件）；
  *    不认 v2、tmp、cache，也不给"读任意文件"留入口。
- * ③ **单文件 ≤ 20 MiB**：超过不读进内存，回 200 + JSON 失败信封。图片的 `onError` 会换成占位；
- *    普通文件走 `<a download>`，没有页面内失败面——浏览器可能把这份错误响应存成文件。
- * ④ 图片按**魔数**给类型（PNG / JPEG / GIF / WebP）；认不出就按下载处理（`application/octet-stream` +
- *    `attachment`），不猜、也不拿请求里的名字当类型来源。
+ * ③ **单文件 ≤ `maxAttachmentBytes`（默认 20 MiB，可配，ADR-0037）**：所有路径共用同一道
+ *    `assertWithinLimit`；服务路径先按引用字节拦一道、再按实际字节复核，流式读在累计处停下。
+ * ④ **直接 fs 路径**按**魔数**给图片类型（PNG / JPEG / GIF / WebP），认不出就按下载处理
+ *    （`application/octet-stream` + `attachment`），不猜、也不拿请求里的名字当类型来源；服务路径用
+ *    宿主归一化后的 `mediaType`（ADR-0035）。
+ *
+ * **读取优先走宿主 `attachments` 服务**（ADR-0035）：`readImage` / `readFileStream` 会按记录里的
+ * 引用校验字节；`attachments` 缺席或请求里没有足够的引用元数据时，才退回直接 fs（旧宿主）。
+ * 两种"接不了这次读"（服务缺席 / 元数据不够）在调用方看来是同一个 `undefined`，不各写一条 fallback。
+ * 直接 fs 的路径仍只由 `attachmentPathOf(home, kind, id)` 推导。
  *
  * 请求本身不对（id/kind 形状）⇒ 400；对象不在 / 超限 / 读失败 ⇒ 200 + 信封（与其余段同一条错误面）。
  */
 import type { FsPort } from '../ports/fs-port.js';
+import type { SessionDeleteConfig } from '../config.js';
+import type { AttachmentsPort } from '../ports/attachments-port.js';
 import type { BinaryResponse } from './route-table.js';
-/** 读附件只需要 stat + read：与 `AttachmentRemovalDeps` 同一条收窄纪律，执行面不给。 */
+/** 读附件只需要 stat + read、宿主 `attachments` 读面与响应上限；执行面（removeDir/removeFile）不给。 */
 export interface AttachmentReadPorts {
     fs: Pick<FsPort, 'statFile' | 'readFile'>;
     home: string;
+    attachments: AttachmentsPort;
+    config: Pick<SessionDeleteConfig, 'maxAttachmentBytes'>;
 }
 export declare function readAttachmentResponse(deps: AttachmentReadPorts, query: URLSearchParams): Promise<BinaryResponse>;

package/lib/types/api/connection-route.d.ts

@@ -0,0 +1,23 @@
+import type { Dispatch } from './dispatch.js';
+/** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
+export declare const JSON_BODY_MAX_BYTES: number;
+/** 宿主 `connection.fetch.register` 的入参形状（只声明本适配器用到的成员）。 */
+export interface ConnectionFetchRouteLike {
+    readonly path: string;
+    readonly methods: readonly ('GET' | 'HEAD' | 'POST')[];
+    readonly requestBody: 'buffered' | 'streaming';
+    readonly fetch: (request: Request) => Promise<Response>;
+}
+/** 宿主 `connection` 服务的窄镜像：只要求 exact Fetch 注册点。 */
+export interface ConnectionFetchServiceLike {
+    readonly fetch?: {
+        register(route: ConnectionFetchRouteLike): () => Promise<void>;
+    };
+}
+/**
+ * 注册九段 exact Fetch 路由。返回一个组合 disposer；调用方把它挂在自己的 effect 上。
+ * `connection` 是插件的硬依赖（web UI / 桌面端都装 `client-connection`）；`fetch.register`
+ * 缺席属于宿主形状漂移，直接抛——静默返回空 disposer 会让插件「在但没有入口」。
+ * `dispatch` 与分发器同源。
+ */
+export declare function registerConnectionRoutes(service: ConnectionFetchServiceLike, dispatch: Dispatch): () => Promise<void>;

package/lib/types/api/dispatch.d.ts

@@ -1,19 +1,26 @@
-/**
- * /dsh-session-delete-api 的前缀路由分发：只负责传输。
- *
- * 四件事：请求栅栏 → 查路由表 → 按段注入窄面 → 回信封。纯度、body 预读与读面的判据都在
- * src/api/route-table.ts（方法也从那张表读，字面量家在 `shared/wire.ts` 的段名表；这里只按判据执行）；
- * 行投影在 src/api/trash-rows.ts。
- *
- * - 请求本身不对用 4xx（400 请求体 / 405 方法 / 404 未知路由 / 403 栅栏拒绝）；
- *   操作失败回 200 + {ok:false,error}。浏览器半先解信封，再看状态。
- * - 请求栅栏（归属 / 身份）归 `src/api/request-trust.ts`，这里只按它的裁决写 403。
- * - purity 为 chained 的请求串行执行，避免读清册/动文件/写清册交错。
- */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { DeleteDeps } from '../deps.js';
-import { type RequestTrustFacts } from './request-trust.js';
-import { type SliceDeps } from './route-table.js';
-/** 三格只建一次：收窄对象在 handler 构造期固定，请求路径只做引用选择。 */
+import { type BinaryResponse, type JsonBody, type RouteSpec, type SliceDeps } from './route-table.js';
+/** 适配器归一后的一次请求：`rest` 是插件前缀之后的段名（如 `/list`）。 */
+export interface ApiInput {
+    readonly method: string;
+    readonly rest: string;
+    readonly search: URLSearchParams;
+    readonly body: JsonBody;
+}
+/** 适配器归一后的一次响应：JSON 信封或二进制字节，状态码与头由适配器写。 */
+export type ApiResult = {
+    readonly kind: 'json';
+    readonly status: number;
+    readonly body: unknown;
+} | {
+    readonly kind: 'binary';
+    readonly body: BinaryResponse;
+};
+/** 段名的 404 与方法的 405 只在这里判一次；空段名按插件前缀显示，避免 404 原文出现一个空串。 */
+export declare function resolveRoute(method: string, rest: string): RouteSpec;
+/** 四格只建一次：收窄对象在 dispatcher 构造期固定，请求路径只做引用选择。 */
 export declare function slicesOf(full: DeleteDeps): SliceDeps;
-export declare function createApiHandler(deps: DeleteDeps, trust: RequestTrustFacts): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** 分发函数：查段 → 方法闸 → 读面 → 处理。 */
+export type Dispatch = (input: ApiInput) => Promise<ApiResult>;
+/** 路由执行器：查段 → 方法闸 → 读面 → 处理；返回归一结果。组合根只建一次。 */
+export declare function createDispatcher(deps: DeleteDeps): Dispatch;

package/lib/types/api/route-table.d.ts

@@ -13,6 +13,7 @@
  */
 import { type ApplyAction, type RouteName } from '../shared/wire.js';
 import type { CoreDeps, DeleteDeps, RemovalDeps } from '../deps.js';
+import type { AttachmentsPort } from '../ports/attachments-port.js';
 import type { TrashEntry } from '../trash/entry.js';
 /** 请求体：`json` 才读下来（GET 一律不读；读两遍会把流消费掉）。 */
 export type BodyKind = 'none' | 'json';
@@ -33,29 +34,43 @@ export interface BinaryResponse {
 export interface RouteRead {
     rows(): Promise<readonly TrashEntry[]>;
 }
-/** deps 切片（ADR-0032）：每一段只声明自己要的那一面。读与探测六段拿基础面，两个删盘段多删除能力，
- *  `/apply` 是唯一拿全量面的行——段的 run 里长出超面调用就是编译错，dispatch 也只按这一格注入
- *  （运行期收窄住 `src/api/dispatch.ts` 的 `slicesOf`）。 */
-export type RouteSlice = 'core' | 'removal' | 'full';
+/** deps 切片（ADR-0032）：每一段只声明自己要的那一面。读与探测五段拿基础面，`attachment` 段另多一条
+ *  宿主 `attachments` 读面，两个删盘段多删除能力，`/apply` 是唯一拿全量面的行——段的 run 里长出超面
+ *  调用就是编译错，dispatch 也只按这一格注入（运行期收窄住 `src/api/dispatch.ts` 的 `slicesOf`）。 */
+export type RouteSlice = 'core' | 'removal' | 'full' | 'attachment';
 /** 切片名 → 依赖面：{@link RouteSpec.run} 的 deps 参数类型与 `depsFor` 的返回类型都从这一格取。 */
 export type SliceDeps = {
     core: CoreDeps;
     removal: RemovalDeps;
     full: DeleteDeps;
+    attachment: CoreDeps & {
+        readonly attachments: AttachmentsPort;
+    };
 };
-export interface RouteSpec<S extends RouteSlice = RouteSlice> {
+interface BaseRouteSpec<S extends RouteSlice> {
     /** 这一行吃哪一格 deps：dispatch 按它注入，`run` 的 deps 参数类型也跟着它走。 */
     readonly slice: S;
     readonly method: 'GET' | 'POST';
     readonly body: BodyKind;
     readonly purity: Purity;
     readonly read: ReadKind;
-    /** 响应形态：`json` 走信封（`{ok:true,value}`）；`binary` 直接把处理函数的 `BinaryResponse` 写出去。 */
-    readonly response: 'json' | 'binary';
+    /** 同源取数闸（ADR-0033）：只有能被别的页面渲染消费的段需要；判据住 `src/api/connection-route.ts`。
+     *  缺省不设闸——JSON 响应跨源读不到（没有 CORS），不需要它。 */
+    readonly fetchGate?: 'same-origin';
+}
+/** JSON 段：处理函数拿请求体与读面；`query` 不在这里（九行里只有二进制段需要查询串）。 */
+export interface JsonRouteSpec<S extends RouteSlice = RouteSlice> extends BaseRouteSpec<S> {
+    readonly response: 'json';
     /** 声明成函数属性而不是方法：方法签名是双变的，显式标注更宽的 deps 能绕过切片闸；属性按逆变校验。 */
-    readonly run: (deps: SliceDeps[S], body: JsonBody, read: RouteRead, query: URLSearchParams) => Promise<unknown>;
+    readonly run: (deps: SliceDeps[S], body: JsonBody, read: RouteRead) => Promise<unknown>;
+}
+/** 二进制段：只有 `/attachment`；处理函数直接拿查询串，交回字节与安全头。 */
+export interface BinaryRouteSpec<S extends RouteSlice = RouteSlice> extends BaseRouteSpec<S> {
+    readonly response: 'binary';
+    readonly run: (deps: SliceDeps[S], query: URLSearchParams) => Promise<BinaryResponse>;
 }
-/** 九行的并集（表的值类型）：每行由自己的 `slice` 字面量定型，`run` 的 deps 面随之收窄。 */
+export type RouteSpec<S extends RouteSlice = RouteSlice> = JsonRouteSpec<S> | BinaryRouteSpec<S>;
+/** 九行的并集（表的值类型）：每行由自己的 `slice` 与 `response` 字面量定型，`run` 的 deps 面随之收窄。 */
 export type AnyRouteSpec = {
     [S in RouteSlice]: RouteSpec<S>;
 }[RouteSlice];
@@ -67,3 +82,4 @@ export declare const APPLY_ACTIONS: readonly ApplyAction[];
 export declare const ROUTE_TABLE: Record<RouteName, AnyRouteSpec>;
 /** 段名 → 那一行；不认识的段名回 `undefined`（调用方抛 404，并带出原路径）。 */
 export declare function routeOf(rest: string): RouteSpec | undefined;
+export {};

package/lib/types/client/api-base.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 取数路径的挂载点：官方 `/api` 前缀 + **当前文档所在的目录**。
+ *
+ * 为什么不能写死根绝对路径：宿主自己的客户端模块按「app-directory-relative form」下发 bundle 与
+ * chunk 描述符，浏览器在**自己的挂载点**下解析（`dsh-client-modules` README 原文：*"which a browser
+ * document resolves under its own mount"*）；同一个部署可以被反代到 `/dsh/`，此时 `/api/...` 会打到
+ * 反代根、而不是宿主。路由注册侧仍然必须写 `/api/...`（宿主 `connection.fetch.register` 用
+ * `endpointFromPath('/api', path)` 校验），所以本文件只给**浏览器半**投影一层挂载点前缀。
+ *
+ * 根部署（`http://host/`）下 `mountPathOf` 返回空串，拼出来的 URL 与旧版逐字相同；只有挂载部署才
+ * 多出 `/dsh` 这一段。目录取自 `new URL('.', baseURI)`：页面是 `/dsh/`、`/dsh/index.html` 都归到
+ * `/dsh/`；`about:blank` 这类不透明 base 退回根路径（此时相对地址本来也无法成立）。
+ */
+/** `baseURI` 所在目录的路径，去掉尾斜杠；根路径回空串。 */
+export declare function mountPathOf(baseURI: string): string;
+/** 一段相对段名 → 宿主 `/api` 前缀 + 挂载点。`path` 以 `/` 开头，与 `ROUTES` 的形状一致。 */
+export declare function apiPathOf(path: string, baseURI: string): string;
+/** 当前文档的取数路径；Node 侧（无 `document`）退回根路径。 */
+export declare function apiPath(path: string): string;

package/lib/types/client/batch-bar.d.ts

@@ -2,7 +2,7 @@
  * 批量删除的浮条：**多选模式内常驻**（0 条也渲染，既显示模式又给退出入口），
  * 汇总「已选 N 条」+（读得到时）「含 K 个子会话」；「查看已选」展开限高可滚动的标题清单
  * （逐条可移除），回答"到底选了哪些"——清单默认收起，不把底部输入区盖住。
- * 模式内的整行点击守卫也挂在这棵常驻宿主上（见 `host-rows.ts` 的 `useSelectionRowClickGuard`）。
+ * 模式内的整行点击守卫也挂在这棵常驻宿主上（见 `batch-pick.ts` 的 `useSelectionRowClickGuard`）。
  *
  * 为什么单独一个文件而不是并进 `batch-select.tsx`：那份是"行开关控件"，而浮条要点开确认框
  * （要 import 它的现场）——两个方向合到一个文件上就是一圈。浮条住在

package/lib/types/client/batch-pick.d.ts

@@ -0,0 +1,19 @@
+import { type PickItem } from './batch-selection-store.js';
+/** 全选：把当前可见可选行按登记序追加；已在名单里的由 `addPicks` 自己跳过，原有选中保持在前。 */
+export declare function selectAllVisible(): void;
+/**
+ * 同一个切换口该显示「全选」还是「取消全选」：
+ * - 有选中、且当前可见可选行全都选中 ⇒ 取消全选；
+ * - 有选中、但当前没有可见可选行（全折叠/过滤掉）⇒ 只能清空，也显示取消全选；
+ * - 其余（含 0 条）⇒ 全选。
+ */
+export declare function areAllVisibleRowsSelected(rows: readonly PickItem[], picks: readonly PickItem[]): boolean;
+/**
+ * 多选态内的整行点击守卫（document 捕获阶段）。
+ *
+ * 边界：行里的按钮 / 链接 / 输入 / 菜单项一律放行（否则 ⋯ 菜单、归档、置顶、单删都点不动）；
+ * 双击的第二下与 dblclick 不翻转（第一下已经选中，第二下不能又反掉，也不能打开宿主的重命名）。
+ * 认行靠 `data-row-key="session:…"`——**这是本文件唯一一处 DOM 读**（ADR-0034）：宿主将来改掉这个
+ * 属性，最差是模式内点行不生效，勾选框本身仍在。模式外不挂监听：这时点行必须还是宿主的"打开会话"。
+ */
+export declare function useSelectionRowClickGuard(): void;

package/lib/types/client/batch-select.d.ts

@@ -4,16 +4,16 @@
  *
  * 入口在每行的「⋯」菜单里（`batch-menu-item.tsx`）：**按下才进入多选模式**，模式内才渲染勾选框、
  * 才把整行点击变成"勾/取消"；退出模式清空名单。选中集只住 `batch-selection-store.ts`（模式 + 名单一份
- * 合并快照）；"哪些行现在可见、点行算不算选中"只住 `host-rows.ts`。四处隔着槽位边界，只有模块级
- * store 能让他们看见同一份名单；本文件不再持有任何现场。
+ * 合并快照）；"哪些行现在可见"住 `host-rows.ts`，"点行算不算选中"住 `batch-pick.ts`。四处隔着
+ * 槽位边界，只有模块级 store 能让他们看见同一份名单；本文件不持有任何现场。
  *
  * **为什么主勾选在行首**：宿主对行尾 `.rowActions` 是 `display:none`，只有 `row:hover` / 菜单打开
  * 才出现（app.asar 0.2.0-rc.2 的 Rows 渲染）；行首 16px 格在无状态点时是空的，模式内可见。
  * 宿主在「有状态点（运行中/待确认/未读完成）」与归档行不渲染行首格 ⇒ 这些行走行尾悬停兜底，
- * 但模式内**点整行**也能选（`host-rows.ts` 的 `useSelectionRowClickGuard`），所以不依赖那颗小框。
+ * 但模式内**点整行**也能选（`batch-pick.ts` 的 `useSelectionRowClickGuard`），所以不依赖那颗小框。
  * 两条勾选不会同时出现（`ui.css` 的 `:has` 兜底隐藏规则，靠宿主行的 `data-row-key`）。
  */
-import { type ReactElement } from 'react';
+import type { ReactElement } from 'react';
 import { type Translate } from './copy.js';
 import { type SessionDeleteRemote } from './remote.js';
 /**
@@ -27,6 +27,8 @@ export interface BatchPickCheckboxProps {
     sessionId: string;
     /** 槽位只投 `sessionId`；标题由宿主侧的 root hook 读出来再传进来（见 `index.tsx` 的 `PickLeadingRow`）。 */
     title: string;
+    /** 运行态同样由 root hook 读：登记表里的 `live` 与行尾兜底保持同一口径。 */
+    live?: boolean;
     /** 文案（缺省 = 内置 zh，见 `copy.ts`）。 */
     t?: Translate;
 }
@@ -37,7 +39,7 @@ export interface BatchPickCheckboxProps {
  * （行首格在宿主行那条 `onClick` 里面）。宿主对「有状态点」和归档行不渲染这一格，
  * 那些行走 `BatchPickButton` 兜底；两条不会同时出现（见 `ui.css` 的兜底隐藏规则）。
  */
-export declare function BatchPickCheckbox({ sessionId, title, t, }: BatchPickCheckboxProps): ReactElement | null;
+export declare function BatchPickCheckbox({ sessionId, title, live, t, }: BatchPickCheckboxProps): ReactElement | null;
 export interface BatchPickButtonProps {
     sessionId: string;
     title: string;

package/lib/types/client/context-menu-actions.d.ts

@@ -0,0 +1,47 @@
+import type { Translate } from './copy.js';
+interface MenuTarget {
+    readonly sessionId: string;
+    readonly displayTitle: string;
+}
+export interface MenuActionLike {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    icon?: {
+        key: string;
+    };
+    danger?: boolean;
+    separatorBefore?: boolean;
+    afterContent?: boolean;
+    run: () => void | Promise<void>;
+}
+export interface ObservableSnapshotLike<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+interface SessionsStateLike {
+    byId?: Record<string, {
+        running?: boolean;
+    } | undefined>;
+}
+export interface SessionsServiceLike {
+    list?: ObservableSnapshotLike<SessionsStateLike>;
+}
+export interface MenuContributionLike {
+    id: string;
+    target: 'session';
+    order: number;
+    observe?: (target: MenuTarget) => readonly ObservableSnapshotLike<unknown>[];
+    resolve: (target: MenuTarget) => readonly MenuActionLike[] | Promise<readonly MenuActionLike[]>;
+}
+export interface ContextMenusLike {
+    register(contribution: MenuContributionLike): () => void;
+}
+export declare const ICON_BATCH = "xrn1997.session-delete.batch-select";
+export declare const ICON_DELETE = "xrn1997.session-delete.delete";
+/**
+ * 造 0.2.2+ 的会话菜单贡献。order 700 落在内置 Archive(600) 之后；两行都是 `afterContent`，
+ * 所以它们与 Archive 一起排掉 legacy 组件行，恢复「归档在多选/删除之前」。
+ */
+export declare function createSessionMenuContribution(t: Translate, sessionList?: ObservableSnapshotLike<SessionsStateLike>): MenuContributionLike;
+export {};

package/lib/types/client/copy.d.ts

@@ -170,6 +170,7 @@ declare const ZH: {
     readonly 'detail.role.assistant': "助手";
     readonly 'menu.delete': "删除";
     readonly 'menu.live': "会话正在运行，先停止再删除";
+    readonly 'menu.deleteLive': "删除（运行中）";
     readonly 'dialog.title': "删除这个会话？";
     readonly 'dialog.subagents': "含 {n} 个子会话，将一起移入回收站。";
     readonly 'dialog.hint': "会话会移入回收站，之后可以随时恢复。彻底删除是回收站里的另一个动作。";
@@ -201,6 +202,13 @@ export declare const zhTranslate: Translate;
 /**
  * 注册字典并交回本插件的 `t`。服务不在时返回 `zhTranslate`（不抛、不 pending）。
  *
+ * **空值判据同时认 `undefined` 与 `null`**：宿主 `ctx.get` 可以回 null（同一条窄镜像的读法见
+ * `main-view.ts` 的 `isReadyUiWorkspace`）。这里只判 `undefined` 的版本会把 null 当成"服务在"，
+ * 下一句 `service.register` 抛错——而本函数跑在**任何槽位注册之前**，抛出去等于整个客户端条目
+ * 从页面消失（`apply` 只打一条 warn）。注册 / 绑定自身失败同样退回内置 zh：文案降级远好过没有插件。
+ * `bind` 在注册之后才跑，它失败时字典已挂上但没人用——留着无害（宿主只是多一份不用的词典），
+ * 不为它补撤销路径再引入新的失败面。
+ *
  * 注册必须挂在 `ctx.effect` 上：`register` 返回的 disposer 是**官方契约**（卸载时要把字典摘掉），
  * 而且同一命名空间的同一语言**只能注册一次**——effect 没挂，HMR 重挂就撞 "already has locale"。
  */

package/lib/types/client/delete-confirm.d.ts

@@ -9,8 +9,8 @@ import { type DeleteConfirmDeps } from './remote.js';
 export declare const TARGET_CARD: {
     readonly padding: "10px 12px";
     readonly background: "var(--dsw-alias-bg-layer-2)";
-    readonly border: "0.5px solid var(--dsw-alias-border-l4)";
-    readonly borderRadius: "var(--dsw-radius-lg)";
+    readonly border: "0.5px solid var(--sd-border-l4)";
+    readonly borderRadius: "var(--sd-radius-lg)";
 };
 /** 菜单行写进现场的一条删除请求（槽位投影原样带过来，浏览器半不自己拼 id）。 */
 export interface DeleteRequest {

package/lib/types/client/host-rows.d.ts

@@ -1,54 +1,49 @@
-import { type PickItem } from './batch-selection-store.js';
+import type { PickItem } from './batch-selection-store.js';
 export interface HostRowInfo {
-    /** 槽位投影的 `displayTitle`（行首槽只投 id，所以守卫靠行尾那颗常驻登记）。 */
+    /** 槽位宿主投影的标题（`PickLeadingRow` / `PickRow` 从 root hook 读）；守卫只读登记，不读 DOM 文本。 */
     readonly title: string;
     /** 在跑的行点整行也不选：与置灰的勾选框同口径（级联遇在跑成员整组拒绝）。 */
     readonly live: boolean;
 }
 /**
- * 行尾兜底勾选开关登记一行：模式内与模式外都要登记（守卫进模式的那一帧就得有标题）。
- * 每次登记算**多一个挂载实例**；只有标题／运行态**真的变了**才标脏：重渲染时的同值登记
- * 不该把快照翻新一遍。
+ * 行槽位开关登记一行：模式内与模式外都要登记（守卫进模式的那一帧就得有标题）。
+ * 每次登记算**多一个挂载实例**；不给 info 时只占位，随后由 {@link updateHostRowInfo} 填值。
  */
-export declare function registerHostRowInfo(sessionId: string, info: HostRowInfo): void;
-/** 行尾开关卸载时调用：那一行已经离开渲染树，登记跟着走。
+export declare function registerHostRowInfo(sessionId: string, info?: HostRowInfo): void;
+/**
+ * 标题/运行态变了就地更新：**不注销、不重登记**，否则这一行会被挪到登记序末尾（ADR-0034 决定 2）。
+ */
+export declare function updateHostRowInfo(sessionId: string, info: HostRowInfo): void;
+/**
+ * 槽位组件共用的登记生命周期：挂载登记、卸载注销；标题/运行态变化只走更新口。
+ * 两次 effect 分工是顺序契约：先占住首次登记序，再填值。
+ */
+export declare function useHostRowRegistration(sessionId: string, info: HostRowInfo): void;
+/** 行槽位开关卸载时调用：那一行已经离开渲染树，登记跟着走。
  *  还有别的挂载实例在用同一行（重复行）就只减计数，不摘登记。 */
 export declare function unregisterHostRowInfo(sessionId: string): void;
 /**
- * 「当前可见」的可选行：侧栏里**已渲染**的会话行（`data-row-key="session:…"`）——折叠组、
- * 归档过滤外的行不在 DOM 里，宿主隐藏的 subagent 也不在；在跑的行跳过（与置灰勾选框同口径）。
- * 标题/运行态来自行尾兜底登记的 `rowInfo`（模式内它对每个非空行都渲染）；DOM 序就是侧栏顺序。
+ * 守卫与全选共用的一行读数：这一行此刻可勾选时交回登记（含标题）；未登记或在跑回 `undefined`。
+ * 登记表是可见行的事实源，所以"没登记"就是"这一行此刻不在可见集合里"。
+ */
+export declare function pickableRowOf(sessionId: string): HostRowInfo | undefined;
+/**
+ * 「当前可见」的可选行：**已登记**的会话行（槽位开关还挂在渲染树上）——折叠组、归档过滤外的行
+ * 没有挂载，因此没有登记；在跑的行跳过（与置灰勾选框同口径）。标题/运行态来自登记值；
+ * 顺序是登记顺序（宿主按列表顺序挂载行）。
  *
  * 这是**当场读**：事件路径（点「全选」那一刻的页面）与测试用它；渲染侧读下面的快照。
  */
 export declare function readVisibleSelectableRows(): PickItem[];
 /**
- * 渲染侧的快照：脏了才查 DOM；干净时回同一个引用（React 的 `useSyncExternalStore` 契约）。
+ * 渲染侧的快照：脏了才重读登记；干净时回同一个引用（React 的 `useSyncExternalStore` 契约）。
  * 没变化时连续两次调用必须同引用，否则订阅方会被自己的快照更新推成死循环。
  */
 export declare function getVisibleSelectableRowsSnapshot(): readonly PickItem[];
 /**
- * 渲染侧只读快照 + DOM 观察订阅；首个订阅者起开始观察，最后一个走了断开。
- * `enabled === false` 不订阅也不读 DOM——行列表只随多选态存在，模式外不必付观察的成本。
+ * 渲染侧只读快照 + 登记订阅；`enabled === false` 不订阅也不读登记——行列表只随多选态存在，
+ * 模式外不必付订阅的成本。
  */
 export declare function useVisibleSelectableRows(enabled: boolean): readonly PickItem[];
-/** 全选：把当前可见可选行按 DOM 序追加；已在名单里的由 `addPicks` 自己跳过，原有选中保持在前。 */
-export declare function selectAllVisible(): void;
-/**
- * 同一个切换口该显示「全选」还是「取消全选」：
- * - 有选中、且当前可见可选行全都选中 ⇒ 取消全选；
- * - 有选中、但当前没有可见可选行（全折叠/过滤掉）⇒ 只能清空，也显示取消全选；
- * - 其余（含 0 条）⇒ 全选。
- */
-export declare function areAllVisibleRowsSelected(rows: readonly PickItem[], picks: readonly PickItem[]): boolean;
-/**
- * 多选态内的整行点击守卫（document 捕获阶段）。
- *
- * 边界：行里的按钮 / 链接 / 输入 / 菜单项一律放行（否则 ⋯ 菜单、归档、置顶、单删都点不动）；
- * 双击的第二下与 dblclick 不翻转（第一下已经选中，第二下不能又反掉，也不能打开宿主的重命名）。
- * 认行靠 `data-row-key="session:…"`——宿主将来改掉这个属性，最差是模式内点行不生效，
- * 勾选框本身仍在。模式外不挂监听：这时点行必须还是宿主的"打开会话"。
- */
-export declare function useSelectionRowClickGuard(): void;
-/** 测试专用：登记表清空并标脏（会话 id 不跨用例复用，名字/运行态别串味）；观察者归订阅者管。 */
+/** 测试专用：登记表清空并标脏（会话 id 不跨用例复用，名字/运行态别串味）。 */
 export declare function resetHostRows(): void;

package/lib/types/client/index.d.ts

@@ -6,6 +6,8 @@ export declare const name = "@xrn1997/dsh-session-delete/client";
  * **`locale` 也不在这里**：宿主自己的 `ui-sidebar` 是硬注入它的，但那是"宿主知道自己那一代"的前提；
  * 本插件要跨代活着 ⇒ 走 `ctx.get('locale')` 可选读，缺席时降级到内置 zh 文案（见 `copy.ts` 头注）。
  * 写进 inject 就等于"这一代没有 locale 就不让整个客户端条目激活"，而那等于宿主进程死。
+ * **`contextMenus` 同理**：0.2.2+ 用 `ctx.get('contextMenus')` 探测，包本身在 package.json 的
+ * `dsh.client.inject` 里排到前面；旧宿主没有这个服务时回退 legacy 槽位。
  */
 export declare const inject: string[];
 /**

package/lib/types/client/main-view.d.ts

@@ -11,7 +11,8 @@
  * 所以关闭/重开是**一段生命周期**，不是一个 id：删除成功后 `afterDelete` 关掉当前
  * 主视图并记下"这一条是我们关掉的"；撤销成功后 `afterRestore` 只重开自己记过的那些。调用方不再
  * 各自判定该不该关、也不再把会话 id 塞进撤销提示传一圈——判据全在这一处。两次重开排队时只有最新
- * 那条会打开（最新票守卫），`resetMainView()` 清掉这份记忆并让在等的重开作废。
+ * 那条会打开（等待本身住 `src/client/pending-open.ts` 的票与订阅），`resetMainView()` 清掉这份记忆
+ * 并取消在等的重开。
  *
  * **不 import 宿主客户端包**（AGENTS.md 红线）：只通过 `ctx.get('uiWorkspace')` 可选读服务，
  * 形状不符/服务缺席都安静退回，绝不影响插件激活。字段与方法名来自上面两个包的产物原文；

package/lib/types/client/maintenance-settings.d.ts

@@ -18,5 +18,7 @@ export interface MaintenanceSettingsProps {
     deps: MaintenanceDeps;
     /** 文案（缺省 = 内置 zh；宿主 locale 服务缺席时也是它，见 `copy.ts`）。 */
     t?: Translate;
+    /** 宿主 `plugins.bundle.config` 的视图：`summary` 是插件行的一行摘要，本卡只属于详情页。 */
+    view?: 'summary' | 'page';
 }
-export declare function MaintenanceSettings({ deps, t }: MaintenanceSettingsProps): ReactElement;
+export declare function MaintenanceSettings({ deps, t, view }: MaintenanceSettingsProps): ReactElement | null;

package/lib/types/client/pending-open.d.ts

@@ -0,0 +1,17 @@
+export interface PendingOpenInput {
+    /** 订阅「清单变了」；返回退订。旧 store 可能没有——那时只有"已经出现"这一支能开。 */
+    readonly subscribe?: ((listener: () => void) => () => void) | undefined;
+    /** 目标是否已经出现在清单里。 */
+    readonly isReady: () => boolean;
+    /** 出现的这一拍还该不该抢焦点（用户可能已经选了别的会话）。 */
+    readonly canOpen: () => boolean;
+    /** 打开目标；调用方自己收宿主抛错。 */
+    readonly open: () => void;
+}
+export interface PendingOpen {
+    /** 取消在等的等待（没有也安全）；后一次 `schedule` 会先取消前一次。 */
+    cancel(): void;
+    /** 等目标出现再打开；已经在清单里就立即打开。 */
+    schedule(input: PendingOpenInput): void;
+}
+export declare function createPendingOpen(giveUpMs?: number): PendingOpen;

package/lib/types/client/remote.d.ts

@@ -1,13 +1,17 @@
 /**
- * 浏览器半的取数通道：同源 fetch /dsh-session-delete-api，并处理信封与失败原文。
+ * 浏览器半的取数通道：同源 fetch 宿主 `connection.fetch` 的 exact Fetch 路由（`/api` + 插件前缀）。
+ * 信封与失败原文在这一层收口。
  *
- * - 路由是宿主 web server 上的插件前缀；官方 remote.<namespace> 需要生成的 Typert 描述符，
- *   第三方无法动态挂载，因此走这条薄线（ADR-0009）。
+ * - 九段注册在宿主 `connection.fetch.register` 上，鉴权归宿主 `/api` bridge（ADR-0033）；
+ *   没有旧前缀 fallback——支持面是 web UI 与桌面端，二者的标准组合都装 `client-connection`。
+ *   官方 remote.<namespace> 仍不可用（第三方拿不到 Typert 描述符的动态发现挂载点）。
  * - 九段的**段名与方法**住 `src/shared/wire.ts` 的结构化段名表（`ROUTES` 每项 `{ path, method }`），
- *   本文件只投影路径（`prefix + ROUTES.x.path`）与方法（GET 段直接取 `ROUTES.x.method`，写段把它
- *   交给 `post()`）——方法字面量不在本文件出现第二份；
- *   写动作统一走 apply；`attachment` 是唯一二进制段，由 `src/client/attachment-view.tsx` 直接拼地址，
- *   不经过本文件的信封通道；`attachment-orphans`（纯读）与 `attachment-clean`（聚合写）是孤儿附件的两段。
+ *   本文件只投影段名与方法（GET 段直接取 `ROUTES.x.method`，写段把它交给 `post()`）——方法字面量
+ *   不在本文件出现第二份；取数地址（官方 `/api` 前缀 + 文档挂载点）归 `src/client/api-base.ts`
+ *   （根部署下与旧版逐字相同）。
+ *   写动作统一走 apply；`attachment` 是唯一二进制段，由 `src/client/attachment-view.tsx` 经同一投影
+ *   拼地址，不经过本文件的信封通道；`attachment-orphans`（纯读）与 `attachment-clean`（聚合写）是孤儿
+ *   附件的两段。
  * - 信封与官方 unary 面同形：{ok:true,value} / {ok:false,error}。HTTP 往返本身失败才 reject；
  *   业务失败以信封返回，由 unwrapRemoteResult 在注入面抛出。
  * - error 在线上是 {code,message,details?} 普通对象；判别依据 isDSHRemoteError 住在
@@ -75,20 +79,19 @@ export interface RawSessionDeleteRemote {
     empty(): Promise<RemoteResult<PurgeResultLike>>;
 }
 /**
- * 前缀路由的 fetch 实现。**相对路径**：不拼 base、不认 origin——页面本身就是从宿主 web server
- * 加载的，同源是这条薄线的全部前提。本机（含转发落在回环的桌面壳）靠回环 + Origin/Referer 过栅栏；
- * 远程（LAN / 反代）客户端另由宿主 `connection` 判「已认证的 Web 身份」，所以这条通道**只对**
- * `dsh web` 打印的 URL 打开过的页面成立（凭据是那行 URL 换来的 cookie，不是插件自己的秘密）。
+ * exact Fetch 路由的 fetch 实现。**同源、带挂载点前缀**：不拼 host、不认 origin——页面本身就是从
+ * 宿主页面加载的，同源是这条通道的全部前提；路径只由 `api-base.ts` 从 `document.baseURI` 的目录
+ * 与官方 `/api` 前缀拼出（根部署下与旧版逐字相同，反代到 `/dsh/` 时得到 `/dsh/api/...`）。
+ * 鉴权归宿主 `/api` bridge（ADR-0033）。所以这条通道**只对**宿主页面打开过、带宿主身份的客户端
+ * 成立（凭据是那次访问换来的 cookie，不是插件自己的秘密）。
  */
-export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemote;
+export declare function createHttpRemote(): RawSessionDeleteRemote;
 /**
- * 取数通道探测：一次 `GET /ping` 走通（或走到）就是"通道在"。
+ * 探测唯一通道：一次 `GET /ping` 回成功信封（`pong`）才注册入口。
  *
- * 判据是**「拿到信封」而不是「操作成功」**：`{ok:false, error}` 也是一次成功的往返（路由在、依赖接上了、
- * 错误映射也生效了），那时该做的是把入口显示出来、让原文上屏；只有往返本身失败才算通道缺席 ⇒
- * 一个槽位贡献都不注册（docs/architecture.md §3「通道探测决定入口出现与否」）。
- *
- * 探测用一次零成本的 `GET /ping`，不读清单，避免每次页面加载都跑全表对账。
+ * - 401/403 是宿主 `/api` 的纯文本身份/归属失败：入口不出现，不装禁用态。
+ * - 失败信封 / 404 / 非信封同样按不可用处理：`/api` 网关对未知路径也可能回错误形状，
+ *   不能据此把入口摆出来让每个动作都失败。
  */
 export declare function probeChannel(raw: RawSessionDeleteRemote): Promise<boolean>;
 /** `shared/wire.ts` 的 `ApplyOutcome`、扫描报告与附件回执从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
@@ -117,7 +120,7 @@ export interface SessionDeleteRemote {
     /** 回收站之外的无主子会话报告（纯读）。读不到就是 throw —— 界面上那是**一次失败的检查**，
      *  不是"零条残留"（把 `io` 折成空报告等于把"不知道"说成"没有"）。 */
     scanOrphans(): Promise<OrphanReportWire>;
-    /** `.dsh` 内无引用图片对象的报告（纯读；含最多 200 条预览清单）。读不到就是 throw，同样不许折成 0。 */
+    /** `.dsh` 内无引用图片对象的报告（纯读；预览清单条数由 Node 半配置，默认 200）。读不到就是 throw，同样不许折成 0。 */
     scanAttachmentOrphans(): Promise<AttachmentOrphanReportWire>;
     /** 清掉报告那一刻无引用的图片副本（聚合回执）。 */
     cleanAttachmentOrphans(): Promise<AttachmentCleanupWire>;

package/lib/types/client/store.d.ts

@@ -24,13 +24,7 @@ export interface LazyStore<T> {
     invalidate: () => void;
     subscribe: (listener: () => void) => () => void;
 }
-export interface LazyStoreLifecycle {
-    /** 第一个订阅者到来时跑（观察者在这里接上）。 */
-    onFirstSubscribe?(): void;
-    /** 最后一个订阅者退订时跑（观察者在这里断开）。 */
-    onLastUnsubscribe?(): void;
-}
-export declare function createLazyStore<T>(initial: T, read: () => T, lifecycle?: LazyStoreLifecycle): LazyStore<T>;
+export declare function createLazyStore<T>(initial: T, read: () => T): LazyStore<T>;
 /**
  * 最新票句柄：每张票记着签发时的序号，只有序号仍等于当前的那张才 `current`。
  * 调用方在发起异步读时 `issue()` 一张票，落地前问 `ticket.current`——旧读因此不会盖掉新状态。

package/lib/types/client/trash-nav.d.ts

@@ -1,4 +1,4 @@
-import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { KeyboardEvent as ReactKeyboardEvent, RefObject } from 'react';
 import type { TrashEntryLike } from './remote.js';
 /**
  * 导航要的面。`ordered` 是**屏幕上的顺序**（只含展开的组），由面板/选择面算好传进来——
@@ -22,6 +22,10 @@ export interface TrashNavInput {
     toggleCheck: (entryId: string) => void;
     back: () => void;
     focusRow: (entryId: string) => void;
+    /** Esc 的作用域（面板根节点；生产入口必须传，测试可传空引用对象）。下钻时清单不在 DOM，
+     *  但详情在面板里；**焦点在面板外**的 Esc 不归清单——否则在侧栏或别的面板按 Esc 会退出下钻，
+     *  还会把焦点拽进回收站。根还没挂上时无从判断包含关系，Esc 不处理。 */
+    scope: RefObject<HTMLElement | null>;
 }
 export interface TrashNav {
     /** `aria-activedescendant` 的那条 id：选中行不在 DOM 里时是 `null`。 */

package/lib/types/client/trash-view.d.ts

@@ -17,6 +17,9 @@ export declare const CARD_SELECTED: CSSProperties;
 /**
  * **整页唯一那块实心红**的写法：`variant="primary"` + 在元素上覆盖 primary 那对填充 token。
  * 宿主插件管理页的 danger 按钮就是这个写法（asar @21658274），所以 hover 仍走 `.primary:hover` 类。
+ *
+ * 覆盖的是**本插件别名层**（`--sd-*`，见 `ui.css` 头注）而不是宿主私有 token：别名在 `body` 上
+ * 就把 `var(--dsw-…, 兜底)` 算完并继承下来了，元素上再覆盖底层私有 token 已经传不进继承值。
  */
 export declare const BULK_DANGER: CSSProperties;
 /**