@xrn1997/dsh-session-delete 0.3.1 → 0.5.0

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

@@ -1,23 +1,18 @@
 /**
- * 本插件 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`。 */
 export interface IconProps {
-    size?: number;
+    size?: number | undefined;
 }
 export declare function IconTrashOutlineRegular({ size }: IconProps): ReactElement;
 export declare function IconWarningOutlineRegular({ size }: IconProps): ReactElement;
@@ -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,18 @@
 /**
  * 撤销提示（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`；本文件只做组件：画通知台已有的事实，「撤销」整趟按下交给
+ * `write-seats.ts` 的 `restoreFromUndo`（编排归恢复座位，见 ADR-0018 的边界）。
+ * 为什么组件要独立：宿主的菜单行随菜单**一起卸载**（真产物 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-section.d.ts

@@ -0,0 +1,52 @@
+import type { RemoteOutcome } from './remote.js';
+/** 一段在飞的动作：检查只读，清理会写。状态行靠它分开说「检查中…」与「清理中…」；`null` = 空闲。 */
+export type MaintenancePhase = 'scanning' | 'cleaning';
+/** 一段维护交给界面的全部：三份读数（报告 / 失败 / 中性提示）、一个确认框、一档忙碌，加四个动作。 */
+export interface MaintenanceSectionView<R> {
+    /** `null` = 还没检查（或上一次检查失败——失败在 `failure` 单独一格，不折成零条）。 */
+    readonly report: R | null;
+    readonly failure: string | null;
+    /** 「这一组已经不在」/ 上一趟清理的回执——不是失败：单独一条中性提示。 */
+    readonly notice: string | null;
+    readonly confirm: boolean;
+    readonly phase: MaintenancePhase | null;
+    /** 段自己给的忙碌（在飞即忙），不再作为 prop 传递。 */
+    readonly busy: boolean;
+    /** 手动检查（也是失败块的重试）。 */
+    scan: () => Promise<void>;
+    /** 唯一开门：先清旧失败与旧提示再开确认框。 */
+    openPreview: () => void;
+    /** 清完必重查；回执句子由 config 拼。 */
+    clean: () => Promise<void>;
+    /** 只收确认框，不碰提示 / 失败。 */
+    cancel: () => void;
+}
+/** `settle` 拼出的这一趟要摆的句子；**缺席的格子表示"不碰"**（重查刚摆上的状态保持原样）。 */
+export interface MaintenanceSettlePlan {
+    readonly notice?: string | null;
+    readonly failure?: string | null;
+}
+export interface MaintenanceSectionConfig<R, C> {
+    /** 手动检查（也是失败块的重试）。交回的已是落地面——glue 用 `callRemote` 包装、不会抛，module 不再包一层。 */
+    scan(): Promise<RemoteOutcome<R>>;
+    /** 清理写动作；入参是点击那一刻的报告（清理输入由各段自己从里面点名）。报告没活可干时
+     *  同步回 `null`：不发请求、只收确认框——"没活"的判据各段不同，是各段的业务。
+     *  同样交回落地面、不抛。`C` 是这一段的回执形状：状态机不认识它，只把它原样递给
+     *  `beforeRescan` / `settle`，段那边就不必把 `outcome.value` 擦回 `unknown` 再 `as` 一次。 */
+    clean(report: R): Promise<RemoteOutcome<C>> | null;
+    /** 清理落地后、必发的重查起飞前先摆的读数；`null` = 不动。附件段用它把"已清空"先收成 0：
+     *  旧报告不再可信，别让旧横幅在重查飞着时冒充"没清"。 */
+    beforeRescan?(outcome: RemoteOutcome<C>): R | null;
+    /** 检查读不到时的上屏句；本地化前缀各段自己给。 */
+    scanFailureText(message: string): string;
+    /** 这一趟检查**赢了**（没被更晚的检查顶掉）之后顺手收掉的东西；输家不调用。它在赢家的读数
+     *  落地**之前**触发，故只许写自己那份不属于读数的状态。孤儿会话段用它清上一趟清理的附件回执
+     *  ——「收掉旧回执」属于最新读数成立的一部分，放在发请求之前会让被顶掉的输家也清掉赢家的回执。 */
+    onScanWon?: () => void;
+    /** 清理回执（含顶层失败）→ 这一趟的句子。重查赢了才调用；段独有的第二回执（如孤儿会话段顺带
+     *  清掉的附件读数）由它顺手写自己的状态——那不是这台状态机的格子。
+     *  `report` 是**这一趟**点击那一刻的报告：回执要按请求名单逐条判读，名单只能随这一趟交下来；
+     *  段自己存一份"最近一次清理的名单"会在两趟交错时把上一趟的回执按后一趟的名单判读。 */
+    settle(outcome: RemoteOutcome<C>, report: R): MaintenanceSettlePlan;
+}
+export declare function useMaintenanceSection<R, C>(config: MaintenanceSectionConfig<R, C>): MaintenanceSectionView<R>;

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

@@ -0,0 +1,17 @@
+import type { Translate } from './copy.js';
+import { type AttachmentOrphanReportWire, type OrphanReportWire, type SessionDeleteRemote } from './remote.js';
+import { type MaintenanceSectionView } from './use-maintenance-section.js';
+/** 维护卡只需要这四段：两份报告 + 孤儿会话的批量写 + 孤儿附件的聚合写。 */
+export type MaintenanceDeps = Pick<SessionDeleteRemote, 'scanOrphans' | 'applyOutcomes' | 'scanAttachmentOrphans' | 'cleanAttachmentOrphans'>;
+export interface Maintenance {
+    /** 孤儿会话段 + 它独有的第二回执：这一趟清理顺带清掉的附件读数（`.dsh` 内独占图片副本）。
+     *  重查读不出来，和段的 `notice` 一样是过去那一趟的回执；下一次检查 / 清理会被收掉。 */
+    readonly orphans: MaintenanceSectionView<OrphanReportWire> & {
+        readonly attachmentNotice: string | null;
+    };
+    readonly attachments: MaintenanceSectionView<AttachmentOrphanReportWire>;
+}
+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,33 @@
 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 { TrashEntryWire } from '../shared/wire.js';
+import type { DetailNav, TrashDetailState } from './trash-detail.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` 取四样：清单（选中从它里面找）、`reload`（挂载、显式重试、失效与写后
+ * 都是同一条读）、清空（面板的写动作那一半）、`noteAttachmentCleanup`（purge 回执里
+ * 附件那半句交给查询侧拼句子上屏）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
+ * 由面板算好传进来——布局常量不搬进控制器。输入的引用**不需稳定**：失效 effect 的判据只有
+ * `revision`，reload 回调经 `useLatest` 读最新那一份（判据住 `store.ts`）。
  */
 export interface TrashPanelControllerInput {
     deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
     gate: BusyGate;
-    query: Pick<TrashQuery, 'entries' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash'>;
+    query: Pick<TrashQuery, 'list' | 'reload' | 'emptyTrash' | 'noteAttachmentCleanup'>;
     ordered: readonly TrashEntryLike[];
     canAutoSelect: boolean;
 }
@@ -20,23 +35,46 @@ export interface TrashPanelController {
     readonly busy: boolean;
     readonly selected: TrashEntryLike | null;
     readonly selectedId: string | null;
+    /** 正在看哪个孩子（离清单的详情导航态；null = 看清单选中那条）。单级是设计（ADR-0029）：
+     *  只有一个槽，`openChild` 换槽不叠栈，返回交还清单选中那条。 */
+    readonly childView: TrashEntryWire | null;
+    /** 详情的导航面（开孩子 / 回父）。ADR-0029 单级判据的**唯一实现**：面板只转交它，
+     *  不再自己拼 openChild / parentContext 两个派生块（判据有第二个家，视图与测试就得各自复述语义）。 */
+    readonly detailNav: DetailNav;
+    /** 打开一个孩子（父详情子会话段点进来）：读它的详情，但清单选中不动。 */
+    openChild(child: TrashEntryWire): Promise<void>;
+    /** 回到父详情（宽档头部那颗「返回父会话」；窄档 back/Esc 的第一程也走它）。 */
+    closeChild(): void;
     readonly drilled: boolean;
     readonly detail: TrashDetailState;
+    /** 更早一页正在读（只对当前详情主体有意义：孩子视图开着就是孩子）。 */
+    readonly loadingOlder: boolean;
+    /** 更早一页读失败的原文（只对当前详情主体有意义；正文本身仍是 ready）。 */
+    readonly olderFailure: string | null;
     /** 待确认的那一批（确认框的开合）；确认落地后由控制器收起。 */
     readonly pending: PendingAction | null;
+    /** 恢复确认框要摆的这一批（按勾选顺序；清单里已找不到的 id 滤掉）。 */
+    readonly pendingEntries: readonly TrashEntryLike[];
     /** 恢复/彻底删除/批量 的失败原文，按条目 id 存：切走再回来还在。 */
     readonly actionFailure: Readonly<Record<string, string>>;
-    select(entry: TrashEntryLike, options?: {
+    /** 下面是面板会**摘下来转交**的动作（导航的 `select`/`back`、确认框的 `cancelPending`）：
+     *  属性声明而不是方法简写，实现体都不读 `this`。方法简写的隐式 `this` 会让 `unbound-method`
+     *  把转交报成可疑；改形状是纯类型面，零运行时改动。 */
+    select: (entry: TrashEntryLike, options?: {
         drill?: boolean;
-    }): Promise<void>;
-    retry(): void;
-    back(): void;
-    setPending(pending: PendingAction | null): void;
+    }) => Promise<void>;
+    /** 按当前详情的 `olderCursor` 读更早一页，拼到现有块前面。 */
+    loadOlder: () => Promise<void>;
+    retry: () => void;
+    back: () => void;
+    /** 构造待确认动作（唯一入口：新增一种确认只改 `PendingAction` 与确认框，不再加一串转调）。 */
+    request: (action: PendingAction) => void;
+    cancelPending: () => void;
     /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存，写完无论成败都重读清单，失败原文落回这一行。 */
-    restore(entry: TrashEntryLike): Promise<void>;
+    restore: (entry: TrashEntryLike) => Promise<void>;
     /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */
-    confirmPurge(): Promise<void>;
+    confirmPurge: () => Promise<void>;
     /** 一组 id 上的同一个动作：逐条成败落成行上原文/缓存失效，整批只重读一次清单。 */
-    confirmApply(action: 'purge' | 'restore', ids: readonly string[]): Promise<void>;
+    confirmApply: (action: 'purge' | 'restore', ids: readonly string[]) => Promise<void>;
 }
 export declare function useTrashPanelController(input: TrashPanelControllerInput): TrashPanelController;

package/lib/types/client/use-trash-query.d.ts

@@ -1,43 +1,48 @@
 import type { BusyGate } from './busy-gate.js';
-import { type OrphanReportWire, type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
-import type { WriteOutcome } from './write.js';
+import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
 import type { Translate } from './copy.js';
-import type { ApplyAction } from '../shared/wire.js';
-export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'scanOrphans' | 'applyOutcomes' | 'emptyTrash'>;
-/** 一次清单读的结局：`stale` = 被后发的读顶掉（什么都没落地，调用方不许拿它当失败清场）。 */
-export type ReloadResult = 'ok' | 'failed' | 'stale';
+import type { AttachmentCleanupWire } from '../shared/wire.js';
+export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'emptyTrash'>;
+/** 清单的唯一状态：加载中 / 有行 / 未知。`unknown` 不向下游交出任何行——旧行不许继续可操作。 */
+export type TrashListState = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'ready';
+    readonly rows: readonly TrashEntryLike[];
+} | {
+    readonly status: 'unknown';
+    readonly failure: string;
+};
+/** 清单状态对视图的**唯一解读**：行、失败原文、加载中与空态一次交出。
+ *  面板与控制器不再各自从 `status` 反推——"未知"不是"空"，也不许把失败折成空态。 */
+export interface TrashListView {
+    readonly rows: readonly TrashEntryLike[] | null;
+    readonly failure: string | null;
+    readonly loading: boolean;
+    readonly empty: boolean;
+}
+export declare function listView(list: TrashListState): TrashListView;
 export interface TrashQuery {
-    /** `null` = 还没读到（第一次读或读失败）；与"空的"是两件事。 */
-    readonly entries: readonly TrashEntryLike[] | null;
-    readonly listFailure: string | null;
-    /** `null` = 还没扫到；失败时也置回 `null`（不拿空报告冒充干净）。 */
-    readonly orphanReport: OrphanReportWire | null;
-    readonly orphanFailure: string | null;
-    /** 「这一组已经不在」不是失败：单独一条中性提示。 */
-    readonly orphanNotice: string | null;
-    readonly orphanConfirm: boolean;
-    setOrphanConfirm(open: boolean): void;
-    /** 「查看并清理」：把上一条失败/中性提示清掉再开预览框（旧提示不该跟新一次预览并排出现）。 */
-    openOrphanPreview(): void;
-    /** 只重读清单（对账 + 读）。交回**这一次读的结局**：落地 / 读失败 / 被后发的读顶掉。
-     *  残留报告与提示的联动不在这里；组合清场归 `refreshAll` / `refreshAfterWrite`。 */
-    reloadRows(): Promise<ReloadResult>;
-    /** 只扫残留。调用方负责先让清单对过账（`refreshAll` / `refreshAfterWrite` 已经排好序）。 */
-    rescanOrphans(): Promise<void>;
-    /** 先读清单、成了再扫残留；挂载与显式「重试」用它。 */
-    refreshAll(): Promise<void>;
-    /** 写后/失效：只重读清单；是否顺带重扫残留由这次的 `outcome` 从 action / ids / 当前清单自行派生
-     *  （判据住 `needsOrphanRescan`）。失效通告不带 outcome：报告未知或非空才重扫。输给后发读时由赢家补扫；
-     *  清单读失败时清空报告与提示。 */
-    refreshAfterWrite(outcome?: WriteOutcome<ApplyAction>): Promise<void>;
-    /** 清理那批无主子会话（一段 `/apply` 的第五个动作），逐条结果落成"已不在了 / N 组未清理"。 */
-    cleanOrphans(): Promise<void>;
-    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把原文摆到清单那块。交回是否成功。 */
-    emptyTrash(): Promise<boolean>;
+    readonly list: TrashListState;
+    /** 最近一次写动作（purge / 清空）的附件读数，已经拼成一句话：**最新的写赢**。
+     *  一次没有附件读数的 purge / 清空、或这一趟写失败（没拿到回执）都会把它清成 `null`，不让上一条的
+     *  读数冒充这一趟；删除与恢复不碰它。它是**过去那一趟的回执**、不是清单状态：清单重读读不出来。 */
+    readonly attachmentNotice: string | null;
+    /** 把一份附件读数摆上屏（`undefined` = 这一趟没有读数，旧提示收掉）；句子怎么拼归这里，调用方只管转交。 */
+    noteAttachmentCleanup: (a: AttachmentCleanupWire | undefined) => void;
+    /** 重读清单：挂载、显式「重试」、写后与失效通告都走这一条读——问的是同一件事（"清单现在长什么样"）。
+     *  曾经分作 `refreshAll` / `refreshAfterWrite` 两个名字，那是调用点问的两件事（"用户要看现在的"与
+     *  "别处动过了，跟上"），不是两条路径，合一为 `reload`。面板没有第二条扫描：孤儿检查是设置页
+     *  维护卡的手动动作（ADR-0021）。清单读失败时旧行进 `unknown`。 */
+    reload: () => Promise<void>;
+    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把清单置为未知并摆上原文。
+     *  三种形状各有意思：`true` = 清空落地了；`false` = 这一趟跑了但没清成（原文已在清单那块上屏）；
+     *  `undefined` = 闸把这一趟挡回来了、什么都没跑（调用方不收框，等在飞那一趟的结论）。 */
+    emptyTrash: () => Promise<boolean | undefined>;
 }
 export declare function useTrashQuery({ deps, t, gate, }: {
     deps: TrashQueryDeps;
     t: Translate;
-    /** 面板的一枚全局闸：清空与无主子会话清理这两条写动作把整趟包在里面（面板的 `busy`）。 */
+    /** 面板的一枚全局闸：清空这条写动作把整趟包在里面（面板的 `busy`）。 */
     gate: BusyGate;
 }): TrashQuery;

package/lib/types/client/use-trash-selection.d.ts

@@ -9,22 +9,25 @@ export interface TrashSelection {
     /** 键盘 ↑↓ 与下钻走这个顺序：**只含展开的组**（折叠的行不在 DOM 里，方向键别停过去）。 */
     readonly ordered: readonly TrashEntryLike[];
     readonly allCollapsed: boolean;
-    isCollapsed(projectDir: string): boolean;
-    enterSelect(): void;
-    exitSelect(): void;
-    toggleGroup(projectDir: string): void;
-    toggleAllGroups(): void;
-    toggleCheck(entryId: string): void;
+    /** 方法一律写成**属性声明**：面板会把它们摘下来传给导航/行组件，实现体也都不读 `this`。
+     *  方法简写带来的隐式 `this: TrashSelection` 会让 `unbound-method` 误报，且会诱导调用点
+     *  为了消警报去包箭头函数——那会让 `TrashSelection` 每次渲染换新身份（见 ADR 外的回归教训）。 */
+    isCollapsed: (projectDir: string) => boolean;
+    enterSelect: () => void;
+    exitSelect: () => void;
+    toggleGroup: (projectDir: string) => void;
+    toggleAllGroups: () => void;
+    toggleCheck: (entryId: string) => void;
     /** 组头那颗：说的是"这个项目的全部会话"，折叠起来的条目也算。勾满再点 = 整组取消。 */
-    toggleGroupCheck(group: {
+    toggleGroupCheck: (group: {
         entries: readonly TrashEntryLike[];
-    }): void;
-    groupFullyChecked(group: {
+    }) => void;
+    groupFullyChecked: (group: {
         entries: readonly TrashEntryLike[];
-    }): boolean;
-    groupPartiallyChecked(group: {
+    }) => boolean;
+    groupPartiallyChecked: (group: {
         entries: readonly TrashEntryLike[];
-    }): boolean;
+    }) => boolean;
 }
 export declare function useTrashSelection({ entries, groups, }: {
     entries: readonly TrashEntryLike[] | null;

package/lib/types/client/write-seats.d.ts

@@ -1,52 +1,60 @@
 /**
- * 逐条 `/apply` 的**写入座位**：一次写入发生在哪个界面位置，就在哪个函数里把呈现材质、闸与重读通道绑好。
+ * 逐条 `/apply` 的写入座位：一次写入发生在哪个界面位置，就在哪个函数里绑定呈现材质、闸与重读通道。
  *
- * 为什么要有它：六个调用点此前各自拼 `runWrite({ presentation: {…} })`，并各自决定要不要外包一层闸。
- * 收尾顺序（`write-settlement.ts`，ADR-0013）与重读策略（`use-trash-query.ts`，ADR-0016）不动；
+ * 收尾顺序住 `write-settlement.ts`（ADR-0013），面板的重读策略住 `use-trash-query.ts`；
  * 座位只拥有「这次是谁在写、交哪些材质、闸在哪」。
  *
- * 边界：不判回执（`receipt.ts`）、不决定收尾顺序、不拥有各面的本地状态（`pending` / 详情缓存 / 行失败）。
- * 面板座位的闸由面板传入：`busy` 是它的 UI 状态，座位不另造第二枚。
+ * 边界：不自己判读回执（verdict 判读住 `receipt.ts`，失败表怎么上屏归各写入面——撤销那一趟的
+ * 横幅改写住 `restoreFromUndo`）、不决定收尾顺序、不拥有各面的本地状态；面板座位的闸由面板传入，
+ * 不另造第二枚；闸挡回来的那一趟**什么都不落地**——座位交回 `undefined`，不伪造 outcome，
+ * 收尾留给在飞的那一趟。
+ * 无主子会话清理**不是**座位：它只在插件设置页的维护卡里手动触发（ADR-0021），
+ * 读数、闸与重查都归 `use-maintenance.ts`。
  */
+import type { Translate } from './copy.js';
 import type { BusyGate } from './busy-gate.js';
 import type { OneShotDeps, TrashEntryLike } from './remote.js';
+import { type UndoNotice } from './undo-notices.js';
 import { type WriteOutcome } from './write.js';
-/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。 */
+/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。
+ *  三种形状各有意思，不许互相冒充：字符串 = 这一条失败了（原文）；`null` = 跑了、这一条没有失败要说；
+ *  `undefined` = 闸把这一趟挡回来了、什么都没跑（框不收，等在飞那一趟的结论——先收就会把它的失败原文
+ *  落在已经卸载的确认框上）。 */
 export declare function deleteSessionFromMenu(deps: OneShotDeps, input: {
     sessionId: string;
     title: string;
-}, gate: BusyGate): Promise<string | null>;
+}, gate: BusyGate): Promise<string | null | undefined>;
 /** 批量删除座位（宿主会话列表的多选 → 批量确认框）：一次 `/apply`，撤销名单只收 ok 支的条目 id（跟着组走的幂等条不单列）。
- *  只收 id：标题是浮条的呈现，不参与这一次写入。 */
-export declare function deleteSessionsFromBatch(deps: OneShotDeps, ids: readonly string[], gate: BusyGate): Promise<ReadonlyMap<string, string>>;
-/** 外部恢复座位（撤销横幅）：没有 busy 面，不传闸；主视图重开归 settlement，这里只让清单失效。 */
-export declare function restoreFromUndo(deps: OneShotDeps, input: {
-    ids: readonly string[];
-    single: boolean;
-}): Promise<WriteOutcome<'restore'>>;
+ *  只收 id：标题是浮条的呈现，不参与这一次写入。**被闸挡回时交回 `undefined`**——这一趟没跑，
+ *  浮条与确认框都不许照着它收缩名单或关框（那会吞掉在飞那一趟的结果）。 */
+export declare function deleteSessionsFromBatch(deps: OneShotDeps, ids: readonly string[], gate: BusyGate): Promise<ReadonlyMap<string, string> | undefined>;
+/** 外部恢复座位：拥有整趟——ids 组装、runWrite、三种回执形状各改写一次横幅、成功收自己。
+ *  闸在调用方（横幅组件每条通知一枚）；座位不传闸（双套会让外层 busy 提前落）。
+ *  单条与批量都走**一次** `applyOutcomes('restore', ids)`（`runWrite` 判读；单条带 `single: true`，
+ *  null 是协议错）；失败就把原因换到同一条横幅上，不静默。多条逐条失败时横幅要说清**条数与各条
+ *  原因**（原因去重）——只显第一条会把条数与其余原因折没（issue #8 第 5 条）；单条失败仍原文上屏。
+ *  settlement 负责重开删除时被关掉的会话（只认 main-view 自己记过的）并让清单重读；
+ *  座位**不传 `dismissUndo`**——部分失败的回滚会让 settlement 先熄灭横幅，随后 `failNotice` 因
+ *  `ownsNotice` 落空而吞掉失败原文。 */
+export declare function restoreFromUndo(deps: OneShotDeps, notice: UndoNotice, t: Translate): Promise<void>;
 /** 面板两个 `/apply` 座位共用的那一半：依赖、条目 id、闸、重读与缓存失效。 */
 interface PanelWriteInput<A extends 'restore' | 'purge'> {
     deps: OneShotDeps;
     ids: readonly string[];
     gate: BusyGate;
-    refreshAfterWrite(outcome: WriteOutcome<A>): Promise<void>;
-    clearDetailCache(ids: readonly string[]): void;
+    /** 属性声明：这两枚回调被摘下来交给 `runWrite`（转交而不是当方法调），实现不读 `this`。 */
+    refreshAfterWrite: (outcome: WriteOutcome<A>) => Promise<void>;
+    clearDetailCache: (ids: readonly string[]) => void;
 }
 /** 面板恢复另要两样：单条读法，以及 already-gone 回执缺行时反查 sessionId 的当前清单。 */
 interface PanelRestoreInput extends PanelWriteInput<'restore'> {
     single?: boolean;
     entries: readonly TrashEntryLike[] | null;
 }
-/** 面板恢复座位：面板已替这条完成「回来」的结算 ⇒ `panelSeat`；撤销横幅与详情缓存都按落地条目收。 */
-export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'>>;
-/** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。 */
-export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'>>;
-interface OrphanCleanSeatInput {
-    deps: OneShotDeps;
-    ids: readonly string[];
-    gate: BusyGate;
-    refreshAfterWrite(outcome: WriteOutcome<'orphan-clean'>): Promise<void>;
-}
-/** 无主子会话清理座位：不碰回收站失效与撤销，回执判读仍归 `use-trash-query.ts`。 */
-export declare function cleanOrphansFromPanel(input: OrphanCleanSeatInput): Promise<WriteOutcome<'orphan-clean'>>;
+/** 面板恢复座位：面板已替这条完成「回来」的结算 ⇒ `panelSeat`；撤销横幅与详情缓存都按落地条目收。
+ *  闸被面板那一趟占着时交回 `undefined`（连点不发第二条），面板照它什么都不改。 */
+export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'> | undefined>;
+/** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。
+ *  与恢复座位同一条：闸被占着时交回 `undefined`，这一趟不改任何界面后果。 */
+export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'> | undefined>;
 export {};