@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

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

@@ -0,0 +1,45 @@
+/**
+ * 无主子会话的**维护块**——警告条、失败块、中性提示与清理确认框。
+ *
+ * 它先是回收站面板上的一块，2026-10-27 起搬进插件设置页的「维护」卡（面板不再自动扫孤儿，ADR-0021）。
+ * 之所以仍收成一个 module：这三段与任何一面的清单渲染、选择、键盘、拖栏都毫无关系；改维护块的文案或
+ * 确认框时，diff 不该与布局改动互相踩。它只吃一个窄接口 `OrphanMaintenanceQuery`——报告、三条提示与
+ * 四个动作，实现方是设置页的 `use-maintenance.ts`。
+ *
+ * 三条界面规则（现状住 `docs/ui-spec.md`）：
+ * - **报告非空才出警告条**：空报告与 `null` 都不出现——"检查过了，什么都没有"不是要给用户看的东西，
+ *   而"还没扫到"更不是"零条"。
+ * - **读不到就说读不到**：检查/清理失败在原位摆原文 + 重试，绝不静默折成一条都不出现
+ *   （"没能回答有多少残留"与"没有残留"是两件事，不许折成空报告）。
+ * - **「已经不在」不是失败**：别处清掉或父已回到清册时单独一条中性提示，不计入失败，下次检查时自然消失。
+ *
+ * 四个动作都由实现方给：警告条开预览（`openOrphanPreview`）、失败块重试（`scanOrphans`）、
+ * 确认框清理（`cleanOrphans`）、取消（`setOrphanConfirm`）。`busy` 不归本 module 管——它是实现方
+ * 那一段自己的忙碌读数，通过 props 传进来。
+ */
+import type { ReactElement } from 'react';
+import type { Translate } from './copy.js';
+import type { OrphanReportWire } from './remote.js';
+/**
+ * 本块消费的那一面：一份报告、三条提示、四个动作。窄到只列它真读的成员——实现方多给（阶段、忙碌、
+ * 附件回执…）都与本块无关，也不许本块去读。设置页的 `Maintenance` 结构上满足它。
+ */
+export interface OrphanMaintenanceQuery {
+    /** `null` = 还没检查/读不到；本块只认"非空报告"那一档。 */
+    readonly orphanReport: OrphanReportWire | null;
+    readonly orphanFailure: string | null;
+    readonly orphanNotice: string | null;
+    readonly orphanConfirm: boolean;
+    setOrphanConfirm(open: boolean): void;
+    openOrphanPreview(): void;
+    cleanOrphans(): Promise<void>;
+    /** 检查（也是失败块那颗「重试」）：维护面上没有第二份扫描入口。 */
+    scanOrphans(): Promise<void>;
+}
+export interface OrphanMaintenanceProps {
+    query: OrphanMaintenanceQuery;
+    /** 这一段自己的忙碌读数：在飞时按住本块里的每一颗按钮。 */
+    busy: boolean;
+    t: Translate;
+}
+export declare function OrphanMaintenance({ query, busy, t }: OrphanMaintenanceProps): ReactElement | null;

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

@@ -1,17 +1,20 @@
-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` 是中性提示而非失败。
+ * 缺 id 是通道错误，`null` 是幂等成功，orphan-clean 的 `not-found` 是中性提示而非失败，
+ * **N=1 的 `null` 是协议错**——最后这条也在这里判，`applyOne` 与 `runWrite` 只消费同一份 verdict。
  *
  * 各 action 可能出现的 kind（类型面故意保持同一个联合，消费方按 action 自己收窄）：
  * - delete / restore：`ok` / `already-gone` / `failed` / `missing`
  * - count / purge：`ok` / `failed` / `missing`
  * - orphan-clean：`ok` / `neutral` / `failed` / `missing`
+ * - 单条读法（`readSingleReceipt`）：不含 `already-gone`；null 折成 `failed`
  */
 export type ReceiptVerdict<A extends ApplyAction> = {
     readonly kind: 'ok';
     readonly id: string;
-    readonly value: ApplyValueByAction[A];
+    readonly value: Exclude<ApplyValueByAction[A], null>;
 } | {
     readonly kind: 'already-gone';
     readonly id: string;
@@ -29,15 +32,82 @@ 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>>;
 }
+/** 浏览器半自己的未分类诊断码（通道打不通 / 非信封 / 单条协议错）。它不过线，线上失败码仍归 `shared/wire.ts`。 */
+export declare const CLIENT_UNKNOWN_CODE = "client/unknown";
+export interface ReceiptOptions {
+    /** N=1：null 只能是通道答错了，不冒充幂等成功。 */
+    readonly single?: boolean;
+}
+export type SingleReceiptVerdict<A extends ApplyAction> = Exclude<ReceiptVerdict<A>, {
+    kind: 'already-gone';
+}>;
+export interface SingleReceipt<A extends ApplyAction> {
+    readonly verdicts: readonly SingleReceiptVerdict<A>[];
+    readonly byId: ReadonlyMap<string, SingleReceiptVerdict<A>>;
+}
 export declare function missingOutcomeMessage(action: ApplyAction, id: string): string;
 /** 三种“这一条没成”的 verdict；`failureMessage` 是它们原文取值的唯一入口。 */
 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[]): Receipt<A>;
+export declare function readReceipt<A extends ApplyAction>(action: A, requestedIds: readonly string[], outcomes: readonly ApplyOutcome[], options?: ReceiptOptions): Receipt<A>;
+/**
+ * N=1 的读法：null 折成协议错，类型面因此不含 `already-gone`（下面那次过滤只服务类型收窄，
+ * 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 是「已被同批前一条带走」的幂等条，跟着组走，不单列。
+ */
+export declare function landedEntryIds<A extends ApplyAction>(receipt: Receipt<A>): string[];
+/**
+ * restore 回执里真正回盘的会话 id：`ok` 支取条目上的 `sessionId`；`already-gone` 没有行，
+ * 由调用方给条目查找兜底。purge / count 的 `ok` 值没有 `sessionId`，会被跳过。
+ */
+export declare function restoredSessionIds<A extends ApplyAction>(receipt: Receipt<A>, sessionIdOfEntry?: (entryId: string) => string | undefined): string[];

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 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,55 +84,54 @@ 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';
-/** 一段管所有写动作的返回值（逐条）。`ApplySuccess<A>` = 某动作成功支（`value` 按动作收窄）。 */
-export type ApplySuccess<A extends ApplyAction> = Extract<ApplyOutcome, {
-    action: A;
-    ok: true;
-}>;
+/** `shared/wire.ts` 的 `ApplyOutcome`、扫描报告与附件回执从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
+export type { ApplyAction, ApplyOutcome, AttachmentCleanupWire, AttachmentOrphanReportWire, OrphanReportWire, } from '../shared/wire.js';
 /**
- * N=1 的成功支：`delete` / `restore` 的幂等 `null` 已被 `applyOne` 判成通道错，
- * 所以它的 `value` 必然非空；其余动作就是 `ApplySuccess`。
+ * N=1 的成功支：`null` 已被 `receipt.ts` 的单条读法折成协议错，所以 `value` 必然非空。
+ * 不再需要条件类型把 `delete` / `restore` 的 null 抠掉——那份判据只住回执读法一处。
  */
-export type OneShotSuccess<A extends ApplyAction> = A extends 'delete' | 'restore' ? Omit<ApplySuccess<A>, 'value'> & {
-    readonly value: NonNullable<ApplySuccess<A>['value']>;
-} : ApplySuccess<A>;
+export type OneShotSuccess<A extends ApplyAction> = {
+    readonly id: string;
+    readonly action: A;
+    readonly ok: true;
+    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 同时躺着
- * `applyOutcomes` 与 `restore`）。现在它们收成一个自由函数 {@link applyOne}——要旧形状就显式调它，
- * 而不是让 interface 多背三个方法。
+ * `applyOutcomes` 与 `restore`）。现在单条非写调用（如 `count`）走自由函数 {@link applyOne}；
+ * 写动作走 `src/client/write.ts` 的 `runWrite`，而不是让 interface 多背三个方法。
  */
 export interface SessionDeleteRemote {
     list(): Promise<TrashEntryLike[]>;
     /** 回收站之外的无主子会话报告（纯读）。读不到就是 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>;
 }
-/** 需要"单条便捷支"的组件只要这一段 deps（同一段 `/apply` 的 N=1 写法，见 {@link applyOne}）。 */
+/** 需要那一段 `/apply` 的组件只要这一段 deps（单条非写调用见 {@link applyOne}，写动作走 `./write.js` 的 `runWrite`）。 */
 export type OneShotDeps = Pick<SessionDeleteRemote, 'applyOutcomes'>;
 /**
- * **N=1 的 `apply`**：一个动作 + 一个 id → 那一条的成功支（`value` 按动作收窄）。
+ * **N=1 的 `apply`**：一个动作 + 一个 id → 那一条的成功支（`value` 必然非空）。
  *
- * 三条判据都在这一处：
+ * 三件事各归一个家：
  * - **按发出去的那个 id** 取结果（取"第一条"会把别条的成败安在这条头上）；
- * - 一条没回是**通道的错**，不是"没做成"（后者住在 outcome 的 `ok:false` 里）；
- * - `null` 是批量里"已被同批前一条带走"的幂等值——N=1 永远不会命中它，回 `null` 只能是通道答错了，
- *   所以同样按通道错抛，不冒充成功。
- *
- * 成/败/幂等/缺失的判读只走 {@link readReceipt}（一个家）。
+ * - 成/败/幂等/缺失与「单条 null 是协议错」的判读只走 {@link readSingleReceipt}；
+ * - 这里只把 verdict 折成「拿到值 / 抛失败」。
  */
 export declare function applyOne<A extends ApplyAction>(deps: OneShotDeps, action: A, id: string): Promise<OneShotSuccess<A>>;
 /**
@@ -163,5 +142,6 @@ export declare function applyOne<A extends ApplyAction>(deps: OneShotDeps, actio
  * 所以在这里展开一次：`ok ? value : throw`。
  */
 export declare function buildDeps(raw: RawSessionDeleteRemote): SessionDeleteRemote;
-/** 「删除」确认框的宿主只需要那一段 `/apply`：提交删除与删除前那一次计数都走 {@link applyOne}。 */
+/** 「删除」确认框的宿主只需要那一段 `/apply`：删除前那一次计数走 {@link applyOne}；
+ *  提交删除走 `src/client/write.ts` 的 `runWrite`。 */
 export type DeleteConfirmDeps = OneShotDeps;

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

@@ -15,3 +15,34 @@ export interface ClientStore<T> {
     reset(): void;
 }
 export declare function createStore<T>(initial: T): ClientStore<T>;
+/** 懒读快照：`get()` 只在脏了时调用 `read()`，干净时回同一个引用（React snapshot 契约）。 */
+export interface LazyStore<T> {
+    get(): T;
+    /** 标脏并通告；下一次 `get()` 重读。 */
+    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>;
+/**
+ * 最新票句柄：每张票记着签发时的序号，只有序号仍等于当前的那张才 `current`。
+ * 调用方在发起异步读时 `issue()` 一张票，落地前问 `ticket.current`——旧读因此不会盖掉新状态。
+ *
+ * 组件里要拿到**同一枚**句柄时用 `useState(createLatestWins)`，不要用 `useMemo`：React 允许丢 memo
+ * 缓存，丢了就是两张各自记数的票台，守卫静默失效。模块级现场（`main-view.ts`）直接建一颗，没这个问题。
+ */
+export interface LatestWinsTicket {
+    readonly current: boolean;
+}
+export interface LatestWins {
+    /** 签发一张新票；之前的票立刻作废。 */
+    issue(): LatestWinsTicket;
+    /** 只作废当前票，不签发新票（用于"这一拍整体作废"）。 */
+    invalidate(): void;
+}
+export declare function createLatestWins(): LatestWins;

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-nav.d.ts

@@ -0,0 +1,30 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { TrashEntryLike } from './remote.js';
+/**
+ * 导航要的面。`ordered` 是**屏幕上的顺序**（只含展开的组），由面板/选择面算好传进来——
+ * 布局常量与本 module 无关。`drillEnabled` 是这一档支不支持整行下钻（窄档为真；宽档 Enter/Space
+ * 只移动选中，与整行点击的 `{ drill: !split }` 同一条判据）。四个动作都由调用方注入：
+ * `select` 只移动选中（带 `drill` 才下钻），`exitDrill` 是控制器那条「← 返回清单」的同一动作，
+ * `focusRow` 把焦点交给某一行。
+ */
+export interface TrashNavInput {
+    ordered: readonly TrashEntryLike[];
+    selectedId: string | null;
+    selectMode: boolean;
+    drillEnabled: boolean;
+    drilled: boolean;
+    select(entry: TrashEntryLike, options?: {
+        drill?: boolean;
+    }): Promise<void>;
+    toggleCheck(entryId: string): void;
+    exitDrill(): void;
+    focusRow(entryId: string): void;
+}
+export interface TrashNav {
+    /** `aria-activedescendant` 的那条 id：选中行不在 DOM 里时是 `null`。 */
+    readonly activeDescendantId: string | null;
+    /** 清单里唯一拿着 `tabIndex=0` 的那一行；清单空时是 `null`。 */
+    readonly tabStopId: string | null;
+    onListKeyDown(event: ReactKeyboardEvent<HTMLElement>): void;
+}
+export declare function useTrashNav(input: TrashNavInput): TrashNav;

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;