@xrn1997/dsh-session-delete 0.3.0 → 0.3.1

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

@@ -10,7 +10,8 @@
  * all belong here"）。
  *
  * 那个 K 是**勾选变化后防抖 300ms 的一次批量 count**（`/apply` 的 `action:'count'`，一组 id 一次），
- * 并且带**序号守卫**：在飞的旧响应不许盖掉新名单的读数（与 2026-10-17 `c66f082` 那条 `reloadSeq` 同一个道理）。
+ * 并且带**最新票守卫**：在飞的旧响应不许盖掉新名单的读数（compare-and-set 住 `createLatestWins`，
+ * 防抖本身仍在下面这个 effect 里）。
  * 读不到就整句不说——K 是合计，缺一条就是假数（「不许拿 0 冒充没有」）。
  */
 import { type ReactElement } from 'react';

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

@@ -11,7 +11,7 @@
  */
 import { type ReactElement } from 'react';
 import { type Translate } from './copy.js';
-import { type SessionDeleteRemote } from './remote.js';
+import type { SessionDeleteRemote } from './remote.js';
 import { type PickItem } from './batch-selection-store.js';
 export interface BatchDeleteRequest {
     /** 每次发布递增：换一批就重挂载，busy / 失败面不带着上一批的记忆。 */

package/lib/types/client/busy-gate.d.ts

@@ -0,0 +1,6 @@
+export interface BusyGate {
+    readonly busy: boolean;
+    /** 把一次任务整个包进「这一趟还算忙」；落地与抛错都放回 false。 */
+    around<T>(task: () => Promise<T>): Promise<T>;
+}
+export declare function useBusyGate(): BusyGate;

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

@@ -1,8 +1,8 @@
 /**
  * 可见文案（界面标签与提示）＋接上宿主 Client locale 服务的那一步。
  *
- * **例外：渠道错误原文。** `src/client/receipt.ts` 的 missing-id、`src/client/remote.ts` 的
- * 幂等空值与取数通道错误是协议诊断原文，固定中文、不随 locale；它们不进本字典。
+ * **例外：渠道错误原文。** `src/client/receipt.ts` 的 missing-id 与单条幂等空值、
+ * `src/client/remote.ts` 的取数通道错误是协议诊断原文，固定中文、不随 locale；它们不进本字典。
  *
  * ## 为什么不是散在各组件里的中文字面量
  *

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

@@ -5,14 +5,29 @@ export interface HostRowInfo {
     /** 在跑的行点整行也不选：与置灰的勾选框同口径（级联遇在跑成员整组拒绝）。 */
     readonly live: boolean;
 }
-/** 行尾兜底勾选开关登记一行：模式内与模式外都要登记（守卫进模式的那一帧就得有标题）。 */
+/**
+ * 行尾兜底勾选开关登记一行：模式内与模式外都要登记（守卫进模式的那一帧就得有标题）。
+ * 只有标题／运行态**真的变了**才标脏：重渲染时的同值登记不该把快照翻新一遍。
+ */
 export declare function registerHostRowInfo(sessionId: string, info: HostRowInfo): void;
 /**
  * 「当前可见」的可选行：侧栏里**已渲染**的会话行（`data-row-key="session:…"`）——折叠组、
  * 归档过滤外的行不在 DOM 里，宿主隐藏的 subagent 也不在；在跑的行跳过（与置灰勾选框同口径）。
  * 标题/运行态来自行尾兜底登记的 `rowInfo`（模式内它对每个非空行都渲染）；DOM 序就是侧栏顺序。
+ *
+ * 这是**当场读**：事件路径（点「全选」那一刻的页面）与测试用它；渲染侧读下面的快照。
  */
 export declare function readVisibleSelectableRows(): PickItem[];
+/**
+ * 渲染侧的快照：脏了才查 DOM；干净时回同一个引用（React 的 `useSyncExternalStore` 契约）。
+ * 没变化时连续两次调用必须同引用，否则订阅方会被自己的快照更新推成死循环。
+ */
+export declare function getVisibleSelectableRowsSnapshot(): readonly PickItem[];
+/**
+ * 渲染侧只读快照 + DOM 观察订阅；首个订阅者起开始观察，最后一个走了断开。
+ * `enabled === false` 不订阅也不读 DOM——行列表只随多选态存在，模式外不必付观察的成本。
+ */
+export declare function useVisibleSelectableRows(enabled: boolean): readonly PickItem[];
 /** 全选：把当前可见可选行按 DOM 序追加；已在名单里的由 `addPicks` 自己跳过，原有选中保持在前。 */
 export declare function selectAllVisible(): void;
 /**
@@ -21,7 +36,7 @@ export declare function selectAllVisible(): void;
  * - 有选中、但当前没有可见可选行（全折叠/过滤掉）⇒ 只能清空，也显示取消全选；
  * - 其余（含 0 条）⇒ 全选。
  */
-export declare function allVisibleSelected(): boolean;
+export declare function areAllVisibleRowsSelected(rows: readonly PickItem[], picks: readonly PickItem[]): boolean;
 /**
  * 多选态内的整行点击守卫（document 捕获阶段）。
  *
@@ -31,5 +46,5 @@ export declare function allVisibleSelected(): boolean;
  * 勾选框本身仍在。模式外不挂监听：这时点行必须还是宿主的"打开会话"。
  */
 export declare function useSelectionRowClickGuard(): void;
-/** 测试专用：登记表清空（会话 id 不跨用例复用，名字/运行态别串味）。 */
+/** 测试专用：登记表清空并标脏（会话 id 不跨用例复用，名字/运行态别串味）；观察者归订阅者管。 */
 export declare function resetHostRows(): void;

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

@@ -11,7 +11,7 @@
  * 所以关闭/重开是**一段生命周期**（2026-10-21），不是一个 id：删除成功后 `afterDelete` 关掉当前
  * 主视图并记下"这一条是我们关掉的"；撤销成功后 `afterRestore` 只重开自己记过的那些。调用方不再
  * 各自判定该不该关、也不再把会话 id 塞进撤销提示传一圈——判据全在这一处。两次重开排队时只有最新
- * 那条会打开（token 守卫），`resetMainView()` 清掉这份记忆并让在等的重开作废。
+ * 那条会打开（最新票守卫），`resetMainView()` 清掉这份记忆并让在等的重开作废。
  *
  * **不 import 宿主客户端包**（AGENTS.md 红线）：只通过 `ctx.get('uiWorkspace')` 可选读服务，
  * 形状不符/服务缺席都安静退回，绝不影响插件激活。字段与方法名来自上面两个包的产物原文；
@@ -31,7 +31,12 @@ export declare function afterDelete(sessionIds: readonly string[]): void;
  * 撤销恢复成功后调用：把**我们自己关掉的**那几个会话重新打开（只认 `afterDelete` 记过的）。
  *
  * 一批里只有最后一条会开（`targets[targets.length - 1]`）：主视图一次只装一个会话，而撤销恢复
- * 的成功条数可能多于一条；`openWhenListed` 的 token 守卫保证前一条的等待不会后落地抢焦点。
+ * 的成功条数可能多于一条；`openWhenListed` 的最新票守卫保证前一条的等待不会后落地抢焦点。
  * 任何更新的删除/恢复都会先作废旧等待；这里只负责「这一次要开哪一条」。
  */
 export declare function afterRestore(sessionIds: readonly string[]): void;
+/**
+ * 面板恢复已经替这些会话完成了“回来”的结算：只忘掉我们关过的那几条，不重开、不抢焦点。
+ * 它不动 `reopen`：同一会话不会既在等重开、又躺在回收站里等面板恢复；在等的重开属于另一条动作。
+ */
+export declare function forgetMainView(sessionIds: readonly string[]): void;

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

@@ -0,0 +1,27 @@
+/**
+ * 无主子会话的**维护块**——警告条、失败块、中性提示与清理确认框，回收站面板上唯一的维护块 seam。
+ *
+ * 为什么收回一个 module：这三段与面板的清单渲染、选择、键盘、拖栏毫无关系，却同住回收站最大的那个文件；
+ * 改维护块的文案或确认框时，diff 会与布局改动互相踩。搬出来之后面板只留一个插入点
+ * （`<OrphanMaintenance />`，在 header 之后、toolbar 之前），本 module 的 interface 就是那四个读数与四个动作。
+ *
+ * 搬字时一处未改的三条界面规则（现状住 `docs/ui-spec.md`）：
+ * - **报告非空才出警告条**：空报告与 `null` 都不出现——"检查过了，什么都没有"不是要给用户看的东西，
+ *   而"还没扫到"更不是"零条"。
+ * - **读不到就说读不到**：检查/清理失败在原位摆原文 + 重试，绝不静默折成一条都不出现
+ *   （"没能回答有多少残留"与"没有残留"是两件事，不许折成空报告）。
+ * - **「已经不在」不是失败**：别处清掉或父已回到清册时单独一条中性提示，不计入失败，下次扫描/刷新时自然消失。
+ *
+ * 写动作仍走 `use-trash-query.ts` 那一条：警告条开预览（`openOrphanPreview`）、失败块重试（`refreshAll`）、
+ * 确认框清理（`cleanOrphans`）。`busy` 不归本 module 管——它是面板那枚全局闸的读数，通过 props 传进来。
+ */
+import type { ReactElement } from 'react';
+import type { Translate } from './copy.js';
+import type { TrashQuery } from './use-trash-query.js';
+export interface OrphanMaintenanceProps {
+    query: Pick<TrashQuery, 'orphanReport' | 'orphanFailure' | 'orphanNotice' | 'orphanConfirm' | 'setOrphanConfirm' | 'openOrphanPreview' | 'cleanOrphans' | 'refreshAll'>;
+    /** 面板那枚全局闸的读数：写动作在飞时按住本块里的每一颗按钮。 */
+    busy: boolean;
+    t: Translate;
+}
+export declare function OrphanMaintenance({ query, busy, t }: OrphanMaintenanceProps): ReactElement | null;

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

@@ -1,17 +1,19 @@
 import { type ApplyAction, type ApplyOutcome, type ApplyValueByAction, 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;
@@ -32,6 +34,19 @@ export interface Receipt<A extends ApplyAction> {
     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>, {
@@ -40,4 +55,19 @@ export type FailureVerdict<A extends ApplyAction> = Extract<ReceiptVerdict<A>, {
 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>;
+/**
+ * `/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

@@ -34,7 +34,7 @@
  * "第二条执行路径"。**清理无主子会话也不另开一段**：它是 `apply` 的第五个动作，`orphans` 只负责
  * "有多少、在哪、多大"。
  */
-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 OrphanReportWire, type PurgeStatsWire, type RemoteFailure, type RemoteResult, type TrashDetailWire, type TrashRowWire } from '../shared/wire.js';
 /**
  * 回收站条目（`/list` 那一行）。**形状的家在 `shared/wire.ts`**（ADR-0003）：这里只是旧名的别名，
  * 所以浏览器半不再自己抄一遍字段；下面几处"只读面"的镜像同理。
@@ -110,25 +110,23 @@ export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemot
 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;
-}>;
 /**
- * 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 层）。
  *
  * **不再有 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[]>;
@@ -141,18 +139,15 @@ export interface SessionDeleteRemote {
     /** 清空回收站（聚合回执）。 */
     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 +158,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-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/undo-toast.d.ts

@@ -13,11 +13,12 @@
  * 不引 `@deepseek-ai/dsh-client-store`（它在平台表内，但这里用不着；React 就够，少一条平台依赖）。
  */
 import { type Translate } from './copy.js';
-import { type OneShotDeps } from './remote.js';
+import type { OneShotDeps } from './remote.js';
 export type UndoToastDeps = OneShotDeps;
 /**
  * 一次待撤销的事。两形（2026-10-17 起）：单条删除（主语是会话名）／批量删除（主语是条数）。
- * 同一个 Toast 宿主、同一停留时长；撤销动作按形走——单条 `restore`，批量**一次** `applyOutcomes`。
+ * 同一个 Toast 宿主、同一停留时长；撤销动作按形分派（单条 / 批量），两条都走同一个外部恢复座位
+ * （`write-seats.ts` 的 `restoreFromUndo`），单条带 `single: true` 的读法（null 是协议错，不冒充幂等成功）。
  */
 export type UndoNotice = {
     /** 每次发布递增：Toast 靠它重挂载，同一段文案连续出现两次也能重新计一次停留。 */
@@ -47,8 +48,15 @@ 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 归零，用例之间互不串味。 */

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

@@ -1,33 +1,20 @@
+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';
-/** 面板的一枚全局闸：写动作在飞时 `busy` 为真，`around` 把一次任务整个包在"这一趟还算忙"里。 */
-export interface TrashPanelGate {
-    readonly busy: boolean;
-    around<T>(task: () => Promise<T>): Promise<T>;
-}
-/**
- * 闸本体（从 `trash-panel.tsx` 的函数体原样收进来）：任务落地或抛错都把 `busy` 放回 false。
- * 不做引用计数：面板同一时刻只允许一趟写动作（按钮在 `busy` 期间全被按住），多一层计数只会
- * 把"这一趟什么时候算完"变成第二个判据。
- *
- * 返回值经 `useMemo` 稳定：`gate` 进 `restore` / `confirmApply` 的 `useCallback` 依赖，每次渲染
- * 换个新对象会让那两个回调跟着失效，进而把引用它们的 effect 也带着重跑。
- */
-export declare function useTrashPanelGate(): TrashPanelGate;
 /**
- * 控制器要的面。`query` 只取三样：清单（选中从它里面找）、重读（失效通告与写动作之后用）、
- * 清空（面板的写动作那一半）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
+ * 控制器要的面。`query` 取四样：清单（选中从它里面找）、`refreshAll`（挂载与显式重试）、
+ * `refreshAfterWrite`（失效与写后）、清空（面板的写动作那一半）。`ordered` 是键盘/自动选中用的
+ * "屏幕上的顺序"（只含展开的组），
  * 由面板算好传进来——布局常量不搬进控制器。
  */
 export interface TrashPanelControllerInput {
     deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
-    gate: TrashPanelGate;
-    query: Pick<TrashQuery, 'entries' | 'refresh' | 'emptyTrash'>;
+    gate: BusyGate;
+    query: Pick<TrashQuery, 'entries' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash'>;
     ordered: readonly TrashEntryLike[];
     canAutoSelect: boolean;
-    focusRow(entryId: string): void;
 }
 export interface TrashPanelController {
     readonly busy: boolean;
@@ -45,7 +32,7 @@ export interface TrashPanelController {
     retry(): void;
     back(): void;
     setPending(pending: PendingAction | null): void;
-    /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存并重读清单，失败原文落回这一行。 */
+    /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存，写完无论成败都重读清单，失败原文落回这一行。 */
     restore(entry: TrashEntryLike): Promise<void>;
     /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */
     confirmPurge(): Promise<void>;

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

@@ -1,6 +1,11 @@
+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 { 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';
 export interface TrashQuery {
     /** `null` = 还没读到（第一次读或读失败）；与"空的"是两件事。 */
     readonly entries: readonly TrashEntryLike[] | null;
@@ -14,19 +19,25 @@ export interface TrashQuery {
     setOrphanConfirm(open: boolean): void;
     /** 「查看并清理」：把上一条失败/中性提示清掉再开预览框（旧提示不该跟新一次预览并排出现）。 */
     openOrphanPreview(): void;
-    /** 交回**这一次读数是否真的落地**：孤儿扫描吃的是对账后的清册，清单没读成就不能扫。 */
-    reload(): Promise<boolean>;
-    scanOrphans(): Promise<void>;
-    /** "重读一遍" = 先对账并读清单，再扫残留；清单没读成就不扫。 */
-    refresh(): Promise<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>;
 }
-export declare function useTrashQuery({ deps, t, around, }: {
+export declare function useTrashQuery({ deps, t, gate, }: {
     deps: TrashQueryDeps;
     t: Translate;
-    /** 把"这一趟还算忙"的一枚全局闸套在一次动作外（面板的 `busy`）。 */
-    around: <T>(task: () => Promise<T>) => Promise<T>;
+    /** 面板的一枚全局闸：清空与无主子会话清理这两条写动作把整趟包在里面（面板的 `busy`）。 */
+    gate: BusyGate;
 }): TrashQuery;

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

@@ -0,0 +1,52 @@
+/**
+ * 逐条 `/apply` 的**写入座位**：一次写入发生在哪个界面位置，就在哪个函数里把呈现材质、闸与重读通道绑好。
+ *
+ * 为什么要有它：六个调用点此前各自拼 `runWrite({ presentation: {…} })`，并各自决定要不要外包一层闸。
+ * 收尾顺序（`write-settlement.ts`，ADR-0013）与重读策略（`use-trash-query.ts`，ADR-0016）不动；
+ * 座位只拥有「这次是谁在写、交哪些材质、闸在哪」。
+ *
+ * 边界：不判回执（`receipt.ts`）、不决定收尾顺序、不拥有各面的本地状态（`pending` / 详情缓存 / 行失败）。
+ * 面板座位的闸由面板传入：`busy` 是它的 UI 状态，座位不另造第二枚。
+ */
+import type { BusyGate } from './busy-gate.js';
+import type { OneShotDeps, TrashEntryLike } from './remote.js';
+import { type WriteOutcome } from './write.js';
+/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。 */
+export declare function deleteSessionFromMenu(deps: OneShotDeps, input: {
+    sessionId: string;
+    title: string;
+}, gate: BusyGate): Promise<string | null>;
+/** 批量删除座位（宿主会话列表的多选 → 批量确认框）：一次 `/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'>>;
+/** 面板两个 `/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;
+}
+/** 面板恢复另要两样：单条读法，以及 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'>>;
+export {};

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

@@ -0,0 +1,72 @@
+/**
+ * 一次逐条 `/apply` 写入成功后的**收尾顺序**，按 action 各一条固定序列。
+ *
+ * 调用方只交呈现材质（`WritePresentation`），顺序与 `anySuccess` 门只住这里；`runWrite` 在拿到
+ * `WriteSuccess` 后、`refresh` 前调一次。为什么按 action 收成一处见 ADR-0013。
+ *
+ * 四条判据：
+ * - **跨槽位在信封成功时就跑**：`afterDelete` / `afterRestore` 与 `invalidate` 不管逐条成败都跑
+ *   （回滚失败可能留下半套，回收站清单不能继续摆旧行）；呈现钩子（发布/熄灭撤销、遗忘主视图、
+ *   清详情缓存）只在至少一条落地（`anySuccess`）时跑——没有落点的撤销是假动作。delete 的撤销
+ *   另要求落地名单非空：全部被同批前一条带走时没有可撤销的条目。
+ * - **面板恢复用 `panelSeat: true` 明说**（「缺席」不再承载语义）：外部恢复（撤销横幅）由 settlement
+ *   调 `afterRestore` 重开；面板恢复自带「回来」的结算，只 `forgetMainView`、不重开、不抢焦点。
+ *   判据住 `src/client/main-view.ts` 的 `forgetMainView`。
+ * - **撤销名单由 settlement 算、座位发布**：delete 支把 `landedEntryIds` 与 `successIds.length` 算成
+ *   `{ entryIds, n }` 交给座位，座位只决定发布哪一形（单条带标题、批量带条数）——那句文案与它的键
+ *   住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
+ *   `anySuccess` 时熄灭指向这些条目的横幅——留着就是一条注定失败的「撤销」。
+ * - **`count` 不结算**；`orphan-clean` 没有跨槽位收尾（清完由 query 自己的写后刷新收尾）。
+ *   不直接读 DOM、不问宿主：主视图收尾只经 `main-view.ts` 的 `afterDelete` / `afterRestore`
+ *   （服务缺席或抛错都静默退回）；重读仍归各调用方的 `refresh`（面板那侧的最新票在 `use-trash-query.ts`）。
+ */
+import type { ApplyAction } from '../shared/wire.js';
+import { type Receipt } from './receipt.js';
+/** 一次写入里与渲染无关的那部分：动作、请求 id、回执、成功名单与“至少一条落地”。 */
+export interface SettledFacts<A extends ApplyAction> {
+    readonly action: A;
+    readonly ids: readonly string[];
+    readonly receipt: Receipt<A>;
+    /** 成功支（`ok` / `already-gone`）的请求 id，按请求顺序。 */
+    readonly successIds: readonly string[];
+    /** 至少一条真的落地（`ok` / `already-gone`；N=1 的协议空值不算）。 */
+    readonly anySuccess: boolean;
+}
+/**
+ * 按 action 切开的一族呈现材质：每个座位只能拿到自己动作那几手，形状对不上的钩子在类型面就不存在。
+ * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 算好的落地名单。
+ * - `restore` 的 `panelSeat: true` 才是「面板已替这条完成『回来』的结算」，不再靠缺席某个钩子暗示。
+ * - `count` / `orphan-clean` 没有呈现材质（用 `noPresentation`）。
+ * 钩子都是同步的：settlement 在 `refresh` 前一次跑完，不 await。
+ */
+export type WritePresentationByAction = {
+    delete: {
+        /** 外部写入座位：让回收站面板重读。面板写不传（自己的 `refreshAfterWrite` 就是重读）。 */
+        invalidate?(): void;
+        /** 撤销发布：settlement 把落地的条目 id 与请求名单算好后交来；名单**非空**——全被同批前一条带走时
+         *  没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
+        publishUndo?(landed: {
+            readonly entryIds: readonly [string, ...string[]];
+            readonly n: number;
+        }): void;
+    };
+    restore: {
+        invalidate?(): void;
+        /** 面板恢复座位：true = 面板已替这条完成「回来」的结算，只遗忘、不重开、不抢焦点。 */
+        panelSeat?: true;
+        dismissUndo?(entryIds: readonly string[]): void;
+        clearDetailCache?(entryIds: readonly string[]): void;
+        /** already-gone 的回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
+        sessionIdOfEntry?(entryId: string): string | undefined;
+    };
+    purge: {
+        dismissUndo?(entryIds: readonly string[]): void;
+        clearDetailCache?(entryIds: readonly string[]): void;
+    };
+    count: Record<string, never>;
+    'orphan-clean': Record<string, never>;
+};
+export type WritePresentation<A extends ApplyAction> = WritePresentationByAction[A];
+/** 没有呈现材质的座位用它：抛掉按 action 的联合，调用点不用各自造一个空对象字面量。 */
+export declare function noPresentation<A extends ApplyAction>(action: A): WritePresentation<A>;
+export declare function settleWrite<A extends ApplyAction>(success: SettledFacts<A>, presentation: WritePresentation<A>): void;