@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

package/lib/types/api/attachment-orphans.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 孤儿附件的报告段：`GET /attachment-orphans`。
+ *
+ * 报告把扫描计划折成数量/字节 + 对象清单（`id`/`bytes`，供设置页预览缩略图；最多
+ * `ORPHAN_PREVIEW_LIMIT` 条，清理不受预览条数限制）。扫描跳过（引用源或对象列表读不出）时
+ * **报告必须失败**——回一份 0 会让界面说"没有孤儿"，而这类失败恰恰是"不知道"，不是"没有"。
+ * 清理是 `POST /attachment-clean`，由路由直接接到 `cleanOrphanImageAttachments`。
+ */
+import { type AttachmentReadDeps } from '../trash/attachments.js';
+import type { AttachmentOrphanReportWire } from '../shared/wire.js';
+export declare function reportAttachmentOrphans(deps: AttachmentReadDeps): Promise<AttachmentOrphanReportWire>;

package/lib/types/api/attachment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 附件原始字节（`GET /attachment`，全仓唯一的二进制响应段）。
+ *
+ * 四条硬口径：
+ * ① **寻址只认 sha256 id**：`id` 必须 `sha256:<64 位小写 hex>`，路径由 `attachmentPathOf(home, kind, id)`
+ *    自己推导——请求里的任何一截都不参与路径拼接（`name` 只做下载名）。
+ * ② **kind 只认 image / file**：分别对应宿主附件库的 `objects`（图片）与 `file-objects`（普通文件）；
+ *    不认 v2、tmp、cache，也不给"读任意文件"留入口。
+ * ③ **单文件 ≤ 20 MiB**：超过不读进内存，回 200 + JSON 失败信封。图片的 `onError` 会换成占位；
+ *    普通文件走 `<a download>`，没有页面内失败面——浏览器可能把这份错误响应存成文件。
+ * ④ 图片按**魔数**给类型（PNG / JPEG / GIF / WebP）；认不出就按下载处理（`application/octet-stream` +
+ *    `attachment`），不猜、也不拿请求里的名字当类型来源。
+ *
+ * 请求本身不对（id/kind 形状）⇒ 400；对象不在 / 超限 / 读失败 ⇒ 200 + 信封（与其余段同一条错误面）。
+ */
+import type { FsPort } from '../ports/fs-port.js';
+import type { BinaryResponse } from './route-table.js';
+/** 读附件只需要 stat + read：与 `AttachmentRemovalDeps` 同一条收窄纪律，执行面不给。 */
+export interface AttachmentReadPorts {
+    fs: Pick<FsPort, 'statFile' | 'readFile'>;
+    home: string;
+}
+export declare function readAttachmentResponse(deps: AttachmentReadPorts, query: URLSearchParams): Promise<BinaryResponse>;

package/lib/types/api/dispatch.d.ts

@@ -1,35 +1,15 @@
 /**
- * `/dsh-session-delete-api` 前缀路由的**内部分发**（薄线的 Node 半）——**只管传输**。
+ * /dsh-session-delete-api 的前缀路由分发：只负责传输。
  *
- * 为什么是这一条路（裁决，不是偏好）：浏览器侧 `remote.<namespace>` 只能由**生成的 Typert 远程
- * 描述符贡献**经 `ctx.remote.$mount(...)` 挂上，而盒内那份装配清单是**写死的 25 条官方包**、
- * 全宿主没有任何"按包发现再挂载"的动态机制 ⇒ 第三方要那个命名空间，
- * 只能自挂自（要生成物 + `zod` + 改包布局），代价与收益完全不成比例。改用宿主**自己的 web server**
- * 开一条插件专属前缀路由：真相/账本/判据全在宿主那边，这一层只搬运。
+ * 三件事：请求栅栏 → 查路由表 → 回信封。方法、纯度、body 预读与读面的判据都在
+ * src/api/route-table.ts（这里只按判据执行）；行投影在 src/api/trash-rows.ts。
  *
- * 本文件只剩三件事：**栅栏 → 查表 → 信封**。
- *  - "这个段名该用什么方法、纯不纯、要不要预读 body、怎么处理"全在 `api/route-table.ts` 那一张表里
- *    （ADR-0004）；这里一个字都不再重复（此前方法判断与纯度判断分居两个函数、靠注释保持一致）。
- *  - 一行里放什么（清册行 → 线上行）归 `api/trash-rows.ts`。
- *  - 前面四条口径（不依赖 Cordis / 信封与浏览器半同形 / 状态语义 / 同源栅栏）与到达序链（口径 ⑤）
- *    仍住这里，因为它们是**传输**的事。
- *
- * 信封（口径 ②）：`{ok:true,value}` / `{ok:false,error:{code,message,details?}}`。
- * `error.code` 走 `src/remote/map-error.ts` 的**同一张表**（src/shared/wire.ts 的五个码），原文进
- * `error.message`，结构化附带物进可选的 `error.details`。
- *
- * HTTP 状态不是第二套语义（口径 ③）：**操作失败**时状态一律 200（含 `ok:false`）——我们与浏览器半之间的
- * 契约是信封本身，判断成败只看 `ok`。**请求本身不对**才用 4xx（400 请求体 / 405 方法 / 404 未知路由），
- * 同源栅栏拒的是**请求**而不是操作，回 403；浏览器半先解信封再看状态。
- *
- * 同源栅栏（口径 ④）：本机回环上一条能删会话的写口不能被任意网页用 simple request CSRF 打——没有栅栏时
- * `content-type: text/plain` 的跨源 POST 不触发预检、直接生效。放行的形状见 {@link isTrustedRequest}。
- *
- * 到达序链（口径 ⑤）：`list`（含对账）与写动作都是"读清单 + 动文件 + 写清单"的多步，交错跑会互相踩
- * ——删除刚把目录搬进回收站、行还没写上时，对账抢先把这行按目录"重建"出来，再被真实行覆盖成降级
- * 元数据。串行的代价只是排队（单进程单用户，毫秒级）；纯读不占这条链（哪几个段名纯、哪个动作纯，
- * 由路由表说，不在这里列）。
+ * - 请求本身不对用 4xx（400 请求体 / 405 方法 / 404 未知路由 / 403 栅栏拒绝）；
+ *   操作失败回 200 + {ok:false,error}。浏览器半先解信封，再看状态。
+ * - 请求栅栏（归属 / 身份）归 `src/api/request-trust.ts`，这里只按它的裁决写 403。
+ * - purity 为 chained 的请求串行执行，避免读清册/动文件/写清册交错。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { DeleteDeps } from '../deps.js';
-export declare function createApiHandler(deps: DeleteDeps): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+import { type RequestTrustFacts } from './request-trust.js';
+export declare function createApiHandler(deps: DeleteDeps, trust: RequestTrustFacts): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/lib/types/api/request-trust.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 请求栅栏：判一条打到 `/dsh-session-delete-api` 的请求归不归本插件办。
+ *
+ * 两件事分开：**归属**（Host / Origin / Referer 是不是本次部署自己的）与**身份**（远程客户端是不是
+ * 宿主的已认证 Web 客户端）。绑定策略归宿主 webserver 配置——它只接受具体接口 IP 字面量、拒绝
+ * wildcard——所以「谁能到达」不是本插件能替它决定的事；栅栏本身只防 browser confused deputy，
+ * 身份留给宿主（见 ②）。口径与宿主 `/api` 的 `isTrustedApiRequest`（asar
+ * `dsh-client-connection/lib/index.js`）对齐，差别只有一条：本模块多查 Referer，因为
+ * `GET /attachment` 是二进制段（见末段）。
+ *
+ * 两条放行支，外加一条缺席规则：
+ * ① 头栅栏全过 ∧ 源地址回环 ∧ Host 属于本次部署（回环名 / 监听 bind 字面量）——本机工具与转发落在
+ *    回环的桌面壳；
+ * ② 宿主 `connection` 服务的 `requestRejection` 放行——远程浏览器。它自带宿主的 Host 白名单
+ *    （含部署声明的 `trustedHosts`）与「已认证 live peer」，身份就是那次 `dsh web` 打印的 URL 换来的
+ *    签名 cookie，不在本插件里复刻；
+ * ③ 身份层缺席（`src/ports/connection-port.ts` 报 `absent`，宿主无 `connection` 服务或成员改名）
+ *    ⇒ 远程一律拒（fail-closed：退回「只有本机」，LAN 上表现为 403 而不是静默放行）。
+ *
+ * **DNS rebinding 由 Host 归属判据挡**：`Origin === Host` 只证两者同名，不证这个名字属于本部署；
+ * 回环 socket 也不构成豁免（重绑到 `127.0.0.1` 的攻击正是回环源地址）。对浏览器来说 Host 是重绑伪造
+ * 不了的那个头——它按连接目标填，而 `Origin` 是页面自己的名字——所以归属判定先于任何本机 / 远程
+ * 分支，别在它前面加 fast-path。
+ *
+ * 末段：`GET /attachment` 的响应不是 opaque 的「读不出内容」——页面若已知某个 `sha256:…` 内容哈希，
+ * 就能把它当 `<img src>` 跨源渲染出来。那条请求不带 Origin，靠 Referer 判同源挡；宿主 `/api` 没有
+ * 二进制段，所以它的栅栏不需要这一条。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { ConnectionPort } from '../ports/connection-port.js';
+export type RequestTrustVerdict = 'allowed' | 'untrusted' | 'unauthenticated';
+export interface RequestTrustFacts {
+    /** 监听器绑定的那个具体接口 IP 字面量；老代次没有这个 getter 时为 `undefined`（bind 支退化，仍 fail-closed）。 */
+    readonly bindHost: string | undefined;
+    /** 宿主的 Web 身份面；端口每次请求惰性解析服务，缺席由它报 `absent`。 */
+    readonly connection: ConnectionPort;
+}
+/**
+ * 这条请求归不归本插件办。`untrusted` = 归属不对（跨源 / 重绑 / 头不成形）；`unauthenticated` =
+ * 归属对但远程客户端没带宿主身份（原文会提示用 `dsh web` 打印的 URL 打开）。
+ *
+ * 远程支的两个失败裁决由端口翻译宿主的区分（401 = 缺身份、403 = 归属不对）。身份层缺席（端口报
+ * `absent`）一律按归属不对处理：那时没有可换的身份，不能让原文提示用户去补一个不存在的东西。
+ */
+export declare function judgeRequest(req: IncomingMessage, facts: RequestTrustFacts): RequestTrustVerdict;

package/lib/types/api/route-table.d.ts

@@ -1,35 +1,49 @@
 /**
- * **路由表**（ADR-0004）：段名 → `{ 方法, 纯度, body, 处理 }`。一条记录，两个消费者。
+ * 路由表（ADR-0004）：段名 → { 方法, 纯度, 读面, body, 处理 }。一条记录，两个消费者。
  *
- * 此前"同一条请求该过哪几道判断"的知识散在两个函数里：`dispatch()` 里六个 `if` 各调一次
- * `requireMethod`，`purityOf()` 里另一组 `if` 决定"要不要进到达序链"，两处靠**注释**维持一致。
- * 不一致的两种后果都不好在测试里撞见：
- * - 该纯的判成写 ⇒ 一次探测/大正文读/扫描把删除按钮堵在串行链后面；
- * - 该写的判成纯 ⇒ 写动作绕开到达序链，与对账交错，回收站出现"目录在、行是降级元数据"的世界；
- * - body 该读没读 ⇒ 下游拿到 `null`；读了两遍 ⇒ 请求流已被消费（Node 的流只能消费一次）。
+ * 一致性要求：
+ * - 该纯的判成写 ⇒ 探测/正文读/扫描被堵在串行链后；
+ * - 该写的判成纯 ⇒ 写动作绕开到达序链，与对账交错；
+ * - body 该读没读 ⇒ 下游拿到 null；读两遍 ⇒ 流已被消费。
  *
- * 为什么这张表**不在** `shared/wire.ts`：处理函数会 import 动词与 `node:fs`，而浏览器半要 import
- * `wire.ts`——值 import 会把 Node 半拖进客户端 bundle，正好撞上 `tsdown` 的纯度门。段名与动作仍住
- * `wire.ts`（两半的共同契约），这张表只回答"怎么处理"。
+ * 这张表不放 shared/wire.ts：处理函数会 import 动词与 node:fs，而浏览器半要 import wire.ts。
+ * 段名与动作仍住 wire.ts；这张表只回答“怎么处理”。
  */
 import { ROUTES, type ApplyAction } from '../shared/wire.js';
 import type { DeleteDeps } from '../deps.js';
+import type { TrashEntry } from '../trash/entry.js';
 /** 请求体：`json` 才读下来（GET 一律不读；读两遍会把流消费掉）。 */
 export type BodyKind = 'none' | 'json';
 /** 到达序：`pure` 不进链；`chained` 进链；函数形式给 `/apply` 用（`count` 是纯读）。 */
 export type Purity = 'pure' | 'chained' | ((body: JsonBody) => 'pure' | 'chained');
-type JsonBody = Record<string, unknown> | null;
+/** 清册读面：`none` = 不读；`list` = 真相读（先对账）；`raw` = 索引快照（不对账）。
+ *  它与纯度是两条独立的轴：`count` 是 pure/不读，`detail` 是 pure/raw，`ping` 是 pure/不读。 */
+export type ReadKind = 'none' | 'list' | 'raw';
+export type JsonBody = Record<string, unknown> | null;
+/** 附件段的二进制落地：处理函数交回字节与安全头，分发器按它写 200（失败仍是 JSON 信封）。 */
+export interface BinaryResponse {
+    readonly body: Buffer;
+    readonly contentType: string;
+    readonly disposition: 'inline' | 'attachment';
+    readonly filename?: string;
+}
+/** 路由交给处理函数的读能力：读段与 `/empty` 只能从这一面取行，不能自己挑 `list()` / `raw()`（`/apply` 的写动词读面归动词自己）。 */
+export interface RouteRead {
+    rows(): Promise<readonly TrashEntry[]>;
+}
 export interface RouteSpec {
     readonly method: 'GET' | 'POST';
     readonly body: BodyKind;
     readonly purity: Purity;
-    run(deps: DeleteDeps, body: JsonBody): Promise<unknown>;
+    readonly read: ReadKind;
+    /** 响应形态：`json` 走信封（`{ok:true,value}`）；`binary` 直接把处理函数的 `BinaryResponse` 写出去。 */
+    readonly response: 'json' | 'binary';
+    run(deps: DeleteDeps, body: JsonBody, read: RouteRead, query: URLSearchParams): Promise<unknown>;
 }
 export declare const APPLY_ACTIONS: readonly ApplyAction[];
 /**
- * 六个段名各一行。`Record<段名, RouteSpec>` 是闸：`wire.ts` 加了段名而这里没加，编译不过。
+ * 九个段名各一行。`Record<段名, RouteSpec>` 是闸：`wire.ts` 加了段名而这里没加，编译不过。
  */
 export declare const ROUTE_TABLE: Record<(typeof ROUTES)[keyof typeof ROUTES], RouteSpec>;
 /** 段名 → 那一行；不认识的段名回 `undefined`（调用方抛 404，并带出原路径）。 */
 export declare function routeOf(rest: string): RouteSpec | undefined;
-export {};

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

@@ -0,0 +1,27 @@
+import { type TrashDetailAttachmentWire } from '../shared/wire.js';
+import type { Translate } from './copy.js';
+/**
+ * 一张附件的取数地址。**只从校验过的 id 与 kind 派生**：不接受路径、不接受任意查询串，
+ * 所以调用面把 URL 交给 `<img src>` / `<a href>` 时不存在"读任意文件"的入口。
+ */
+export declare function attachmentUrl(a: TrashDetailAttachmentWire): string;
+/**
+ * 一条消息的全部附件。顺序照日志，不重排：用户先发图后发文件，读起来应是他当时的顺序。
+ *
+ * `align` 是这一行的对齐（默认 `end`，与用户气泡同侧）：用户行靠右、助手行靠左，条跟着自己那条消息走。
+ * `failed` 按 `attachmentId` 记：同一个内容哈希在一段会话里可能被引用多次，裂一次就都不再画破图。
+ * 四个 `useState` 都在早退之前调用——附件从有到无时 hook 数量不变。
+ */
+export declare function AttachmentStrip({ attachments, t, align, }: {
+    attachments: readonly TrashDetailAttachmentWire[];
+    t: Translate;
+    /** `end`（默认）= 靠右，用户气泡那一侧；`start` = 靠左，助手正文那一侧。 */
+    align?: 'start' | 'end';
+}): import("react").JSX.Element | null;
+/**
+ * 附件清理回执那一行提示（「N 个附件未能清理」/「附件未清理：原因」）。表现层只收一句已经拼好的话；
+ * 什么时候该有这句话、失败与跳过怎么拼，归接线的那一侧（判据住 `receipt.ts` 与 `use-trash-query.ts`）。
+ */
+export declare function AttachmentNotice({ message }: {
+    message: string | null;
+}): import("react").JSX.Element | null;

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

@@ -1,5 +1,5 @@
 /**
- * 批量删除的浮条（2026-10-17 `6f24fd4`）：**多选模式内常驻**（0 条也渲染，既显示模式又给退出入口），
+ * 批量删除的浮条：**多选模式内常驻**（0 条也渲染，既显示模式又给退出入口），
  * 汇总「已选 N 条」+（读得到时）「含 K 个子会话」；「查看已选」展开限高可滚动的标题清单
  * （逐条可移除），回答"到底选了哪些"——清单默认收起，不把底部输入区盖住。
  * 模式内的整行点击守卫也挂在这棵常驻宿主上（见 `host-rows.ts` 的 `useSelectionRowClickGuard`）。
@@ -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

@@ -1,17 +1,17 @@
 /**
- * 批量删除的确认框（2026-10-17）——挂在 `shell.overlay` 上的宿主，加它读的那个模块级现场。
+ * 批量删除的确认框——挂在 `shell.overlay` 上的宿主，加它读的那个模块级现场。
  *
  * 为什么又开一个文件而不是把 `delete-confirm.tsx` 撑大：单删那张框是**已交付的面**（docs/ui-spec.md 状态 ②，
  * 用例钉着），批量形与它只有三件不同——标题随条数、目标卡逐条列、执行是一次批量 `apply`。共用一个壳
  * 意味着单删的 `busy` / 失败面要跟着学批量形，那是拿已交付的行为去换省一个文件。卡片样式（`TARGET_CARD`）
  * 与 hint、子会话那两句**复用**单删的，一句不造第二个键。
  *
- * 现场是模块级的（同 `delete-confirm.tsx` / `undo-toast.tsx`）：请求从浮条那颗按钮发来，确认框住在
+ * 现场是模块级的（同 `delete-confirm.tsx` / `undo-notices.ts`）：请求从浮条那颗按钮发来，确认框住在
  * `shell.overlay` 上——它必须活在行开关那棵子树之外（槽位行随宿主重排而卸载，见 `delete-confirm.tsx` 头注）。
  */
 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/batch-menu-item.d.ts

@@ -1,5 +1,5 @@
 /**
- * 会话「⋯」菜单里的「多选」入口（2026-10-17）。
+ * 会话「⋯」菜单里的「多选」入口。
  *
  * 常驻勾选框被用户打回后，入口改成显式模式：按下这一行才进入多选态（再按一次退出），
  * 模式内才渲染勾选框、才把整行点击变成"勾/取消"（守卫在 `host-rows.ts`）。

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

@@ -1,5 +1,5 @@
 /**
- * 宿主列表批量删除的**控件面**（2026-10-17，2026-10-20 拆出状态与行适配）：行首勾选框、行尾兜底开关，
+ * 宿主列表批量删除的**控件面**：行首勾选框、行尾兜底开关，
  * 以及确认框/浮条读的那一份计数问句。
  *
  * 入口在每行的「⋯」菜单里（`batch-menu-item.tsx`）：**按下才进入多选模式**，模式内才渲染勾选框、

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/confirm-close.d.ts

@@ -0,0 +1,11 @@
+/** 写入在飞时，确认框的关闭/取消都拦住：一次批量在飞时关掉框，用户会以为"没动"，而它其实正在动。
+ *  各张确认框（单删 / 批量删除 / 回收站恢复与彻底删除 / 孤儿会话清理 / 孤儿附件清理）共用这一条规则；
+ *  `Modal` 的遮罩 / X / Esc 都走同一个 `onClose`。
+ *
+ *  返回的 `closeDisabled` 与 `close` 同源：取消键的置灰读数也从这里取，各组件不再各写一遍
+ *  `disabled={busy}`——否则"拦住"这件事会有两个判据。 */
+export interface IdleClose {
+    close(): void;
+    readonly closeDisabled: boolean;
+}
+export declare function useIdleClose(busy: boolean, onClose: () => void): IdleClose;

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

@@ -1,39 +1,12 @@
 /**
- * 可见文案（界面标签与提示）＋接上宿主 Client locale 服务的那一步。
+ * 界面文案与宿主 locale 服务的接入。
  *
- * **例外：渠道错误原文。** `src/client/receipt.ts` 的 missing-id、`src/client/remote.ts` 的
- * 幂等空值与取数通道错误是协议诊断原文，固定中文、不随 locale；它们不进本字典。
- *
- * ## 为什么不是散在各组件里的中文字面量
- *
- * 官方给第三方 UI 插件的规则是「Route visible UI text through the Client locale service」
- * （宿主技能 `cordis-plugin-development/references/ui-plugin.md`）。宿主自己那套就是这么做的：
- * `ui-sidebar` 声明 `inject = ['slots','layout','uiWorkspace','locale','shortcuts']`，并在
- * `ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sidebar: dictionaries')` 里注册字典
- * （真产物原文）。所以本插件也把文案收成一份带**命名空间**的字典，`zh` 是完整真源、`en` 逐键镜像
- * ——宿主 `register` 的**对象形式要求两套内置语言都齐**（缺一个键就是运行期报错）。
- *
- * ## 服务是**可选读**的，不进 `inject`
- *
- * `ctx.get('locale')` 而不是把 `locale` 写进 `inject`。理由是本仓那条硬约束的另一面：**客户端半的
- * 条目激活失败 = 宿主进程死**（前端启动自检 `web boot: N entry did not activate` ⇒ 桌面壳
- * `reportFatal('web-boot')`）。宿主自己的 `ui-sidebar` 敢硬注入 `locale`（它是宿主的一部分，知道
- * 那一行一定在），而本插件要跨宿主代数活着 ⇒ 服务缺席时**降级到内置 zh 文案继续工作**，
- * 好过整个进程死。这与宿主对可选服务的官方写法同形（`ctx.get('…')?.…`）。
- *
- * 取数面：[`dsh-client-locale`] 的 `LocaleRuntime.register(ns, { zh, en })` 返回一个 disposer
- * （必须挂进 `ctx.effect`，否则卸载后字典留在注册表里，下次挂载会撞 "already has locale"），
- * `bind(ns)` 交回一个**按命名空间记忆化**的 `t(key, params)`（官方明说它"retain stable identity …
- * so they can ride inject surfaces without breaking memoization"——所以我们把它塞进槽位的
- * `inject` 载荷是正当用法）。
- *
- * ## 面板行那一行字为什么要用 thunk
- *
- * `sidebar.panellist` 的行名字由宿主 `syncPanels` 逐字 `label: resolveSlotLabel(options.label) ?? id`
- * 解析，而 `resolveSlotLabel` 的实现是 `typeof label === 'function' ? label() : label`，
- * 其 JSDoc 原文即 "thunks follow the active locale"；宿主自己还挂了
- * `ctx.effect(() => ctx.locale.subscribe(syncPanels), 'ui-sidebar: panel labels')` 在语言切换时重读。
- * ⇒ 面板名传 `() => t('trash.title')` 就随语言走；**换成活计数就会 stale**（只在条目或语言变化时重读）。
+ * - zh 是完整真源，en 逐键镜像。
+ * - locale 服务通过 ctx.get('locale') 可选读，服务缺席时退回内置 zh；为什么不进 inject 见
+ *   docs/architecture.md §3。
+ * - 面板行名传 thunk，语言切换时宿主会重读；其余文案走 t(key, params)。
+ * - 渠道错误原文（src/client/receipt.ts 的 missing-id/幂等空值、src/client/remote.ts 的取数通道错误）
+ *   不在此字典，它们是协议诊断，固定中文。
  */
 import { type RelativeTimeUnit } from './ui/format.js';
 import type { ClientContextLike } from './context.js';
@@ -50,7 +23,7 @@ declare const ZH: {
     readonly 'trash.readFailed': "回收站读不到";
     readonly 'trash.empty.title': "回收站是空的";
     readonly 'trash.empty.hint': "在会话条目的「…」菜单里选「删除」，会话会先进到这里，随时可以恢复。";
-    readonly 'trash.summary': "{count} 个会话 · 共 {size}";
+    readonly 'trash.summary': "{count} 个会话 · 可释放 {size}";
     readonly 'trash.group.count': "{count} 个会话";
     readonly 'trash.project.unknown': "未记录项目";
     readonly 'trash.row.deletedNow': "刚刚删除";
@@ -70,7 +43,7 @@ declare const ZH: {
     readonly 'trash.confirm.all': "清空回收站？";
     readonly 'trash.confirm.one': "彻底删除 1 个会话？";
     readonly 'trash.confirm.one.meta': "{project} · 删除于 {at} · {size}";
-    readonly 'trash.confirm.body': "这会从回收站移除文件，{strong}。";
+    readonly 'trash.confirm.body': "这会从回收站移除文件，{strong}。只清理会话独占的图片附件副本（共享副本保留）；宿主投影缓存与你磁盘上的原图不受影响。";
     readonly 'trash.confirm.body.strong': "之后没有任何副本可以恢复";
     readonly 'trash.confirm.purge': "彻底删除";
     readonly 'trash.toolbar.collapseAll': "全部折叠";
@@ -92,14 +65,40 @@ declare const ZH: {
     readonly 'trash.orphans.meta': "共 {size}，来自 {parents} 个失踪的父会话";
     readonly 'trash.orphans.open': "查看并清理";
     readonly 'trash.orphans.confirm': "清理 {count} 个无主子会话？";
-    readonly 'trash.orphans.body': "这些子会话的父会话已经不在会话列表或回收站里，清理后不可恢复。正在运行的子会话会被拒绝，不会被删除。";
+    readonly 'trash.orphans.body': "这些子会话的父会话已经不在会话列表或回收站里，清理后不可恢复。正在运行的子会话会被拒绝，不会被删除。只清理会话独占的图片附件副本（共享副本保留）；宿主投影缓存与你磁盘上的原图不受影响。若剩余引用源读不出，本次附件清理会跳过（会话目录仍会删除）。";
     readonly 'trash.orphans.group': "{project} · {count} 个 · {size}";
-    readonly 'trash.orphans.cacheNote': "本次只清理会话目录，不包含宿主投影缓存和附件。";
+    readonly 'trash.orphans.cacheNote': "本次会一并清理会话独占的图片附件副本；宿主投影缓存不包含在内。若剩余引用源读不出，本次附件清理会跳过（会话目录仍会删除）。";
     readonly 'trash.orphans.clean': "清理";
     readonly 'trash.orphans.failure': "残留检查/清理失败：{message}";
     readonly 'trash.orphans.cleanFailed': "{count} 组未清理：{message}";
     readonly 'trash.orphans.cleanPartial': "已先删掉 {removed} 个会话目录（{size}）";
     readonly 'trash.orphans.cleanGone': "有 {count} 组已不在了（可能已被别处清理，或父会话已恢复）";
+    readonly 'trash.attachments.failed': "已删除会话，但 {count} 个附件未能清理";
+    readonly 'trash.attachments.skipped': "附件未清理：{reason}";
+    readonly 'trash.attachments.skippedPartial': "部分附件未清理：{reason}（已清理 {removed} 个）";
+    readonly 'trash.attachments.alsoFailed': "；另有 {count} 个附件删除失败";
+    readonly 'maintenance.title': "维护";
+    readonly 'maintenance.orphans.title': "孤儿会话";
+    readonly 'maintenance.orphans.hint': "父会话已不在会话列表或回收站里的子会话。检查只读，不会自动运行。";
+    readonly 'maintenance.attachments.title': "孤儿附件";
+    readonly 'maintenance.attachments.hint': "在 .dsh 里没有任何引用的图片副本。检查只读，清理只动这些副本。";
+    readonly 'maintenance.scan': "检查";
+    readonly 'maintenance.scanning': "检查中…";
+    readonly 'maintenance.cleaning': "清理中…";
+    readonly 'maintenance.checkFailed': "检查失败";
+    readonly 'maintenance.notScanned': "尚未检查";
+    readonly 'maintenance.none': "没有发现";
+    readonly 'maintenance.orphans.count': "{count} 个";
+    readonly 'maintenance.attachments.count': "{count} 个";
+    readonly 'maintenance.attachments.scanFailed': "检查失败：{message}";
+    readonly 'maintenance.attachments.cleaned': "已清理 {count} 个（{size}）";
+    readonly 'maintenance.attachments.cleanFailed': "{count} 个附件未能清理（已清理 {removed} 个）";
+    readonly 'maintenance.attachments.cleanError': "附件清理失败：{message}";
+    readonly 'maintenance.attachments.confirm': "查看并清理 {count} 个孤儿附件？";
+    readonly 'maintenance.attachments.body': "只清理 .dsh 内无引用的图片副本；源文件不受影响；共享引用保留。";
+    readonly 'maintenance.attachments.previewTruncated': "仅预览前 {shown} 个；清理会处理全部 {total} 个。";
+    readonly 'maintenance.attachments.previewHint': "点图片可放大；关闭这个框不会删除任何东西。";
+    readonly 'maintenance.attachments.clean': "清理这些附件";
     readonly 'detail.notSelected': "选中一条会话，看它讲了什么";
     readonly 'detail.loading': "正在读这条会话…";
     readonly 'detail.readFailed': "这条会话的正文读不出来";
@@ -107,6 +106,7 @@ declare const ZH: {
     readonly 'detail.field.created': "创建";
     readonly 'detail.field.lastActivity': "最后活动";
     readonly 'detail.field.deletedAt': "删除于";
+    readonly 'detail.deletedAt.combined': "{relative}（{absolute}）";
     readonly 'detail.field.span': "活跃跨度";
     readonly 'detail.field.size': "大小";
     readonly 'detail.field.turns': "轮数";
@@ -124,6 +124,16 @@ declare const ZH: {
     readonly 'detail.value.spanDays': "{n} 天";
     readonly 'detail.messages.hidden': "另有 {count} 条宿主注入的上下文未显示";
     readonly 'detail.messages.omitted': "还有 {count} 条未显示";
+    readonly 'detail.image': "[图片]";
+    readonly 'detail.image.alt': "[图片 · {alt}]";
+    readonly 'detail.attachment.file': "文件";
+    readonly 'detail.attachment.preview': "附件预览";
+    readonly 'detail.attachment.alt': "附件图片";
+    readonly 'detail.attachment.open': "打开图片「{name}」";
+    readonly 'detail.attachment.unavailable': "附件不可用";
+    readonly 'detail.attachment.save': "另存为";
+    readonly 'detail.attachment.saving': "保存中…";
+    readonly 'detail.attachment.saveFailed': "保存失败：{message}";
     readonly 'detail.back': "← 返回清单";
     readonly 'detail.list.label': "回收站清单";
     readonly 'detail.role.user': "你";

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

@@ -26,8 +26,6 @@ export declare function requestDelete(input: {
     sessionId: string;
     title: string;
 }): void;
-/** 收起确认框（用户点「取消」/「关闭」、或删除成功后收工）。 */
-export declare function clearDeleteRequest(): void;
 /** 供宿主组件订阅。 */
 export declare function useDeleteRequest(): DeleteRequest | null;
 /** 测试专用：现场与 seq 归零，用例之间互不串味。 */

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

@@ -8,10 +8,10 @@
  * 清掉——**除非把常驻实例本身丢掉**。宿主自己的归档走的就是这条路：`clearArchivedCurrent()`
  * 发现当前会话进了归档集就 `clearMain()`（`dsh-client-ui-workspace/lib/client.js`）。
  *
- * 所以关闭/重开是**一段生命周期**（2026-10-21），不是一个 id：删除成功后 `afterDelete` 关掉当前
+ * 所以关闭/重开是**一段生命周期**，不是一个 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/maintenance-parts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 维护卡两段共用的两块皮：警告条外壳与失败块。
+ *
+ * 两段（孤儿会话 / 孤儿附件）在结构上只差正文：图标、底色、动作按钮与失败块的「原文 + 重试」
+ * 都一样。收在这里，改布局或按钮材质时不必在同一条卡里改两遍；正文仍由各段自己给。
+ */
+import type { ReactElement, ReactNode } from 'react';
+import type { Translate } from './copy.js';
+interface MaintenanceChromeProps {
+    /** 给测试与界面规格一个稳定的块名；缺省不写 `data-*`。 */
+    slot?: string;
+    busy: boolean;
+    t: Translate;
+    /** 旧面板块用过的下边距；设置页段内间距由父级 gap 给，默认不加。 */
+    gapBelow?: boolean;
+}
+export declare function MaintenanceBanner({ slot, busy, t, gapBelow, onOpen, children, }: MaintenanceChromeProps & {
+    onOpen: () => void;
+    children: ReactNode;
+}): ReactElement;
+export declare function MaintenanceFailure({ slot, message, busy, t, gapBelow, onRetry, }: MaintenanceChromeProps & {
+    message: string;
+    onRetry: () => void;
+}): ReactElement;
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * 插件设置页的「维护」卡（`plugins.bundle.config` 的占用者）。
+ *
+ * 两张段都是**手动**的：检查 → 预览 → 清理，没有挂载即扫、没有定时器。卡片的职责只有呈现：
+ * 状态那一行、检查按钮、以及各段自己的横幅 / 失败 / 提示 / 确认框；读数与动作全归
+ * `src/client/use-maintenance.ts`。
+ *
+ * 与回收站面板的区别：这里没有面板高度、没有清单与详情两栏、没有全局闸。控件只用
+ * `CARD` / `Button` / `Modal` / `fileSizeText`，所以同一张卡放在插件详情页的任意宽度下都成立。
+ *
+ * 孤儿会话段直接复用 `OrphanMaintenance`（警告条 / 失败 / 中性提示 / 预览确认的既有呈现）；
+ * 孤儿附件段是本文件里的 `AttachmentMaintenance`（横幅 + 失败 + 回执 + 缩略图预览与清理确认）。
+ */
+import type { ReactElement } from 'react';
+import { type Translate } from './copy.js';
+import { type MaintenanceDeps } from './use-maintenance.js';
+export interface MaintenanceSettingsProps {
+    deps: MaintenanceDeps;
+    /** 文案（缺省 = 内置 zh；宿主 locale 服务缺席时也是它，见 `copy.ts`）。 */
+    t?: Translate;
+}
+export declare function MaintenanceSettings({ deps, t }: MaintenanceSettingsProps): ReactElement;

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

@@ -1,11 +1,19 @@
+import type { Translate } from './copy.js';
 import './ui/styles.js';
 /**
  * `memo` 是必需的而不是优化：`react-markdown@10.1.0` 里**一处 memoization 都没有**（读实
  * `node_modules/react-markdown/lib/index.js:175-178`——`Markdown()` 每次调用都 `createProcessor(options)`
  * 再 `runSync(parse(file))`，`MarkdownHooks` 那一支也一样），而面板任何一次重渲（悬停、↑↓、
  * 「刚刚删除」那句要读 `Date.now()`）都会走到这里 ⇒ 不按住就是每条助手回复每拍重解析一遍。
- * 按住的条件就只有 `text`：它是这里唯一的输入，样式挂在 `.sd-md` 上、不随渲染变。
+ * 按住的条件是 `text` 与**探针 `localeKey`**（调用方在渲染时算好的一句固定键译文 `t('common.close')`）。
+ * `t` 本身是宿主 `bind` 出来的**稳定身份**（`copy.ts` 头注），一次客户端激活只造一个——拿身份当判据，
+ * 换语言就漏了：同一个 `t` 换 locale 后吐另一套词，烘进正文树的那句图片占位会滞留旧语言，而周围的
+ * 标签那一拍已经改口。探针也不能在 comparator 里现调 `t` 取——宿主 `t` 读的是**当前** locale，
+ * prev/next 那一拍都取到新值、恒等；只有渲染时算好存进 props 的那份才是换语言那一刻的读数。
+ * 探针没变 = 同语言同 `t` ⇒ 跳过重解析；变了（换语言或换 `t`）⇒ 重解析。
  */
 export declare const MarkdownBody: import("react").NamedExoticComponent<{
     text: string;
+    t: Translate;
+    localeKey: string;
 }>;