@xrn1997/dsh-session-delete 0.3.1 → 0.4.0

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

@@ -1,4 +1,5 @@
-import { type ApplyAction, type ApplyOutcome, type ApplyValueByAction, type RemoteFailure } from '../shared/wire.js';
+import type { Translate } from './copy.js';
+import { type ApplyAction, type ApplyOutcome, type ApplyValueByAction, type AttachmentCleanupWire, type RemoteFailure } from '../shared/wire.js';
 /**
  * 一条 `/apply` 结果对一个请求 id 的含义。各写入面不许再各自推导：
  * 缺 id 是通道错误，`null` 是幂等成功，orphan-clean 的 `not-found` 是中性提示而非失败，
@@ -31,6 +32,8 @@ export type ReceiptVerdict<A extends ApplyAction> = {
     readonly message: string;
 };
 export interface Receipt<A extends ApplyAction> {
+    /** 产生这份回执的动作：摘要据此只派发该动作真的有的那几种落地 id。 */
+    readonly action: A;
     readonly verdicts: readonly ReceiptVerdict<A>[];
     readonly byId: ReadonlyMap<string, ReceiptVerdict<A>>;
 }
@@ -52,7 +55,6 @@ export declare function missingOutcomeMessage(action: ApplyAction, id: string):
 export type FailureVerdict<A extends ApplyAction> = Extract<ReceiptVerdict<A>, {
     kind: 'failed' | 'neutral' | 'missing';
 }>;
-export declare function isFailureVerdict<A extends ApplyAction>(verdict: ReceiptVerdict<A>): verdict is FailureVerdict<A>;
 /** failed / neutral 取服务端原文 `error.message`；missing 取通道自己写的那句。 */
 export declare function failureMessage<A extends ApplyAction>(verdict: FailureVerdict<A>): string;
 export declare function readReceipt<A extends ApplyAction>(action: A, requestedIds: readonly string[], outcomes: readonly ApplyOutcome[], options?: ReceiptOptions): Receipt<A>;
@@ -61,6 +63,44 @@ export declare function readReceipt<A extends ApplyAction>(action: A, requestedI
  * single 读法运行期不会产出它）。`applyOne` 用它之后只剩「按 id 取一条 + 抛失败」。
  */
 export declare function readSingleReceipt<A extends ApplyAction>(action: A, id: string, outcomes: readonly ApplyOutcome[]): SingleReceipt<A>;
+/** 一次写入回执的**一个读法**：成功、失败、中性、部分计数与落地 id 都从这里出。
+ *  座位与收尾不再自己 walk `verdicts`——那会把同一套判据在调用点再组装一遍。 */
+export interface ReceiptSummary {
+    readonly successIds: readonly string[];
+    readonly neutralIds: readonly string[];
+    /** failed + missing（通道没回）；neutral 单独在 `neutralIds`，部分计数只从 failed 的 details 取。 */
+    readonly failed: readonly {
+        readonly id: string;
+        readonly error: RemoteFailure;
+    }[];
+    readonly partial: {
+        readonly removed: number;
+        readonly freedBytes: number;
+    };
+    /** 这次动作真正落地的 id。**域由 `action` 定**：delete 是条目 id（撤销名单），restore 是会话 id
+     *  （回盘名单）；purge / count / orphan-clean 没有可撤销的落地 id，恒为空。
+     *  两个域不混在一个数组里靠调用方猜，也不各留一个永远为空的字段。 */
+    readonly landedIds: readonly string[];
+    readonly anySuccess: boolean;
+    /** purge / orphan-clean 的 `ok` 回执里那半份附件读数，**按批相加**（一段 `/apply` 可能带多条 ok）。
+     *  `skipped` 取第一条有的：它说的是"这一轮为什么没敢清"，不是可累加的计数。
+     *  两种动作都没有读数（或这一批一条都没落地）时缺席——不拿零冒充"清过"。 */
+    readonly attachmentCleanup?: AttachmentCleanupWire;
+}
+/** 一次摘要派生的两样产物：聚合摘要与逐条失败原文。
+ *  失败表只挂在 `WriteSuccess` 上（成败两支的统一读法），摘要自己不再留第二份。 */
+export interface ReceiptRead {
+    readonly summary: ReceiptSummary;
+    readonly failures: ReadonlyMap<string, string>;
+}
+/**
+ * 附件清理回执的「跳过半句」：`skipped` 说的是"这一轮为什么没敢清"，不是失败——原因上屏，
+ * `removed > 0` 时说「部分」，`failed` 件数追加在句尾（不被跳过原因吞掉）。
+ * 面板（`use-trash-query.ts`）与维护卡（`use-maintenance.ts`）共用这一判据，不许各拼一份。
+ * 没 `skipped` 时回 `null`：后半句（全清/失败怎么说）两个面各有各的口径，由调用方自己接。
+ */
+export declare function attachmentSkippedSentence(a: AttachmentCleanupWire, t: Translate): string | null;
+export declare function summarizeReceipt<A extends ApplyAction>(receipt: Receipt<A>, sessionIdOfEntry?: (entryId: string) => string | undefined): ReceiptRead;
 /**
  * `/apply` 成功支回执里的条目 id（delete / restore 的 `value.id`）；purge 的聚合值与 count 的数字值跳过。
  * 撤销名单只收 `ok` 支的条目 id：already-gone 是「已被同批前一条带走」的幂等条，跟着组走，不单列。

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

@@ -1,42 +1,19 @@
 /**
- * 浏览器半的**取数通道**：同源 fetch 宿主 web server 上的 `/dsh-session-delete-api`，
- * 加上信封判别与注入面那一处「展开成裸值」的适配。
+ * 浏览器半的取数通道：同源 fetch /dsh-session-delete-api，并处理信封与失败原文。
  *
- * 通道形状（裁决）：真相/账本/判据全在宿主那边，Node 半用宿主**自己的 web server** 开一条
- * 插件专属前缀路由把六个段名（`list` / `ping` / `orphans` / `detail` / `apply` / `empty`）搬出来
- * （`src/api/dispatch.ts`），浏览器半同源调用。**不是重造后端**：
- * 路由层只做搬运与信封。为什么不用官方的 `remote.<namespace>`：那条路要**生成的 Typert 远程描述符**
- * 加一次 `$mount`，而盒内装配清单写死在 `dsh-api-remotes` 里、全宿主没有动态发现，第三方只能自挂自，
- * 对一个薄插件不划算。
- *
- * 三条约束决定了这个文件长这样：
- *
- * 1. **信封刻意与官方 unary 面同形**：`{ ok: true, value }` / `{ ok: false, error }`。这不是"还留着
- *    官方通道"——它现在是**我们两半之间**的 wire 契约（Node 半按它产出，见 `src/api/dispatch.ts`），
- *    选它是为了让组件面、`unwrapRemoteResult` 与既有用例一行都不用改。失败是**返回**而不是
- *    reject（同宿主网关原文："Every unary call resolves to `RemoteResult<T>` … and never rejects for a
- *    carrier problem"）；只有往返本身失败（打不通、回的不是信封）才 reject，那是**通道缺席**。
- * 2. **不许值 import 跨插件包**。`error` 在线上就是一段 JSON（`{code, message, details?}`），不是
- *    `RemoteError` 实例——所以判别**所依据的那一个标记位**只镜一份，家在两半共用的
- *    `src/shared/wire.ts`（`isDSHRemoteError`）。浏览器半落到本地时用 `throwRemoteFailure` 就地补上
- *    Error 本体与标记位；Node 半（`src/remote/map-error.ts`）只用它做「这已经是一次远程失败」的判别，
- *    产出的是线上那三件（`details` 可缺席）、不造任何 Error，更不 import 宿主那个类。
- * 3. **失败原文必须能上屏**。调用方（`callRemote`）只把**抛出来的失败**收成判别式状态——
- *    `{ ok: false, error }` 不是第三种落地：它在注入面那一处已经被 `unwrapRemoteResult` 抛成了异常，
- *    所以到了组件面前只剩「裸值 / throw」两支，调用方只写 `if (!outcome.ok)`，正常流里没有 try/catch；
- *    非本信封形状的异常（网络层、TypeError…）也不丢原文（见 `failureOf`）。
- *
- * 面（`list` / `ping` / `orphans` / `detail` / `apply` / `empty`）与 Node 半路由的六个段名一一对应（段名本身的家是
- * `src/shared/wire.ts`）；`list` 回一行行的条目，`ping` 只回一个探针值，`orphans` 回一份**纯读**的
- * 残留扫描报告，`detail` 回单条正文，
- * `apply` 回**一组逐条结果**，`empty` 回聚合回执。2026-10-17 之前是六个动作段（一条一段），
- * 批量只能由调用方循环拼——那正是「恢复 100 条很慢」的形状来源，收成一段之后这条通道不再有
- * "第二条执行路径"。**清理无主子会话也不另开一段**：它是 `apply` 的第五个动作，`orphans` 只负责
- * "有多少、在哪、多大"。
+ * - 路由是宿主 web server 上的插件前缀；官方 remote.<namespace> 需要生成的 Typert 描述符，
+ *   第三方无法动态挂载，因此走这条薄线（ADR-0009）。
+ * - 九段：list / ping / orphans / detail / apply / empty / attachment / attachment-orphans / attachment-clean；
+ *   写动作统一走 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 住在
+ *   src/shared/wire.ts，这里不 import 任何宿主客户端包。
  */
-import { type ApplyAction, type ApplyOutcome, type ApplyValueByAction, type OrphanReportWire, type PurgeStatsWire, type RemoteFailure, type RemoteResult, type TrashDetailWire, type TrashRowWire } from '../shared/wire.js';
+import { type ApplyAction, type ApplyOutcome, type ApplyValueByAction, type AttachmentCleanupWire, type AttachmentOrphanReportWire, type OrphanReportWire, type PurgeStatsWire, type RemoteFailure, type RemoteResult, type TrashDetailWire, type TrashRowWire } from '../shared/wire.js';
 /**
- * 回收站条目（`/list` 那一行）。**形状的家在 `shared/wire.ts`**（ADR-0003）：这里只是旧名的别名，
+ * 回收站条目（`/list` 那一行）。**形状的家在 `shared/wire.ts`**（ADR-0003）：这里只是别名，
  * 所以浏览器半不再自己抄一遍字段；下面几处"只读面"的镜像同理。
  */
 export type TrashEntryLike = TrashRowWire;
@@ -72,11 +49,9 @@ export type RemoteOutcome<T> = {
  */
 export declare function callRemote<T>(run: () => Promise<T>): Promise<RemoteOutcome<T>>;
 /** 本插件前缀路由那套**响应信封**的窄镜像（不是宿主服务 `ctx.remote.*`——那条 typert 通道为什么用不了，见 `AGENTS.md` 的 `remote.<namespace>` 那条）：
- *  每个方法 resolve 成 `RemoteResult<T>`。
- *
- * 2026-10-17 批量重构：写动词收成**一个 `apply`**（一段管所有动作、一组 id 进、逐条结果出），
- * 再加一段**纯探测** `ping`；2026-10-19 又加一段**纯读扫描** `orphans` ⇒ 面是六段：
- * `list` / `ping` / `orphans` / `detail` / `apply` / `empty`（原先六个动作段）。 */
+ *  每个方法 resolve 成 `RemoteResult<T>`。九个段名里这层走八个 JSON 段：`list` / `ping` / `orphans` / `detail` / `apply` / `empty` /
+ *  `attachment-orphans` / `attachment-clean`；写动作统一走 `apply`（一组 id 进、逐条结果出）；
+ *  `/attachment` 是二进制段，由 `src/client/attachment-view.tsx` 直接拼地址。 */
 export interface RawSessionDeleteRemote {
     list(): Promise<RemoteResult<TrashEntryLike[]>>;
     /** 通道的"在不在"：一次零成本的 GET（探测专用，见 `src/api/dispatch.ts` 的 `ping` 支）。 */
@@ -84,6 +59,10 @@ export interface RawSessionDeleteRemote {
     /** 纯读：回收站之外的无主子会话扫描。它**不清理**——清理是 `apply` 的 `orphan-clean` 动作，
      *  这一段只交回"有多少、在哪、多大"（读不到语料时报 `io`，调用方不许把它折成"零条残留"）。 */
     orphans(): Promise<RemoteResult<OrphanReportWire>>;
+    /** 纯读：`.dsh` 内无引用图片对象的数量、字节与预览清单（引用源读不出时报 `io`，不折成 0）。 */
+    attachmentOrphans(): Promise<RemoteResult<AttachmentOrphanReportWire>>;
+    /** 聚合写：只删上一条报告那一刻无引用的图片对象，回 `AttachmentCleanupWire`。 */
+    attachmentClean(): Promise<RemoteResult<AttachmentCleanupWire>>;
     detail(entryId: string): Promise<RemoteResult<TrashDetailLike>>;
     /** 一组 id 上的同一个动作。顶层信封的 `ok:false` 只表示**整次调用**没办成（路由自检、栅栏之外）；
      *  单条动作的成败住在 `ApplyOutcome` 里——这是批量接口的判据，别在信封层找它。 */
@@ -93,8 +72,9 @@ export interface RawSessionDeleteRemote {
 }
 /**
  * 前缀路由的 fetch 实现。**相对路径**：不拼 base、不认 origin——页面本身就是从宿主 web server
- * 加载的，同源是这条薄线的全部前提（也是它敢不带凭据的原因：宿主那行 URL 上的 browser-trust token
- * 不是这条通道的凭据，栅栏在 Node 半那一侧按 Origin/Referer 判）。
+ * 加载的，同源是这条薄线的全部前提。本机（含转发落在回环的桌面壳）靠回环 + Origin/Referer 过栅栏；
+ * 远程（LAN / 反代）客户端另由宿主 `connection` 判「已认证的 Web 身份」，所以这条通道**只对**
+ * `dsh web` 打印的 URL 打开过的页面成立（凭据是那行 URL 换来的 cookie，不是插件自己的秘密）。
  */
 export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemote;
 /**
@@ -104,12 +84,11 @@ export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemot
  * 错误映射也生效了），那时该做的是把入口显示出来、让原文上屏；只有往返本身失败才算通道缺席 ⇒
  * 一个槽位贡献都不注册（docs/architecture.md §3「通道探测决定入口出现与否」）。
  *
- * 2026-10-17：探测从"读一遍清单"改成这一问——**每次页面加载都跑全表对账**是白付的钱，
- * 而"信封到不到"这件事一次零成本的 GET 就答得出来。
+ * 探测用一次零成本的 `GET /ping`，不读清单，避免每次页面加载都跑全表对账。
  */
 export declare function probeChannel(raw: RawSessionDeleteRemote): Promise<boolean>;
-/** `shared/wire.ts` 的 `ApplyOutcome` 与那份扫描报告从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
-export type { ApplyAction, ApplyOutcome, OrphanReportWire } from '../shared/wire.js';
+/** `shared/wire.ts` 的 `ApplyOutcome`、扫描报告与附件回执从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
+export type { ApplyAction, ApplyOutcome, AttachmentCleanupWire, AttachmentOrphanReportWire, OrphanReportWire, } from '../shared/wire.js';
 /**
  * N=1 的成功支：`null` 已被 `receipt.ts` 的单条读法折成协议错，所以 `value` 必然非空。
  * 不再需要条件类型把 `delete` / `restore` 的 null 抠掉——那份判据只住回执读法一处。
@@ -121,7 +100,8 @@ export type OneShotSuccess<A extends ApplyAction> = {
     readonly value: Exclude<ApplyValueByAction[A], null>;
 };
 /**
- * 注入面（`deps`）的 interface：**与六个段名一一对应的五个方法**（`ping` 只给探测用，留在 raw 层）。
+ * 注入面（`deps`）的 interface：**七个方法**（raw 层另有 `ping` 供探测；九段里的 `/attachment` 由
+ * `src/client/attachment-view.tsx` 直接拼地址，也不在这层）。
  *
  * **不再有 N=1 的便捷方法**：`delete` / `restore` / `countSubagents` 曾是同一段
  * `/apply` 的三种写法，于是一个 `module` 里同一个动作有两条路（回收站面板的 deps 同时躺着
@@ -133,8 +113,12 @@ export interface SessionDeleteRemote {
     /** 回收站之外的无主子会话报告（纯读）。读不到就是 throw —— 界面上那是**一次失败的检查**，
      *  不是"零条残留"（把 `io` 折成空报告等于把"不知道"说成"没有"）。 */
     scanOrphans(): Promise<OrphanReportWire>;
+    /** `.dsh` 内无引用图片对象的报告（纯读；含最多 200 条预览清单）。读不到就是 throw，同样不许折成 0。 */
+    scanAttachmentOrphans(): Promise<AttachmentOrphanReportWire>;
+    /** 清掉报告那一刻无引用的图片副本（聚合回执）。 */
+    cleanAttachmentOrphans(): Promise<AttachmentCleanupWire>;
     detail(entryId: string): Promise<TrashDetailLike>;
-    /** 一段管所有写动作（2026-10-17 批量重构）：一次调用把整批办完，逐条结果原样交回组件。 */
+    /** 一段管所有写动作：一次调用把整批办完，逐条结果原样交回组件。 */
     applyOutcomes(action: ApplyAction, ids: readonly string[]): Promise<ApplyOutcome[]>;
     /** 清空回收站（聚合回执）。 */
     emptyTrash(): Promise<PurgeResultLike>;

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

@@ -1,19 +1,6 @@
 import { type Translate } from './copy.js';
 import type { OrphanReportWire, TrashEntryLike } from './remote.js';
-/** 待确认的动作：一条记录、整个回收站、或多选挑出来的一批（`ids` 已按清单顺序排好）。
- *  `purge` 与 `restore` 的确认框共用这一个壳——两者都是"点之前先说清这一批有哪些、要去哪"。 */
-export type PendingAction = {
-    kind: 'entry';
-    entry: TrashEntryLike;
-} | {
-    kind: 'all';
-} | {
-    kind: 'entries';
-    ids: readonly string[];
-} | {
-    kind: 'restore';
-    ids: readonly string[];
-};
+import type { PendingAction } from './use-trash-panel-controller.js';
 /**
  * 两种批量动作共用这一个确认框壳：`purge`（不可恢复）与 `restore`（加法，但一批条目多、去向是
  * 各自的旧项目目录，点之前也要过一道）。标题、正文、确认键的措辞各处一套；批量恢复把选中条目
@@ -29,7 +16,7 @@ export declare function TrashConfirm({ pending, restoreEntries, busy, t, onCance
     onConfirmPurge: () => void;
     onConfirmRestore: (ids: readonly string[]) => void;
 }): import("react").JSX.Element;
-/** 无主子会话的清理确认框（2026-10-19）。载荷是刚扫出来的那份报告，界面不重算。 */
+/** 无主子会话的清理确认框。载荷是刚扫出来的那份报告，界面不重算。 */
 export declare function OrphanConfirm({ report, busy, t, onCancel, onConfirm, }: {
     report: OrphanReportWire;
     busy: boolean;

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

@@ -1,9 +1,10 @@
 import { type Translate } from './copy.js';
 import { type SessionDeleteRemote } from './remote.js';
-/** 面板的依赖面：三个读（`list` / `detail` / `scanOrphans`）+ **一段 `apply`** + 清空。
+/** 面板的依赖面：两个读（`list` / `detail`）+ **一段 `apply`** + 清空。
  *  **没有第二条路**：「恢复一条」也走 `apply`（N=1），面板不再同时吃
- *  `applyOutcomes` 与一个便捷的 `restore`。 `scanOrphans` 是回收站之外那批无主子会话的纯读报告。 */
-export type TrashPanelDeps = Pick<SessionDeleteRemote, 'list' | 'detail' | 'applyOutcomes' | 'emptyTrash' | 'scanOrphans'>;
+ *  `applyOutcomes` 与一个便捷的 `restore`。无主子会话的检查/清理不在这里——它是插件设置页
+ *  维护卡的手动动作（`use-maintenance.ts`），面板一次都不自动扫（ADR-0021）。 */
+export type TrashPanelDeps = Pick<SessionDeleteRemote, 'list' | 'detail' | 'applyOutcomes' | 'emptyTrash'>;
 export interface TrashPanelProps {
     deps: TrashPanelDeps;
     /** 文案（缺省 = 内置 zh，见 `copy.ts`：这不是"忘了传"，而是"这次没有 locale 服务"）。 */

package/lib/types/client/ui/Checkbox.d.ts

@@ -1,5 +1,5 @@
 /**
- * 勾选框（2026-10-15 加，回收站多选态用）。
+ * 勾选框，回收站多选态用。
  *
  * 样式与行为抄自 `@deepseek-ai/dsh-client-ui-primitives` 的 `lib/Checkbox.module.css`
  * （那四条声明逐字进了 `ui.css` 的 `.sd-checkbox`）：**本体是原生 `input[type=checkbox]` +

package/lib/types/client/ui/Modal.d.ts

@@ -14,8 +14,8 @@
  * - **官方的多层栈**（`layers` WeakMap + `closeTopModal` / `isBehindModal`）：那是给"对话框里还能再开
  *   对话框、且宿主菜单也在抢 Escape"的场景准备的。本插件同一时刻只会有一个确认框，所以这里只保留它
  *   的**判据本身**——Escape 只在"自己就是文档里最后一个 `[role="dialog"][aria-modal="true"]`
- *   或 `[role="menu"]`"时生效（`isTopLayer`）。这一条不能省：菜单/对话框先后打开时，
- *   "谁在最上面谁收 Escape"是用户能看见的规矩。
+ *   或 `[role="menu"]`"时生效（`isTopLayer`，名单与判据住 `ui/top-layer.ts`）。这一条不能省：
+ *   菜单/对话框先后打开时，"谁在最上面谁收 Escape"是用户能看见的规矩。
  * - **输入法合成守卫**（`observeComposition`）：本插件的对话框里没有文本输入框，不可能处在合成态。
  */
 import { type ReactElement, type ReactNode } from 'react';

package/lib/types/client/ui/icons.d.ts

@@ -1,18 +1,13 @@
 /**
- * 本插件 UI 层要用的图标（**逐条抄自** `@deepseek-ai/dsh-client-ui-primitives@0.2.0-rc.2`
- * 随包发布的明文产物 `lib/index.js`；出处与改写规则见 `ui.css` 头注）。
+ * 本插件 UI 层要用的图标（逐条抄自 `@deepseek-ai/dsh-client-ui-primitives` 的明文产物；
+ * 出处与改写规则见 `ui.css` 头注）。
  *
- * 只留本插件用到的：垃圾桶（删除动作 / 回收站）、警示（失败面）、打开的项目文件夹、
- * 关闭叉（对话框）、圆圈对勾（撤销提示的 success 档）、对勾（行尾兜底勾选开关，2026-10-17 加；
- * 行首主勾选走原生 Checkbox）、下折与右折 chevron（清单的分组折叠头，
- * 2026-10-15 加：`DisclosureRow` 那套折叠行的两态 glyph）。「刷新」那枚随按钮一起删了
- * （2026-10-16，见 `trash-panel.tsx` 工具排的注释）——本文件不留无人消费的几何。
+ * 只留本插件用到的：垃圾桶、警示、打开的项目文件夹、关闭叉、圆圈对勾、对勾、下折/右折 chevron。
  * **几何、`viewBox`、`strokeWidth` 逐字不动**——它们是官方图标集的形状，改了就不再与宿主同屏同形。
  *
  * 两条与官方实现的差异（都是减法，不是改写）：
- * - 只暴露 `size`（官方是 `{size, className, strokeWidth}` 三件套 + `Medium` 1.3px 那一档）：
- *   本插件调用处只传 `size`，加别的等于摊开官方整个图标 API。
- * - 不做 `ICON_REGULAR_STROKE` / `ICON_MEDIUM_STROKE` 常量：只有一个档位，直接写 1。
+ * - 只暴露 `size`：调用处只传 `size`，不摊开官方整个图标 API。
+ * - 不做 stroke 常量：只有一个档位，直接写 1。
  */
 import type { ReactElement } from 'react';
 /** 宿主图标组件的实际使用面：一个方形边长，色走 `currentColor`。 */
@@ -25,7 +20,7 @@ export declare function IconFolderOpenOutlineRegular({ size }: IconProps): React
 export declare function IconCloseOutlineRegular({ size }: IconProps): ReactElement;
 /** 撤销提示 success 档的前导 glyph（官方 `Toast` 在 `tone="success"` 时自带的那一枚）。 */
 export declare function IconCheckCircleOutlineRegular({ size }: IconProps): ReactElement;
-/** 行尾兜底「勾选开关」那枚对勾（状态点/归档行；官方 `IconCheckOutlineRegular`，`viewBox`/`d` 逐字；2026-10-17 加）。 */
+/** 行尾兜底勾选开关那枚对勾（状态点/归档行；官方几何逐字）。 */
 export declare function IconCheckOutlineRegular({ size }: IconProps): ReactElement;
 /** 分组头「展开中」那一枚（官方 `IconChevronDownOutlineRegular`，`viewBox`/`d` 逐字）。 */
 export declare function IconChevronDownOutlineRegular({ size }: IconProps): ReactElement;

package/lib/types/client/ui/top-layer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 「谁在最上层收 Escape」的名单与判据。`Modal` 的关闭键和清单的 Esc 退下钻共用这一份：
+ * 两份各写一次选择器，菜单/对话框换代时必然只剩一处跟上。
+ *
+ * 名单与官方 `modalSelector` 同形：模态对话框 + 菜单。文档序里最后一个是「最上层」。
+ */
+/** 文档里是否还有打开的顶层浮层。清单只问「有没有」，它自己不是其中一员。 */
+export declare function hasTopLayer(doc: Document): boolean;
+/** 自己是不是文档里最上面的那一层。Modal 只在这时收 Escape。 */
+export declare function isTopLayer(element: HTMLElement): boolean;

package/lib/types/client/undo-notices.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 一次待撤销的事。两形：单条删除（主语是会话名）／批量删除（主语是条数）。
+ * 同一个 Toast 宿主、同一停留时长；撤销动作按形分派（单条 / 批量），两条都走同一个外部恢复座位
+ * （`write-seats.ts` 的 `restoreFromUndo`），单条带 `single: true` 的读法（null 是协议错，不冒充幂等成功）。
+ */
+export type UndoNotice = {
+    /** 每次发布递增：Toast 靠它重挂载，同一段文案连续出现两次也能重新计一次停留。 */
+    seq: number;
+    /** 撤销失败时把原因顶上来：这时不再有「撤销」动作，只剩原文。 */
+    failure?: string;
+} & ({
+    kind: 'one';
+    /** 回收站条目 id——撤销就是拿它去 `restore`。 */
+    entryId: string;
+    /** 删除那一刻的会话名（菜单槽投影的 `displayTitle`；取不到时是空串）。 */
+    title: string;
+} | {
+    kind: 'batch';
+    /** 撤销名单：只收成功支里非 null 的条目 id（「被同批带走」的成员跟着组走，不单列）。 */
+    entryIds: readonly string[];
+    /** 横幅那句的条数 = 那一次成功支的条数（含幂等带走的）——与撤销名单是两个数，各说各的。 */
+    n: number;
+});
+/** 删除成功后发布一条撤销提示（单条）。 */
+export declare function publishUndoNotice(input: {
+    entryId: string;
+    title: string;
+}): void;
+/** 批量删除成功后发布一条撤销提示：覆盖上一条，只报这一次移走的条数。 */
+export declare function publishUndoBatchNotice(input: {
+    entryIds: readonly string[];
+    n: number;
+}): void;
+/** 整条横幅不再留：撤销成了、停留时间走完，或清空回收站把所有落点一起清了。
+ *  与 `dismissUndoNotice` 的分别是「整条不再留」与「按条目匹配」——清空之后没有条目还能撤销，
+ *  所以那一路不需要名单。 */
+export declare function clearUndoNotice(): void;
+/**
+ * 某个条目已经在别处恢复：把指向它的横幅熄掉。
+ * 批量里任一命中就清整条——名单少了、计数没变，留着就是一条会骗人的「撤销」动作。
+ */
+export declare function dismissUndoNotice(entryIds: readonly string[]): void;
+/** 供组件订阅。 */
+export declare function useUndoNotice(): UndoNotice | null;
+/** 测试专用：现场与 seq 归零，用例之间互不串味。 */
+export declare function resetUndoNotice(): void;
+/** 提示停留时长。**6 秒** 定死在本行（比 Toast 默认的 3 秒长）——`docs/ui-spec.md` §2 状态 ③ 只指到这里，不抄这个数。 */
+export declare const UNDO_HOLD_MS = 6000;
+/** 这次撤销开始时的那条横幅还在吗——期间被新删除覆盖、或由面板恢复熄灭时，旧请求不许改写它。 */
+export declare function ownsNotice(current: UndoNotice): boolean;
+/** 撤销失败：把原因换到同一条横幅上（seq 递增 ⇒ Toast 重挂载、重新计停留）。 */
+export declare function failNotice(current: UndoNotice, message: string): void;

package/lib/types/client/undo-toast.d.ts

@@ -1,71 +1,17 @@
 /**
  * 撤销提示（docs/ui-spec.md 状态 ③）：删除成功后一条可撤销的横幅。
  *
- * 为什么是**独立组件 + 模块级通知台**，而不是死在菜单行里：宿主的菜单行随菜单**一起卸载**
- * （真产物 Menu 的注释原文 "the rows unmount with the list"），而提示要在菜单关掉之后还活着。
- * 宿主的官方配方同形——会话行的动作把请求写进一个模块级 store，`shell.overlay` 里的
- * `workspace.row-toast` 读它（asar 原文：`inject("shell.overlay", … id: "workspace.row-toast" …
- * inject: rowToastInjected … }, RowActionToast)`，而
- * `rowToastInjected = () => ({ hooks: { toast: rowToast }, dismissToast, undoArchive: unarchiveSession })`）。
- * 本文件就是那份 store + 那个常驻组件。
- *
- * 状态源走 `store.ts` 的 `createStore`（内部用 React 自带的 `useSyncExternalStore`）——
- * 不引 `@deepseek-ai/dsh-client-store`（它在平台表内，但这里用不着；React 就够，少一条平台依赖）。
+ * 现场与发布住在 `undo-notices.ts`；本文件只做组件，并把通知台与外部恢复座位组合起来。
+ * 为什么组件要独立：宿主的菜单行随菜单**一起卸载**（真产物 Menu 的注释原文
+ * "the rows unmount with the list"），而提示要在菜单关掉之后还活着。宿主的官方配方同形——
+ * 会话行的动作把请求写进一个模块级 store，`shell.overlay` 里的 `workspace.row-toast` 读它。
  */
 import { type Translate } from './copy.js';
 import type { OneShotDeps } from './remote.js';
 export type UndoToastDeps = OneShotDeps;
-/**
- * 一次待撤销的事。两形（2026-10-17 起）：单条删除（主语是会话名）／批量删除（主语是条数）。
- * 同一个 Toast 宿主、同一停留时长；撤销动作按形分派（单条 / 批量），两条都走同一个外部恢复座位
- * （`write-seats.ts` 的 `restoreFromUndo`），单条带 `single: true` 的读法（null 是协议错，不冒充幂等成功）。
- */
-export type UndoNotice = {
-    /** 每次发布递增：Toast 靠它重挂载，同一段文案连续出现两次也能重新计一次停留。 */
-    seq: number;
-    /** 撤销失败时把原因顶上来：这时不再有「撤销」动作，只剩原文。 */
-    failure?: string;
-} & ({
-    kind: 'one';
-    /** 回收站条目 id——撤销就是拿它去 `restore`。 */
-    entryId: string;
-    /** 删除那一刻的会话名（菜单槽投影的 `displayTitle`；取不到时是空串）。 */
-    title: string;
-} | {
-    kind: 'batch';
-    /** 撤销名单：只收成功支里非 null 的条目 id（「被同批带走」的成员跟着组走，不单列）。 */
-    entryIds: readonly string[];
-    /** 横幅那句的条数 = 那一次成功支的条数（含幂等带走的）——与撤销名单是两个数，各说各的。 */
-    n: number;
-});
-/** 删除成功后发布一条撤销提示（单条）。 */
-export declare function publishUndoNotice(input: {
-    entryId: string;
-    title: string;
-}): void;
-/** 批量删除成功后发布一条撤销提示（2026-10-17）：覆盖上一条，只报这一次移走的条数。 */
-export declare function publishUndoBatchNotice(input: {
-    entryIds: readonly string[];
-    n: number;
-}): void;
-/** 整条横幅不再留：撤销成了、停留时间走完，或清空回收站把所有落点一起清了。
- *  与下面 `dismissUndoNotice` 的分别是「整条不再留」与「按条目匹配」——清空之后没有条目还能撤销，
- *  所以那一路不需要名单。 */
-export declare function clearUndoNotice(): void;
-/**
- * 某个条目已经在别处恢复：把指向它的横幅熄掉。
- * 批量里任一命中就清整条——名单少了、计数没变，留着就是一条会骗人的「撤销」动作。
- */
-export declare function dismissUndoNotice(entryIds: readonly string[]): void;
-/** 供组件订阅。 */
-export declare function useUndoNotice(): UndoNotice | null;
-/** 测试专用：现场与 seq 归零，用例之间互不串味。 */
-export declare function resetUndoNotice(): void;
-/** 提示停留时长。**6 秒** 定死在本行（比 Toast 默认的 3 秒长）——`docs/ui-spec.md` §2 状态 ③ 只指到这里，不抄这个数。 */
-export declare const UNDO_HOLD_MS = 6000;
 /**
  * 常驻的撤销提示宿主。挂 `shell.overlay`（框架级浮层；槽位说明原文 "a toast stack or a status
- * pill all belong here"，见 asar 里 `shell.overlay` 的声明）：没有待撤销的事时什么都不渲染。
+ * pill all belong here"）：没有待撤销的事时什么都不渲染。
  */
 export declare function UndoToast({ deps, t }: {
     deps: UndoToastDeps;

package/lib/types/client/use-column-resize.d.ts

@@ -1,26 +1,15 @@
 /**
- * 清单列与详情列之间那根**可拖的宽度把手**（2026-10-15 加，`docs/ui-spec.md` 的「面板与清单」）。
+ * 清单列与详情列之间那根可拖的宽度把手（docs/ui-spec.md 的「面板与清单」）。
  *
- * 三件事住在这里，因为它们互相咬合、分开测各自都不成立：
- * ① **宽度夹在两个界之间**。下限由调用方给（回收站那条的来历写在 `trash-panel.tsx`：真 Chromium
- *    上扫出来的，约束不是"两颗按钮放得下"——它们 `flex:none`，再窄也是文字列缩；而是「删除于 … ·
- *    大小」那一行不再被省略号截断），上限 = 面板宽 − `reserve`。**`reserve` 的数值与来历都住在调用方**
- *    （`DETAIL_RESERVE`，那三件东西怎么加出来的见 `trash-panel.tsx` 该常量的注释与几何用例）：
- *    这一层不复制那份算式——上一版在这里钉过一个"480 ⇒ 900 那档正好回 420"，调用方改到 489 之后
- *    它就成了假数，而 900 那档的真实读数是**清单被夹到 411**（比默认窄 9px，还能往里拖）。
- * ② **夹在"读"的时候也做一次**。窗口变窄不触发任何写入，若只在写入时夹，之前拖出来的超宽
- *    清单会一直留到下次交互 ⇒ `listWidth` 每次渲染都按当前 `panelWidth` 重算。
- * ③ **按下才算在拖**。指针捕获挂在把手元素上（`setPointerCapture`），move 只可能来自这一根把手；
- *    `origin === null` 时 move 直接返回——鼠标扫过不该改布局。抬起不用显式 release：规范里
- *    pointerup/pointercancel 会隐式释放捕获，多写那一行只会引入"指针已不活跃"的抛错面。
- *    **但"结束"不能只挂在把手上**：拖动途中把手会被卸载（面板窄过断点、或清单被读空 ⇒ `split`
- *    翻了），而卸载后的节点收不到任何事件 ⇒ `resizing` 永远挂着：面板根留着 `.sd-resizing`
- *    （关文字选中），下次变宽时把手还带着 `data-dragging` 长回来。所以拖住期间另在 window 上兜
- *    一层 `pointerup`/`pointercancel`（复用同一个 `stop`）。move 仍然只认把手，捕获那套一点没动。
+ * 三件事住在这里：
+ * ① 宽度夹在两个界之间：下限由调用方给，上限 = 面板宽 − reserve。
+ *    reserve 的数值与来历住在调用方（DETAIL_RESERVE），这一层不复制算式。
+ * ② 夹在“读”的时候也做一次：窗口变窄不触发写入，listWidth 每次渲染按当前 panelWidth 重算。
+ * ③ 按下才算在拖：指针捕获挂在把手元素上；拖动途中把手可能卸载，所以 window 上另兜一层
+ *    pointerup/pointercancel 复用 stop；move 仍只认把手。
  *
- * 键盘那条不是装饰：`role="separator"` 可聚焦、←→ 各一格、Home 回默认、End 到上限。
- * 这一代的 `--dsw-focus-ring-color` 是 transparent（宿主自己那份焦点环靠别的属性撑），
- * 所以焦点态的可见性由 `ui.css` 里 `.sd-width-handle:focus-visible::after` 那一条负责。
+ * 键盘：role=separator、←→ 各一格、Home 回默认、End 到上限；焦点态可见性由 ui.css 的
+ * .sd-width-handle:focus-visible::after 负责。
  */
 import { type KeyboardEvent, type PointerEvent } from 'react';
 export interface ColumnResizeArgs {

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

@@ -0,0 +1,45 @@
+import type { Translate } from './copy.js';
+import { type AttachmentOrphanReportWire, type OrphanReportWire, type SessionDeleteRemote } from './remote.js';
+/** 维护卡只需要这四段：两份报告 + 孤儿会话的批量写 + 孤儿附件的聚合写。 */
+export type MaintenanceDeps = Pick<SessionDeleteRemote, 'scanOrphans' | 'applyOutcomes' | 'scanAttachmentOrphans' | 'cleanAttachmentOrphans'>;
+/** 一段在飞的动作：检查只读，清理会写。状态行靠它分开说「检查中…」与「清理中…」；`null` = 空闲。 */
+export type MaintenancePhase = 'scanning' | 'cleaning';
+export interface Maintenance {
+    readonly orphanReport: OrphanReportWire | null;
+    readonly orphanFailure: string | null;
+    /** 「这一组已经不在」不是失败：单独一条中性提示。 */
+    readonly orphanNotice: string | null;
+    /** 上一趟孤儿会话清理顺带清掉的附件读数（`.dsh` 内独占图片副本）。重查读不出来，和
+     *  `orphanNotice` 一样是过去那一趟的回执；下一次检查 / 清理会被收掉。 */
+    readonly orphanAttachmentNotice: string | null;
+    readonly orphanConfirm: boolean;
+    readonly orphanBusy: boolean;
+    /** 在飞的是检查还是清理；`null` = 空闲。写动作在飞时状态行据此说「清理中…」。 */
+    readonly orphanPhase: MaintenancePhase | null;
+    /** 手动检查（`GET /orphans`）。失败回 `null` + 原文，不折成零条。 */
+    scanOrphans(): Promise<void>;
+    /** 「查看并清理」：先收掉旧提示再开确认框。 */
+    openOrphanPreview(): void;
+    /** `/apply` 的 `orphan-clean`：清完必重查；中性 / 失败 / 部分计数按回执说。 */
+    cleanOrphans(): Promise<void>;
+    setOrphanConfirm(open: boolean): void;
+    readonly attachmentReport: AttachmentOrphanReportWire | null;
+    readonly attachmentFailure: string | null;
+    /** 上一趟清理的回执（已清 / 跳过 / 逐文件失败），重查读不出来。 */
+    readonly attachmentNotice: string | null;
+    readonly attachmentConfirm: boolean;
+    readonly attachmentBusy: boolean;
+    /** 在飞的是检查还是清理；`null` = 空闲。 */
+    readonly attachmentPhase: MaintenancePhase | null;
+    /** 手动检查（`GET /attachment-orphans`）。 */
+    scanAttachmentOrphans(): Promise<void>;
+    /** 「查看并清理」：先收掉旧提示再开确认框。 */
+    openAttachmentPreview(): void;
+    /** `POST /attachment-clean`：清完必重查；`removed` / `failed` / `skipped` 按回执说。 */
+    cleanAttachmentOrphans(): Promise<void>;
+    setAttachmentConfirm(open: boolean): void;
+}
+export declare function useMaintenance({ deps, t }: {
+    deps: MaintenanceDeps;
+    t: Translate;
+}): Maintenance;

package/lib/types/client/use-panel-width.d.ts

@@ -6,7 +6,7 @@
  *
  * 量的是**盒子的 border-box 宽**（`getBoundingClientRect().width`），不是 `contentRect.width`：
  * 后者已经扣掉内边距，而"多宽才分两栏"那个阈值说的是整块盒子——拿扣过内边垫的数去比就是**扣两次**，
- * 结果明明够宽却退化成下钻（2026-10-15 真机反馈后定的判据）。
+ * 结果明明够宽却退化成下钻（真机反馈后定的判据）。
  *
  * 首帧读一次当前宽度，之后跟着 RO 走；读到 0 就是窄档 ⇒ **窄档是默认、宽档要被证明**。
  * RO 缺席（不可能的宿主）时停在窄档：功能一条不少，只是同屏两栏变成下钻。

package/lib/types/client/use-trash-panel-controller.d.ts

@@ -1,18 +1,31 @@
 import type { BusyGate } from './busy-gate.js';
 import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
-import type { PendingAction } from './trash-confirm.js';
 import type { TrashDetailState } from './trash-detail.js';
-import type { TrashQuery } from './use-trash-query.js';
+import { type TrashQuery } from './use-trash-query.js';
+/** 待确认的动作：一条记录、整个回收站、或多选挑出来的一批（`ids` 已按清单顺序排好）。
+ *  类型归状态机，视图只 import 它来渲染。 */
+export type PendingAction = {
+    kind: 'entry';
+    entry: TrashEntryLike;
+} | {
+    kind: 'all';
+} | {
+    kind: 'entries';
+    ids: readonly string[];
+} | {
+    kind: 'restore';
+    ids: readonly string[];
+};
 /**
- * 控制器要的面。`query` 取四样：清单（选中从它里面找）、`refreshAll`（挂载与显式重试）、
- * `refreshAfterWrite`（失效与写后）、清空（面板的写动作那一半）。`ordered` 是键盘/自动选中用的
- * "屏幕上的顺序"（只含展开的组），
+ * 控制器要的面。`query` 取五样：清单（选中从它里面找）、`refreshAll`（挂载与显式重试）、
+ * `refreshAfterWrite`（失效与写后）、清空（面板的写动作那一半）、`noteAttachmentCleanup`（purge 回执里
+ * 附件那半句交给查询侧拼句子上屏）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
  * 由面板算好传进来——布局常量不搬进控制器。
  */
 export interface TrashPanelControllerInput {
     deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
     gate: BusyGate;
-    query: Pick<TrashQuery, 'entries' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash'>;
+    query: Pick<TrashQuery, 'list' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash' | 'noteAttachmentCleanup'>;
     ordered: readonly TrashEntryLike[];
     canAutoSelect: boolean;
 }
@@ -24,6 +37,8 @@ export interface TrashPanelController {
     readonly detail: TrashDetailState;
     /** 待确认的那一批（确认框的开合）；确认落地后由控制器收起。 */
     readonly pending: PendingAction | null;
+    /** 恢复确认框要摆的这一批（按勾选顺序；清单里已找不到的 id 滤掉）。 */
+    readonly pendingEntries: readonly TrashEntryLike[];
     /** 恢复/彻底删除/批量 的失败原文，按条目 id 存：切走再回来还在。 */
     readonly actionFailure: Readonly<Record<string, string>>;
     select(entry: TrashEntryLike, options?: {
@@ -31,7 +46,9 @@ export interface TrashPanelController {
     }): Promise<void>;
     retry(): void;
     back(): void;
-    setPending(pending: PendingAction | null): void;
+    /** 构造待确认动作（唯一入口：新增一种确认只改 `PendingAction` 与确认框，不再加一串转调）。 */
+    request(action: PendingAction): void;
+    cancelPending(): void;
     /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存，写完无论成败都重读清单，失败原文落回这一行。 */
     restore(entry: TrashEntryLike): Promise<void>;
     /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */