@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

package/lib/types/ports/connection-port.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 宿主 `connection` 服务（`dsh-client-connection` 的 `HostConnectionService`，`super(ctx, "connection")`）
+ * 的窄镜像：`requestRejection(request)` 一次做宿主 `/api` 的那两道——Host/Origin 栅栏与「已认证 live peer」。
+ *
+ * **每次请求惰性解析服务**，不在激活时取一次：插件与 `client-connection` 的激活顺序没有承诺，取早了
+ * 会让远程支永远缺席（LAN 上全 403 且难排查）。`ctx.get` 是同步查表，代价可以忽略。
+ *
+ * **状态码在这里翻成裁决**（401 = 归属对、缺身份；403 = 归属不对；其余按归属不对处理），
+ * 调用方拿到的就是自己的词表，不需要知道宿主用哪个码表达哪件事。成员名与返回值按 asar
+ * `dsh-client-connection/lib/index.js` 原文读实。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+export type ConnectionVerdict = {
+    readonly kind: 'allowed';
+}
+/** 组成里没有这个服务（无 web 组成 / 老代次）——调用方 fail-closed。 */
+ | {
+    readonly kind: 'absent';
+}
+/** 宿主认可归属，但这条请求没带已认证身份。 */
+ | {
+    readonly kind: 'unauthenticated';
+}
+/** 宿主不认可归属（Host/Origin 栅栏不过，或它给出的其余状态码）。 */
+ | {
+    readonly kind: 'untrusted';
+};
+export interface ConnectionPort {
+    verdictFor(req: IncomingMessage): ConnectionVerdict;
+}
+/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
+export declare function createConnectionPort(ctx: Context): ConnectionPort;

package/lib/types/ports/fs-port.d.ts

@@ -2,15 +2,27 @@ export interface FsPort {
     exists(p: string): Promise<boolean>;
     /** 建目录（含中间层）。首删时 `~/.dsh/session-trash/` 还不存在，而 `rename` 不建父目录。 */
     ensureDir(p: string): Promise<void>;
+    /** 搬目录：**目标已存在一律失败**，跨卷（EXDEV）也失败并说清楚——不替换、也不偷偷改成复制。
+     *  Linux 的 `rename` 会静默替代空目录而 Windows 不会，这个差别不能交给操作系统决定。 */
     rename(from: string, to: string): Promise<void>;
     removeDir(p: string): Promise<void>;
     sizeOfDir(p: string): Promise<number>;
     /** 目录下的条目名（**不递归**）。回收站详情要用它在那条目录里挑 `*.jsonl.zstd`。 */
     listFiles(p: string): Promise<string[]>;
-    /** 目录下的**子目录**名（不递归）。回收站对账用它找出"清单里还没有行"的条目目录——
+    /** 目录下的**子目录**名（不递归；**跟随软链**）。回收站对账用它找出"清单里还没有行"的条目目录——
      *  与 `listFiles` 分开是为了让"拒收文件"发生在挑选阶段（回收站根里落进来的杂散文件当外人）。 */
     listDirs(p: string): Promise<string[]>;
+    /** 解析符号链接后的真实路径。递归走目录时防环用：跟随软链之后，目录图不再是树。 */
+    realpath(p: string): Promise<string>;
     /** 整个文件读进内存。实测本机回收站里最大单文件 4.66 MB；**内存口径由逐帧解压把住**（见 `src/log/session-log.ts`），不在这里。 */
     readFile(p: string): Promise<Buffer>;
+    /** 只读的单文件读数：附件渲染与独占计划都用它（不递归、不跟随目录）。 */
+    statFile(p: string): Promise<{
+        size: number;
+    }>;
+    /** 删单个文件（不是目录）。危险能力，只挂到 `RemovalDeps` 上。 */
+    removeFile(p: string): Promise<void>;
 }
+/** 动词的基础面：读与搬移都有，**不拿删除**。删目录与删单文件只挂在 `RemovalDeps` 上（ADR-0006）。 */
+export type CoreFsPort = Omit<FsPort, 'removeDir' | 'removeFile'>;
 export declare function createFsPort(): FsPort;

package/lib/types/ports/host-port.d.ts

@@ -1,23 +1,12 @@
 /** 摘内存的三种落地（见 {@link HostPort.evictLive}）：`not-live` / `evicted` 都意味着**宿主列表已经不含它**；
  *  `unknown` 意味着读不到或摘不掉，**不能**据此通告客户端（发了就是假话，重连后那一行会自己长回来）。 */
 export type EvictionOutcome = 'evicted' | 'not-live' | 'unknown';
-/**
- * 角色一：**身份与归属**——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
- *
- * 为什么拆成角色：宿主能力的端口按角色切成三块，而不是一个什么都有的接口。调用方要的是
- * "一句话能说清的那一组能力"，而一个什么都有的端口让每条用例都得凑齐不相干的成员。
- * 这里只切**类型**，adapter 仍是同一颗对象。
- */
+/** 角色一：身份与归属——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
+ *  只切类型，adapter 仍是同一颗对象。 */
 export interface HostIdentityPort {
     workspaceOf(sessionId: string): Promise<string | undefined>;
-    /** 账本里还有这个工作区吗。**只读的判别**（`registry.get(id) !== undefined`），不抛。
-     *
-     *  **为什么恢复需要它**：宿主的「删除工作区」只删**注册**、保留目录与每一份会话日志
-     *  （asar `WorkspaceRegistry.delete` 的 JSDoc 原文 "Delete one workspace registration while
-     *  retaining its directory and every session log"），那些会话之后显示在「未分组」下。回收站里
-     *  **删在工作区之前**的条目记着那个已被删掉的 `workspaceId`，恢复时若照旧 `attach` 就会
-     *  `workspace not found` 整条失败（会话留在回收站里，用户看起来就是"恢复报错"）。所以恢复
-     *  先问这一句：不在 ⇒ 不挂账本，照常回盘、归入「未分组」（与宿主自己处理这类会话一致）。 */
+    /** 账本里还有这个工作区吗：只读判别，不抛。
+     *  宿主的「删除工作区」只删注册、保留目录与日志；恢复这类会话时跳过 attach，归入「未分组」。 */
     workspaceExists(workspaceId: string): Promise<boolean>;
     /** 会话落盘的**项目目录名**（`<sessions>/<projectKey(cwd)>`）；账本里没有这个会话 ⇒ `undefined`。
      *  与 `workspaceOf` 同一口径：**未命中是正常的 no-op，不是故障**（存储真故障照抛）。 */
@@ -49,23 +38,9 @@ export interface HostPresencePort {
     /** **如实通告**客户端"这个会话没了"：发宿主自己声明并转发的 `api-session/removed`，客户端当场删行。
      *  冷会话没有活体可摘，但同样需要这一条——否则那一行要等到重连（`handleConnected` → 重列）才消失。 */
     announceRemoved(sessionId: string): Promise<void>;
-    /** **如实通告**客户端"这个会话回来了"：摘要取自宿主自己的会话列表，发 `api-session/added`。
-     *  正常恢复走 {@link HostPresencePort.announceRestoredBatch}（整批一次预取）；这一条单条路是**删除组回滚**
-     *  用的（成员已经收过"已移除"、退回原处后补发）。取不到摘要就不发。 */
-    announceRestored(sessionId: string): Promise<void>;
-    /** 宿主会话表的一次预取：`[{ sessionId, summary }]`，`summary` 是宿主**原样**那一条。
-     *  给 {@link announceRestoredBatch} 当 `known` 用——整批只拉一次表。服务没挂回空表，不抛。 */
-    restoredSummariesOf(): Promise<readonly {
-        readonly sessionId: string;
-        readonly summary: unknown;
-    }[]>;
-    /** 一组会话的通告（2026-10-17 批量重构）：`known` 是调用方**整批预取**的摘要表——给了就一次都不
-     *  再拉表（每条一次 `controller.list()` 在 100 条的批量里就是 100 遍全表扫，那是那次"恢复很慢"的
-     *  头号来源）；没给则自己拉一次。缺席 id 不发，不影响已完成的恢复。 */
-    announceRestoredBatch(ids: readonly string[], known?: readonly {
-        readonly sessionId: string;
-        readonly summary: unknown;
-    }[]): Promise<void>;
+    /** 一组会话的「回来了」通告：implementation 拉一次宿主会话表，按 id 逐条发 added。
+     *  单条就是长度为 1 的批；批量只调一次。缺席 id 不发，不影响已完成的恢复。 */
+    announceRestored(sessionIds: readonly string[]): Promise<void>;
 }
 /**
  * 一次语料读的结果：**缺席显式化**——`available: false` 说的是"这一趟看不见语料"（`sessionQuery` 没挂，
@@ -83,7 +58,7 @@ export type CorpusRead<T> = {
  * 角色三：**会话语料**——整表身份与子会话闭包。
  *
  * 两个读面都把"这一趟看不见语料"写成显式的 {@link CorpusRead}：`{ available: false }` 与
- * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `CONTEXT.md` 的「语料缺席」**。
+ * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `docs/architecture.md` §2 的「语料缺席」**。
  */
 export interface HostCorpusPort {
     /** 整个会话语料（live ∪ persisted）的只读身份表。**服务缺席是显式的**：`sessionQuery` 没挂，或它的
@@ -96,8 +71,11 @@ export interface HostCorpusPort {
      *  键按调用方传进来的写法回（同一个父的 `session-x` / `x` 两种写法是同一个根，见 `membersFor`）。 */
     subagentMembersOf(parentIds: readonly string[]): Promise<CorpusRead<Record<string, readonly SubagentMember[]>>>;
 }
-/** 复合别名：adapter（`createHostPort`）与调用方把这 17 个方法当一个端口用；三个角色是它的切面。 */
+/** 复合别名：adapter（`createHostPort`）与调用方把这 15 个方法当一个端口用；三个角色是它的切面。 */
 export type HostPort = HostIdentityPort & HostPresencePort & HostCorpusPort;
+/** 动词的宿主面：身份与语料两片；不含在场三件。摘活体与通告只经 `CoreDeps.presence`（`PresenceCapability`）。
+ *  用交集而不是 `Omit` 黑名单：`HostPresencePort` 将来长出新方法时，不会自动漏进每个动词的 `host`。 */
+export type HostCorePort = HostIdentityPort & HostCorpusPort;
 export interface SessionIdentity {
     readonly sessionId: string;
     readonly parentSessionId?: string;
@@ -108,40 +86,20 @@ export interface SubagentMember {
     readonly sessionId: string;
     readonly projectDir: string;
 }
-/** 无 cwd 的会话落在 `<sessions>/_no-cwd/`（asar `dsh-session-persistence-jsonl/lib/index.js`
- *  的 `projectDir(root, cwd)`：`if (cwd === void 0) return join(root, "_no-cwd");`）。
- *  `projectDirOf` 与回收站对账（`src/trash/reconcile.ts` 重建条目）共用这一个字面量。 */
+/** 无 cwd 的会话落在 `_no-cwd/`；`projectDirOf` 与回收站对账共用这个字面量。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectDir`（`if (cwd === void 0) return join(root, "_no-cwd");`）。 */
 export declare const NO_CWD_PROJECT_DIR = "_no-cwd";
-/**
- * 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
- *
- * 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
- * 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
- * （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
- *
- * 原文（asar `dsh/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`）：
- * `function projectKey(cwd) { … if (ch === "/" || ch === "\\" || ch === ":") { if (!separatorRun) readable += "-"; separatorRun = true; }
- *  else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) { readable += ch; separatorRun = false; }
- *  else { readable += "~" + code.toString(16).toUpperCase().padStart(4, "0"); separatorRun = false; }
- *  return \`--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--\`; }`
- * 调用链：`locate(meta)` → `logPath(root, meta.cwd, meta.id, …)` → `projectDir(root, cwd)` → `projectKey(cwd)`。
- * 本机实测对得上：`D:/develop/GitHub/dsh-session-delete` → `--D-develop-GitHub-dsh-session-delete--`
- * （`~/.dsh/sessions` 下真有这个目录名；`D:/document/deepseek-harness/default-workspace` 同理）。
- *
- * **两个调用方共用这一份**：`projectDirOf`（删除时定位会话目录）与回收站对账的重建路径
- * （手工放进回收站的目录，从日志 header 的 `cwd` 反推它原本属于哪个项目目录）——算法只有这一处家。
- */
+/** 宿主 `projectKey(cwd)` 的逐字镜像：跨插件不能 import，宿主也没把它暴露成服务。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectKey`；调用链
+ *  `locate` → `logPath` → `projectDir` → `projectKey`。本机实测 `D:/develop/GitHub/dsh-session-delete`
+ *  → `--D-develop-GitHub-dsh-session-delete--`。`projectDirOf` 与回收站对账重建共用这一份；
+ *  宿主换代先复核算法。 */
 export declare function projectKey(cwd: string): string;
 /** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostCorpusPort.subagentMembersOf}）。 */
 export declare function bareSessionId(id: string): string;
 /** 这次失败是不是"账本里没那个工作区"（而不是另有故障）。恢复侧靠它把两种失败分开：
  *  前者按「未分组」收，后者照旧回滚报 `io`——不给真故障静默改归属的机会。 */
 export declare function isWorkspaceMissingError(error: unknown): boolean;
-/**
- * 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
- *
- * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
- * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
- * `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（src/remote/map-error.ts 的两行映射）。
- */
+/** 宿主服务的真实绑定；出错原样抛，由 `toRemoteFailure` 按 name 映射。
+ *  各方法调用的服务与方法见上方成员注释；错误映射表住 `src/remote/map-error.ts`。 */
 export declare function createHostPort(ctx: unknown): HostPort;

package/lib/types/ports/presence-port.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 在场能力：动词只拿到「成员离场 / 归位 / 一批归位」三条，不再拿到宿主的 `evictLive` / `announce*`。
+ *
+ * 生产实现住 `src/verbs/member-presence.ts`；组合根装配一次，挂在 `CoreDeps.presence`。这样
+ * “谁可以摘活体、谁可以发通告”由依赖面回答，而不是靠源码扫描维持。
+ */
+export interface MemberBackFacts {
+    readonly diskBack: boolean;
+    readonly workspaceBack: boolean;
+}
+export interface PresenceCapability {
+    /** 成员已经不在宿主可见列表：摘活体；三态不是 unknown 时发 removed。
+     *  `backInTrash: false` 表示目录没退回回收站（恢复回滚失败），此时什么都不做；`facts` 缺席按
+     *  「正常退回」处理（`createMemberPresence` 的缺省），不再留第三种含义。 */
+    memberGone(sessionId: string, facts?: {
+        readonly backInTrash: boolean;
+    }): Promise<void>;
+    /** 成员已经回到原来的可见状态：目录与账本两件写都回去才发 added。 */
+    memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
+    /** 批量恢复的「回来了」通告；单条就是长度为 1 的批。 */
+    announceRestored(ids: readonly string[]): Promise<void>;
+}

package/lib/types/shared/wire.d.ts

@@ -1,18 +1,9 @@
 /**
- * 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
- * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
- * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
+ * 跨半 wire 契约：前缀、九个端点、请求/响应形状与失败码。
+ * Node 半（src/api/dispatch.ts）与浏览器半（src/client/remote.ts）共用这一份，不各写字面量。
  *
- * 两条构建期硬约束（不是偏好）：
- *  ① tsdown 的浏览器半纯度门拦 Node 内建与平台模块表外的 `@deepseek-ai/*` 值 import——
- *     本文件两者都不涉及，且**零运行时依赖**（client 半把它整个 inline 进 bundle）；
- *  ② 跨插件一律 `import type`——本文件干脆没有 import。
- *
- * 信封（`RemoteResult`）与失败形状（`RemoteFailure`）也在这里——**因为它们本来就是两半的共同契约**：
- * Node 半按它产出（`src/api/dispatch.ts` 的失败支就是 `RemoteFailure` 那三件），浏览器半按它判别
- * （`src/client/remote.ts` 的 `unwrapRemoteResult` / `failureOf`）。形状取自宿主网关客户端面的原文
- * 「每次 unary 调用 resolve 成 RemoteResult、不为载体问题 reject」，但**它是本仓自己的 wire 契约**，
- * 不是对宿主模块的 import。
+ * 构建约束：本文件零运行时依赖、无 import；浏览器半把整个文件 inline 进 bundle。
+ * 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
  */
 /**
  * 插件专属前缀。
@@ -22,15 +13,18 @@
  * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 六个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
- *  一次 HTTP 带一组 id、逐条回结果；单条就是长度为 1 的批量，仓里不再留第二条执行路径。
- *  - `GET /list`：**对账并读**清单（`session-trash/` 里的目录是准）。
- *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链）——客户端探测用它，不用一次全表读。
- *  - `POST /detail`：单条详情（用 POST 表达一个读：判据就写在 `src/api/route-table.ts` 那一行的上方）。
+/** 九个段名（相对前缀）。写动作统一走一段 `/apply`：一次 HTTP 带一组 id、逐条回结果；
+ *  单条就是长度为 1 的批量，仓里不留第二条执行路径。
+ *  - `GET /list`：对账并读清单（`session-trash/` 里的目录是准）。
+ *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链），供客户端探测。
+ *  - `POST /detail`：单条详情（用 POST 表达一个读，判据在 `src/api/route-table.ts`）。
  *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
- *  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。
- *  - `GET /orphans`：无主子会话的扫描报告（纯读，2026-10-19）。**清理不在这里**——它是 `/apply` 的
- *    第五个动作，这一段只负责"有多少、在哪、多大"。 */
+ *  - `POST /empty`：清空回收站（聚合回执，不按条回）。
+ *  - `GET /orphans`：无主子会话的扫描报告（纯读）。清理是 `/apply` 的第五个动作，
+ *    这一段只负责"有多少、在哪、多大"。
+ *  - `GET /attachment`：附件原始字节（全仓唯一的二进制响应段；失败仍回 JSON 信封）。
+ *  - `GET /attachment-orphans`：无引用图片对象的扫描报告（纯读；数量/字节 + 供预览的对象清单）。
+ *  - `POST /attachment-clean`：清掉报告那一刻无引用的图片对象（聚合回执 `AttachmentCleanupWire`）。 */
 export declare const ROUTES: {
     readonly list: "/list";
     /** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
@@ -43,9 +37,17 @@ export declare const ROUTES: {
     readonly empty: "/empty";
     /** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
     readonly orphans: "/orphans";
+    /** 附件字节（图片/普通文件）：全仓唯一的二进制响应段，读的是宿主附件库。 */
+    readonly attachment: "/attachment";
+    /** 纯读：扫全部引用源与附件库 `objects`，报无引用图片的数量、字节与预览清单。 */
+    readonly attachmentOrphans: "/attachment-orphans";
+    /** 聚合清理：只删 `objects` 下无引用的图片，回 `AttachmentCleanupWire`。 */
+    readonly attachmentClean: "/attachment-clean";
 };
 /** `/apply` 的五个动作。id 的含义随动作走：`delete`/`count`/`orphan-clean` 是**宿主会话 id**
- *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。 */
+ *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。
+ *  两域都是 string（线上形状）；这里不引入品牌类型——错域不靠类型拦，交给各动词在运行期按自己的
+ *  语义处理，批处理不猜格式。 */
 export type ApplyAction = 'delete' | 'restore' | 'purge' | 'count' | 'orphan-clean';
 /** 每个动作的成功值：`count` 是一个数（拿不到就是 0，界面上那半句整句不出现）；
  *  `delete`/`restore` 是回收站那一行（`null` = 这一条已被**同批前一条**带走，幂等 no-op）；
@@ -112,12 +114,25 @@ export interface TrashRowWire extends TrashEntryWire {
     /** 删除时记下的工作区**已经不在账本里**（宿主的「删除工作区」只删注册、保留日志）。 */
     workspaceMissing?: boolean;
 }
-/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。 */
+/** 单条详情里的一条附件读数（`trash/attachments.ts` 的 `attachmentsInContent` 产出、详情投影上线）。
+ *  `attachmentId` 是宿主附件库的 sha256 键，也是 `GET /attachment` 的唯一寻址依据。 */
+export interface TrashDetailAttachmentWire {
+    attachmentId: string;
+    kind: 'image' | 'file';
+    name?: string;
+    mediaType?: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+}
+/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。
+ *  `attachments` 必填：没有附件就是空数组（界面上"这一条带没带附件"不靠字段缺席判断）。 */
 export interface TrashDetailMessageWire {
     role: 'user' | 'assistant';
     time: number;
     text: string;
     truncated: boolean;
+    attachments: TrashDetailAttachmentWire[];
 }
 /** 回收站单条详情的线上形状（`POST /detail`）。 */
 export interface TrashDetailWire {
@@ -137,10 +152,33 @@ export interface TrashDetailWire {
     messages: TrashDetailMessageWire[];
     omittedByPayloadCap: number;
 }
-/** 清空回收站的回执（与旧 `purge` 同形）。 */
+/** 一次永久删除顺带、或一次孤儿附件清理的附件读数。`skipped` 有值 = 这一轮**部分或整体没清**：
+ *  有候选日志或剩余引用源读不出（原因上屏）。此时 `removed` 仍可能 > 0——损坏的只是某一组候选，
+ *  其余照常清；跳过不是失败：`failed` 是逐文件真出错的那几件。 */
+export interface AttachmentCleanupWire {
+    removed: number;
+    freedBytes: number;
+    failed: number;
+    skipped?: string;
+}
+/** 孤儿附件报告里的一条：内容哈希 + 实测字节。没有原始文件名（附件库只存内容）。 */
+export interface AttachmentOrphanItemWire {
+    attachmentId: string;
+    bytes: number;
+}
+/** 孤儿附件报告（`GET /attachment-orphans`）：数量、总字节与对象清单。
+ *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图，最多 200 条；数量与字节按全量算。
+ *  读不出任何一处引用源时**不返回这一形状**，而是 `io` 失败——不拿 0 冒充"没有孤儿"。 */
+export interface AttachmentOrphanReportWire {
+    count: number;
+    totalBytes: number;
+    items: AttachmentOrphanItemWire[];
+}
+/** 清空回收站的聚合回执。`attachments` 缺席 = 这一版/这一轮没有附件清理读数（不拿零冒充"清过"）。 */
 export interface PurgeStatsWire {
     removed: number;
     freedBytes: number;
+    attachments?: AttachmentCleanupWire;
 }
 /** 无主子会话扫描里**一个项目目录**的汇总（界面上那条"哪一家还剩多少"的读数）。 */
 export interface OrphanProjectGroupWire {
@@ -157,16 +195,22 @@ export interface OrphanReportWire {
     missingParents: number;
     groups: readonly OrphanProjectGroupWire[];
 }
-/** 清理一组无主子会话的回执（与 {@link PurgeStatsWire} 同形，但计的是"删掉的会话目录"）。 */
+/** 清理一组无主子会话的回执（与 {@link PurgeStatsWire} 同形，但计的是"删掉的会话目录"）。
+ *  `attachments` 的口径与 purge 相同。 */
 export interface OrphanCleanStatsWire {
     removed: number;
     freedBytes: number;
+    attachments?: AttachmentCleanupWire;
 }
-/** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
+/** 请求参数名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。
+ *  附件段是 **query 参数**（GET 二进制响应，没有请求体）。 */
 export declare const PARAMS: {
     readonly entryId: "entryId";
     readonly action: "action";
     readonly ids: "ids";
+    readonly attachmentId: "id";
+    readonly attachmentKind: "kind";
+    readonly attachmentName: "name";
 };
 /**
  * 失败信封的**线上形状**（本文件）：`code` 是判别依据、`message` 是上屏原文、
@@ -212,6 +256,13 @@ export type RouteCode = (typeof ROUTE_CODES)[number];
  */
 export type AllCodeSuffix = VerbCode | RouteCode;
 export declare const SESSION_DELETE_CODES: Record<AllCodeSuffix, `sessiondelete/${AllCodeSuffix}`>;
+/** `error.code` 是不是本仓的失败形状（`sessiondelete/<后缀>`）。**只认前缀**：后缀在不在册是
+ *  {@link verbCodeOf} 的问题。任何要「已经是本仓的码就原样对待」的调用点都问这一句，不在调用点
+ *  再写一份前缀字面量。 */
+export declare function isSessionDeleteCodeError(error: unknown): boolean;
+/** `error.code` 折回那个动词词：前缀与后缀两件都成立才交回（后缀要在 {@link VERB_CODES} 册上）。
+ *  路由自检码、别域的码、非字符串 code 一律 `undefined`。 */
+export declare function verbCodeOf(error: unknown): VerbCode | undefined;
 /** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
 export declare const TRASH_DIR_NAME = "session-trash";
 /** 页脚/文案里带尾斜杠的那一版（`splitOn` 按它切一刀再把目录名包成 code）。 */

package/lib/types/trash/attachments.d.ts

@@ -0,0 +1,85 @@
+import type { FsPort } from '../ports/fs-port.js';
+import { type AttachmentCleanupWire } from '../shared/wire.js';
+export interface ImageRef {
+    kind: 'image';
+    id: string;
+    mediaType?: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    name?: string;
+}
+export interface FileRef {
+    kind: 'file';
+    id: string;
+    name: string;
+    bytes: number;
+}
+export type AttachmentRef = ImageRef | FileRef;
+export declare function isAttachmentId(value: unknown): value is string;
+/** `statFile` / `readFile` / `sizeOfDir` 里只有 ENOENT 能当"不在"；权限、盘挂、I/O 错误都必须露成读不出。 */
+export declare function isMissing(error: unknown): boolean;
+/** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
+export declare function attachmentPathOf(home: string, kind: 'image' | 'file', id: string): string;
+/** 一条消息的 `content[]` 里的附件块；畸形 id / 非附件段一律跳过。 */
+export declare function attachmentsInContent(content: unknown): AttachmentRef[];
+export interface AttachmentReadDeps {
+    fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath'>;
+    home: string;
+}
+export interface AttachmentRemovalDeps extends AttachmentReadDeps {
+    fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath' | 'removeFile'>;
+}
+/** 一个会话目录里的图片引用；`unreadable` 有值 = 这一组不可知（调用方按"跳过它"处理）。
+ *
+ *  **没有规范 zstd 日志 ≠ 没有引用**：明文日志、别的版本/布局、以及子目录都可能藏着引用。
+ *  **有规范日志但目录里还有子目录也不够**：日志只覆盖本目录，子目录里的引用读它看不见——
+ *  同样按不可读处理（宁可留下对象等维护卡兜底，不冒"没引用"）。
+ *  **规范日志旁的文件也要过关**：老一代规范日志可以并存（新代包含旧代）；0 字节临时日志是
+ *  写盘未完成的空产物，也没有引用。非空临时日志、明文日志或其他任何文件仍按不可读处理（fail closed）。
+ */
+export declare function imageIdsOfDir(deps: AttachmentReadDeps, dir: string): Promise<{
+    ids: Set<string>;
+    unreadable?: string;
+}>;
+interface PlannedImageRemoval {
+    id: string;
+    path: string;
+    bytes: number;
+}
+export interface ImageRemovalPlan {
+    entries: readonly PlannedImageRemoval[];
+    bytes: number;
+    skipped?: string;
+}
+/**
+ * 独占计划：候选 = 本次被删会话日志里的图片 id；剩余引用 = 活动会话 + 全部未删 `session-trash`
+ * 目录 + storages/cache。
+ * 剩余引用源读不出 ⇒ 整体跳过；候选日志读不出 / 附件对象 stat 失败 ⇒ 只跳过那一部分，其余照常。
+ */
+export declare function planImageAttachmentRemoval(deps: AttachmentReadDeps, removedDirs: readonly string[]): Promise<ImageRemovalPlan>;
+/**
+ * 逐文件删；ENOENT 由端口的 `force` 吞掉；其他错误计数并继续。
+ *
+ * 删除动作只认「`home` + `id` 自己推导出来的那一条路径」：计划是数据，手搭的/被改过的条目
+ * 只要路径与推导不一致就拒绝（计数为失败，不删），源文件因此没有删除入口。
+ */
+export declare function executeImageAttachmentRemoval(deps: AttachmentRemovalDeps, plan: ImageRemovalPlan): Promise<{
+    removed: number;
+    freedBytes: number;
+    failed: number;
+}>;
+/**
+ * 扫「当前没有任何引用源引用」的图片对象。
+ *
+ * 引用侧与删除计划共用同一条判据：活动会话 + 全部 `session-trash` 目录 + `storages/cache` JSON。
+ * 任何一处读不出 ⇒ 整份报告跳过（fail closed），绝不把"读不出"折成"没有引用"。
+ * 候选侧只认 `attachments/v1/objects` 下 `<2 hex>/<64 hex>` 这一种真实形状：`file-objects` /
+ * `tmp` / `v2` / `cache` 与非规范名字一律不进候选——清理只处理 `.dsh` 内的图片副本。
+ *
+ * 对象列表或 stat 读不出同样整份跳过：报告宁可失败，也不给一份"少算了一些"的清理计划。
+ */
+export declare function scanOrphanImageAttachments(deps: AttachmentReadDeps): Promise<ImageRemovalPlan>;
+/** 清掉扫描那一刻无引用的图片对象；扫描跳过 ⇒ 零删，并原样带回跳过的原因。 */
+export declare function cleanOrphanImageAttachments(deps: AttachmentRemovalDeps): Promise<AttachmentCleanupWire>;
+export {};

package/lib/types/trash/detail.d.ts

@@ -1,17 +1,40 @@
-import type { ManifestPort } from './manifest.js';
+/**
+ * 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（用例见 `tests/trash-detail.test.ts`）。
+ *
+ * 三层里的策略层——编解码在 `src/log/*`，这里只回答"给谁看、给多少、算不算失败"。
+ *
+ * 三条硬口径，都不是口味：
+ * ① **寻址只认清册（raw 索引）**：`entryId` 先在对账之外的 raw 索引里查，目录一律由 `trashDirOf(record.id, home)` 推
+ *    ⇒ 外部输入进不了文件系统寻址（不给"传个路径就读任意目录"留缝）。
+ * ② **正文只认 `source.kind === "user"`**：`user/message` 里绝大多数是宿主注入的上下文
+ *    （本机实测一条会话：真实提问 21 条、注入 241 条），不过滤就被淹掉；注入条数照样上线
+ *    （`injectedCount`），让"为什么少了这么多条"能与页面上的数字对账。
+ * ③ **两个闸是载荷闸，不是读盘闸**：每条 3 000 字符、累计 50 万字符（CJK 最坏 ≈ 1.5 MB UTF-8）。
+ *    本机存量一条都触发不了（量级随盘上会话数摆动，不在这里钉数）⇒ 它们是防异常
+ *    膨胀的；**不设"文件太大就拒绝"**，那种阈值只会把真读得出来的正文挡在外面。
+ *
+ * 计数与正文**同源过滤、各过各的闸**：`user/message` 先要求 `source.kind === 'user'`，两类都过"空文本**且**
+ * 无附件"过滤；`userMessageCount` / `assistantMessageCount` 数的是通过过滤的条数，**不受载荷闸影响**。正文再受
+ * 单条/累计两个闸：单条超限截断并把那一条标成 `truncated`，累计到上限后剩下的整条不再收、只累进
+ * `omittedByPayloadCap`——所以计数可以大于正文条数，详情里两件事分开说。
+ * 附件随消息一起收（`attachmentsInContent`），也有两个闸：每条 20、总量 200；超出的**静默丢**，
+ * 不累进 `omittedByPayloadCap`——那个计数说的是"整条正文没进来"，拿它兼报少了几张附件会让两个数都对不上。
+ */
+import { type TrashEntry } from './entry.js';
 import type { FsPort } from '../ports/fs-port.js';
-import type { TrashDetailMessageWire, TrashDetailWire } from '../shared/wire.js';
+import type { TrashDetailWire } from '../shared/wire.js';
 /** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
 export declare const PER_MESSAGE_CHAR_CAP = 3000;
 /** 一次回信的正文总量上限（字符）。 */
 export declare const TOTAL_CHAR_CAP = 500000;
-/** 详情正文里的一条消息 / 整份详情：**线上形状的家在 `shared/wire.ts`**（ADR-0003）——
- *  Node 半产出它，浏览器半按同一份类型消费，这里只留旧名做别名。 */
-export type TrashDetailMessage = TrashDetailMessageWire;
 export type TrashDetail = TrashDetailWire;
 export type DetailDeps = {
+    /** 详情自己直接要的三件（判目录在不在、挑日志、读日志）。对账不在这条路上，所以不需要 `listDirs`。 */
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'readFile'>;
-    manifest: ManifestPort;
+    /** 路由交来的清册 **raw 行**：`/detail` 声明为 pure，读一次不能顺手对账——对账会写清册行，那是写动作，
+     *  必须排在到达序链上。读面由路由记录选好（`read: 'raw'`），这里只消费行，不再自己挑 `list()` / `raw()`。
+     *  代价是有意的：只有目录、清册还没这一行的手工搬入条目读不到（`/list` 对账后可见）。 */
+    rows: () => Promise<readonly TrashEntry[]>;
     home: string;
 };
 /** 两个载荷闸（可调是为把策略单独验穿；生产走的就是这两个默认值，用例里钉着）。 */

package/lib/types/trash/entry.d.ts

@@ -8,8 +8,8 @@ export interface TrashEntry {
     /** 删除时它所属的工作区；**空串 = 删除时就没有账目**（「未分组」的会话，宿主的"删除工作区"会造出这种），
      *  恢复时据此跳过 `attach`。 */
     workspaceId: string;
-    /** 删除**之前**的归档态，**只作事实记录**：2026-10-21 起删除不归档、恢复也不按它还原可见性。
-     *  旧清单迁移只用它区分"删除时是我们归档的"（false 且当前仍归档）与"用户删前自己归档的"（true，保持归档）。 */
+    /** 删除前的归档态，只作事实记录：删除不再改变归档，恢复也不按它还原可见性。
+     *  旧条目迁移用它区分“删除时被我们归档的”（false 且当前仍归档）与“用户删前自己归档的”（true）。 */
     wasArchived: boolean;
     deletedAt: number;
     /** 删除时**尽力**取的会话标题（来源：宿主 projection cache 服务；底层是
@@ -19,7 +19,7 @@ export interface TrashEntry {
     sizeBytes: number;
     /** **组语义**：这一条是跟着父一起进回收站的子会话 ⇒ 记父那一行的 `id`。
      *  缺席 = 这一行是父（或它自己就是被单独删掉的）。清单据此把孩子折进父行、不单独列。
-     *  老代留底 / 清册被清后由目录重建出来的行**没有这个字段**（文件侧没有它的副本，与
+     *  清册被清后由目录重建出来的行没有这个字段（文件侧没有它的副本，与
      *  `workspaceId`/`wasArchived`/`title` 同一类降级），那一趟它们会各占一行——那是"分组信息随清册一起没了"
      *  的如实结果，不假装知道（CONTEXT.md 的「无主子会话」条）。 */
     parentEntryId?: string;

package/lib/types/trash/groups.d.ts

@@ -1,16 +1,10 @@
 /**
- * **组语义的唯一家**（ADR-0001）：回收站里「这一组有谁」以及「哪些行在清单里露面」。
+ * 组语义的唯一家（ADR-0001）：回收站里「这一组有谁」以及「哪些行在清单里露面」。
  *
- * 此前这条关系在四个地方各算一遍，而且已经算出两种答案：
- * `assembleTrashRows` 与 `restoreSession` 都认为「父自己也是孩子时，它接不住孩子」，
- * 而 `purgeTrash` 的 `id === x || parentEntryId === x` 不认这条 ⇒ 嵌套组上它会连带删掉不属于这一组的孙代
- * （不可恢复）。判据原文只在这里写一次：
+ * 接得住孩子的只有组根——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
+ * 孩子必须自己占一行，否则它的字节会被头部合计数两遍，而它自己既看不见也清不掉。
  *
- * **接得住孩子的只有组根**——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
- * 孩子必须自己占一行，否则它的字节会被头部合计数两遍（而它自己既看不见也清不掉）。
- *
- * 三个函数都是**纯函数**、都吃一份快照：`/apply` 那条路会在同一批里多次重问、而快照会被就地收缩，
- * 收缩的时机归调用方——groups module 不持有可变状态，也就没有"这份快照谁负责更新"的第二套契约。
+ * 三个函数都是纯函数、都吃一份快照；收缩时机归调用方，本模块不持有可变状态。
  */
 import type { TrashEntry } from './entry.js';
 /** 一条露面的组根，连同它接住的孩子（顺序与清册一致）。 */
@@ -35,11 +29,21 @@ export declare function visibleGroups(rows: readonly TrashEntry[]): TrashGroupVi
  *   调用方据此报 `trash-empty` / 判"已被同批前一条带走"。
  */
 export declare function groupOf(rows: readonly TrashEntry[], id: string): TrashEntry[];
+/** 一条 id 在「原始快照 vs 当前视图」里的三态。判别联合：**只有 `fresh` 带当前这一组**——
+ *  组语义只对"还在"的 id 有意义，carried / absent 没有可交的组，调用方也就无从误用。 */
+export type GroupClaim = {
+    readonly verdict: 'fresh';
+    readonly group: readonly TrashEntry[];
+} | {
+    readonly verdict: 'carried';
+} | {
+    readonly verdict: 'absent';
+};
 /**
- * 「这条是被**同批前一条**带走的，还是整批开始前就没有？」
+ * 「这条是被**同批前一条**带走的，还是整批开始前就没有，还是仍在？」
  *
- * 幂等语义只属于前者：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
+ * 幂等语义只属于 `carried`：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
  * `trash-empty`，不能被"已被带走"这句话掩盖成成功。**所以判据是快照的原始形状，不是当前形状**：
- * 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+ * 原始快照里认得出（它自己、或指向它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
  */
-export declare function takenByEarlierInBatch(original: readonly TrashEntry[], current: readonly TrashEntry[], id: string): boolean;
+export declare function claimOf(original: readonly TrashEntry[], current: readonly TrashEntry[], id: string): GroupClaim;

package/lib/types/trash/ledger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 清册的两个读面：**真相读走 `list()`（先对账，再交行）；pure 读面走 `raw()`（只回索引，不写行）**。
+ *
+ * 外部事实源是 `session-trash/` 里的目录；`manifest.list()` 只是 raw 索引。
+ * 消费方只认这个 seam：写动作与真相读用 `list()`，不再各自记得"读前先 reconcile"；`/orphans` 与 `/detail`
+ * 声明为 pure，只许 `raw()`——一次 pure 读若顺手对账，就等于把一个写动作带到了到达序链之外。
+ * **它不是 `ManifestPort`**：同名 `list()` 的语义已经换成真相读，拿它当 raw 端口用会漏对账或递归对账。
+ * 两条写口从 raw 端口取；raw 端口本身只留给本 module 与 `src/trash/reconcile.ts` 的 implementation。
+ */
+import type { FsPort } from '../ports/fs-port.js';
+import type { TrashEntry } from './entry.js';
+import type { ManifestPort } from './manifest.js';
+export interface TrashLedger extends Pick<ManifestPort, 'add' | 'remove'> {
+    /** 真相读：先对账、再交行。`/list`、`/empty` 与写动词都认这一条。 */
+    list(): Promise<TrashEntry[]>;
+    /** raw 索引快照：**不对账、不写行**。只给声明为 pure 的读面（`/orphans` 扫描、`/detail` 详情）；
+     *  要知道"此刻真有的一切"用 `list()`。 */
+    raw(): Promise<TrashEntry[]>;
+}
+export declare function createTrashLedger(raw: ManifestPort, fs: FsPort, home: string): TrashLedger;

package/lib/types/trash/manifest.d.ts

@@ -1,5 +1,6 @@
 import type { TrashEntry } from './entry.js';
-/** 回收站清单的**唯一**读法（动词只依赖这个端口，不认 storage domain 的形状）。 */
+/** 回收站清单的 **raw 索引端口**：只给 `src/trash/ledger.ts` 与对账实现；动词与路由只认 ledger，
+ *  不认 storage domain 的形状。`list()` 不保证与 `session-trash/` 目录一致（对账在 ledger 的 `list()`）。 */
 export interface ManifestPort {
     list(): Promise<TrashEntry[]>;
     add(e: TrashEntry): Promise<void>;