@xrn1997/dsh-session-delete 0.2.1 → 0.3.0

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

@@ -3,7 +3,7 @@
  * 加上信封判别与注入面那一处「展开成裸值」的适配。
  *
  * 通道形状（裁决）：真相/账本/判据全在宿主那边，Node 半用宿主**自己的 web server** 开一条
- * 插件专属前缀路由把五个段名（`list` / `ping` / `detail` / `apply` / `empty`）搬出来
+ * 插件专属前缀路由把六个段名（`list` / `ping` / `orphans` / `detail` / `apply` / `empty`）搬出来
  * （`src/api/dispatch.ts`），浏览器半同源调用。**不是重造后端**：
  * 路由层只做搬运与信封。为什么不用官方的 `remote.<namespace>`：那条路要**生成的 Typert 远程描述符**
  * 加一次 `$mount`，而盒内装配清单写死在 `dsh-api-remotes` 里、全宿主没有动态发现，第三方只能自挂自，
@@ -26,70 +26,30 @@
  *    所以到了组件面前只剩「裸值 / throw」两支，调用方只写 `if (!outcome.ok)`，正常流里没有 try/catch；
  *    非本信封形状的异常（网络层、TypeError…）也不丢原文（见 `failureOf`）。
  *
- * 面（`list` / `ping` / `detail` / `apply` / `empty`）与 Node 半路由的五个段名一一对应（段名本身的家是
- * `src/shared/wire.ts`）；`list` 回一行行的条目，`ping` 只回一个探针值，`detail` 回单条正文，
+ * 面（`list` / `ping` / `orphans` / `detail` / `apply` / `empty`）与 Node 半路由的六个段名一一对应（段名本身的家是
+ * `src/shared/wire.ts`）；`list` 回一行行的条目，`ping` 只回一个探针值，`orphans` 回一份**纯读**的
+ * 残留扫描报告，`detail` 回单条正文，
  * `apply` 回**一组逐条结果**，`empty` 回聚合回执。2026-10-17 之前是六个动作段（一条一段），
  * 批量只能由调用方循环拼——那正是「恢复 100 条很慢」的形状来源，收成一段之后这条通道不再有
- * "第二条执行路径"。
+ * "第二条执行路径"。**清理无主子会话也不另开一段**：它是 `apply` 的第五个动作，`orphans` 只负责
+ * "有多少、在哪、多大"。
  */
-import { type ApplyAction, type ApplyOutcome, type RemoteFailure, type RemoteResult } from '../shared/wire.js';
-/** 回收站条目（镜像 `src/trash/entry.ts` 的 `TrashEntry`；只读面）。 */
-export interface TrashEntryLike {
-    id: string;
-    sessionId: string;
-    projectDir: string;
-    workspaceId: string;
-    wasArchived: boolean;
-    deletedAt: number;
-    title: string;
-    sizeBytes: number;
-    /** 组视图的只读数，**都由 `list` 现算现给、不住在清册里**（清册只记 `parentEntryId` 那件事实）。
-     *  缺席 = 不知道或没有 ⇒ 界面上半句都不出现，也不许拿 0 冒充"没有"。
-     *  `subagentCount`：跟着这条父会话**一起进了回收站**的孩子数（清册里指向它的孩子行）。
-     *  `subagentBytes`：那些孩子的字节合计——孩子不单独列行，头部合计只加父那一格就会少报。
-     *  `strandedSubagents`：**还留在盘上没被带走**的孩子数（来源是宿主 `sessionQuery`），
-     *  级联落地之前删掉的那些存量才非零。与 `subagentCount` 各说各的，不许互相冒充。
-     *  `workspaceMissing`：删除时记下的工作区已被删掉（宿主的「删除工作区」只删注册、保留日志）——
-     *  恢复照常回盘，但会落在「未分组」。行上先说一句，别等它从清单里消失才发现换了地方。 */
-    subagentCount?: number;
-    subagentBytes?: number;
-    strandedSubagents?: number;
-    workspaceMissing?: boolean;
-}
-/** 彻底删除的回执（镜像 `PurgeResult`）。 */
-export interface PurgeResultLike {
-    removed: number;
-    freedBytes: number;
-}
-/** 详情正文里的一条消息（镜像 `TrashDetailMessage`；只读面）。 */
-export interface TrashDetailMessageLike {
-    role: 'user' | 'assistant';
-    time: number;
-    text: string;
-    truncated: boolean;
-}
+import { type ApplyAction, type ApplyOutcome, type OrphanReportWire, type PurgeStatsWire, type RemoteFailure, type RemoteResult, type TrashDetailWire, type TrashRowWire } from '../shared/wire.js';
+/**
+ * 回收站条目（`/list` 那一行）。**形状的家在 `shared/wire.ts`**（ADR-0003）：这里只是旧名的别名，
+ * 所以浏览器半不再自己抄一遍字段；下面几处"只读面"的镜像同理。
+ */
+export type TrashEntryLike = TrashRowWire;
+/** 彻底删除的回执（`PurgeStatsWire`）。 */
+export type PurgeResultLike = PurgeStatsWire;
 /**
- * 回收站单条详情（镜像 `src/trash/detail.ts` 的 `TrashDetail`；只读面）。
+ * 回收站单条详情（`TrashDetailWire`）。
  *
  * **线上只有"日志里读出来的那几件"**：`deletedAt` / `sizeBytes` / `wasArchived` / 清册 `title` 这些
  * 清册已有的字段一律不过线——组件按 `entryId` 与自己手上那份清单配对，这样"清单里的大小"和
  * "详情里的大小"永远是同一个数，不会因为两次读数不同而各说各话。
  */
-export interface TrashDetailLike {
-    entryId: string;
-    cwd: string;
-    createdAt: number;
-    lastActivity: number;
-    logTitle: string;
-    models: string[];
-    turnCount: number;
-    userMessageCount: number;
-    assistantMessageCount: number;
-    toolCallCount: number;
-    injectedCount: number;
-    messages: TrashDetailMessageLike[];
-    omittedByPayloadCap: number;
-}
+export type TrashDetailLike = TrashDetailWire;
 /** 任意异常 → 失败面。非带标记的失败（网络层、TypeError…）也保留原文，绝不吞；带标记的失败把
  *  `details` 第三件一起带出。 */
 export declare function failureOf(reason: unknown): RemoteFailure;
@@ -111,15 +71,19 @@ export type RemoteOutcome<T> = {
  * code，其余按原文兜底）。
  */
 export declare function callRemote<T>(run: () => Promise<T>): Promise<RemoteOutcome<T>>;
-/** 本插件前缀路由那套**响应信封**的窄镜像（不是宿主服务 `ctx.remote.*`——那条 typert 通道见 §10）：
+/** 本插件前缀路由那套**响应信封**的窄镜像（不是宿主服务 `ctx.remote.*`——那条 typert 通道为什么用不了，见 `AGENTS.md` 的 `remote.<namespace>` 那条）：
  *  每个方法 resolve 成 `RemoteResult<T>`。
  *
  * 2026-10-17 批量重构：写动词收成**一个 `apply`**（一段管所有动作、一组 id 进、逐条结果出），
- * 再加一段**纯探测** `ping` ⇒ 面是五段：`list` / `ping` / `detail` / `apply` / `empty`（原先六个动作段）。 */
+ * 再加一段**纯探测** `ping`；2026-10-19 又加一段**纯读扫描** `orphans` ⇒ 面是六段：
+ * `list` / `ping` / `orphans` / `detail` / `apply` / `empty`（原先六个动作段）。 */
 export interface RawSessionDeleteRemote {
     list(): Promise<RemoteResult<TrashEntryLike[]>>;
     /** 通道的"在不在"：一次零成本的 GET（探测专用，见 `src/api/dispatch.ts` 的 `ping` 支）。 */
     ping(): Promise<RemoteResult<string>>;
+    /** 纯读：回收站之外的无主子会话扫描。它**不清理**——清理是 `apply` 的 `orphan-clean` 动作，
+     *  这一段只交回"有多少、在哪、多大"（读不到语料时报 `io`，调用方不许把它折成"零条残留"）。 */
+    orphans(): Promise<RemoteResult<OrphanReportWire>>;
     detail(entryId: string): Promise<RemoteResult<TrashDetailLike>>;
     /** 一组 id 上的同一个动作。顶层信封的 `ok:false` 只表示**整次调用**没办成（路由自检、栅栏之外）；
      *  单条动作的成败住在 `ApplyOutcome` 里——这是批量接口的判据，别在信封层找它。 */
@@ -138,44 +102,66 @@ export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemot
  *
  * 判据是**「拿到信封」而不是「操作成功」**：`{ok:false, error}` 也是一次成功的往返（路由在、依赖接上了、
  * 错误映射也生效了），那时该做的是把入口显示出来、让原文上屏；只有往返本身失败才算通道缺席 ⇒
- * 一个槽位贡献都不注册（设计稿 §7「未接通态」）。
+ * 一个槽位贡献都不注册（docs/architecture.md §3「通道探测决定入口出现与否」）。
  *
- * 2026-10-17 第四批：探测从"读一遍清单"改成这一问——**每次页面加载都跑全表对账**是白付的钱，
+ * 2026-10-17：探测从"读一遍清单"改成这一问——**每次页面加载都跑全表对账**是白付的钱，
  * 而"信封到不到"这件事一次零成本的 GET 就答得出来。
  */
 export declare function probeChannel(raw: RawSessionDeleteRemote): Promise<boolean>;
-/** `shared/wire.ts` 的 `ApplyOutcome` 从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
-export type { ApplyAction, ApplyOutcome } from '../shared/wire.js';
+/** `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`。
+ */
+export type OneShotSuccess<A extends ApplyAction> = A extends 'delete' | 'restore' ? Omit<ApplySuccess<A>, 'value'> & {
+    readonly value: NonNullable<ApplySuccess<A>['value']>;
+} : ApplySuccess<A>;
+/**
+ * 注入面（`deps`）的 interface：**与六个段名一一对应的五个方法**（`ping` 只给探测用，留在 raw 层）。
+ *
+ * **不再有 N=1 的便捷方法**：`delete` / `restore` / `countSubagents` 曾是同一段
+ * `/apply` 的三种写法，于是一个 `module` 里同一个动作有两条路（回收站面板的 deps 同时躺着
+ * `applyOutcomes` 与 `restore`）。现在它们收成一个自由函数 {@link applyOne}——要旧形状就显式调它，
+ * 而不是让 interface 多背三个方法。
+ */
 export interface SessionDeleteRemote {
     list(): Promise<TrashEntryLike[]>;
+    /** 回收站之外的无主子会话报告（纯读）。读不到就是 throw —— 界面上那是**一次失败的检查**，
+     *  不是"零条残留"（把 `io` 折成空报告等于把"不知道"说成"没有"）。 */
+    scanOrphans(): Promise<OrphanReportWire>;
     detail(entryId: string): Promise<TrashDetailLike>;
     /** 一段管所有写动作（2026-10-17 批量重构）：一次调用把整批办完，逐条结果原样交回组件。 */
     applyOutcomes(action: ApplyAction, ids: readonly string[]): Promise<ApplyOutcome[]>;
     /** 清空回收站（聚合回执）。 */
     emptyTrash(): Promise<PurgeResultLike>;
-    /** 单条便捷包装 = `applyOutcomes` 的 N=1 支。`null` 是批量里"已被同批前一条带走"的幂等值；
-     *  单条删除（N=1）永远不会命中它。 */
-    delete(sessionId: string): Promise<TrashEntryLike | null>;
-    restore(entryId: string): Promise<TrashEntryLike | null>;
-    /** 这条会话在盘上有几个后代（删除确认框那句「含 N 个子会话」）。拿不到 ⇒ 0，那一栏整句不出现。 */
-    countSubagents(sessionId: string): Promise<number>;
 }
+/** 需要"单条便捷支"的组件只要这一段 deps（同一段 `/apply` 的 N=1 写法，见 {@link applyOne}）。 */
+export type OneShotDeps = Pick<SessionDeleteRemote, 'applyOutcomes'>;
+/**
+ * **N=1 的 `apply`**：一个动作 + 一个 id → 那一条的成功支（`value` 按动作收窄）。
+ *
+ * 三条判据都在这一处：
+ * - **按发出去的那个 id** 取结果（取"第一条"会把别条的成败安在这条头上）；
+ * - 一条没回是**通道的错**，不是"没做成"（后者住在 outcome 的 `ok:false` 里）；
+ * - `null` 是批量里"已被同批前一条带走"的幂等值——N=1 永远不会命中它，回 `null` 只能是通道答错了，
+ *   所以同样按通道错抛，不冒充成功。
+ *
+ * 成/败/幂等/缺失的判读只走 {@link readReceipt}（一个家）。
+ */
+export declare function applyOne<A extends ApplyAction>(deps: OneShotDeps, action: A, id: string): Promise<OneShotSuccess<A>>;
 /**
- * 注入面的**唯一一处适配**：`RemoteResult` → 裸值，外加「一段批量」→「单条便捷面」的展开。
+ * 注入面的**唯一一处适配**：`RemoteResult` → 裸值。
  *
  * **为什么必须有这一步**：通道那头的调用 resolve 成 `RemoteResult<T>`（`{ ok: true, value }` /
  * `{ ok: false, error }`），失败是**返回**而不是 reject。组件面要的是「拿到值 / 抛异常」，
- * 所以在这里展开一次：`ok ? value : throw`。放在这一处而不是组件里，是为了让三个组件的 props 契约
- * （以及钉住它们的用例）保持裸值形状不变。
- *
- * **单条支里只有一条落地**：没有它（幽灵 id、或路由整次没办成）就 throw——"批量只回了一条别的"
- * 不是成功，也不是 0。
+ * 所以在这里展开一次：`ok ? value : throw`。
  */
 export declare function buildDeps(raw: RawSessionDeleteRemote): SessionDeleteRemote;
-/** 「删除」确认框的宿主需要的两件：提交删除的那条便捷包装，与删除前那一次计数（那句「含 N 个子会话」）。 */
-export type DeleteConfirmDeps = Pick<SessionDeleteRemote, 'delete' | 'countSubagents'>;
+/** 「删除」确认框的宿主只需要那一段 `/apply`：提交删除与删除前那一次计数都走 {@link applyOne}。 */
+export type DeleteConfirmDeps = OneShotDeps;

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

@@ -0,0 +1,17 @@
+export interface ClientStore<T> {
+    get(): T;
+    set(next: T): void;
+    /** 回调回同一引用 ⇒ `false`（不发通告）；新值 ⇒ `true`。 */
+    update(next: (current: T) => T): boolean;
+    /**
+     * 以本次递增的 seq（从 1 起）造新值并通告，值没变也通告。
+     * **`make` 回的值必须把 seq 带上**（放进快照字段，如 `{ seq, items }`）：订阅方拿它当 React key
+     * 才会在"同一段文案连续出现两次"时重挂载；丢了 seq，重挂载语义会静默消失。
+     */
+    publish(make: (seq: number) => T): void;
+    subscribe(listener: () => void): () => void;
+    use(): T;
+    /** 测试专用：回初值并清零 seq。 */
+    reset(): void;
+}
+export declare function createStore<T>(initial: T): ClientStore<T>;

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

@@ -0,0 +1,39 @@
+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[];
+};
+/**
+ * 两种批量动作共用这一个确认框壳：`purge`（不可恢复）与 `restore`（加法，但一批条目多、去向是
+ * 各自的旧项目目录，点之前也要过一道）。标题、正文、确认键的措辞各处一套；批量恢复把选中条目
+ * 列成卡片（标题 + 项目名——恢复的去向是**每条各自的**旧项目目录，逐条列出来是这句话的正文）；
+ * 批量彻底删除只给条数——那批的"去哪"没有可说的，而"不可恢复"那句警告才是要读的。
+ */
+export declare function TrashConfirm({ pending, restoreEntries, busy, t, onCancel, onConfirmPurge, onConfirmRestore, }: {
+    pending: PendingAction;
+    restoreEntries: readonly TrashEntryLike[];
+    busy: boolean;
+    t: Translate;
+    onCancel: () => void;
+    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;
+    t: Translate;
+    onCancel: () => void;
+    onConfirm: () => void;
+}): import("react").JSX.Element;

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

@@ -1,7 +1,9 @@
 import { type Translate } from './copy.js';
 import { type SessionDeleteRemote } from './remote.js';
-/** 批量重构（2026-10-17）后这份依赖面：两个读 + 一个批量口 + 清空 + 单条恢复的便捷包装。 */
-export type TrashPanelDeps = Pick<SessionDeleteRemote, 'list' | 'detail' | 'applyOutcomes' | 'emptyTrash' | 'restore'>;
+/** 面板的依赖面：三个读（`list` / `detail` / `scanOrphans`）+ **一段 `apply`** + 清空。
+ *  **没有第二条路**：「恢复一条」也走 `apply`（N=1），面板不再同时吃
+ *  `applyOutcomes` 与一个便捷的 `restore`。 `scanOrphans` 是回收站之外那批无主子会话的纯读报告。 */
+export type TrashPanelDeps = Pick<SessionDeleteRemote, 'list' | 'detail' | 'applyOutcomes' | 'emptyTrash' | 'scanOrphans'>;
 export interface TrashPanelProps {
     deps: TrashPanelDeps;
     /** 文案（缺省 = 内置 zh，见 `copy.ts`：这不是"忘了传"，而是"这次没有 locale 服务"）。 */

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

@@ -2,3 +2,5 @@
 export declare function invalidateTrash(): void;
 /** 供面板订阅。 */
 export declare function useTrashRevision(): number;
+/** 测试专用：修订号归零（订阅者随组件卸载自行退订）。 */
+export declare function resetTrashStore(): void;

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

@@ -0,0 +1,38 @@
+/**
+ * 回收站界面共用的**视图词汇**：卡片配方、危险红、项目名的念法。
+ *
+ * 它从 `trash-panel.tsx` 拆出来，因为清单面板与两个确认框（`trash-confirm.tsx`）都要用这几样——
+ * 拆之前它们同住一个文件、只能靠"同一个文件里的常量"共享。拆之后两处读的是同一份，不是两份抄写。
+ *
+ * **配色与圆角一律走 token，字号是字面量 px**（宿主同类面也这么写）：卡片用宿主设置面的底层 token
+ * （`bg-layer-2` + `border-l4` + `radius-lg`），选中态换宿主"选中"那一档（见 `trash-panel.tsx` 头注）。
+ */
+import type { CSSProperties } from 'react';
+import type { Translate } from './copy.js';
+import type { TrashEntryLike } from './remote.js';
+/** 卡片配方：宿主设置面的 fill/stroke 底层 token + 官方 `lg` 圆角。 */
+export declare const CARD: CSSProperties;
+/** 选中行：底色与描边都换成宿主"选中"那一档（`trash-panel.tsx` 头注里有这两枚 token 的实测取值）。 */
+export declare const CARD_SELECTED: CSSProperties;
+/**
+ * **整页唯一那块实心红**的写法：`variant="primary"` + 在元素上覆盖 primary 那对填充 token。
+ * 宿主插件管理页的 danger 按钮就是这个写法（asar @21658274），所以 hover 仍走 `.primary:hover` 类。
+ */
+export declare const BULK_DANGER: CSSProperties;
+/**
+ * 项目名怎么念：宿主的 `projectKey` 把 cwd 里的 `/`、`\`、`:` 全折成**一个** `-` ⇒ 分隔符那部分有损、
+ * 拆不回真实路径；但**非分隔符那部分可逆**（`~XXXX` 十六进制码元，字面 `~` 编成 `~007E`）。
+ * 摘掉 `--…--` 裹边、还原这些转义，剩下的原样摆出来，完整串交给组头 `title`。
+ * 字母表只有一份：还原走 `shared/wire.ts`。
+ */
+export declare function projectLabel(projectDir: string, t: Translate): string;
+/** 清单上的一个项目组（组头 + 组内的条目，组内按删除时间倒序）。 */
+export interface ProjectGroup {
+    projectDir: string;
+    label: string;
+    /** 组内最新一条的删除时间——组间排序的键。 */
+    latest: number;
+    entries: readonly TrashEntryLike[];
+}
+/** 按项目分组：组内按删除时间倒序，组间按各组最新一条倒序（刚删掉的那个项目排在最上面）。 */
+export declare function groupByProject(entries: readonly TrashEntryLike[], t: Translate): ProjectGroup[];

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

@@ -3,8 +3,8 @@
  * 随包发布的明文产物 `lib/index.js`；出处与改写规则见 `ui.css` 头注）。
  *
  * 只留本插件用到的：垃圾桶（删除动作 / 回收站）、警示（失败面）、打开的项目文件夹、
- * 关闭叉（对话框）、圆圈对勾（撤销提示的 success 档）、对勾（行尾兜底勾选开关，2026-10-17
- * 第十三批加；行首主勾选走原生 Checkbox）、下折与右折 chevron（清单的分组折叠头，
+ * 关闭叉（对话框）、圆圈对勾（撤销提示的 success 档）、对勾（行尾兜底勾选开关，2026-10-17 加；
+ * 行首主勾选走原生 Checkbox）、下折与右折 chevron（清单的分组折叠头，
  * 2026-10-15 加：`DisclosureRow` 那套折叠行的两态 glyph）。「刷新」那枚随按钮一起删了
  * （2026-10-16，见 `trash-panel.tsx` 工具排的注释）——本文件不留无人消费的几何。
  * **几何、`viewBox`、`strokeWidth` 逐字不动**——它们是官方图标集的形状，改了就不再与宿主同屏同形。
@@ -25,7 +25,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 第十三批加）。 */
+/** 行尾兜底「勾选开关」那枚对勾（状态点/归档行；官方 `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/undo-toast.d.ts

@@ -1,8 +1,22 @@
+/**
+ * 撤销提示（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 就够，少一条平台依赖）。
+ */
 import { type Translate } from './copy.js';
-import { type SessionDeleteRemote } from './remote.js';
-export type UndoToastDeps = Pick<SessionDeleteRemote, 'restore' | 'applyOutcomes'>;
+import { type OneShotDeps } from './remote.js';
+export type UndoToastDeps = OneShotDeps;
 /**
- * 一次待撤销的事。两形（第十三批②起）：单条删除（主语是会话名）／批量删除（主语是条数）。
+ * 一次待撤销的事。两形（2026-10-17 起）：单条删除（主语是会话名）／批量删除（主语是条数）。
  * 同一个 Toast 宿主、同一停留时长；撤销动作按形走——单条 `restore`，批量**一次** `applyOutcomes`。
  */
 export type UndoNotice = {
@@ -28,7 +42,7 @@ export declare function publishUndoNotice(input: {
     entryId: string;
     title: string;
 }): void;
-/** 批量删除成功后发布一条撤销提示（第十三批②）：覆盖上一条，只报这一次移走的条数。 */
+/** 批量删除成功后发布一条撤销提示（2026-10-17）：覆盖上一条，只报这一次移走的条数。 */
 export declare function publishUndoBatchNotice(input: {
     entryIds: readonly string[];
     n: number;
@@ -37,7 +51,9 @@ export declare function publishUndoBatchNotice(input: {
 export declare function clearUndoNotice(): void;
 /** 供组件订阅。 */
 export declare function useUndoNotice(): UndoNotice | null;
-/** 提示停留时长。设计稿 §7 定死：**6 秒**（Toast 自己的默认是 3 秒）。 */
+/** 测试专用：现场与 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

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

@@ -1,11 +1,11 @@
 /**
- * 清单列与详情列之间那根**可拖的宽度把手**（2026-10-15 加，设计稿 §7 状态④）。
+ * 清单列与详情列之间那根**可拖的宽度把手**（2026-10-15 加，`docs/ui-spec.md` 的「面板与清单」）。
  *
  * 三件事住在这里，因为它们互相咬合、分开测各自都不成立：
  * ① **宽度夹在两个界之间**。下限由调用方给（回收站那条的来历写在 `trash-panel.tsx`：真 Chromium
  *    上扫出来的，约束不是"两颗按钮放得下"——它们 `flex:none`，再窄也是文字列缩；而是「删除于 … ·
  *    大小」那一行不再被省略号截断），上限 = 面板宽 − `reserve`。**`reserve` 的数值与来历都住在调用方**
- *    （`DETAIL_RESERVE`，那三件东西怎么加出来的见设计稿 2026-10-15 §7.1 与现状稿 §8 的几何读数）：
+ *    （`DETAIL_RESERVE`，那三件东西怎么加出来的见 `trash-panel.tsx` 该常量的注释与几何用例）：
  *    这一层不复制那份算式——上一版在这里钉过一个"480 ⇒ 900 那档正好回 420"，调用方改到 489 之后
  *    它就成了假数，而 900 那档的真实读数是**清单被夹到 411**（比默认窄 9px，还能往里拖）。
  * ② **夹在"读"的时候也做一次**。窗口变窄不触发任何写入，若只在写入时夹，之前拖出来的超宽

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

@@ -1,5 +1,5 @@
 /**
- * 观测**面板自己那一块**的宽度（回收站的断点全靠它，设计稿 2026-10-15 §2.1）。
+ * 观测**面板自己那一块**的宽度（回收站的断点全靠它，docs/ui-spec.md）。
  *
  * 为什么不是 `window.innerWidth`：这块住在宿主的中央列里，**侧栏折叠/展开、拖动分栏**都会改它的宽度
  * 而 window 一点不动——只听 window 的 resize 会在侧栏折叠后拿着旧宽度画错形态。

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

@@ -0,0 +1,55 @@
+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` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
+ * 由面板算好传进来——布局常量不搬进控制器。
+ */
+export interface TrashPanelControllerInput {
+    deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
+    gate: TrashPanelGate;
+    query: Pick<TrashQuery, 'entries' | 'refresh' | 'emptyTrash'>;
+    ordered: readonly TrashEntryLike[];
+    canAutoSelect: boolean;
+    focusRow(entryId: string): void;
+}
+export interface TrashPanelController {
+    readonly busy: boolean;
+    readonly selected: TrashEntryLike | null;
+    readonly selectedId: string | null;
+    readonly drilled: boolean;
+    readonly detail: TrashDetailState;
+    /** 待确认的那一批（确认框的开合）；确认落地后由控制器收起。 */
+    readonly pending: PendingAction | null;
+    /** 恢复/彻底删除/批量 的失败原文，按条目 id 存：切走再回来还在。 */
+    readonly actionFailure: Readonly<Record<string, string>>;
+    select(entry: TrashEntryLike, options?: {
+        drill?: boolean;
+    }): Promise<void>;
+    retry(): void;
+    back(): void;
+    setPending(pending: PendingAction | null): void;
+    /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存并重读清单，失败原文落回这一行。 */
+    restore(entry: TrashEntryLike): Promise<void>;
+    /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */
+    confirmPurge(): Promise<void>;
+    /** 一组 id 上的同一个动作：逐条成败落成行上原文/缓存失效，整批只重读一次清单。 */
+    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

@@ -0,0 +1,32 @@
+import { type OrphanReportWire, type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
+import type { Translate } from './copy.js';
+export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'scanOrphans' | 'applyOutcomes' | 'emptyTrash'>;
+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;
+    /** 交回**这一次读数是否真的落地**：孤儿扫描吃的是对账后的清册，清单没读成就不能扫。 */
+    reload(): Promise<boolean>;
+    scanOrphans(): Promise<void>;
+    /** "重读一遍" = 先对账并读清单，再扫残留；清单没读成就不扫。 */
+    refresh(): Promise<void>;
+    /** 清理那批无主子会话（一段 `/apply` 的第五个动作），逐条结果落成"已不在了 / N 组未清理"。 */
+    cleanOrphans(): Promise<void>;
+    /** 清空回收站（聚合回执）：成功就重读，失败就把原文摆到清单那块。交回是否成功。 */
+    emptyTrash(): Promise<boolean>;
+}
+export declare function useTrashQuery({ deps, t, around, }: {
+    deps: TrashQueryDeps;
+    t: Translate;
+    /** 把"这一趟还算忙"的一枚全局闸套在一次动作外（面板的 `busy`）。 */
+    around: <T>(task: () => Promise<T>) => Promise<T>;
+}): TrashQuery;

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

@@ -0,0 +1,32 @@
+import type { TrashEntryLike } from './remote.js';
+import type { ProjectGroup } from './trash-view.js';
+export interface TrashSelection {
+    /** 多选模式：入口在工具排（「多选」/「退出多选」），模式内点行说的是"勾/取消"。 */
+    readonly selectMode: boolean;
+    readonly checked: ReadonlySet<string>;
+    /** 按**清单从上往下**排好的勾选 id（页脚两颗与批量执行都读这一份）。 */
+    readonly checkedIds: readonly string[];
+    /** 键盘 ↑↓ 与下钻走这个顺序：**只含展开的组**（折叠的行不在 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;
+    /** 组头那颗：说的是"这个项目的全部会话"，折叠起来的条目也算。勾满再点 = 整组取消。 */
+    toggleGroupCheck(group: {
+        entries: readonly TrashEntryLike[];
+    }): void;
+    groupFullyChecked(group: {
+        entries: readonly TrashEntryLike[];
+    }): boolean;
+    groupPartiallyChecked(group: {
+        entries: readonly TrashEntryLike[];
+    }): boolean;
+}
+export declare function useTrashSelection({ entries, groups, }: {
+    entries: readonly TrashEntryLike[] | null;
+    groups: readonly ProjectGroup[];
+}): TrashSelection;

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

@@ -0,0 +1,10 @@
+/**
+ * 回收站面板之外发生的写入（菜单删除、批量删除、撤销恢复）的**跨槽位收尾顺序**：
+ * 主视图收尾 → 失效回收站 → 撤销通告。面板自己的写入，本地 refresh / 缓存的
+ * 生命周期仍住在 controller 与 query 里。
+ */
+export declare function commitExternalDelete(input: {
+    sessionIds: readonly string[];
+    publishUndo(): void;
+}): void;
+export declare function commitExternalRestore(sessionIds: readonly string[]): void;

package/lib/types/deps.d.ts

@@ -0,0 +1,14 @@
+import type { FsPort } from './ports/fs-port.js';
+import type { HostPort } from './ports/host-port.js';
+import type { ManifestPort } from './trash/manifest.js';
+/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。 */
+export interface CoreDeps {
+    fs: FsPort;
+    host: HostPort;
+    manifest: ManifestPort;
+    home: string;
+}
+/** 只有删除读时钟；其余读 / 计划 / 恢复 / 永久删除只用 CoreDeps。 */
+export type DeleteDeps = CoreDeps & {
+    now(): number;
+};

package/lib/types/index.d.ts

@@ -1,33 +1,27 @@
 import type { Context } from '@deepseek-ai/cordis';
-import { type ManifestPort } from './trash/manifest.js';
 export declare const name = "@xrn1997/dsh-session-delete";
 /**
  * 插件依赖：**只写字符串数组**（隔离数据根上实测：写成 `{ required, optional }` 会让插件停在
  * `pending (waiting for services: required, optional)`）。
  *
- * 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。三个**故意不写**的：
+ * 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。**不进 inject 的**：
  * - `remote`：那是**浏览器半**的服务（asar `dsh-api-gateway/lib/client.js`：`super(ctx, "remote")`），
  *   Node 半挂的是 `ctx.typertGateway`。把它写进 Node 半的 inject 会让插件永远 pending（同 `slots` 那次的形状）。
- * - `sessions` / `sessionProjectionCache`：前者本实现不用（活跃判据走 waterfall，见设计稿 §5）；后者是**可选**服务，
- *   官方消费方也按可选读（`ctx.get('sessionProjectionCache')?.…`），inject 一个可能没挂的服务 = 整个插件 pending。
+ * - `sessions` / `sessionProjectionCache`：两者都按 `ctx.get(...)` **可选读**——`sessions` 只给 `evictLive`
+ *   用（活跃判据走 waterfall，见 src/ports/host-port.ts；服务缺席回 `unknown`），`sessionProjectionCache` 是标题的尽力读面。
+ *   inject 一个可能没挂的服务 = 整个插件 pending。
  *   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
+ * - `agents`：只给 handle 捕获用（`ctx.get('agents')`；缺席时 `ctx.inject(['agents'])` 等服务就绪再装）。
+ *   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
  *
  * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
- * 前缀路由，浏览器半同源 fetch 那五个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+ * 前缀路由，浏览器半同源 fetch 那六个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
  * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
  * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
- */
-export declare const inject: string[];
-/**
- * 清单的真实绑定：官方 storage domain → `ManifestPort`（`StorageDomainLike` 在动词层保持一种读法）。
- * 域**懒开**且成功句柄只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
- * 插件卸载时关掉句柄并把 `close()` 的落地交回框架（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约；
- * 2026-10-17 起不再 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
  *
- * **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
- * 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。
+ * 清单（storage domain 绑定）与数据根各有一个家：`src/trash/storage-manifest.ts`、`src/ports/home.ts`。
  */
-export declare function createStorageManifest(ctx: Context): ManifestPort;
+export declare const inject: string[];
 /**
  * 装配顺序：**清单 → 端口 → 动词依赖 → 前缀路由**（`DeleteDeps` 就是前两者的合一）。
  *

package/lib/types/log/zstd-frames.d.ts

@@ -1,5 +1,5 @@
 /**
- * 多帧 zstd 流的**帧边界**（设计稿 2026-10-15 §1.1）。
+ * 多帧 zstd 流的**帧边界**（2026-10-15 实测）。
  *
  * 为什么要有这个文件：会话日志是一次次 append 出来的**帧序列**，而 Node 的 `zstdDecompressSync`
  * **与** `createZstdDecompress()` 流式**都只给第一帧**（实测：本机一个 3.8 MB 的文件，两个 API 都只回