@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

package/lib/index.js

@@ -1,24 +1,15 @@
+import path, { join, resolve } from "node:path";
 import zlib from "node:zlib";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { mkdir, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 //#region src/shared/wire.ts
 /**
-* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
-* Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
-* 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
-*
-* 两条构建期硬约束（不是偏好）：
-*  ① 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。
+* 跨半 wire 契约：前缀、九个端点、请求/响应形状与失败码。
+* Node 半（src/api/dispatch.ts）与浏览器半（src/client/remote.ts）共用这一份，不各写字面量。
+*
+* 构建约束：本文件零运行时依赖、无 import；浏览器半把整个文件 inline 进 bundle。
+* 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
 */
 /**
 * 插件专属前缀。
@@ -28,15 +19,18 @@ import { homedir } from "node:os";
 * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 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`）。 */
 const ROUTES = {
 	list: "/list",
 	/** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
@@ -48,13 +42,23 @@ const ROUTES = {
 	/** 清空回收站。 */
 	empty: "/empty",
 	/** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
-	orphans: "/orphans"
+	orphans: "/orphans",
+	/** 附件字节（图片/普通文件）：全仓唯一的二进制响应段，读的是宿主附件库。 */
+	attachment: "/attachment",
+	/** 纯读：扫全部引用源与附件库 `objects`，报无引用图片的数量、字节与预览清单。 */
+	attachmentOrphans: "/attachment-orphans",
+	/** 聚合清理：只删 `objects` 下无引用的图片，回 `AttachmentCleanupWire`。 */
+	attachmentClean: "/attachment-clean"
 };
-/** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
+/** 请求参数名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。
+*  附件段是 **query 参数**（GET 二进制响应，没有请求体）。 */
 const PARAMS = {
 	entryId: "entryId",
 	action: "action",
-	ids: "ids"
+	ids: "ids",
+	attachmentId: "id",
+	attachmentKind: "kind",
+	attachmentName: "name"
 };
 /**
 * 进程内判别「这已经是一次失败」——**按标记位认，不按 `instanceof`**（跨 realm / 跨 bundle 都不成立）。
@@ -72,7 +76,7 @@ function isDSHRemoteError(value) {
 /** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见本文件。 */
 const SESSION_DELETE_ERROR_DOMAIN = "sessiondelete";
 /** 五个**动词码**（本文件那张表）。`io` 是唯一兜底。 */
-const VERB_CODES$1 = [
+const VERB_CODES = [
 	"live",
 	"not-found",
 	"trash-empty",
@@ -89,13 +93,27 @@ const SESSION_DELETE_CODES = {
 	"not-found-route": "sessiondelete/not-found-route",
 	"bad-request": "sessiondelete/bad-request"
 };
+/** 失败码的前缀。读码只走下面两条，别在调用点各写一份字面量。 */
+const CODE_PREFIX = `${SESSION_DELETE_ERROR_DOMAIN}/`;
+/** `error.code` 是不是本仓的失败形状（`sessiondelete/<后缀>`）。**只认前缀**：后缀在不在册是
+*  {@link verbCodeOf} 的问题。任何要「已经是本仓的码就原样对待」的调用点都问这一句，不在调用点
+*  再写一份前缀字面量。 */
+function isSessionDeleteCodeError(error) {
+	const raw = error?.code;
+	return typeof raw === "string" && raw.startsWith(CODE_PREFIX);
+}
+/** `error.code` 折回那个动词词：前缀与后缀两件都成立才交回（后缀要在 {@link VERB_CODES} 册上）。
+*  路由自检码、别域的码、非字符串 code 一律 `undefined`。 */
+function verbCodeOf(error) {
+	const raw = error?.code;
+	if (typeof raw !== "string" || !raw.startsWith(CODE_PREFIX)) return void 0;
+	const suffix = raw.slice(CODE_PREFIX.length);
+	return VERB_CODES.includes(suffix) ? suffix : void 0;
+}
 /** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
 const TRASH_DIR_NAME = "session-trash";
 //#endregion
 //#region src/remote/map-error.ts
-/** 插件专属远程域名（src/shared/wire.ts）：与宿主官方域（`workspace/*`、`session/*`、`gateway/*`…）不重名。
-*  字面量的家在 `shared/wire.ts`（ADR-0003）——浏览器半也按同一个域认码。 */
-const DOMAIN = SESSION_DELETE_ERROR_DOMAIN;
 /** 宿主两条类型化错误 → 我们的码（本文件的两行映射）。
 *  类不可 import（跨插件值 import 是红线；且宿主包与运行中的宿主不同代）⇒ 按官方构造器写死的 `this.name` 认。
 *  证据：asar `dsh/node_modules/@deepseek-ai/dsh-workspace/lib/index.js` 原文
@@ -185,7 +203,7 @@ function toRemoteFailure(error) {
 		};
 	}
 	const raw = error?.code;
-	if (typeof raw === "string" && OFFICIAL_CODE.test(raw) && !raw.startsWith(`${DOMAIN}/`)) {
+	if (typeof raw === "string" && OFFICIAL_CODE.test(raw) && !isSessionDeleteCodeError(error)) {
 		const details = detailsOf(error);
 		return {
 			code: raw,
@@ -193,36 +211,24 @@ function toRemoteFailure(error) {
 			...details === void 0 ? {} : { details }
 		};
 	}
-	const reason = typeof raw === "string" && raw.startsWith(`${DOMAIN}/`) ? raw.slice(14) : void 0;
-	const fromVerb = reason !== void 0 && VERB_CODES$1.includes(reason) ? reason : void 0;
+	const fromVerb = verbCodeOf(error);
 	const host = hostErrorOf(error);
 	const own = detailsOf(error) ?? (host === void 0 ? void 0 : detailsOf(host));
 	if (host === void 0 && fromVerb === void 0 && typeof raw === "string" && raw.includes("/")) return {
-		code: `${DOMAIN}/io`,
+		code: SESSION_DELETE_CODES.io,
 		message: messageOf(error)
 	};
 	const code = host !== void 0 ? HOST_ERROR_CODE[host.name] : fromVerb ?? "io";
 	return {
-		code: `${DOMAIN}/${code}`,
+		code: SESSION_DELETE_CODES[code],
 		message: messageOf(error),
 		...own === void 0 ? {} : { details: own }
 	};
 }
 //#endregion
 //#region src/verbs/errors.ts
-/** 五个码 / 三个路由自检码的**家都在 `shared/wire.ts`**（ADR-0003）：浏览器半也要认它们（比如
-*  `not-found` 在界面上是中性提示而不是失败），所以它们属于两半共同的契约，不属于 Node 半。
-*  这里只转出旧名，免得调用点全改一遍。 */
-const VERB_CODES = VERB_CODES$1;
-/** `sessiondelete/` 这个前缀——拆码用它，别在下面几处各写一遍字面量。 */
-const VERB_CODE_PREFIX = `${SESSION_DELETE_ERROR_DOMAIN}/`;
-/** `error.code` 是不是本仓的动词码（`sessiondelete/<码>`）。**唯一判据**：`journalFailure` 与永久删除
-*  执行器要"已经是动词码就原样抛"时都问这一句。同文件的 `withRollbackFailures` 还要码的后缀，所以它
-*  就地 `slice` 一次——前缀仍只住 `VERB_CODE_PREFIX` 这一处，别在调用点另写一份字面量。 */
-function isVerbCodeError(error) {
-	const raw = error?.code;
-	return typeof raw === "string" && raw.startsWith(VERB_CODE_PREFIX);
-}
+/** 失败的**结构与措辞**。码本身、码的前缀读法与动词词表都住在 `shared/wire.ts`（ADR-0003）：
+*  浏览器半也要认它们，它们属于两半共同的契约，不属于 Node 半。这里只做动词抛错与回滚措辞。 */
 function verbError(code, message, cause, details) {
 	const e = new Error(message);
 	e.code = SESSION_DELETE_CODES[code];
@@ -230,6 +236,10 @@ function verbError(code, message, cause, details) {
 	if (details !== void 0) e.details = details;
 	return e;
 }
+/** `trash-empty` 的原文：有具体条目就点名那个 id，拿不到时只报通用那句。 */
+function trashEmpty(entryId) {
+	return verbError("trash-empty", entryId === void 0 ? "回收站里没有这一条" : `回收站里没有这一条：${entryId}`);
+}
 /** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
 function routeError(code, httpStatus, message) {
 	const e = verbError("io", message);
@@ -252,9 +262,7 @@ function carriedRollbackFailures(error) {
 *  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
 *  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。 */
 function withRollbackFailures(error, failures) {
-	const raw = error?.code;
-	const reason = typeof raw === "string" && raw.startsWith(VERB_CODE_PREFIX) ? raw.slice(VERB_CODE_PREFIX.length) : void 0;
-	const code = reason !== void 0 && VERB_CODES.includes(reason) ? reason : "io";
+	const code = verbCodeOf(error) ?? "io";
 	const carried = carriedRollbackFailures(error);
 	const merged = [.../* @__PURE__ */ new Set([...carried, ...failures])];
 	const base = error instanceof Error ? error.message : String(error);
@@ -262,6 +270,90 @@ function withRollbackFailures(error, failures) {
 	return verbError(code, base.includes("；回滚未完成：") ? extra.length > 0 ? `${base}；${extra.join("；")}` : base : `${base}；回滚未完成：${merged.join("；")}`, error, { rollbackFailures: merged });
 }
 //#endregion
+//#region src/api/request-trust.ts
+/** 桌面壳那条路（asar `/lib/main.js` 的 `forwardWebRequest`）：渲染进程从 `dsh-app://app/` 加载，
+*  转发前把 `host` / `origin` / `cookie` / `sec-fetch-site` 删掉、换上一枚宿主自己的 cookie，
+*  `Referer` 保留。判据按 `protocol` + `host` 比，**不能比 `URL.origin`**（`dsh-app:` 不是 WHATWG
+*  special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`）。 */
+const DESKTOP_APP_SCHEME = "dsh-app:";
+const DESKTOP_APP_HOST = "app";
+/** 回环 socket 的三种写法（IPv4 / IPv6 / IPv4-mapped IPv6）。 */
+const LOOPBACK_SOCKETS = [
+	"127.0.0.1",
+	"::1",
+	"::ffff:127.0.0.1"
+];
+function isDesktopShellUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === DESKTOP_APP_SCHEME && url.host === DESKTOP_APP_HOST;
+	} catch {
+		return false;
+	}
+}
+/** 裸 authority（`host` / `host:port`）按给定 scheme 解析；解析不了回 `undefined`。 */
+function parseAuthority(authority, scheme = "http:") {
+	try {
+		return new URL(`${scheme}//${authority}`);
+	} catch {
+		return;
+	}
+}
+/** 与宿主 `isLoopbackHostname` 同口径：`localhost`、`[::1]`、任意 127/8。 */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Host 是不是本部署的 bind 字面量：忽略端口与 `%zone`（zone 是接口选择器，不是地址文本）。 */
+function isBindAddress(hostUrl, bindHost) {
+	if (bindHost === void 0) return false;
+	const zoneAt = bindHost.indexOf("%");
+	const address = zoneAt === -1 ? bindHost : bindHost.slice(0, zoneAt);
+	const bindUrl = parseAuthority(address.includes(":") ? `[${address}]` : address);
+	return bindUrl !== void 0 && bindUrl.hostname === hostUrl.hostname;
+}
+/** 携带 authority 的头（Origin / Referer）是否与 Host 同 authority：按这个头自己的 scheme 归一
+*  默认端口（`http://x:80` 与 Host `x` 是同一个 authority）。 */
+function isSameAuthority(value, hostHeader) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return false;
+	}
+	const scheme = url.protocol === "https:" ? "https:" : url.protocol === "http:" ? "http:" : void 0;
+	if (scheme === void 0) return false;
+	const hostUrl = parseAuthority(hostHeader, scheme);
+	return hostUrl !== void 0 && url.host === hostUrl.host;
+}
+/** 头栅栏：`sec-fetch-site` / Origin / Referer 三条，任何客户端都要过。 */
+function passesHeaderFence(headers, host) {
+	if (headers["sec-fetch-site"] === "cross-site") return false;
+	const origin = headers.origin;
+	if (origin !== void 0 && !isDesktopShellUrl(origin) && !isSameAuthority(origin, host)) return false;
+	const referer = headers.referer;
+	if (referer !== void 0 && !isDesktopShellUrl(referer) && !isSameAuthority(referer, host)) return false;
+	return true;
+}
+/**
+* 这条请求归不归本插件办。`untrusted` = 归属不对（跨源 / 重绑 / 头不成形）；`unauthenticated` =
+* 归属对但远程客户端没带宿主身份（原文会提示用 `dsh web` 打印的 URL 打开）。
+*
+* 远程支的两个失败裁决由端口翻译宿主的区分（401 = 缺身份、403 = 归属不对）。身份层缺席（端口报
+* `absent`）一律按归属不对处理：那时没有可换的身份，不能让原文提示用户去补一个不存在的东西。
+*/
+function judgeRequest(req, facts) {
+	const host = req.headers.host;
+	if (host === void 0 || !passesHeaderFence(req.headers, host)) return "untrusted";
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === void 0) return "untrusted";
+	if ((isLoopbackHostname(hostUrl.hostname) || isBindAddress(hostUrl, facts.bindHost)) && LOOPBACK_SOCKETS.includes(req.socket.remoteAddress ?? "")) return "allowed";
+	const verdict = facts.connection.verdictFor(req);
+	if (verdict.kind === "allowed") return "allowed";
+	return verdict.kind === "unauthenticated" ? "unauthenticated" : "untrusted";
+}
+//#endregion
 //#region src/ports/agent-handles.ts
 const CAPTURED_AGENT_HANDLES = Symbol.for("dsh-session-delete.captured-agent-handles");
 /** 在 `ctx.agents` 上包一层 `resume` / `create`，把返回的 agent handle 的 dispose 按会话 id 记下。
@@ -348,16 +440,11 @@ async function filterChildrenOf(sessionQuery, values) {
 	}]);
 }
 /**
-* 从若干根出发**逐层往下**把盘上的后代问出来，交回 `父（bare）→ 孩子` 的索引。
-*
-* 为什么一次问一层而不是官方的 `traceSession`：那条在父已经进回收站时认不出目标
-* （`SESSION_QUERY_SESSION_NOT_FOUND`），而我们要的那批正是"父已经不在宿主列表里之后还剩在盘上的"。
-* `kind:'parent'` 是唯一能按 `header.parentSession` 反着问的一支。
-*
-* 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
-* （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
-* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostCorpusPort.subagentMembersOf} 那条），
-* 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
+* 从若干根逐层向下问出后代，交回 `父（bare）→ 孩子` 的索引。
+* 用 `kind:'parent'` 而不是 traceSession：父进回收站后 traceSession 认不出目标（宿主失败码
+* `SESSION_QUERY_SESSION_NOT_FOUND`），而这里要的正是父不在宿主列表之后仍留在盘上的那批。
+* 出处：asar `dsh-session-query/lib/index.js` 的 `filterSessions`。一层一次宿主调用，问空即停；
+* `seen` 防环；没有 `header.id` 的记录整条跳过（无法作为身份继续下问）。
 */
 async function descendantsByParent(sessionQuery, roots) {
 	const children = /* @__PURE__ */ new Map();
@@ -425,29 +512,14 @@ async function membersFor(sessionQuery, parentIds) {
 	for (const id of wanted) out[id] = subtreeOf(children, bareSessionId(id));
 	return out;
 }
-/** 无 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");`）。 */
 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` 与回收站对账重建共用这一份；
+*  宿主换代先复核算法。 */
 function projectKey(cwd) {
 	let readable = "";
 	let separatorRun = false;
@@ -474,17 +546,10 @@ function projectionCacheOf(ctx) {
 	if (typeof cache.cachedSnapshot !== "function" || typeof cache.cachedPredecessorTitle !== "function") return void 0;
 	return cache;
 }
-/**
-* 「账本里没有这个会话」的判别串——宿主 `readSessionHeader(id)` 对未知会话抛的是**裸 `Error`**
-* （没有类型、没有码），只认这一句。asar `dsh-workspace/lib/types/index.js` 原文（逐字）：
-* `throw new Error(\`cannot validate session '${id}': session persistence holds no such session\`)`。
-*
-* 为什么按消息判而不是全吞：同一个方法里 `listStoredHeaders()` / `indexHeaders()` 会抛**真存储故障**
-* （读盘失败、账本不一致…），那是 `io` 该走的路，绝不能被当成「无此会话」。
-* 同文件另一处近似句是有类型的那条（`cannot ${verb} session '…': live sessions and session persistence
-* hold no such session`，`WorkspaceUnknownSessionError`）——`holds` 与 `hold`、有无 `live sessions and`
-* 都不相同，所以这条串不会误伤它，`toRemoteFailure` 的 cause 链映射仍按 `name` 走。
-*/
+/** 宿主 `readSessionHeader` 对未知会话抛的是裸 `Error`，只认这句；真存储故障照抛，不能折成未命中。
+*  出处：asar `dsh-workspace/lib/types/index.js` 的
+*  `cannot validate session '${id}': session persistence holds no such session`。
+*  同文件有类型的近似句是 `WorkspaceUnknownSessionError`（`hold` 无 `s`），不会误伤。 */
 const NO_SUCH_SESSION = "session persistence holds no such session";
 /** 只认上面那一句；其余（含非 Error 抛出物）一律**不算未命中**。 */
 function isUnknownSession(error) {
@@ -525,13 +590,8 @@ const WORKSPACE_MISSING_MESSAGE = "workspace not found";
 function isWorkspaceMissingError(error) {
 	return error instanceof Error && error.message.startsWith(WORKSPACE_MISSING_MESSAGE);
 }
-/**
-* 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
-*
-* 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
-* 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
-* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（src/remote/map-error.ts 的两行映射）。
-*/
+/** 宿主服务的真实绑定；出错原样抛，由 `toRemoteFailure` 按 name 映射。
+*  各方法调用的服务与方法见上方成员注释；错误映射表住 `src/remote/map-error.ts`。 */
 function createHostPort(ctx) {
 	const host = ctx;
 	const registry = host.workspaceRegistry;
@@ -547,14 +607,9 @@ function createHostPort(ctx) {
 			return registry.get(workspaceId) !== void 0;
 		},
 		/**
-		* 原生 cwd → 宿主项目目录名（`projectKey`）；没有 cwd 时按宿主约定落到 `_no-cwd`。
-		*
-		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
-		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
-		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ src/shared/wire.ts 的 `not-found`
-		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
-		*
-		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
+		* cwd → 宿主项目目录名；没有 cwd 落到 `_no-cwd`。
+		* 账本里没有这个会话回 `undefined`（未命中，不是故障）；真存储故障照抛。
+		* 未命中由 `delete-session.ts` 折成 `not-found`，真故障留 `io`——两者不能混。
 		*/
 		async projectDirOf(sessionId) {
 			let header;
@@ -566,12 +621,7 @@ function createHostPort(ctx) {
 			}
 			return header.cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(header.cwd);
 		},
-		/**
-		* 标题：走官方**投影缓存**读面（`title` 投影单元的 `wire.view` 值就是标题文本本身：
-		* 单元定义原文 `{ key: "title", stateVersion: 1, wire: { view: (state) => state } }`，
-		* 所以 `values.title` 是 `string | null`）。
-		* 契约：**尽力取、取不到返回空串、绝不因此让删除失败** ⇒ 这里吞掉一切异常。
-		*/
+		/** 标题走宿主投影缓存；尽力取，取不到返回空串，绝不因此让删除失败。 */
 		async titleOf(sessionId) {
 			try {
 				const header = await registry.readSessionHeader(sessionId);
@@ -582,12 +632,8 @@ function createHostPort(ctx) {
 				return "";
 			}
 		},
-		/**
-		* 活跃判据 = 宿主官方那一条（本文件）：`workspace/session-activity` waterfall 问一次，
-		* **空数组 = 无活动**；与宿主自己的 `archiveSession` 准入同源，不自创第二套。
-		* asar 原文：`const activity = await this.ctx.waterfall('workspace/session-activity', { sessionId }, () => Promise.resolve([]));
-		* if (activity.length > 0) throw new WorkspaceActiveSessionError(sessionId, activity);`
-		*/
+		/** 活跃判据走宿主 `workspace/session-activity` waterfall：空数组 = 无活动；
+		*  与宿主 archiveSession 的准入同源。 */
 		async isLive(sessionId) {
 			return (await host.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]))).length > 0;
 		},
@@ -596,25 +642,15 @@ function createHostPort(ctx) {
 			return registry.archivedSessionIds.includes(sessionId);
 		},
 		/**
-		* 从 `ctx.sessions`（live store）里摘掉会话，并把它的 **agent 一起关掉**（有捕获 handle 时）。
-		*
-		* **为什么需要**：会话列表读面是并集——`sessionQuery.listSessions()` = 磁盘上的持久化 ∪ `ctx.sessions` 里的活体
-		* （见本文件的「通告」一段）。搬走文件只清掉一侧；本机运行期打开过的会话是活体，列表照样把它交出来。
-		*
-		* **agent 也必须关**：`ctx.agents` 没有 per-agent dispose；宿主 `AgentService.resume` / `create` 返回的
-		* `AgentHandle` 带宿主自己的外层 teardown（关写句柄、摘 agent/session），但 `SessionController` 只取
-		* `.agent`、把 handle 丢掉。agent handle 捕获（`src/ports/agent-handles.ts`）在 `ctx.agents` 上包一层，
-		* 按会话 id 留住 handle；这里先 `entry.detach()`（摘 session、发 `session/disposed`），再
-		* `await agentHandles.dispose(sessionId)`。
-		* **只摘 session 的后果**：恢复后 `SessionController.resolve` 会先命中那具旧 agent，prompt 被收下、
-		* 日志不再增长，直到宿主重启（2026-10-21 真机复现）。
+		* 从 `ctx.sessions` 摘掉会话，并关闭捕获到的 agent handle。
 		*
-		* **捕获不到 handle 的 agent**（插件激活前已启动的配置 agent，或 `ctx.agents` 形状变化）只能摘 session；
-		* 这是已知的残留限制，不拿归档当兜底（ADR-0008）。
+		* 会话列表 = 磁盘持久化 ∪ 内存活体，搬走文件只清掉一侧；宿主 `SessionController` 会丢掉
+		* `AgentHandle`，所以 `agent-handles.ts` 按会话 id 留住 handle，这里先 detach 再 dispose。
+		* 捕获不到 handle（插件激活前已启动，或 `ctx.agents` 形状变化）时只能摘 session，这是已知限制，
+		* 不拿归档兜底（ADR-0008）。
 		*
-		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 或 dispose 抛 ⇒ `unknown`（**不通告**，
-		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
-		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
+		* 三态：读不到 store / 形状不符 / detach 或 dispose 抛 ⇒ `unknown`（不通告）；
+		* 内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。任何一步都不抛。
 		*/
 		async evictLive(sessionId) {
 			try {
@@ -635,19 +671,9 @@ function createHostPort(ctx) {
 			}
 		},
 		/**
-		* 通告客户端"这个会话没了"。
-		*
-		* **为什么需要**：客户端那一行只由两条路更新——重连时的整表重列（`handleConnected` → `refreshList`），
-		* 或宿主转发的 `api-session/*` 事件。删除一个**冷**会话时宿主不会发任何事件（`session/disposed` 只在摘掉
-		* 活体时才有），所以那一行会一直挂到下次重连为止（真机实测就是这个形状）。
-		*
-		* **为什么这样发是对的**：`api-session/removed` 是宿主**自己声明并转发**的事件
-		* （asar `dsh-api-remotes/lib/remote-events.js` 的 `API_REMOTE_FORWARDED_EVENTS` 里
-		* `{ event: "api-session/removed", mode: "emit" }`；转发器就是 `ctx.on(event, …)` 的普通监听者）；
-		* 我们不带 carrier 地 emit ⇒ 全量派发到它（见 {@link HostCtxLike.emit}）⇒ 客户端
-		* `ctx.remote.$on("api-session/removed", …)` 收到后 `recordMutation({kind:'remove'})` + `handleRemoved()`。
-		* **只在"宿主列表确实已经不含它"时调用**（调用方按 {@link EvictionOutcome} 判）：这条通告在语义上是**如实**
-		* 的，不是障眼法。
+		* 通告客户端这个会话没了：发宿主自己转发的 `api-session/removed`，客户端当场删行。
+		* 冷会话没有 `session/disposed`，不发这条就只能等重连。
+		* 只在宿主列表确实已不含它时调用（调用方按 {@link EvictionOutcome} 判）；不发假通告。
 		*/
 		async announceRemoved(sessionId) {
 			try {
@@ -655,41 +681,21 @@ function createHostPort(ctx) {
 			} catch {}
 		},
 		/**
-		* 通告客户端"这个会话回来了"。
-		*
-		* 摘要**取自宿主自己的会话列表**（`ctx.sessionController.list()`），不自己造一行：客户端 `handleSessionAdded`
-		* 要的是宿主 `summaryFor` 那套形状（sessionId / updatedAt / blank / projections…），照抄宿主的那一份最可靠。
-		* 取不到（控制器缺席 / 列表里没有它 / 抛错）就**一条都不发**。
-		*
-		* **这一条单条路是删除组回滚用的**：成员已经收过 `api-session/removed`，退回 `sessions/` 之后要补一条
-		* "added"，否则客户端那一行要等到重连才回来。正常恢复走 {@link announceRestoredBatch} + 一次预取——
-		* 100 条的批量用单条路就是 100 遍全表扫，那正是 2026-10-17 那次"恢复很慢"的头号来源。
+		* 通告这组会话回来了：拉一次宿主会话表，按 id 逐条发 `api-session/added`。
+		* 摘要直接用宿主 `sessionController.list()` 的形状；取不到就不发。
+		* 批量只预取一次，避免按条全表扫。
 		*/
-		async announceRestored(sessionId) {
-			const summary = (await this.restoredSummariesOf()).find((item) => item.sessionId === sessionId)?.summary;
-			if (summary === void 0) return;
-			try {
-				host.emit("api-session/added", JSON.parse(JSON.stringify(summary)));
-			} catch {}
-		},
-		/** 整批预取一次会话表（`[{ sessionId, summary }]`）：通告的路径与单条一致，**拉表从每条一次抬成整批一次**。 */
-		async restoredSummariesOf() {
-			const out = [];
+		async announceRestored(sessionIds) {
+			if (sessionIds.length === 0) return;
+			const summaries = [];
 			for (const item of await controllerItems(host)) {
 				const sessionId = item?.sessionId;
-				if (typeof sessionId === "string") out.push({
+				if (typeof sessionId === "string") summaries.push({
 					sessionId,
 					summary: item
 				});
 			}
-			return out;
-		},
-		/** 一组会话的通告（2026-10-17 批量重构）：`known` 给了就**一次都不拉表**，只按它筛。
-		*  与 {@link announceRestored} 同一判据、同一事件、同一载荷形状，只是取数由整批共享。 */
-		async announceRestoredBatch(ids, known) {
-			if (ids.length === 0) return;
-			const summaries = known ?? await this.restoredSummariesOf();
-			for (const id of ids) {
+			for (const id of sessionIds) {
 				const summary = summaries.find((item) => item.sessionId === id)?.summary;
 				if (summary === void 0) continue;
 				try {
@@ -744,26 +750,9 @@ function createHostPort(ctx) {
 		},
 		/**
 		* 官方 `sessionQuery.filterSessions([{kind:'parent', values}])`，不自扫 `~/.dsh/sessions`。
-		*
-		* 数的是**传递闭包**（孩子与孙代都算），不是"直接孩子"（issue #1）：宿主客户端对所有
-		* `origin:"subagent"` 一律藏行 ⇒ 深度 ≥2 上"删了父还剩多少看不见"原样存在，只数一层就是把那件事
-		* 说成没有。问法见 {@link descendantsByParent}。
-		*
-		* 归堆必须**两边都去前缀**再比：本机实测父会话自己的 header id 带 `session-` 前缀
-		* （`session-ac07f2bb-…`）、它的子会话写的 `parentSession` 也带，但 v3 那一代的 id 不带 ⇒
-		* 同一个父有两种写法。所以问的时候把一个 id 的两种形状都塞进 `values`，回来按去前缀后的形状归堆，
-		* 最后按**调用方给的那个写法**把键交回去（调用方拿 `entry.sessionId` 直接查得到）。
-		*
-		* 删除要一起带走**整个组**，先得把他们点出来：身份取宿主自己记录里的 `header.id`，项目目录由
-		* `header.cwd` 走同一个 `projectKey`（与 {@link HostPort.projectDirOf} 同一根算法，不另起一套）。
-		* 交回的是**全部后代**——孙代跟着父一起进回收站（issue #1），顺序是逐层往下问出来的（近的先）。
-		* `header.id` 缺席的后代直接跳过——不拿目录名冒充身份（冒充了会把一个来路不明的目录搬进回收站）。
-		*
-		* **缺席显式化**（见 {@link CorpusRead}）：`sessionQuery` 没挂，或它的 `filterSessions` 缺席 / 不是函数
-		* ⇒ `{ available: false }`，不拿空表冒充"盘上没有后代"——写侧据此决定降级还是响亮失败，不再靠"空表"
-		* 兼表两种意思。
-		* **先判服务、再判空入参**：语料本来就看不见时，"没有后代"这句话不该被说出口（哪怕入参是空的）；
-		* 服务在场时空入参由 `membersFor` 的短路保证零宿主调用。
+		* 数传递闭包（孩子与孙代），不是直接孩子；`session-` 前缀两边都去掉再比，
+		* 按调用方给的写法回键。`sessionQuery` 缺席或方法缺失 ⇒ `{available:false}`，
+		* 不拿空表冒充“没有后代”；服务在场时空入参零宿主调用。
 		*/
 		async subagentMembersOf(parentIds) {
 			const sessionQuery = host.get("sessionQuery");
@@ -820,14 +809,59 @@ function groupOf(rows, id) {
 	return kidsOf(rows, id);
 }
 /**
-* 「这条是被**同批前一条**带走的，还是整批开始前就没有？」
+* 「这条是被**同批前一条**带走的，还是整批开始前就没有，还是仍在？」
 *
-* 幂等语义只属于前者：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
+* 幂等语义只属于 `carried`：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
 * `trash-empty`，不能被"已被带走"这句话掩盖成成功。**所以判据是快照的原始形状，不是当前形状**：
-* 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+* 原始快照里认得出（它自己、或指向它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+*/
+function claimOf(original, current, id) {
+	if (groupOf(original, id).length === 0) return { verdict: "absent" };
+	const group = groupOf(current, id);
+	return group.length === 0 ? { verdict: "carried" } : {
+		verdict: "fresh",
+		group
+	};
+}
+//#endregion
+//#region src/verbs/batch-carried.ts
+/**
+* **同批已带走集**（「已被同批前一条带走」的 id）的唯一实现（ADR-0002 的内部实现）。
+*
+* 两种 id 域各一个 adapter：
+* - entry 适配：restore / purge 的条目 id，`claim` 是三态（fresh / carried / absent），组语义仍读
+*   `trash/groups.ts`；
+* - session 适配：delete 的会话 id，`claim` 只有 fresh / carried，集合由动词结果长出。
+*
+* entry 适配的三态判据读 `groups.claimOf`；session 适配没有原始清册视图，只记 `take` 过的会话 id。
+* 当前只读视图（`rows`）只挂在 entry 域上：只有 purge 要它——盘上后代要按清册里还在的 id 排除。
 */
-function takenByEarlierInBatch(original, current, id) {
-	return groupOf(original, id).length > 0 && groupOf(current, id).length === 0;
+/** 恢复 / 彻底删除：原始快照认得、当前视图已经空了 ⇒ 同批前一条带走的。 */
+function createEntryCarried(original) {
+	let current = [...original];
+	return {
+		claim(id) {
+			return claimOf(original, current, id);
+		},
+		take(id) {
+			const gone = new Set(groupOf(current, id).map((row) => row.id));
+			if (gone.size === 0) return;
+			current = current.filter((row) => !gone.has(row.id));
+		},
+		rows: () => current
+	};
+}
+/** 删除：会话 id 域；`take` 只收这次真的搬走的成员（父 + 盘上的孩子）。 */
+function createSessionCarried() {
+	const carried = /* @__PURE__ */ new Set();
+	return {
+		claim(id) {
+			return carried.has(bareSessionId(id)) ? { verdict: "carried" } : { verdict: "fresh" };
+		},
+		take(id) {
+			carried.add(bareSessionId(id));
+		}
+	};
 }
 //#endregion
 //#region src/trash/entry.ts
@@ -890,412 +924,174 @@ function trashDirOf(entryId, home) {
 	return `${home}/${TRASH_DIR_NAME}/${entryId}`;
 }
 //#endregion
-//#region src/log/zstd-frames.ts
-const MAGIC = [
-	40,
-	181,
-	47,
-	253
-];
-/** magic(4) + Frame_Header_Descriptor(1) 之后第一个字节的偏移。 */
-const AFTER_DESCRIPTOR = 5;
-const BLOCK_HEADER_BYTES = 3;
-const BLOCK_LAST = 1;
-const BLOCK_TYPE_SHIFT = 1;
-const BLOCK_SIZE_SHIFT = 3;
-const BLOCK_SIZE_MASK = 2097151;
-const BLOCK_RAW = 0;
-const BLOCK_RLE = 1;
-const BLOCK_COMRESSED = 2;
-/** 规范（RFC 8878 表 4）里 3 是 **Reserved**，不是"未压缩块"：见到就抛，别照 Raw 吞块体。 */
-const BLOCK_RESERVED = 3;
-/** descriptor 各字段的取值 → 字段字节数（zstd 帧头的两张尺寸表）。 */
-const DID_SIZES = [
-	0,
-	1,
-	2,
-	4
-];
-const FCS_SIZES_SINGLE = [
-	1,
-	2,
-	4,
-	8
-];
-const FCS_SIZES_MULTI = [
-	0,
-	2,
-	4,
-	8
-];
-/** 实测的帧尾长度（校验和位置；bit5 没置位也照样带，见文件头注）。 */
-const FRAME_TAIL_BYTES = 4;
-function isMagicAt(raw, at) {
-	return MAGIC.every((byte, i) => raw[at + i] === byte);
-}
-function readUint24LE(raw, at) {
-	return raw[at] | raw[at + 1] << 8 | raw[at + 2] << 16;
-}
-/** 块体之后有没有那 4 字节尾巴：只有"跳过它之后仍是帧头或到 EOF"才认。 */
-function withFrameTail(raw, at) {
-	const afterTail = at + FRAME_TAIL_BYTES;
-	if (afterTail <= raw.length && (afterTail === raw.length || isMagicAt(raw, afterTail))) return afterTail;
-	return at;
-}
+//#region src/verbs/member-journal.ts
 /**
-* 把 `raw` 切成帧区间。
-* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
-*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
+* 一次成员移动 = 一串自带反向动作的步骤（ADR-0002）。
+*
+* 这里独占四件事，动词只声明“这次要做哪几步、每步怎么退”：
+* - 相反顺序退化；
+* - 一步失败时把已做成的那些退回去；
+* - 失败收集：回滚不干净时不让原错误独走（details.rollbackFailures）；
+* - 非原子步骤：undoOnFailure 让“这一步自己失败”也跑反向动作。
+*
+* 边界：只服务成员在 sessions/ 与 session-trash/ 之间搬；不做通用撤销框架。
 */
-function frameRanges(raw) {
-	const ranges = [];
-	let at = 0;
-	while (at < raw.length) {
-		if (!isMagicAt(raw, at)) throw new Error(`zstd 帧头缺席：偏移 ${at} 处不是 magic（前面第 ${ranges.length} 帧的边界算歪了？）`);
-		const descriptor = raw[at + 4];
-		if (descriptor === void 0) throw new Error(`zstd 帧头不完整：偏移 ${at} 之后不足 ${AFTER_DESCRIPTOR} 字节`);
-		const fcsFlag = descriptor & 3;
-		const singleSegment = descriptor >> 2 & 1;
-		const didFlag = descriptor >> 6 & 3;
-		let cursor = at + AFTER_DESCRIPTOR;
-		if (!singleSegment) cursor += 1;
-		cursor += DID_SIZES[didFlag];
-		cursor += (singleSegment ? FCS_SIZES_SINGLE : FCS_SIZES_MULTI)[fcsFlag];
-		for (;;) {
-			const blockHeader = readUint24LE(raw, cursor);
-			cursor += BLOCK_HEADER_BYTES;
-			if (cursor > raw.length) throw new Error(`zstd 块头越界：帧起于 ${at}，读到偏移 ${cursor}（文件长 ${raw.length}）`);
-			const blockType = blockHeader >> BLOCK_TYPE_SHIFT & 3;
-			const blockSize = blockHeader >> BLOCK_SIZE_SHIFT & BLOCK_SIZE_MASK;
-			if (blockType === BLOCK_RESERVED) throw new Error(`zstd 保留块类型：帧起于 ${at}，偏移 ${cursor - BLOCK_HEADER_BYTES} 的块头 type=3（规范 Reserved，对面解不开）`);
-			if (blockType === BLOCK_RAW || blockType === BLOCK_COMRESSED) cursor += blockSize;
-			else if (blockType === BLOCK_RLE) cursor += 1;
-			if (blockHeader & BLOCK_LAST) break;
+/** 已经把某个前缀做成了的 journal——`undo()` 就退那一个前缀。 */
+function createJournal(steps) {
+	const done = [];
+	const undoAll = async (alsoFailing) => {
+		const failures = [];
+		const restored = /* @__PURE__ */ new Map();
+		const runUndo = async (step) => {
+			if (step.undo === void 0) return;
+			const result = await step.undo();
+			failures.push(...result.failures);
+			restored.set(step.key, result.restored);
+		};
+		if (alsoFailing?.undo !== void 0) await runUndo(alsoFailing);
+		for (const step of [...done].reverse()) await runUndo(step);
+		return {
+			failures,
+			restored: (key) => restored.get(key) ?? false
+		};
+	};
+	return {
+		async run() {
+			for (const step of steps) {
+				try {
+					await step.run();
+				} catch (error) {
+					const undo = await undoAll(step.undoOnFailure === true ? step : void 0);
+					const base = journalFailure(step, error);
+					throw undo.failures.length > 0 ? withRollbackFailures(base, undo.failures) : base;
+				}
+				done.push(step);
+			}
+		},
+		undo() {
+			return undoAll();
 		}
-		cursor = withFrameTail(raw, cursor);
-		if (cursor !== raw.length && !isMagicAt(raw, cursor)) throw new Error(`zstd 帧边界算歪了：帧起于 ${at}，算到 ${cursor}，那里既不是下一帧帧头也不是 EOF`);
-		ranges.push({
-			start: at,
-			end: cursor
-		});
-		at = cursor;
+	};
+}
+/** 跑一步反向动作并把它自己的失败收成一条原因（不抛：这些失败由调用方汇总成 `rollbackFailures`）。 */
+async function attempt(label, run) {
+	try {
+		await run();
+		return [];
+	} catch (error) {
+		return [rollbackReason(label, error)];
 	}
-	return ranges;
 }
-//#endregion
-//#region src/log/session-log.ts
+/** 一步反向动作的完整结果：主写是否回到原样 + 失败串。附属写失败只进 `failures`，不推翻 `restored`。 */
+async function stepUndo(label, run) {
+	const failures = await attempt(label, run);
+	return {
+		restored: failures.length === 0,
+		failures
+	};
+}
 /**
-* 会话日志（`session.vN.jsonl.zstd`）的**逐帧读法**：帧边界交给 `zstd-frames.ts`，这一层只做
-* 「帧 → 明文 → 一行一条 JSON」的解码，并把每条记录原样交给回调。
-*
-* **策略不在这里**（哪些 `type` 算正文、截断到多少字、算不算失败）——那是 `src/trash/detail.ts` 的事。
-* 这一层只懂编解码，所以它能被单独验穿。
-*
-* 两条实测决定的口径：
-* ① **必须逐帧**：Node 的 `zstdDecompressSync` 与 `createZstdDecompress()` 都只给第一帧（见
-*    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
-*    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
-* ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
-*    本机实测**没有一帧切在行中间**（连最后一帧都整行收尾；绝对帧数随盘上会话数摆动，那份读数
-*    不在这里钉，来历留在 git 历史），
-*    所以旧口径当时并不丢东西；但"逐帧 `split('\n')`"一旦遇上切行就是**静默少一条记录**（半个头
-*    加半个身，两半都解不开 JSON），而少掉的那条正是页面上要跟账的正文。带上余量之后这条不变量
-*    不必再成立，顺带把**跨帧的多字节字符**也解对了——拼接在字节层做，`toString('utf8')` 只看整行。
-*    真被切断的尾巴（写一半）仍然**跳过并计数**：绝不因为一行就抛整个读数，前面几百条是真的。
+* **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
+* `details.rollbackFailures`，绝不让原错误独走。那些失败句子的合并与措辞住 `src/verbs/errors.ts`；
+* 删除与恢复两个按组走的动词共用这一处。
 */
-const NEWLINE = 10;
+async function rollbackJournals(journals, error) {
+	const failures = [];
+	for (const journal of [...journals].reverse()) {
+		const undo = await journal.undo();
+		failures.push(...undo.failures);
+	}
+	if (failures.length > 0) throw withRollbackFailures(error, failures);
+	throw error;
+}
 /**
-* 宿主给每一代日志的词法（逐字取自 `@deepseek-ai/dsh-session-format@0.2.0-rc.2` 的
-* `CANONICAL_LOG_FILENAME`，剥掉压缩后缀那段由我们自己在正则里补上 `.zstd`）：
-* 裸名 `session.jsonl` 是**第 0 代**，往后是 `session.vN`；`.v0`、前导零、大写、临时名都不是规范名。
+* 这一步的失败形状：已经是动词码（`verbError` 的输出）就原样带，否则折成 `sessiondelete/io`。
+* 原文用 `String(error)` 而不是 `.message`——那 22 处既有措辞就是这么拼的（`Error: boom` 也在里面），
+* 换一种拼法会让上屏原文跟着变。
 */
-const CANONICAL_ZSTD_LOG = /^session(?:\.v([1-9][0-9]*))?\.jsonl\.zstd$/u;
+function journalFailure(step, error) {
+	if (isSessionDeleteCodeError(error)) return error;
+	return verbError("io", `${step.label}：${String(error)}`, error);
+}
+//#endregion
+//#region src/verbs/live-admission.ts
+/** 逐个问，任一在跑就抛 `live`。名单的挑选（哪些成员算这一组）归调用方，这里只按传入顺序问完。 */
+async function assertNoLive(host, sessionIds) {
+	for (const sessionId of sessionIds) if (await host.isLive(sessionId)) throw verbError("live", `会话正在运行：${sessionId}`);
+}
+//#endregion
+//#region src/verbs/member-presence.ts
+/** 本仓的在场能力实现：端口形状住 `src/ports/presence-port.ts`，这里只做三态与真值表。
+*  `announceRestored` 直接交宿主那一手：能力面与宿主面同名同签名，再包一层只会多一个转调。 */
+function createMemberPresence(host) {
+	return {
+		async memberGone(sessionId, facts = { backInTrash: true }) {
+			if (!facts.backInTrash) return;
+			if (await host.evictLive(sessionId) !== "unknown") await host.announceRemoved(sessionId);
+		},
+		async memberBack(sessionId, facts) {
+			if (!facts.diskBack || !facts.workspaceBack) return;
+			await host.announceRestored([sessionId]);
+		},
+		announceRestored: host.announceRestored
+	};
+}
 /**
-* 同一个会话目录里**可以并存多代日志**（宿主换代时把老代留在原地当历史语料，本机实测 7 个目录如此），
-* 而新代是老代的**迁移后超集**（实测：`firstTs` 与开头那条提问完全相同、记录更多、末尾更晚）
-* ⇒ 要读的是版本号最大的那一代，读旧代 = 读到一份截了尾巴的快照；把几代拼起来 = 重复计数。
+* 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场，undo 之后按事实归位或离场。
 *
-* 明文（无 `.zstd`）不在此列：本插件的读法逐帧解 zstd，明文得走另一条解码路。
+* 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表归 `createMemberPresence`；
+* 这里只把事实原样递过去。
 */
-function pickSessionLog(names) {
-	let best;
-	let bestVersion = -1;
-	for (const name of names) {
-		const match = CANONICAL_ZSTD_LOG.exec(name);
-		if (match === null) continue;
-		const version = match[1] === void 0 ? 0 : Number(match[1]);
-		if (version > bestVersion) {
-			bestVersion = version;
-			best = name;
-		}
-	}
-	return best;
-}
-/**
-* 逐帧走一遍日志，每条记录交给回调。
-*
-* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
-* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
-*/
-function walkSessionLog(raw, onRecord) {
-	const stats = {
-		frames: 0,
-		records: 0,
-		unparsedLines: 0,
-		truncatedTailBytes: 0
-	};
-	let stopped = false;
-	const feed = (line) => {
-		if (line === "") return;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			stats.unparsedLines += 1;
+function withPresenceTail(presence, journal, tail) {
+	const announce = async (undo) => {
+		const fact = tail.onUndone(undo);
+		if (fact.kind === "leave") {
+			await presence.memberGone(tail.sessionId, { backInTrash: fact.backInTrash });
 			return;
 		}
-		stats.records += 1;
-		if (onRecord(parsed !== null && typeof parsed === "object" ? parsed : {}) === false) stopped = true;
+		await presence.memberBack(tail.sessionId, {
+			diskBack: fact.diskBack,
+			workspaceBack: fact.workspaceBack
+		});
 	};
-	/** 上一帧没闭合的那一行。**存字节不存字符**：切在多字节字符中间的帧要拼回完整才解得对。 */
-	let carry = Buffer.alloc(0);
-	for (const { start, end } of frameRanges(raw)) {
-		if (stopped) break;
-		stats.frames += 1;
-		let plain;
-		try {
-			plain = zlib.zstdDecompressSync(raw.subarray(start, end));
-		} catch (error) {
-			throw new Error(`回收站日志第 ${stats.frames} 帧解压失败：${String(error)}`);
-		}
-		const merged = carry.length === 0 ? plain : Buffer.concat([carry, plain]);
-		const cut = merged.lastIndexOf(NEWLINE);
-		if (cut === -1) {
-			carry = merged;
-			continue;
-		}
-		carry = merged.subarray(cut + 1);
-		for (const line of merged.subarray(0, cut).toString("utf8").split("\n")) {
-			feed(line);
-			if (stopped) break;
-		}
-	}
-	stats.truncatedTailBytes = carry.length;
-	if (carry.length > 0 && !stopped) feed(carry.toString("utf8"));
-	return stats;
-}
-/**
-* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
-* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
-* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
-* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
-*/
-function readSessionHeader(raw) {
-	let header;
-	walkSessionLog(raw, (record) => {
-		if (record.type !== "session") return;
-		header = record;
-		return false;
-	});
-	return header;
-}
-//#endregion
-//#region src/trash/reconcile.ts
-/**
-* 回收站清单的**对账**：以 `session-trash/` 里的条目目录为准，把清单修回一致（CONTEXT.md 的「对账」条）。
-*
-* 手工动回收站**只需要动那一个目录**——多出来的目录在这里被重建出行、目录没了的行在这里被摘掉；
-* `~/.dsh/storages/` 那份清单从此是**内部索引**，不用手碰。
-*
-* 五条口径（都不是口味）：
-* ① **每次读清单都对账**（`GET /list` 的正文就是"对账 + 读"）：挂载、刷新、别处动过后的自动重读、
-*    客户端启动探测全走这条 ⇒ "改完目录不用再做任何事，下一次读就对了"。代价 = 每次读多一次目录枚举
-*    （本机 124 条，毫秒级）；**零漂移零写入**（快路直接返回原清单）。
-* ② **回收站根不在 ⇒ 整套跳过、一个字节都不动**：那不是"回收站空了"，是"这块地不在原处"
-*    （人为搬走、盘没挂上）——照常对账会把全部行的元数据一次判没。
-* ③ **重建行只写"文件里真有的事实"**：`id` = 目录名、`sessionId`/`cwd` 读日志 header、
-*    `projectDir` 由 `cwd` 经宿主同名算法 `projectKey` 反推、`deletedAt` 从目录名的时间戳解、
-*    `sizeBytes` 现场量。**文件侧没有副本的三件**按缺省落：`workspaceId: ''`（恢复时跳过挂账本，
-*    落在「未分组」）、`wasArchived: false`（文件侧没有归档事实；旧条目恢复走迁移支）、`title: ''`（详情有日志标题兜底）
-*    ——这是重建的固有代价，不是可以"再读读看"的东西。
-* ④ **认不出 / 读不出的目录：不动、不列**（名字不像条目、目录里没有日志、header 读不出、尺寸量不出，
-*    各跳过各的）。它是"外人放进来的东西"，不是用户动作失败：跳过即静默，绝不为它删目录或抛掉整次读数。
-* ⑤ **幂等**：再跑一遍零写入；崩在任何一步，下一次读清单接着把它修完。
-*
-* 与三个写动词的**串行化不在这里**（那是传输层的事，见 `src/api/dispatch.ts` 的到达序链）：
-* 对账与删除/恢复/彻底删除都是"读清单 + 动文件 + 写清单"的多步，交错跑会互相踩——删除刚把目录搬进
-* 回收站、行还没写上时，对账抢先把这行按目录"重建"出来，随后又被真实行覆盖成降级元数据。
-*/
-/** 目录名是不是一条条目 id（形状契约在 `entry.ts`：`<删除时刻UTC>-<原目录名>`；
-*  原目录名还必须能安全地拼回磁盘路径——带分隔符的名字仍按"外人"跳过，不让一次对账读崩）。 */
-function isEntryId(name) {
-	try {
-		return isSinglePathSegment(parseEntryId(name).sessionDirName);
-	} catch {
-		return false;
-	}
-}
-/**
-* 从一个手工放进回收站的目录重建清单行。**任一件事实拿不到就整体放弃这一条**（回 `undefined`）：
-* 半截行比"不列"更坏——恢复会照它把目录搬去一个错的地方（同 `detail.ts` 那条"半截正文"的口径）。
-*
-* `sessionId` 取日志 header 的 `id`（恢复之后宿主按日志 header 建索引，那才是会话身份）；
-* header 缺席这个字段才回落到目录名里那段原目录名。
-*/
-async function buildEntry(deps, id) {
-	const dir = trashDirOf(id, deps.home);
-	let logName;
-	try {
-		logName = pickSessionLog(await deps.fs.listFiles(dir));
-	} catch {
-		return;
-	}
-	if (logName === void 0) return void 0;
-	let raw;
-	try {
-		raw = await deps.fs.readFile(`${dir}/${logName}`);
-	} catch {
-		return;
-	}
-	let header;
-	try {
-		header = readSessionHeader(raw);
-	} catch {
-		return;
-	}
-	if (header === void 0) return void 0;
-	let sizeBytes;
-	try {
-		sizeBytes = await deps.fs.sizeOfDir(dir);
-	} catch {
-		return;
-	}
-	const { deletedAt, sessionDirName } = parseEntryId(id);
-	const cwd = typeof header.cwd === "string" ? header.cwd : "";
 	return {
-		id,
-		sessionId: typeof header.id === "string" && header.id !== "" ? header.id : sessionDirName,
-		projectDir: cwd === "" ? NO_CWD_PROJECT_DIR : projectKey(cwd),
-		workspaceId: "",
-		wasArchived: false,
-		deletedAt,
-		title: "",
-		sizeBytes
+		async run() {
+			await journal.run();
+			if (tail.onDone === "leave") await presence.memberGone(tail.sessionId);
+		},
+		async undo() {
+			const undo = await journal.undo();
+			await announce(undo);
+			return undo;
+		}
 	};
 }
-/** 对账并回清单——**返回的就是修好之后的那份**（与 `manifest.list()` 同序：最近删除在前）。 */
-async function reconcileTrash(deps) {
-	const rows = await deps.manifest.list();
-	const root = `${deps.home}/${TRASH_DIR_NAME}`;
-	if (!await deps.fs.exists(root)) return rows;
-	const dirIds = /* @__PURE__ */ new Set();
-	for (const name of await deps.fs.listDirs(root)) if (isEntryId(name)) dirIds.add(name);
-	const rowIds = new Set(rows.map((row) => row.id));
-	const drops = rows.filter((row) => !dirIds.has(row.id));
-	const rebuilds = [];
-	for (const id of dirIds) {
-		if (rowIds.has(id)) continue;
-		const entry = await buildEntry(deps, id);
-		if (entry !== void 0) rebuilds.push(entry);
-	}
-	if (drops.length === 0 && rebuilds.length === 0) return rows;
-	for (const row of drops) await deps.manifest.remove(row.id);
-	for (const entry of rebuilds) await deps.manifest.add(entry);
-	return await deps.manifest.list();
-}
 //#endregion
-//#region src/verbs/member-journal.ts
+//#region src/verbs/move-group.ts
 /**
-* 一次成员移动 = 一串**自带反向动作的步骤**（ADR-0002）。
-*
-* 为什么需要它：`delete-session.ts` 的 `moveOneIn`/`undoOneIn` 与 `restore-session.ts` 的 `restoreOne`
-* （含它的反向闭包）互为镜像，各自手写了三到四段嵌套 `try/catch`：迁移前全仓 `rollbackReason(` **22 处**、
-* `withRollbackFailures(` **8 处**。那不是"回滚值得自己的候选"，而是**同一条正反动作对被写了两遍**。
+* 组级成员移动：组根先跑（拿到 `undefined`），跟随者按序跑并拿到根结果；任一失败就把**已经做成**的
+* 按相反顺序退回。
 *
-* 这里独占四件事，三个动词各自只声明"这次要做哪几步、每步怎么退"：
-* ① **相反顺序**退化（最后做成的先退）；
-* ② 一步失败时把**已经做成的**那些退回去；
-* ③ 失败收集：某一步退不干净时**不让原错误独走**（`details.rollbackFailures`，见 `verbs/errors.ts`）；
-* ④ **非原子步骤**：`undoOnFailure` 让"这一步自己失败了"也跑它的反向动作（例如"取消归档"半做完了，
-*    得先把会话重新藏回去）。
-*
-* 边界：它只服务"成员在 `sessions/` 与 `session-trash/` 之间搬"这一件事。做成通用撤销框架就会吸进
-* 不属于它的知识（谁该通告、通告几次、哪些失败算成功）。
+* 这里拥有顺序、整组回滚与**组根结果的交回**：根先跑，跟随者按序拿到根结果；调用方直接拿
+* 返回的根结果，不按位置索引结果数组。跟随者自己的结果不向上交回——当前调用方不需要。
+* 单成员的步骤与反向动作仍归 `member-journal.ts`；这条归属的裁决见 ADR-0002。
 */
-/** 已经把某个前缀做成了的 journal——`undo()` 就退那一个前缀。 */
-function createJournal(steps) {
-	const done = [];
-	const undoAll = async (alsoFailing) => {
-		const failures = [];
-		if (alsoFailing?.undo !== void 0) failures.push(...await alsoFailing.undo());
-		for (const step of [...done].reverse()) {
-			if (step.undo === void 0) continue;
-			failures.push(...await step.undo());
-		}
-		return failures;
-	};
-	return {
-		async run() {
-			for (const step of steps) {
-				try {
-					await step.run();
-				} catch (error) {
-					const failures = await undoAll(step.undoOnFailure === true ? step : void 0);
-					const base = journalFailure(step, error);
-					throw failures.length > 0 ? withRollbackFailures(base, failures) : base;
-				}
-				done.push(step);
-			}
-		},
-		undo() {
-			return undoAll();
-		}
+async function moveGroup({ root, followers, move }) {
+	const journals = [];
+	const run = async (member, rootResult) => {
+		const prepared = await move(member, rootResult);
+		await prepared.journal.run();
+		journals.push(prepared.journal);
+		return prepared.result;
 	};
-}
-/** 跑一步反向动作并把它自己的失败收成一条原因（不抛：这些失败由调用方汇总成 `rollbackFailures`）。 */
-async function attempt(label, run) {
 	try {
-		await run();
-		return [];
+		const rootResult = await run(root, void 0);
+		for (const follower of followers) await run(follower, rootResult);
+		return rootResult;
 	} catch (error) {
-		return [rollbackReason(label, error)];
+		return await rollbackJournals(journals, error);
 	}
 }
-/**
-* **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
-* `details.rollbackFailures`，绝不让原错误独走（2026-10-19 `f2a7757`；那些失败句子的合并与措辞住
-* `src/verbs/errors.ts`，这里只是唯一的调用方）。删除与恢复两个按组走的动词共用这一处，
-* "相反顺序 + 失败合并"不再各写一遍。
-*/
-async function rollbackJournals(journals, error) {
-	const failures = [];
-	for (const journal of [...journals].reverse()) failures.push(...await journal.undo());
-	if (failures.length > 0) throw withRollbackFailures(error, failures);
-	throw error;
-}
-/**
-* 这一步的失败形状：已经是动词码（`verbError` 的输出）就原样带，否则折成 `sessiondelete/io`。
-* 原文用 `String(error)` 而不是 `.message`——那 22 处既有措辞就是这么拼的（`Error: boom` 也在里面），
-* 换一种拼法会让上屏原文跟着变。
-*/
-function journalFailure(step, error) {
-	if (isVerbCodeError(error)) return error;
-	return verbError("io", `${step.label}：${String(error)}`, error);
-}
-//#endregion
-//#region src/verbs/member-presence.ts
-function createMemberPresence(host) {
-	return {
-		async memberGone(sessionId, facts = {}) {
-			if (facts.backInTrash === false) return;
-			if (await host.evictLive(sessionId) !== "unknown") await host.announceRemoved(sessionId);
-		},
-		async memberBack(sessionId, facts) {
-			if (!facts.diskBack || !facts.workspaceBack) return;
-			await host.announceRestored(sessionId);
-		}
-	};
-}
 //#endregion
 //#region src/verbs/delete-session.ts
 /**
@@ -1303,7 +1099,7 @@ function createMemberPresence(host) {
 * 整排藏了 ⇒ 那些目录既看不见也继续占着字节（本机实测 41 条父留了 320 个目录 / 74.6 MB）。
 * 所以这里把父在盘上的孩子一起搬进来，各自成目录、各自一行，清册用 `parentEntryId` 记它是谁的孩子。
 *
-* 三段，顺序承重：
+* 三段，顺序承重（成员循环与整组回滚的实现住 `verbs/move-group.ts`）：
 * ① **先点组、先验活体**（一个字节都不写）。任一成员在跑就整组拒绝——不替用户终止正在跑的活，
 *    也绝不允许"父已经搬进回收站、孩子因为在跑而搬不动"这种半套。
 * ② **逐个搬**：每个成员是一份 `journal`（`verbs/member-journal.ts`），搬不动时 journal 自己把
@@ -1311,50 +1107,43 @@ function createMemberPresence(host) {
 * ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
 *    账本跟着挂），失败照抛——不留"半组在回收站、半组在原地"的世界。
 *
-* interface 只有**一个 id**：批量的性质不在这里（同批"已被前一条带走"的判据归 `verbs/batch.ts`）。
+* interface 只有**一个 id**：批量的性质不在这里（同批已带走集归 `verbs/batch-carried.ts`，
+* 组语义归 `trash/groups.ts`）。
 * 结果带回这次真的搬走的整组（`movedSessionIds`）——它是动词交回的内部数据，不再靠回调借用动词的手。
 */
 function deleteSession(deps) {
-	const presence = createMemberPresence(deps.host);
+	const presence = deps.presence;
 	return async function deleteSession(sessionId) {
 		const read = await deps.host.subagentMembersOf([sessionId]);
 		const kids = read.available ? read.value[sessionId] ?? [] : [];
 		const parentProjectDir = await deps.host.projectDirOf(sessionId);
 		if (parentProjectDir === void 0) throw verbError("not-found", `宿主的持久化里没有这个会话：${sessionId}`);
-		const candidates = [{
-			sessionId,
-			projectDir: parentProjectDir
-		}, ...kids.map((k) => ({
-			sessionId: k.sessionId,
-			projectDir: k.projectDir
-		}))];
-		for (const member of candidates) if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
+		await assertNoLive(deps.host, [sessionId, ...kids.map((kid) => kid.sessionId)]);
 		const parentDir = sessionDirOf(parentProjectDir, sessionId, deps.home);
 		if (!await deps.fs.exists(parentDir)) throw verbError("not-found", `会话目录不存在：${parentDir}`);
-		const members = [{
+		const parent = {
 			sessionId,
 			projectDir: parentProjectDir
-		}];
+		};
+		const members = [parent];
 		for (const kid of kids) if (await deps.fs.exists(sessionDirOf(kid.projectDir, kid.sessionId, deps.home))) members.push({
 			sessionId: kid.sessionId,
 			projectDir: kid.projectDir
 		});
 		const deletedAt = deps.now();
-		const done = [];
-		let parentEntry;
-		try {
-			for (const member of members) {
-				const isParent = member.sessionId === sessionId;
-				const move = await memberMove(deps, presence, member, deletedAt, isParent ? void 0 : parentEntry.id);
-				if (isParent) parentEntry = move.entry;
-				await move.journal.run();
-				done.push(move.journal);
-			}
-		} catch (error) {
-			await rollbackJournals(done, error);
-		}
 		return {
-			entry: parentEntry,
+			entry: await moveGroup({
+				root: parent,
+				followers: members.slice(1),
+				move: async (member, rootResult) => {
+					const parentEntryId = rootResult?.id;
+					const move = await memberMove(deps, presence, member, deletedAt, parentEntryId);
+					return {
+						journal: move.journal,
+						result: move.entry
+					};
+				}
+			}),
 			movedSessionIds: members.map((member) => member.sessionId)
 		};
 	};
@@ -1369,8 +1158,7 @@ function deleteSession(deps) {
 * 会留下"文件在、agent 已关"的半个世界。窗口与可选修法登记在 ADR-0008 的「边界」。
 *
 * 每一步的反向动作都是"把这件写退回原样"；**清册行是最后一件写**，它失败时 journal 会把目录搬回去、
-* 账本挂回去。清册行的反向动作带一道闸：**回收站目录还没搬回来就不摘那一行**——留着行至少元数据还在
-* （与旧实现"目录退不回就不摘行"同一条判据）。
+* 账本挂回去。清册行的反向动作带一道闸：**回收站目录还没搬回来就不摘那一行**，留着行至少元数据还在。
 */
 async function memberMove(deps, presence, member, deletedAt, parentEntryId) {
 	const { sessionId, projectDir } = member;
@@ -1391,86 +1179,707 @@ async function memberMove(deps, presence, member, deletedAt, parentEntryId) {
 	};
 	/** 目录真的搬进回收站了吗——决定那一步的反向动作有没有东西可退。 */
 	let moved = false;
-	/** 回滚的两件写是否都真正退回原样：目录、账本。两个事实交给成员在场 module 判「归位」通告。
-	*  删除不碰归档集 ⇒ 可见性不是这次删除改过的事实，不进真值表。 */
-	let movedBack = false;
-	let workspaceBack = workspaceId === void 0;
-	const journal = createJournal([
-		{
-			label: "读取会话现场失败",
-			run: async () => {
-				entry.title = await deps.host.titleOf(sessionId);
-				entry.sizeBytes = await deps.fs.sizeOfDir(sessionDir);
-			}
-		},
-		...workspaceId === void 0 ? [] : [{
-			label: "摘账本失败",
-			run: async () => {
-				await deps.host.detach(sessionId, workspaceId);
+	return {
+		entry,
+		journal: withPresenceTail(presence, createJournal([
+			{
+				key: "read",
+				label: "读取会话现场失败",
+				run: async () => {
+					entry.title = await deps.host.titleOf(sessionId);
+					entry.sizeBytes = await deps.fs.sizeOfDir(sessionDir);
+				}
 			},
-			undo: async () => {
-				return await attempt("账本挂回失败", async () => {
-					await deps.host.attach(sessionId, workspaceId);
-					workspaceBack = true;
-				});
+			...workspaceId === void 0 ? [] : [{
+				key: "workspace",
+				label: "摘账本失败",
+				run: async () => {
+					await deps.host.detach(sessionId, workspaceId);
+				},
+				undo: () => stepUndo("账本挂回失败", () => deps.host.attach(sessionId, workspaceId))
+			}],
+			{
+				key: "dir",
+				label: "移动会话目录失败",
+				undoOnFailure: true,
+				run: async () => {
+					await deps.fs.ensureDir(`${deps.home}/${TRASH_DIR_NAME}`);
+					await deps.fs.rename(sessionDir, trashDir);
+					moved = true;
+					try {
+						await deps.ledger.add(entry);
+					} catch (error) {
+						throw verbError("io", `登记回收站条目失败：${String(error)}`, error);
+					}
+				},
+				undo: async () => {
+					if (!moved) return {
+						restored: true,
+						failures: []
+					};
+					const directory = await stepUndo("目录搬回失败", () => deps.fs.rename(trashDir, sessionDir));
+					const failures = [...directory.failures];
+					if (directory.restored) failures.push(...await attempt("清册行摘除失败", () => deps.ledger.remove(entry.id)));
+					return {
+						restored: directory.restored,
+						failures
+					};
+				}
 			}
-		}],
-		{
-			label: "移动会话目录失败",
-			undoOnFailure: true,
-			run: async () => {
-				await deps.fs.ensureDir(`${deps.home}/${TRASH_DIR_NAME}`);
-				await deps.fs.rename(sessionDir, trashDir);
-				moved = true;
-				try {
-					await deps.manifest.add(entry);
-				} catch (error) {
-					throw verbError("io", `登记回收站条目失败：${String(error)}`, error);
+		]), {
+			sessionId,
+			onDone: "leave",
+			/** 组级回滚：先按相反顺序退步骤，再判「目录与账本两件写都回去了吗」。
+			*  这一行已经收过 `api-session/removed`；不发「回来了」它就会在客户端消失到重连为止。
+			*  「退没退成」由 journal 的逐步结果交出来，这里只读键，不自己累计布尔。 */
+			onUndone: (undo) => ({
+				kind: "return",
+				diskBack: undo.restored("dir"),
+				workspaceBack: workspaceId === void 0 ? true : undo.restored("workspace")
+			})
+		})
+	};
+}
+//#endregion
+//#region src/log/zstd-frames.ts
+const MAGIC = [
+	40,
+	181,
+	47,
+	253
+];
+/** magic(4) + Frame_Header_Descriptor(1) 之后第一个字节的偏移。 */
+const AFTER_DESCRIPTOR = 5;
+const BLOCK_HEADER_BYTES = 3;
+const BLOCK_LAST = 1;
+const BLOCK_TYPE_SHIFT = 1;
+const BLOCK_SIZE_SHIFT = 3;
+const BLOCK_SIZE_MASK = 2097151;
+const BLOCK_RAW = 0;
+const BLOCK_RLE = 1;
+const BLOCK_COMRESSED = 2;
+/** RFC 8878 表 3 的帧头描述符位段：1-0 字典 ID、2 校验和、5 单段、7-6 FCS 尺寸。 */
+const DESC_DID_FLAG = 3;
+const DESC_SINGLE_SHIFT = 5;
+const DESC_FCS_SHIFT = 6;
+/** 规范（RFC 8878 表 4）里 3 是 **Reserved**，不是"未压缩块"：见到就抛，别照 Raw 吞块体。 */
+const BLOCK_RESERVED = 3;
+/** descriptor 各字段的取值 → 字段字节数（zstd 帧头的两张尺寸表）。 */
+const DID_SIZES = [
+	0,
+	1,
+	2,
+	4
+];
+const FCS_SIZES_SINGLE = [
+	1,
+	2,
+	4,
+	8
+];
+const FCS_SIZES_MULTI = [
+	0,
+	2,
+	4,
+	8
+];
+/** 实测的帧尾长度（规范里就是 descriptor 校验位声明的 XXH32；收不收由文件头注的自证判据决定）。 */
+const FRAME_TAIL_BYTES = 4;
+function isMagicAt(raw, at) {
+	return MAGIC.every((byte, i) => raw[at + i] === byte);
+}
+function readUint24LE(raw, at) {
+	return raw[at] | raw[at + 1] << 8 | raw[at + 2] << 16;
+}
+/** 块体之后有没有那 4 字节尾巴：只有"跳过它之后仍是帧头或到 EOF"才认。 */
+function withFrameTail(raw, at) {
+	const afterTail = at + FRAME_TAIL_BYTES;
+	if (afterTail <= raw.length && (afterTail === raw.length || isMagicAt(raw, afterTail))) return afterTail;
+	return at;
+}
+/**
+* 把 `raw` 切成帧区间。
+* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
+*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
+*/
+function frameRanges(raw) {
+	const ranges = [];
+	let at = 0;
+	while (at < raw.length) {
+		if (!isMagicAt(raw, at)) throw new Error(`zstd 帧头缺席：偏移 ${at} 处不是 magic（前面第 ${ranges.length} 帧的边界算歪了？）`);
+		const descriptor = raw[at + 4];
+		if (descriptor === void 0) throw new Error(`zstd 帧头不完整：偏移 ${at} 之后不足 ${AFTER_DESCRIPTOR} 字节`);
+		const didFlag = descriptor & DESC_DID_FLAG;
+		const singleSegment = descriptor >> DESC_SINGLE_SHIFT & 1;
+		const fcsFlag = descriptor >> DESC_FCS_SHIFT & 3;
+		let cursor = at + AFTER_DESCRIPTOR;
+		if (!singleSegment) cursor += 1;
+		cursor += DID_SIZES[didFlag];
+		cursor += (singleSegment ? FCS_SIZES_SINGLE : FCS_SIZES_MULTI)[fcsFlag];
+		for (;;) {
+			const blockHeader = readUint24LE(raw, cursor);
+			cursor += BLOCK_HEADER_BYTES;
+			if (cursor > raw.length) throw new Error(`zstd 块头越界：帧起于 ${at}，读到偏移 ${cursor}（文件长 ${raw.length}）`);
+			const blockType = blockHeader >> BLOCK_TYPE_SHIFT & 3;
+			const blockSize = blockHeader >> BLOCK_SIZE_SHIFT & BLOCK_SIZE_MASK;
+			if (blockType === BLOCK_RESERVED) throw new Error(`zstd 保留块类型：帧起于 ${at}，偏移 ${cursor - BLOCK_HEADER_BYTES} 的块头 type=3（规范 Reserved，对面解不开）`);
+			if (blockType === BLOCK_RAW || blockType === BLOCK_COMRESSED) cursor += blockSize;
+			else if (blockType === BLOCK_RLE) cursor += 1;
+			if (blockHeader & BLOCK_LAST) break;
+		}
+		cursor = withFrameTail(raw, cursor);
+		if (cursor !== raw.length && !isMagicAt(raw, cursor)) throw new Error(`zstd 帧边界算歪了：帧起于 ${at}，算到 ${cursor}，那里既不是下一帧帧头也不是 EOF`);
+		ranges.push({
+			start: at,
+			end: cursor
+		});
+		at = cursor;
+	}
+	return ranges;
+}
+//#endregion
+//#region src/log/session-log.ts
+/**
+* 会话日志（`session.vN.jsonl.zstd`）的**逐帧读法**：帧边界交给 `zstd-frames.ts`，这一层只做
+* 「帧 → 明文 → 一行一条 JSON」的解码，并把每条记录原样交给回调。
+*
+* **策略不在这里**（哪些 `type` 算正文、截断到多少字、算不算失败）——那是 `src/trash/detail.ts` 的事。
+* 这一层只懂编解码，所以它能被单独验穿。
+*
+* 两条实测决定的口径：
+* ① **必须逐帧**：Node 的 `zstdDecompressSync` 与 `createZstdDecompress()` 都只给第一帧（见
+*    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
+*    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
+* ② **一行的余量跨帧带走**：写作侧一条条 append，帧边界不保证落在行边界；逐帧 split('\n') 会静默少一条
+*    记录（半个头加半个身，两半都解不开 JSON）。带上余量后跨帧的多字节字符也解对了——拼接在字节层做，
+*    toString('utf8') 只看整行。真被切断的尾巴（写一半）跳过并计数，绝不因为一行就抛整个读数。
+*/
+const NEWLINE = 10;
+/**
+* 宿主给每一代日志的词法（逐字取自 `@deepseek-ai/dsh-session-format@0.2.0-rc.2` 的
+* `CANONICAL_LOG_FILENAME`，剥掉压缩后缀那段由我们自己在正则里补上 `.zstd`）：
+* 裸名 `session.jsonl` 是**第 0 代**，往后是 `session.vN`；`.v0`、前导零、大写、临时名都不是规范名。
+*/
+const CANONICAL_ZSTD_LOG = /^session(?:\.v([1-9][0-9]*))?\.jsonl\.zstd$/u;
+/** 这个名字是不是规范日志（任意一代）。附件引用扫描用它区分"老一代日志"与"读不懂的旁文件"。 */
+function isCanonicalSessionLogName(name) {
+	return CANONICAL_ZSTD_LOG.test(name);
+}
+/**
+* 同一个会话目录里可以并存多代日志；只读版本号最大的那代，因为新代包含旧代的记录且末尾更晚
+* ⇒ 读旧代 = 一份截了尾巴的快照；把几代拼起来 = 重复计数。
+*
+* 明文（无 `.zstd`）不在此列：本插件的读法逐帧解 zstd，明文得走另一条解码路。
+*/
+function pickSessionLog(names) {
+	let best;
+	let bestVersion = -1;
+	for (const name of names) {
+		const match = CANONICAL_ZSTD_LOG.exec(name);
+		if (match === null) continue;
+		const version = match[1] === void 0 ? 0 : Number(match[1]);
+		if (version > bestVersion) {
+			bestVersion = version;
+			best = name;
+		}
+	}
+	return best;
+}
+/**
+* 逐帧走一遍日志，每条记录交给回调。
+*
+* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
+* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
+*/
+function walkSessionLog(raw, onRecord) {
+	const stats = {
+		frames: 0,
+		records: 0,
+		unparsedLines: 0,
+		truncatedTailBytes: 0
+	};
+	let stopped = false;
+	const feed = (line) => {
+		if (line === "") return;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			stats.unparsedLines += 1;
+			return;
+		}
+		stats.records += 1;
+		if (onRecord(parsed !== null && typeof parsed === "object" ? parsed : {}) === false) stopped = true;
+	};
+	/** 上一帧没闭合的那一行。**存字节不存字符**：切在多字节字符中间的帧要拼回完整才解得对。 */
+	let carry = Buffer.alloc(0);
+	for (const { start, end } of frameRanges(raw)) {
+		if (stopped) break;
+		stats.frames += 1;
+		let plain;
+		try {
+			plain = zlib.zstdDecompressSync(raw.subarray(start, end));
+		} catch (error) {
+			throw new Error(`回收站日志第 ${stats.frames} 帧解压失败：${String(error)}`);
+		}
+		const merged = carry.length === 0 ? plain : Buffer.concat([carry, plain]);
+		const cut = merged.lastIndexOf(NEWLINE);
+		if (cut === -1) {
+			carry = merged;
+			continue;
+		}
+		carry = merged.subarray(cut + 1);
+		for (const line of merged.subarray(0, cut).toString("utf8").split("\n")) {
+			feed(line);
+			if (stopped) break;
+		}
+	}
+	stats.truncatedTailBytes = carry.length;
+	if (carry.length > 0 && !stopped) feed(carry.toString("utf8"));
+	return stats;
+}
+/**
+* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
+* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
+* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
+* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
+*/
+function readSessionHeader(raw) {
+	let header;
+	walkSessionLog(raw, (record) => {
+		if (record.type !== "session") return;
+		header = record;
+		return false;
+	});
+	return header;
+}
+//#endregion
+//#region src/trash/attachments.ts
+/**
+* 附件的**唯一域模块**：内容块提取、ID/路径闸、引用扫描、独占计划与执行。
+*
+* 两条红线：
+* ① 只删 `$DSH_HOME/attachments/v1/objects` 下的图片；普通文件、tmp、v2、cache 一律不碰；
+*    源文件（$DSH_HOME 之外）没有进入路径拼接的入口。
+* ② 只要剩余引用源读不出来，就整体跳过（fail closed）——宁可留孤儿，不许删共享。
+*    引用源"读不出来"包括：目录/文件读失败、目录非空却没有规范 zstd 日志（明文/陌生布局）、
+*    JSON 超出扫描上限、日志有坏行或尾巴被截断。
+*/
+const ATTACHMENT_ID = /^sha256:[0-9a-f]{64}$/u;
+function isAttachmentId(value) {
+	return typeof value === "string" && ATTACHMENT_ID.test(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function numberOf(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+/** `statFile` / `readFile` / `sizeOfDir` 里只有 ENOENT 能当"不在"；权限、盘挂、I/O 错误都必须露成读不出。 */
+function isMissing(error) {
+	return error?.code === "ENOENT";
+}
+/** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
+function attachmentPathOf(home, kind, id) {
+	if (!isAttachmentId(id)) throw new Error(`附件 id 形状不对：${id}`);
+	const hex = id.slice(7);
+	const base = `${home}/attachments/v1/${kind === "image" ? "objects" : "file-objects"}`;
+	const file = `${base}/${hex.slice(0, 2)}/${hex}`;
+	const rel = path.relative(path.resolve(base), path.resolve(file));
+	if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`附件路径越界：${id}`);
+	return file;
+}
+/** 一条消息的 `content[]` 里的附件块；畸形 id / 非附件段一律跳过。 */
+function attachmentsInContent(content) {
+	if (!Array.isArray(content)) return [];
+	const out = [];
+	for (const part of content) {
+		if (!isRecord(part)) continue;
+		const type = part.type;
+		const attachment = part.attachment;
+		if (type !== "image" && type !== "file" || !isRecord(attachment)) continue;
+		const id = attachment.attachmentId;
+		if (!isAttachmentId(id)) continue;
+		if (type === "image") out.push({
+			kind: "image",
+			id,
+			...typeof attachment.mediaType === "string" ? { mediaType: attachment.mediaType } : {},
+			bytes: numberOf(attachment.bytes),
+			...numberOf(attachment.width) > 0 ? { width: numberOf(attachment.width) } : {},
+			...numberOf(attachment.height) > 0 ? { height: numberOf(attachment.height) } : {},
+			...typeof attachment.name === "string" ? { name: attachment.name } : {}
+		});
+		else out.push({
+			kind: "file",
+			id,
+			name: typeof attachment.name === "string" ? attachment.name : "",
+			bytes: numberOf(attachment.bytes)
+		});
+	}
+	return out;
+}
+function contentArraysOf(record) {
+	const data = record.data;
+	if (!isRecord(data)) return [];
+	const out = [];
+	if (Array.isArray(data.content)) out.push(data.content);
+	if (isRecord(data.message) && Array.isArray(data.message.content)) out.push(data.message.content);
+	return out;
+}
+/**
+* `walkSessionLog` 对坏行与截断尾巴是**跳过并计数**，不抛：引用扫描如果只看解析出来的记录，
+* 就会把"少读了一行"当成"那一行没有引用"。这里的 `.damaged` 有值 ⇒ 调用方必须按不可读处理。
+*/
+function scanImageIdsInLog(raw) {
+	const ids = /* @__PURE__ */ new Set();
+	const stats = walkSessionLog(raw, (record) => {
+		for (const content of contentArraysOf(record)) for (const ref of attachmentsInContent(content)) if (ref.kind === "image") ids.add(ref.id);
+	});
+	const damaged = stats.unparsedLines > 0 || stats.truncatedTailBytes > 0 ? `日志不完整（坏行 ${stats.unparsedLines} 条、截断尾巴 ${stats.truncatedTailBytes} 字节）` : void 0;
+	return {
+		ids,
+		...damaged === void 0 ? {} : { damaged }
+	};
+}
+/** 宿主写日志时的临时名：`session.vN.jsonl.zstd.<hash>.tmp`（内容写完后才 rename 成规范名）。 */
+const TEMP_LOG_NAME = /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?\.[0-9a-f]+\.tmp$/u;
+/** 规范日志之外允许并存的两类文件：更老一代的规范日志（新代包含旧代）与 0 字节临时日志（没有消息）。
+*  其余任何文件都可能是规范日志没覆盖到的引用（例如写入中的非空临时日志），一律按不可读处理。 */
+async function unreadableExtraFile(deps, dir, names) {
+	for (const name of names) {
+		if (isCanonicalSessionLogName(name)) continue;
+		if (!TEMP_LOG_NAME.test(name)) return `${dir}: 规范日志旁还有无法确认的文件 ${name}`;
+		if ((await deps.fs.statFile(`${dir}/${name}`)).size > 0) return `${dir}: 规范日志旁还有非空临时日志 ${name}`;
+	}
+}
+/** 一个会话目录里的图片引用；`unreadable` 有值 = 这一组不可知（调用方按"跳过它"处理）。
+*
+*  **没有规范 zstd 日志 ≠ 没有引用**：明文日志、别的版本/布局、以及子目录都可能藏着引用。
+*  **有规范日志但目录里还有子目录也不够**：日志只覆盖本目录，子目录里的引用读它看不见——
+*  同样按不可读处理（宁可留下对象等维护卡兜底，不冒"没引用"）。
+*  **规范日志旁的文件也要过关**：老一代规范日志可以并存（新代包含旧代）；0 字节临时日志是
+*  写盘未完成的空产物，也没有引用。非空临时日志、明文日志或其他任何文件仍按不可读处理（fail closed）。
+*/
+async function imageIdsOfDir(deps, dir) {
+	if (!await deps.fs.exists(dir)) return { ids: /* @__PURE__ */ new Set() };
+	let names;
+	try {
+		names = await deps.fs.listFiles(dir);
+	} catch (error) {
+		return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: String(error)
+		};
+	}
+	const log = pickSessionLog(names);
+	if (log === void 0) {
+		if (names.length > 0 && names.every((name) => TEMP_LOG_NAME.test(name))) {
+			let subdirs;
+			try {
+				subdirs = await deps.fs.listDirs(dir);
+				if (subdirs.length === 0) {
+					let allEmpty = true;
+					for (const name of names) if ((await deps.fs.statFile(`${dir}/${name}`)).size > 0) {
+						allEmpty = false;
+						break;
+					}
+					if (allEmpty) return { ids: /* @__PURE__ */ new Set() };
 				}
-			},
-			undo: async () => {
-				if (!moved) return [];
-				const failures = [...await attempt("目录搬回失败", async () => {
-					await deps.fs.rename(trashDir, sessionDir);
-					movedBack = true;
-				})];
-				if (failures.length === 0) failures.push(...await attempt("清册行摘除失败", () => deps.manifest.remove(entry.id)));
-				return failures;
+			} catch (error) {
+				return {
+					ids: /* @__PURE__ */ new Set(),
+					unreadable: String(error)
+				};
+			}
+		}
+		if (names.length > 0) return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: `${dir}: 没有可读的会话日志`
+		};
+		let subdirs;
+		try {
+			subdirs = await deps.fs.listDirs(dir);
+		} catch (error) {
+			return {
+				ids: /* @__PURE__ */ new Set(),
+				unreadable: String(error)
+			};
+		}
+		if (subdirs.length > 0) return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: `${dir}: 没有可读的会话日志`
+		};
+		return { ids: /* @__PURE__ */ new Set() };
+	}
+	try {
+		const extra = await unreadableExtraFile(deps, dir, names);
+		if (extra !== void 0) return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: extra
+		};
+		if ((await deps.fs.listDirs(dir)).length > 0) return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: `${dir}: 目录里还有子目录，规范日志覆盖不到它们`
+		};
+		const scan = scanImageIdsInLog(await deps.fs.readFile(`${dir}/${log}`));
+		if (scan.damaged !== void 0) return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: `${dir}/${log}: ${scan.damaged}`
+		};
+		return { ids: scan.ids };
+	} catch (error) {
+		return {
+			ids: /* @__PURE__ */ new Set(),
+			unreadable: String(error)
+		};
+	}
+}
+/** 单个 JSON 引用源的扫描上限；超过就记成不可读（fail closed），**不许当作"没有引用"跳过**。 */
+const MAX_JSON_REF_BYTES = 10485760;
+/** 读全部剩余引用源；任何一处读不出都记进 `unreadable`。 */
+async function collectRemainingImageRefs(deps, input) {
+	const exclude = new Set(input.excludeDirs);
+	const visited = /* @__PURE__ */ new Set();
+	const ids = /* @__PURE__ */ new Set();
+	const unreadable = [];
+	const visit = async (dir) => {
+		if (exclude.has(dir) || visited.has(dir)) return;
+		visited.add(dir);
+		const read = await imageIdsOfDir(deps, dir);
+		if (read.unreadable !== void 0) unreadable.push(read.unreadable);
+		for (const id of read.ids) ids.add(id);
+	};
+	if (await deps.fs.exists(input.sessionRoot)) for (const project of await deps.fs.listDirs(input.sessionRoot)) {
+		const projectDir = `${input.sessionRoot}/${project}`;
+		if (exclude.has(projectDir)) continue;
+		for (const session of await deps.fs.listDirs(projectDir)) await visit(`${projectDir}/${session}`);
+	}
+	const trashRoot = `${deps.home}/${TRASH_DIR_NAME}`;
+	if (await deps.fs.exists(trashRoot)) for (const name of await deps.fs.listDirs(trashRoot)) await visit(`${trashRoot}/${name}`);
+	const scanJson = async (root) => {
+		if (!await deps.fs.exists(root)) return;
+		const stack = [root];
+		const seen = /* @__PURE__ */ new Set();
+		while (stack.length > 0) {
+			const dir = stack.pop();
+			try {
+				const real = await deps.fs.realpath(dir);
+				if (seen.has(real)) continue;
+				seen.add(real);
+				for (const name of await deps.fs.listDirs(dir)) stack.push(`${dir}/${name}`);
+				for (const name of await deps.fs.listFiles(dir)) {
+					if (!name.endsWith(".json")) continue;
+					const file = `${dir}/${name}`;
+					const stat = await deps.fs.statFile(file);
+					if (stat.size > MAX_JSON_REF_BYTES) {
+						unreadable.push(`${file}: JSON 引用源 ${stat.size} 字节超过扫描上限 ${MAX_JSON_REF_BYTES} 字节，未扫描`);
+						continue;
+					}
+					const text = (await deps.fs.readFile(file)).toString("utf8");
+					for (const match of text.matchAll(/sha256:[0-9a-f]{64}/gu)) ids.add(match[0]);
+				}
+			} catch (error) {
+				unreadable.push(`${dir}: ${String(error)}`);
 			}
 		}
-	]);
+	};
+	await scanJson(`${deps.home}/storages`);
+	await scanJson(`${deps.home}/cache`);
 	return {
-		entry,
-		journal: {
-			async run() {
-				await journal.run();
-				await presence.memberGone(sessionId);
-			},
-			/** 组级回滚：先把成员自己的步骤按相反顺序退回，再交给成员在场 module 判「三件写都回去了吗」。
-			*  这一行此前已经收过 `api-session/removed`；不发"回来了"它就会在客户端消失到重连为止。 */
-			async undo() {
-				const failures = await journal.undo();
-				await presence.memberBack(sessionId, {
-					diskBack: movedBack,
-					workspaceBack
+		ids,
+		unreadable
+	};
+}
+/**
+* 独占计划：候选 = 本次被删会话日志里的图片 id；剩余引用 = 活动会话 + 全部未删 `session-trash`
+* 目录 + storages/cache。
+* 剩余引用源读不出 ⇒ 整体跳过；候选日志读不出 / 附件对象 stat 失败 ⇒ 只跳过那一部分，其余照常。
+*/
+async function planImageAttachmentRemoval(deps, removedDirs) {
+	const candidates = /* @__PURE__ */ new Set();
+	let unreadableCandidates = 0;
+	for (const dir of removedDirs) {
+		const read = await imageIdsOfDir(deps, dir);
+		if (read.unreadable !== void 0) {
+			unreadableCandidates += 1;
+			continue;
+		}
+		for (const id of read.ids) candidates.add(id);
+	}
+	const skipReasons = [];
+	if (unreadableCandidates > 0) skipReasons.push(`${unreadableCandidates} 个被删会话日志读不出`);
+	if (candidates.size === 0) return {
+		entries: [],
+		bytes: 0,
+		...skipReasons.length > 0 ? { skipped: skipReasons.join("；") } : {}
+	};
+	let remaining;
+	try {
+		remaining = await collectRemainingImageRefs(deps, {
+			sessionRoot: `${deps.home}/sessions`,
+			excludeDirs: removedDirs
+		});
+	} catch (error) {
+		return {
+			entries: [],
+			bytes: 0,
+			skipped: `读不到剩余引用源，无法证明独占：${String(error)}`
+		};
+	}
+	if (remaining.unreadable.length > 0) return {
+		entries: [],
+		bytes: 0,
+		skipped: `读不到剩余引用源，无法证明独占：${remaining.unreadable[0]}`
+	};
+	const entries = [];
+	let bytes = 0;
+	let unreadableObjects = 0;
+	for (const id of candidates) {
+		if (remaining.ids.has(id)) continue;
+		const path = attachmentPathOf(deps.home, "image", id);
+		try {
+			const stat = await deps.fs.statFile(path);
+			entries.push({
+				id,
+				path,
+				bytes: stat.size
+			});
+			bytes += stat.size;
+		} catch (error) {
+			if (!isMissing(error)) unreadableObjects += 1;
+		}
+	}
+	if (unreadableObjects > 0) skipReasons.push(`${unreadableObjects} 个附件对象读不出`);
+	return {
+		entries,
+		bytes,
+		...skipReasons.length > 0 ? { skipped: skipReasons.join("；") } : {}
+	};
+}
+/**
+* 逐文件删；ENOENT 由端口的 `force` 吞掉；其他错误计数并继续。
+*
+* 删除动作只认「`home` + `id` 自己推导出来的那一条路径」：计划是数据，手搭的/被改过的条目
+* 只要路径与推导不一致就拒绝（计数为失败，不删），源文件因此没有删除入口。
+*/
+async function executeImageAttachmentRemoval(deps, plan) {
+	let removed = 0;
+	let freedBytes = 0;
+	let failed = 0;
+	for (const entry of plan.entries) {
+		let derived;
+		try {
+			derived = attachmentPathOf(deps.home, "image", entry.id);
+		} catch (error) {
+			failed += 1;
+			console.warn(`附件清理拒绝：计划条目的 id 形状不对：${entry.id}`, error);
+			continue;
+		}
+		if (derived !== entry.path) {
+			failed += 1;
+			console.warn(`附件清理拒绝：计划路径与 id 推导不一致：${entry.id}`, entry.path);
+			continue;
+		}
+		try {
+			await deps.fs.removeFile(derived);
+			removed += 1;
+			freedBytes += entry.bytes;
+		} catch (error) {
+			failed += 1;
+			console.warn(`附件清理失败：${entry.id}`, error);
+		}
+	}
+	return {
+		removed,
+		freedBytes,
+		failed
+	};
+}
+/** 真实宿主的图片库布局是 `objects/<2 hex>/<64 hex>`；这两条形状之外的名字一律不是候选。 */
+const OBJECT_PREFIX = /^[0-9a-f]{2}$/u;
+const OBJECT_NAME = /^[0-9a-f]{64}$/u;
+/**
+* 扫「当前没有任何引用源引用」的图片对象。
+*
+* 引用侧与删除计划共用同一条判据：活动会话 + 全部 `session-trash` 目录 + `storages/cache` JSON。
+* 任何一处读不出 ⇒ 整份报告跳过（fail closed），绝不把"读不出"折成"没有引用"。
+* 候选侧只认 `attachments/v1/objects` 下 `<2 hex>/<64 hex>` 这一种真实形状：`file-objects` /
+* `tmp` / `v2` / `cache` 与非规范名字一律不进候选——清理只处理 `.dsh` 内的图片副本。
+*
+* 对象列表或 stat 读不出同样整份跳过：报告宁可失败，也不给一份"少算了一些"的清理计划。
+*/
+async function scanOrphanImageAttachments(deps) {
+	let remaining;
+	try {
+		remaining = await collectRemainingImageRefs(deps, {
+			sessionRoot: `${deps.home}/sessions`,
+			excludeDirs: []
+		});
+	} catch (error) {
+		return {
+			entries: [],
+			bytes: 0,
+			skipped: `读不到引用源，无法判定孤儿附件：${String(error)}`
+		};
+	}
+	if (remaining.unreadable.length > 0) return {
+		entries: [],
+		bytes: 0,
+		skipped: `读不到引用源，无法判定孤儿附件：${remaining.unreadable[0]}`
+	};
+	const objectsRoot = `${deps.home}/attachments/v1/objects`;
+	const entries = [];
+	let bytes = 0;
+	try {
+		if (!await deps.fs.exists(objectsRoot)) return {
+			entries: [],
+			bytes: 0
+		};
+		for (const prefix of await deps.fs.listDirs(objectsRoot)) {
+			if (!OBJECT_PREFIX.test(prefix)) continue;
+			for (const name of await deps.fs.listFiles(`${objectsRoot}/${prefix}`)) {
+				if (!OBJECT_NAME.test(name) || !name.startsWith(prefix)) continue;
+				const id = `sha256:${name}`;
+				if (remaining.ids.has(id)) continue;
+				const objectPath = attachmentPathOf(deps.home, "image", id);
+				const stat = await deps.fs.statFile(objectPath);
+				entries.push({
+					id,
+					path: objectPath,
+					bytes: stat.size
 				});
-				return failures;
+				bytes += stat.size;
 			}
 		}
+	} catch (error) {
+		return {
+			entries: [],
+			bytes: 0,
+			skipped: `读不到附件对象列表，无法判定孤儿：${String(error)}`
+		};
+	}
+	return {
+		entries,
+		bytes
+	};
+}
+/** 清掉扫描那一刻无引用的图片对象；扫描跳过 ⇒ 零删，并原样带回跳过的原因。 */
+async function cleanOrphanImageAttachments(deps) {
+	const plan = await scanOrphanImageAttachments(deps);
+	if (plan.skipped !== void 0) return {
+		removed: 0,
+		freedBytes: 0,
+		failed: 0,
+		skipped: plan.skipped
 	};
+	return executeImageAttachmentRemoval(deps, plan);
 }
 //#endregion
 //#region src/verbs/permanent-removal.ts
 /**
-* 永久删除的**测量、计划与执行**：一次永久删除（`/list` 的只读读数或 purge / orphan-clean 的删除计划）
-* 之前要记下的事实（目录、字节、账本归属），以及拿到计划之后按它动盘的那一步。计划函数**只读**——
-* 写不写由执行器决定，但活体准入在这里就做掉，调用方拿到计划才允许动盘。
+* 永久删除的测量、计划与执行：先记录目录/字节/账本归属，再按计划动盘。
+* 计划函数只读；活体准入在计划阶段、任何写之前完成。
 */
-/** `exists` 与 `sizeOfDir` 之间目录消失（ENOENT）是唯一一种当"不在"的失败：盘没挂、权限、I/O 错误
-*  都不许伪装成"目录没了"，那会让 `/list` 静默少算释放量、让删除计划少一条该删的目录。 */
-function isMissing(error) {
-	return error?.code === "ENOENT";
-}
 /** `exists → sizeOfDir` 的唯一一条度量口径（成员目录与回收站目录共用）：先问在不在，再量字节；
 *  ENOENT 是唯一一种当"不在"的失败，别的错误照旧响亮。别再在调用点各写一遍这段 try/catch。
 *
@@ -1593,36 +2002,36 @@ async function planVisibleTrash(deps, rows, groups) {
 		};
 	}));
 }
-/** 活体准入：逐个问，任一在跑就抛 `live`。**计划函数就是执行前的闸**——调用方拿到计划才允许写，
-*  所以这里必须发生在任何写之前（`admission:'none'` 的调用方自己承担这个风险，不进来）。 */
-async function assertNoLive(deps, sessionIds) {
-	for (const sessionId of sessionIds) if (await deps.host.isLive(sessionId)) throw verbError("live", `会话正在运行：${sessionId}`);
-}
 function totalBytes(items) {
 	return items.reduce((total, item) => total + item.bytes, 0);
 }
 /**
 * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
+* **计划函数就是执行前的闸**——调用方拿到计划才允许写，所以准入必须发生在任何写之前。
 *
 * - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
 * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
 * - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
 *   只摘这一次真要碰的 id。
-* - `admission:'live'` 在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；
-*   任一在跑就整条拒绝，零副作用。
+* - `attachments` 由被删目录（targets + 这些成员）里的图片引用与全部剩余引用源算独占；共享的保留、
+*   剩余引用源读不出就整体跳过（判据住 `trash/attachments.ts`，这里只接线）。
+* - 活体准入在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；任一在跑就整条拒绝、
+*   零副作用。没有跳过它的开关——计划就是执行前的闸（ADR-0006）。
 * - `sessionQuery` 缺席时端口回 `{ available: false }` ⇒ members 为空、不抛（盘上残留留给 `GET /orphans` 兜底）。
 */
-async function planTrashRemoval(deps, rows, targets, options) {
+async function planTrashRemoval(deps, rows, targets) {
 	const candidates = (await selectStrandedMembers(deps.host, rows, targets.map((entry) => entry.sessionId))).flat();
-	if (options.admission === "live") await assertNoLive(deps, [...targets.map((entry) => entry.sessionId), ...candidates.map((member) => member.sessionId)]);
+	await assertNoLive(deps.host, [...targets.map((entry) => entry.sessionId), ...candidates.map((member) => member.sessionId)]);
 	const trash = await Promise.all(targets.map((entry) => measureTrashRow(deps, entry)));
 	const members = await planMemberRemovals(deps, candidates);
+	const attachments = await planImageAttachmentRemoval(deps, [...trash.map((row) => row.dir), ...members.map((member) => member.dir)]);
 	return {
 		kind: "trash",
 		trash,
 		members,
 		unarchive: [...targets.map((entry) => entry.sessionId), ...members.map((member) => member.sessionId)],
-		bytes: totalBytes(trash) + totalBytes(members)
+		bytes: totalBytes(trash) + totalBytes(members),
+		attachments
 	};
 }
 /**
@@ -1632,45 +2041,54 @@ async function planTrashRemoval(deps, rows, targets, options) {
 * - `unarchive` 覆盖**全部传入成员**（含目录缺席）：orphan-clean 在删目录之前整批摘归档集，
 *   目录缺席的 id 也可能还挂在归档集里；重试时不会再长出一条幽灵 id。
 * - live 准入覆盖**全部传入成员**（含目录缺席）：它们都在这一组的可见面里，任一在跑就整组拒绝。
+* - `attachments` 的剩余引用源由附件域自己扫（活动会话 + 全部 session-trash + storages/cache），
+*   共享图片因此保留（判据住 `trash/attachments.ts`）。
 * - 回执由 `kind:'orphan'` 派生：删目录阶段失败时执行器要交回 `{removed, freedBytes, failedSessionId}`。
 */
 async function planOrphanRemoval(deps, members) {
-	await assertNoLive(deps, members.map((member) => member.sessionId));
+	await assertNoLive(deps.host, members.map((member) => member.sessionId));
 	const present = await planMemberRemovals(deps, members);
+	const attachments = await planImageAttachmentRemoval(deps, present.map((member) => member.dir));
 	return {
 		kind: "orphan",
 		trash: [],
 		members: present,
 		unarchive: members.map((member) => member.sessionId),
-		bytes: totalBytes(present)
+		bytes: totalBytes(present),
+		attachments
 	};
 }
 /**
-* 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。
+* 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。回执的字节念计划
+* （`plan.bytes`），执行期不再累加一遍。
+*
+* 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
+* （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
+* 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
 *
-* 顺序（与迁移前的 purge / orphan-clean 一致）：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
-* （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）。目录删掉就没有
-* "退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
+* 附件清理排在**所有会话目录删完之后**：对象只在会话真的没了之后才动；单文件失败只进
+* `attachments.failed`，不影响（也不回滚）会话删除的回执。
 *
-* 失败形状沿用调用方原来的措辞与结构：
+* 失败形状：
 * - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
-* - `kind:'trash'`（purge）⇒ 同一个标签、不带 details。
-* - orphan-clean 的 unarchive / detach 在旧实现里不包装，这里原样抛出（不改变现有错误形状）。
+* - `kind:'trash'`（purge）⇒ 同一个标签、不带 details；
+* - orphan-clean 的 unarchive / detach 原样抛出。
 *
 * 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
 */
 async function executeRemoval(deps, plan) {
-	const presence = createMemberPresence(deps.host);
+	const presence = deps.presence;
 	let removed = 0;
-	let freedBytes = 0;
+	/** 删到这一刻已经腾出的**进度**：只喂 `orphan` 的部分回执；成功回执念计划的合计（`plan.bytes`）。 */
+	let freedSoFar = 0;
 	/** 删除途中失败的唯一出口：标签沿用旧措辞；部分回执只属于 `orphan`（由计划的 `kind` 派生）。
 	*  已经是本仓动词码的错误原样抛（与 `member-journal.ts` 的 `journalFailure` 同一条判据）——
 	*  `not-found` / `live` 之类不许在这里被折成 `io`。 */
 	const fail = (label, error, failedSessionId) => {
-		if (isVerbCodeError(error)) throw error;
+		if (isSessionDeleteCodeError(error)) throw error;
 		const details = plan.kind === "orphan" ? {
 			removed,
-			freedBytes,
+			freedBytes: freedSoFar,
 			failedSessionId
 		} : void 0;
 		throw verbError("io", `${label}：${String(error)}`, error, details);
@@ -1700,10 +2118,10 @@ async function executeRemoval(deps, plan) {
 			} catch (error) {
 				fail("删除回收站目录失败", error, row.entry.sessionId);
 			}
-			freedBytes += row.bytes;
+			freedSoFar += row.bytes;
 		}
 		try {
-			await deps.manifest.remove(row.entry.id);
+			await deps.ledger.remove(row.entry.id);
 		} catch (error) {
 			fail("删除回收站目录失败", error, row.entry.sessionId);
 		}
@@ -1718,12 +2136,17 @@ async function executeRemoval(deps, plan) {
 			fail(memberLabel, error, member.sessionId);
 		}
 		removed += 1;
-		freedBytes += member.bytes;
+		freedSoFar += member.bytes;
 		await presence.memberGone(member.sessionId);
 	}
+	const attachments = await executeImageAttachmentRemoval(deps, plan.attachments);
 	return {
 		removed,
-		freedBytes
+		freedBytes: plan.bytes,
+		attachments: {
+			...attachments,
+			...plan.attachments.skipped === void 0 ? {} : { skipped: plan.attachments.skipped }
+		}
 	};
 }
 //#endregion
@@ -1777,17 +2200,19 @@ function orphanGroupsOf(corpus, trashSessionIds) {
 	}
 	return groups;
 }
-/** 纯读：调用方应先走一次 `/list` 对账（面板的 refresh 就是这样）；本函数不写清单。
-*  写动作 `orphan-clean` 会自己先 reconcile，避免拿一份过期清册判"父没了"。
+/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。
+*  清册行由调用方选好再交进来：`/orphans` 交 `read.rows()`（raw 索引），`orphan-clean` 交
+*  `ledger.list()`（对账后的行）——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成
+*  "父没了"直接删盘。扫描不再自己回落到 `ledger.raw()`：读面归属住路由记录（ADR-0004 / ADR-0012）。
 *
 *  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
 *  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
 *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
-async function loadOrphanGroups(deps) {
+async function loadOrphanGroups(deps, trash) {
 	const read = await deps.host.listSessions();
 	if (!read.available) throw verbError("io", "无主子会话扫描需要宿主的 sessionQuery.listSessions");
 	const corpus = read.value;
-	const groups = orphanGroupsOf(corpus, (await deps.manifest.list()).map((entry) => entry.sessionId));
+	const groups = orphanGroupsOf(corpus, trash.map((entry) => entry.sessionId));
 	const out = [];
 	for (const group of groups) {
 		const members = [];
@@ -1847,6 +2272,7 @@ function reportOrphans(groups) {
 * - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以这里不需要那次
 *   `wasArchived` 读——这里没有"还原到删除前"的义务。
 * - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
+* - 独占图片的剩余引用源由附件域自己扫：活动会话 + 全部 session-trash + storages/cache。
 */
 async function cleanOrphanGroup(deps, group) {
 	return await executeRemoval(deps, await planOrphanRemoval(deps, group.members));
@@ -1856,72 +2282,68 @@ async function cleanOrphanGroup(deps, group) {
 /**
 * 彻底删除：从回收站里**真的**抹掉一条（或整组、或整站），并连带那些"还留在盘上、没被带走"的后代。
 *
-* 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
-* 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
+* 与另外两个动词的关系（ADR-0002）：它的 interface 是"这一组目标 + 一份只读清册快照
+*（targets 缺席 = 清空）"；目标由 `verbs/batch-carried.ts` 按组语义算好，批量的"已被同批前一条
+* 带走"判据不在这里。`requestedId` 是唯一的例外参数，但它**不参与任何判据**：只是让
+* `trash-empty` 的原文点得出用户点的是哪一条（原文要上屏，点名承重），批量语义仍在批量层。
 *
-* **这条动词只做两件事：选目标、拿计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
+* **这条动词只做两件事：拿目标、把计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
 * 再摘账本、最后删目录"的顺序都住 `verbs/permanent-removal.ts`——计划只读，执行器只写，计划就是
 * 执行前的闸（别在这里再长出一段手写步骤）。
 *
-* **这条动词不做回滚**：目录删掉就没有"退回去"这回事（2026-10-19 `f2a7757`：删到一半失败时已删目录不回滚；
+* **这条动词不做回滚**：目录删掉就没有"退回去"这回事（删到一半失败时已删目录不回滚；
 * 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
 * 对应地，`kind:'trash'` 的计划失败时执行器只抛那一步的 `io` 与原文、不带 details。
+*
+* 回执里的 `attachments` 原样来自执行器：独占图片在会话目录删完之后才清，附件失败只计数、不改
+* `removed` / `freedBytes`（`skipped` = 有候选或剩余引用源读不出、这一轮部分或整体没清，原因上屏）。
 */
 function purgeTrash(deps) {
-	return async function purgeTrash(entryId, snapshot) {
-		const all = snapshot ?? await deps.manifest.list();
-		const targets = entryId === void 0 ? all : groupOf(all, entryId);
-		if (entryId !== void 0 && targets.length === 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		return await executeRemoval(deps, await planTrashRemoval(deps, all, targets, { admission: "live" }));
+	return async function purgeTrash(targets, rows, requestedId) {
+		const selected = targets ?? rows;
+		if (targets !== void 0 && selected.length === 0) throw trashEmpty(requestedId);
+		return await executeRemoval(deps, await planTrashRemoval(deps, rows, selected));
 	};
 }
 //#endregion
 //#region src/verbs/restore-session.ts
 /**
-* 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
-* 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
-*
-* 三段与删除对称：
-* ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
-*    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
-*    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
-*    **工作区账本不在这条硬前提里**：宿主的「删除工作区」只删注册、保留日志，记下的工作区没了就按
-*    「未分组」收（判据在 {@link attachableWorkspaceId}），照旧回盘——恢复是加法，不该因为一个可选的账目而失败。
-* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 →（旧清单迁移）取消归档 → 摘清册行。
-* ③ 中途失败时 journal 把这个成员自己退回回收站；**已经恢复完的**兄弟由整组 catch 按相反顺序一起退回。
-*
-* **通告不在这里**：一次批量只该拉一遍宿主会话表、只发一次 `api-session/added`（2026-10-17 那次
-* "恢复很慢"就是逐条发）。通告归 `verbs/batch.ts`（ADR-0002），所以这个动词的 interface 只有
-* "一个条目 id 进、回收站那一行出"，没有批量专用的开关。
+* 恢复：把删除那次按原路退回，并按组走。
+*
+* 三段：
+* 1. 预检整组（不写盘）：每个成员的回收站目录与原项目目录都必须在；工作区账本缺席不算硬失败，
+*    恢复后归入「未分组」。预检在任何写之前，避免留下半组。
+* 2. 逐个恢复：文件先回来 → 挂账本 →（旧条目）取消归档 → 摘清册行。
+* 3. 中途失败由 journal 回滚当前成员；已恢复的兄弟由整组按相反顺序退回。
+*
+* 通告不在本文件：批量层在批尾一次 `announceRestored(ids)`（ADR-0002）。
 */
 function restoreSession(deps) {
-	const presence = createMemberPresence(deps.host);
-	return async function restoreSession(entryId, snapshot) {
-		const all = snapshot ?? await deps.manifest.list();
-		const target = all.find((e) => e.id === entryId);
-		if (!target) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		const group = groupOf(all, entryId);
+	const presence = deps.presence;
+	return async function restoreSession(entryId, group) {
+		const [root, ...followers] = group;
+		const target = group.find((e) => e.id === entryId);
+		if (root === void 0 || target === void 0) throw trashEmpty(entryId);
 		for (const entry of group) {
 			const trashDir = trashDirOf(entry.id, deps.home);
 			if (!await deps.fs.exists(trashDir)) throw verbError("trash-empty", `回收站条目已不在磁盘上：${trashDir}`);
 			const projectRoot = sessionDirOf(entry.projectDir, "", deps.home).replace(/\/$/, "");
 			if (!await deps.fs.exists(`${deps.home}/sessions`) || !await deps.fs.exists(projectRoot)) throw verbError("project-missing", `原项目目录已不存在：${projectRoot}`);
 		}
-		const done = [];
-		try {
-			for (const entry of group) {
-				const move = await memberRestore(deps, presence, entry);
-				await move.journal.run();
-				done.push(move.journal);
+		await moveGroup({
+			root,
+			followers,
+			move: async (entry) => {
+				return {
+					journal: (await memberRestore(deps, presence, entry)).journal,
+					result: void 0
+				};
 			}
-		} catch (error) {
-			await rollbackJournals(done, error);
-		}
+		});
 		return target;
 	};
 }
-/** 放回哪儿：用**删除时记进 entryId 的那段原目录名**，不从 `sessionId` 现推（CONTEXT.md 的「条目」条）——
-*  因此不依赖宿主当时的目录命名约定（v3 无前缀 / v4 带 `session-` 前缀）。 */
+/** 放回哪儿：用删除时记进 entryId 的原目录名，不从 sessionId 现推；因此不依赖宿主的目录命名约定。 */
 function restoreTargetDir(deps, entry) {
 	return sessionDirOf(entry.projectDir, parseEntryId(entry.id).sessionDirName, deps.home);
 }
@@ -1946,38 +2368,30 @@ async function isWorkspaceMissing(host, entry) {
 	return entry.workspaceId !== "" && await attachableWorkspaceId(host, entry) === void 0;
 }
 /**
-* 一个成员的恢复步骤（顺序与删除相反）：放回目录 → 挂账本 →（旧清单迁移）取消归档 → 摘清册行。
-*
-* 账本那一步有个**只认端口那句**的兜底：查过之后、挂之前账本被删掉（宿主的「删除工作区」与这次恢复
-* 撞上）⇒ 按未分组收、不回滚；**别的**失败是真故障，照旧抛（吞掉它就等于把一次存储故障伪装成"未分组"）。
+* 一个成员的恢复步骤：放回目录 → 挂账本 →（旧条目）取消归档 → 摘清册行。
+* 挂账本时若工作区刚被删除，按未分组收、不回滚；其他失败照抛，不能伪装成未分组。
 */
 async function memberRestore(deps, presence, entry) {
 	const trashDir = trashDirOf(entry.id, deps.home);
 	const sessionDir = restoreTargetDir(deps, entry);
 	const workspaceId = await attachableWorkspaceId(deps.host, entry);
-	/**
-	* **旧清单迁移**：2026-10-21 之前的删除用归档来藏会话，所以那些条目在盘上仍是归档态。
-	* 新删除不再碰归档（回收站与归档解耦）⇒ `wasArchived:false` 且当前**仍**归档的，只可能是旧条目；
-	* 恢复时取消归档。`wasArchived:true` 是用户删除前自己归档的，保持归档态不动。
-	*/
+	/** 旧条目迁移：早期删除用归档藏会话，盘上仍是归档态。
+	*  `wasArchived:false` 且当前仍归档 ⇒ 只可能是旧条目，恢复时取消归档；
+	*  `wasArchived:true` 是用户删除前自己归档的，保持归档态。 */
 	const legacyArchived = !entry.wasArchived && await deps.host.isArchived(entry.sessionId);
 	/** 真挂上了账本才记下那个 id——回滚里"摘账本"那一步只对挂过的成员存在。 */
 	let attached = false;
-	/** 组级回滚时，目录是否真的退回回收站——作为事实交给成员在场 module 判「已移除」通告。 */
-	let movedBack = false;
-	const journal = createJournal([
+	return { journal: withPresenceTail(presence, createJournal([
 		{
+			key: "dir",
 			label: "放回会话目录失败",
 			run: async () => {
 				await deps.fs.rename(trashDir, sessionDir);
 			},
-			undo: async () => {
-				const failures = await attempt("目录退回回收站失败", () => deps.fs.rename(sessionDir, trashDir));
-				if (failures.length === 0) movedBack = true;
-				return failures;
-			}
+			undo: () => stepUndo("目录退回回收站失败", () => deps.fs.rename(sessionDir, trashDir))
 		},
 		...workspaceId === void 0 ? [] : [{
+			key: "workspace",
 			label: "挂回账本失败",
 			run: async () => {
 				try {
@@ -1987,54 +2401,51 @@ async function memberRestore(deps, presence, entry) {
 					if (!isWorkspaceMissingError(error) || await deps.host.workspaceExists(workspaceId)) throw error;
 				}
 			},
-			undo: async () => attached ? attempt("摘账本失败", () => deps.host.detach(entry.sessionId, workspaceId)) : []
+			undo: async () => {
+				if (!attached) return {
+					restored: true,
+					failures: []
+				};
+				return stepUndo("摘账本失败", () => deps.host.detach(entry.sessionId, workspaceId));
+			}
 		}],
 		...!legacyArchived ? [] : [{
+			key: "archive",
 			label: "取消归档失败",
 			undoOnFailure: true,
 			run: async () => {
 				await deps.host.unarchive(entry.sessionId);
 			},
-			undo: () => attempt("重新归档失败", () => deps.host.archive(entry.sessionId, workspaceId))
+			undo: () => stepUndo("重新归档失败", () => deps.host.archive(entry.sessionId, workspaceId))
 		}],
 		{
+			key: "manifest",
 			label: "摘回收站条目失败",
 			run: async () => {
-				await deps.manifest.remove(entry.id);
+				await deps.ledger.remove(entry.id);
 			},
-			undo: () => attempt("清册行写回失败", () => deps.manifest.add(entry))
-		}
-	]);
-	return { journal: {
-		run: () => journal.run(),
-		async undo() {
-			const failures = await journal.undo();
-			await presence.memberGone(entry.sessionId, { backInTrash: movedBack });
-			return failures;
+			undo: () => stepUndo("清册行写回失败", () => deps.ledger.add(entry))
 		}
-	} };
+	]), {
+		sessionId: entry.sessionId,
+		onUndone: (undo) => ({
+			kind: "leave",
+			backInTrash: undo.restored("dir")
+		})
+	}) };
 }
 //#endregion
 //#region src/verbs/batch.ts
 /**
-* **「这一批」的唯一拥有者**（ADR-0002）：`POST /apply` 的落点——一组 id 上的同一个动作。
+* 「这一批」的唯一实现（ADR-0002）：POST /apply 的落点——一组 id 上的同一个动作。
 *
-* 五个动作：`delete` / `restore` / `purge` / `count` / `orphan-clean`。
+* 批量是请求的性质，不是单个动词的性质。这里拥有三件事：
+* - 去重并保持输入顺序；
+* - 逐条信封：一条失败不传染下一条，失败按 map-error 折成错误对象；
+* - 恢复通告攒到批尾，一次 announceRestored(ids)。
 *
-* 为什么批量要有自己的 module：批量是**请求**的性质，不是某一条动词的性质。此前它长在三个动词的
-* interface 上（`onMembers` / `snapshot` / `suppressAnnounce`），于是每个动词都得知道"我是第几个、
-* 前面的兄弟带走了谁"，同一个事实还有三种机制（回调、调用方 `taken` 集合、动词就地收缩数组）。
-*
-* 这一层独占四件（每条批量语义都在这里）：
-* ① **去重保序**：输入顺序就是界面"清单从上往下"的读感；
-* ② **清册快照**：整批只读一次"最初的样子"，用来判断"已被同批前一条带走"；
-* ③ **逐条信封**：一条失败不传染下一条，失败按 `map-error` 那张表折成 `{code,message,details?}`；
-* ④ **一批一次通告**：恢复的 `api-session/added` 攒到批尾、配一次预取的摘要表发（逐条发 = 每条一次
-*   宿主全表扫，那正是 2026-10-17 "恢复很慢"的头号来源）。
-*
-* 「已被同批前一条带走」是**幂等成功**，不是失败：用户要的结果本来就已经达成了（`delete`/`restore`
-* 回 `null`；`purge` 回 `{removed:0,freedBytes:0}`）。判据读 `trash/groups.ts`（ADR-0001），
-* 与 `/list` 的装配、与三个动词同一条。
+* 「已被同批前一条带走」是幂等成功（delete/restore 回 null，purge 回 0），不是失败；
+* 判据在 trash/groups.ts，同批已带走集在 batch-carried.ts。
 */
 function failure(id, action, error) {
 	return {
@@ -2077,54 +2488,46 @@ async function forEachId(action, ids, run) {
 	}
 	return outcomes;
 }
-/** 这一组的行从"当前快照"里摘掉（父行带走孩子后，后到的孩子 id 要认得出"已经不在了"）。 */
-function shrink(current, rows) {
-	for (const row of rows) {
-		const at = current.indexOf(row);
-		if (at >= 0) current.splice(at, 1);
-	}
-}
 async function applyDelete(deps, ids) {
 	const run = deleteSession(deps);
-	const carried = /* @__PURE__ */ new Set();
+	const carried = createSessionCarried();
 	return forEachId("delete", ids, async (sessionId) => {
-		const root = bareSessionId(sessionId);
-		if (carried.has(root)) return null;
+		if (carried.claim(sessionId).verdict === "carried") return null;
 		const { entry, movedSessionIds } = await run(sessionId);
-		for (const movedId of movedSessionIds) carried.add(bareSessionId(movedId));
+		for (const movedId of movedSessionIds) carried.take(movedId);
 		return entry;
 	});
 }
-/** 「这条是不是被同批前一条带走了」：原始快照里认得出、当前快照里已经空了。
-*  **收缩归这一层**（动词只拿只读快照）——`apply` 整批只读一次清册，`takenByEarlierInBatch` 不比它多读。 */
+/** 「这条是不是被同批前一条带走了」与视图收缩都归 `batch-carried.ts`；`apply` 整批只读一次清册，
+*  动词只拿它交回的只读组与当前清册。 */
 async function applyRestore(deps, ids) {
-	const original = await deps.manifest.list();
-	const current = [...original];
+	const carried = createEntryCarried(await deps.ledger.list());
 	const run = restoreSession(deps);
 	const restored = [];
 	const outcomes = await forEachId("restore", ids, async (entryId) => {
-		if (takenByEarlierInBatch(original, current, entryId)) return null;
-		const group = groupOf(current, entryId);
-		const entry = await run(entryId, current);
+		const claim = carried.claim(entryId);
+		if (claim.verdict === "carried") return null;
+		const group = claim.verdict === "fresh" ? claim.group : [];
+		const entry = await run(entryId, group);
+		carried.take(entryId);
 		restored.push(...group.map((row) => row.sessionId));
-		shrink(current, group);
 		return entry;
 	});
-	if (restored.length > 0) await deps.host.announceRestoredBatch(restored, await deps.host.restoredSummariesOf());
+	if (restored.length > 0) await deps.presence.announceRestored(restored);
 	return outcomes;
 }
 async function applyPurge(deps, ids) {
-	const original = await deps.manifest.list();
-	const current = [...original];
+	const carried = createEntryCarried(await deps.ledger.list());
 	const run = purgeTrash(deps);
 	return forEachId("purge", ids, async (entryId) => {
-		if (takenByEarlierInBatch(original, current, entryId)) return {
+		const claim = carried.claim(entryId);
+		if (claim.verdict === "carried") return {
 			removed: 0,
 			freedBytes: 0
 		};
-		const group = groupOf(current, entryId);
-		const stats = await run(entryId, current);
-		shrink(current, group);
+		const group = claim.verdict === "fresh" ? claim.group : [];
+		const stats = await run(group, carried.rows(), entryId);
+		carried.take(entryId);
 		return stats;
 	});
 }
@@ -2142,30 +2545,19 @@ async function applyCount(deps, ids) {
 * （父又被人放回回收站、组已被上一个请求带走，或另一处已经把目录清掉），不是"用户打错了一个 id"。
 * 根 id 两边都去 `session-` 前缀再比：报告原样回传是正常路径，外部调用带另一种写法也认。
 *
-* **这是写动作，排在到达序链上**，而且**先对账再扫**（2026-10-19）：判"父没了"用的是清册，而刚被人
-* 手工搬进 `session-trash/` 的那一格目录此刻可能还没有对应行——不对账就会把"父还在回收站里等着"的
-* 一组当成孤儿**直接删盘**，替用户做了一个没人点过的决定（那种组该跟着父恢复或彻底删除）。
-* 对账写在动词这一侧而不是只写在路由里，为的是 `apply` 的批量入口只有一个：链上的排队与这份快照
-* 谁也别想只占一半。
+* **这是写动作，排在到达序链上**，而且**先对账再扫**：`loadOrphanGroups` 本身只扫描、不写清册；
+* 这里先把 `ledger.list()` 对账后的行交给它——刚被人手工搬进 `session-trash/` 的那一格目录此刻可能还
+* 没有对应行，拿 raw 索引扫就会把"父还在回收站里等着"的一组当成孤儿**直接删盘**，替用户做了一个没人
+* 点过的决定（那种组该跟着父恢复或彻底删除）。
 */
 async function applyOrphanClean(deps, ids) {
-	await reconcileTrash(deps);
-	const groups = await loadOrphanGroups(deps);
+	const groups = await loadOrphanGroups(deps, await deps.ledger.list());
 	const byRoot = new Map(groups.map((group) => [bareSessionId(group.root.sessionId), group]));
-	const outcomes = [];
-	for (const id of unique(ids)) {
+	return forEachId("orphan-clean", ids, async (id) => {
 		const group = byRoot.get(bareSessionId(id));
-		if (group === void 0) {
-			outcomes.push(failure(id, "orphan-clean", verbError("not-found", `不再是可清理的无主子会话：${id}`)));
-			continue;
-		}
-		try {
-			outcomes.push(success(id, "orphan-clean", await cleanOrphanGroup(deps, group)));
-		} catch (error) {
-			outcomes.push(failure(id, "orphan-clean", error));
-		}
-	}
-	return outcomes;
+		if (group === void 0) throw verbError("not-found", `不再是可清理的无主子会话：${id}`);
+		return await cleanOrphanGroup(deps, group);
+	});
 }
 function applyActions(deps, action, ids) {
 	switch (action) {
@@ -2176,19 +2568,63 @@ function applyActions(deps, action, ids) {
 		case "orphan-clean": return applyOrphanClean(deps, ids);
 	}
 }
+//#endregion
+//#region src/trash/detail.ts
+/**
+* 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（用例见 `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`——那个计数说的是"整条正文没进来"，拿它兼报少了几张附件会让两个数都对不上。
+*/
+/** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
+const PER_MESSAGE_CHAR_CAP = 3e3;
+/** 一次回信的正文总量上限（字符）。 */
+const TOTAL_CHAR_CAP = 5e5;
+/** 一条消息带多少张附件上线。 */
+const MAX_ATTACHMENTS_PER_MESSAGE = 20;
+/** 一次回信的附件总量上限。 */
+const MAX_ATTACHMENTS_TOTAL = 200;
 const DEFAULT_LIMITS = {
-	perMessageChars: 3e3,
-	totalChars: 5e5
+	perMessageChars: PER_MESSAGE_CHAR_CAP,
+	totalChars: TOTAL_CHAR_CAP
 };
 /** 一条记录里那些 `content[]` 段的文字拼起来（`\n` 分隔；非 text 段一律不参与）。 */
 function textOf(content) {
 	if (!Array.isArray(content)) return "";
 	return content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n").trim();
 }
+/** 一条记录的 `content[]` 里的附件块，映射成线上读数（形状只映射，不改判据——闸在 `attachmentsInContent` 里）。 */
+function attachmentWires(content) {
+	return attachmentsInContent(content).map((ref) => ({
+		attachmentId: ref.id,
+		kind: ref.kind,
+		...ref.name === void 0 ? {} : { name: ref.name },
+		...ref.kind === "image" && ref.mediaType !== void 0 ? { mediaType: ref.mediaType } : {},
+		bytes: ref.bytes,
+		...ref.kind === "image" && ref.width !== void 0 ? { width: ref.width } : {},
+		...ref.kind === "image" && ref.height !== void 0 ? { height: ref.height } : {}
+	}));
+}
 function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 	return async function readTrashDetail(entryId) {
-		const record = (await deps.manifest.list()).find((e) => e.id === entryId);
-		if (record === void 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
+		const record = (await deps.rows()).find((e) => e.id === entryId);
+		if (record === void 0) throw trashEmpty(entryId);
 		const dir = trashDirOf(record.id, deps.home);
 		if (!await deps.fs.exists(dir)) throw verbError("io", `回收站目录不在：${dir}`);
 		const names = await deps.fs.listFiles(dir);
@@ -2217,9 +2653,10 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 		};
 		const models = /* @__PURE__ */ new Set();
 		let usedChars = 0;
+		let usedAttachments = 0;
 		let capped = false;
-		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停。 */
-		function push(role, time, text) {
+		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停；附件另有 20/200 两道闸。 */
+		function push(role, time, text, attachments) {
 			if (capped) {
 				detail.omittedByPayloadCap += 1;
 				return;
@@ -2232,11 +2669,15 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 				return;
 			}
 			usedChars += kept.length;
+			const room = Math.max(0, Math.min(MAX_ATTACHMENTS_PER_MESSAGE, MAX_ATTACHMENTS_TOTAL - usedAttachments));
+			const keptAttachments = attachments.slice(0, room);
+			usedAttachments += keptAttachments.length;
 			detail.messages.push({
 				role,
 				time,
 				text: kept,
-				truncated
+				truncated,
+				attachments: keptAttachments
 			});
 		}
 		try {
@@ -2263,9 +2704,10 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 							return;
 						}
 						const text = textOf(data.content);
-						if (text === "") return;
+						const attachments = attachmentWires(data.content);
+						if (text === "" && attachments.length === 0) return;
 						detail.userMessageCount += 1;
-						push("user", r.time ?? 0, text);
+						push("user", r.time ?? 0, text, attachments);
 						return;
 					}
 					case "assistant/message": {
@@ -2273,9 +2715,10 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 						const source = message.source ?? {};
 						if (typeof source.model === "string") models.add(source.model);
 						const text = textOf(message.content);
-						if (text === "") return;
+						const attachments = attachmentWires(message.content);
+						if (text === "" && attachments.length === 0) return;
 						detail.assistantMessageCount += 1;
-						push("assistant", r.time ?? 0, text);
+						push("assistant", r.time ?? 0, text, attachments);
 						return;
 					}
 					default: return;
@@ -2289,6 +2732,94 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 	};
 }
 //#endregion
+//#region src/api/attachment.ts
+const MAX_ATTACHMENT_BYTES = 20971520;
+const PNG_MAGIC = Buffer.from([
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+]);
+/** 按魔数认图片类型；认不出回 `undefined`（调用方按未知字节处理，不猜）。 */
+function sniffImage(bytes) {
+	if (bytes.length >= PNG_MAGIC.length && bytes.subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC)) return "image/png";
+	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "image/jpeg";
+	const head6 = bytes.subarray(0, 6).toString("ascii");
+	if (head6 === "GIF87a" || head6 === "GIF89a") return "image/gif";
+	if (bytes.length >= 12 && bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
+}
+/**
+* 下载名过闸：只当头部里的一个串用，**不参与寻址**。
+* 路径分隔符、控制字符、`..` 与不成对的代理项一律换 `_`；按码点截到 120 个字符（不劈开代理对，
+* 否则 `encodeURIComponent` 会在写头时抛）。
+*/
+function safeFilename(name, fallback) {
+	const base = [...name === null || name === "" ? fallback : name].slice(0, 120).join("").replace(/[\\/:*?"<>|\u0000-\u001f\uD800-\uDFFF]/gu, "_").replace(/\.\./gu, "_");
+	return base === "" ? fallback : base;
+}
+async function readAttachmentResponse(deps, query) {
+	const id = query.get(PARAMS.attachmentId);
+	const kind = query.get(PARAMS.attachmentKind);
+	if (!isAttachmentId(id)) throw routeError("bad-request", 400, `附件 id 需为 sha256:<64 位小写 hex>：${String(id)}`);
+	if (kind !== "image" && kind !== "file") throw routeError("bad-request", 400, `附件 kind 只认 image / file：${String(kind)}`);
+	const path = attachmentPathOf(deps.home, kind, id);
+	let size;
+	try {
+		size = (await deps.fs.statFile(path)).size;
+	} catch (error) {
+		throw verbError("io", `附件不在：${id}（${String(error)}）`, error);
+	}
+	if (size > MAX_ATTACHMENT_BYTES) throw verbError("io", `附件超过 ${MAX_ATTACHMENT_BYTES} 字节上限：${id}（${size} 字节）`);
+	const bytes = await deps.fs.readFile(path);
+	if (bytes.length > MAX_ATTACHMENT_BYTES) throw verbError("io", `附件超过 ${MAX_ATTACHMENT_BYTES} 字节上限：${id}（${bytes.length} 字节）`);
+	if (kind === "file") return {
+		body: bytes,
+		contentType: "application/octet-stream",
+		disposition: "attachment",
+		filename: safeFilename(query.get(PARAMS.attachmentName), id.slice(7, 19))
+	};
+	const contentType = sniffImage(bytes);
+	if (contentType === void 0) return {
+		body: bytes,
+		contentType: "application/octet-stream",
+		disposition: "attachment",
+		filename: safeFilename(query.get(PARAMS.attachmentName), `${id.slice(7, 19)}.bin`)
+	};
+	return {
+		body: bytes,
+		contentType,
+		disposition: "inline"
+	};
+}
+//#endregion
+//#region src/api/attachment-orphans.ts
+/**
+* 孤儿附件的报告段：`GET /attachment-orphans`。
+*
+* 报告把扫描计划折成数量/字节 + 对象清单（`id`/`bytes`，供设置页预览缩略图；最多
+* `ORPHAN_PREVIEW_LIMIT` 条，清理不受预览条数限制）。扫描跳过（引用源或对象列表读不出）时
+* **报告必须失败**——回一份 0 会让界面说"没有孤儿"，而这类失败恰恰是"不知道"，不是"没有"。
+* 清理是 `POST /attachment-clean`，由路由直接接到 `cleanOrphanImageAttachments`。
+*/
+/** 预览清单的上限：与详情附件的载荷闸同一量级。数量与字节仍按全量报告。 */
+const ORPHAN_PREVIEW_LIMIT = 200;
+async function reportAttachmentOrphans(deps) {
+	const plan = await scanOrphanImageAttachments(deps);
+	if (plan.skipped !== void 0) throw verbError("io", plan.skipped);
+	return {
+		count: plan.entries.length,
+		totalBytes: plan.bytes,
+		items: plan.entries.slice(0, ORPHAN_PREVIEW_LIMIT).map((entry) => ({
+			attachmentId: entry.id,
+			bytes: entry.bytes
+		}))
+	};
+}
+//#endregion
 //#region src/api/trash-rows.ts
 /**
 * 清册那一行 → 线上那一行。**显式字面量、不用 `...row`**：线上形状多一个必填字段时，这里编译不过，
@@ -2342,18 +2873,15 @@ async function assembleTrashRows(deps, rows) {
 //#endregion
 //#region src/api/route-table.ts
 /**
-* **路由表**（ADR-0004）：段名 → `{ 方法, 纯度, body, 处理 }`。一条记录，两个消费者。
-*
-* 此前"同一条请求该过哪几道判断"的知识散在两个函数里：`dispatch()` 里六个 `if` 各调一次
-* `requireMethod`，`purityOf()` 里另一组 `if` 决定"要不要进到达序链"，两处靠**注释**维持一致。
-* 不一致的两种后果都不好在测试里撞见：
-* - 该纯的判成写 ⇒ 一次探测/大正文读/扫描把删除按钮堵在串行链后面；
-* - 该写的判成纯 ⇒ 写动作绕开到达序链，与对账交错，回收站出现"目录在、行是降级元数据"的世界；
-* - body 该读没读 ⇒ 下游拿到 `null`；读了两遍 ⇒ 请求流已被消费（Node 的流只能消费一次）。
-*
-* 为什么这张表**不在** `shared/wire.ts`：处理函数会 import 动词与 `node:fs`，而浏览器半要 import
-* `wire.ts`——值 import 会把 Node 半拖进客户端 bundle，正好撞上 `tsdown` 的纯度门。段名与动作仍住
-* `wire.ts`（两半的共同契约），这张表只回答"怎么处理"。
+* 路由表（ADR-0004）：段名 → { 方法, 纯度, 读面, body, 处理 }。一条记录，两个消费者。
+*
+* 一致性要求：
+* - 该纯的判成写 ⇒ 探测/正文读/扫描被堵在串行链后；
+* - 该写的判成纯 ⇒ 写动作绕开到达序链，与对账交错；
+* - body 该读没读 ⇒ 下游拿到 null；读两遍 ⇒ 流已被消费。
+*
+* 这张表不放 shared/wire.ts：处理函数会 import 动词与 node:fs，而浏览器半要 import wire.ts。
+* 段名与动作仍住 wire.ts；这张表只回答“怎么处理”。
 */
 /** 必填的非空字符串字段（缺、空串、类型不对都是**同一句话**：说清是哪个字段）。 */
 function requireString(body, field) {
@@ -2361,17 +2889,26 @@ function requireString(body, field) {
 	if (typeof value !== "string" || value === "") throw routeError("bad-request", 400, `请求体需带非空字符串字段 ${field}`);
 	return value;
 }
-const APPLY_ACTIONS = Object.keys({
-	delete: true,
-	restore: true,
-	purge: true,
-	count: true,
-	"orphan-clean": true
-});
+/**
+* `/apply` 的五个动作与各自的**静态纯度**。一张表两个用途：动作名单由键派生，纯度也从同一格读——
+* 新增动作必须同时给出纯度，漏了编译不过；新加一个纯读动作也不会再静默落进 `chained`。
+*/
+const APPLY_ACTION_TABLE = {
+	delete: "chained",
+	restore: "chained",
+	purge: "chained",
+	count: "pure",
+	"orphan-clean": "chained"
+};
+const APPLY_ACTIONS = Object.keys(APPLY_ACTION_TABLE);
+/** 认不认得这个动作：`/apply` 的纯度与拒否共用同一条判据，名单只有上面那一张。 */
+function isApplyAction(value) {
+	return typeof value === "string" && Object.hasOwn(APPLY_ACTION_TABLE, value);
+}
 /** `/apply` 的动作：认不得的一律点名拒掉，不折成"空批量"糊弄过去。 */
 function requireAction(body) {
 	const value = body?.[PARAMS.action];
-	if (typeof value !== "string" || !APPLY_ACTIONS.includes(value)) throw routeError("bad-request", 400, `批量动作不认识：需是 ${APPLY_ACTIONS.join(" / ")} 之一`);
+	if (!isApplyAction(value)) throw routeError("bad-request", 400, `批量动作不认识：需是 ${APPLY_ACTIONS.join(" / ")} 之一`);
 	return value;
 }
 /** `/apply` 的 id 组：必须是非空字符串数组（空数组不是"什么都不做"，是调用方自己没组好）。 */
@@ -2381,39 +2918,76 @@ function requireIdArray(body) {
 	return value;
 }
 /**
-* 六个段名各一行。`Record<段名, RouteSpec>` 是闸：`wire.ts` 加了段名而这里没加，编译不过。
+* 九个段名各一行。`Record<段名, RouteSpec>` 是闸：`wire.ts` 加了段名而这里没加，编译不过。
 */
 const ROUTE_TABLE = {
 	[ROUTES.list]: {
 		method: "GET",
 		body: "none",
 		purity: "chained",
-		run: async (deps) => assembleTrashRows(deps, await reconcileTrash(deps))
+		read: "list",
+		response: "json",
+		run: async (deps, _body, read) => assembleTrashRows(deps, await read.rows())
 	},
 	[ROUTES.ping]: {
 		method: "GET",
 		body: "none",
 		purity: "pure",
+		read: "none",
+		response: "json",
 		run: async () => "pong"
 	},
+	[ROUTES.attachment]: {
+		method: "GET",
+		body: "none",
+		purity: "pure",
+		read: "none",
+		response: "binary",
+		run: async (deps, _body, _read, query) => readAttachmentResponse(deps, query)
+	},
+	[ROUTES.attachmentOrphans]: {
+		method: "GET",
+		body: "none",
+		purity: "pure",
+		read: "none",
+		response: "json",
+		run: async (deps) => reportAttachmentOrphans(deps)
+	},
+	[ROUTES.attachmentClean]: {
+		method: "POST",
+		body: "none",
+		purity: "chained",
+		read: "none",
+		response: "json",
+		run: async (deps) => cleanOrphanImageAttachments(deps)
+	},
 	[ROUTES.orphans]: {
 		method: "GET",
 		body: "none",
 		purity: "pure",
-		run: async (deps) => reportOrphans(await loadOrphanGroups(deps))
+		read: "raw",
+		response: "json",
+		run: async (deps, _body, read) => reportOrphans(await loadOrphanGroups(deps, await read.rows()))
 	},
 	[ROUTES.apply]: {
 		method: "POST",
 		body: "json",
-		purity: (body) => body?.[PARAMS.action] === "count" ? "pure" : "chained",
+		purity: (body) => {
+			const action = body?.[PARAMS.action];
+			return isApplyAction(action) ? APPLY_ACTION_TABLE[action] : "chained";
+		},
+		read: "none",
+		response: "json",
 		run: async (deps, body) => applyActions(deps, requireAction(body), requireIdArray(body))
 	},
 	[ROUTES.empty]: {
 		method: "POST",
 		body: "none",
 		purity: "chained",
-		run: async (deps) => {
-			const rows = await reconcileTrash(deps);
+		read: "list",
+		response: "json",
+		run: async (deps, _body, read) => {
+			const rows = await read.rows();
 			return await purgeTrash(deps)(void 0, rows);
 		}
 	},
@@ -2421,7 +2995,13 @@ const ROUTE_TABLE = {
 		method: "POST",
 		body: "json",
 		purity: "pure",
-		run: async (deps, body) => readTrashDetail(deps)(requireString(body, PARAMS.entryId))
+		read: "raw",
+		response: "json",
+		run: async (deps, body, read) => readTrashDetail({
+			fs: deps.fs,
+			rows: () => read.rows(),
+			home: deps.home
+		})(requireString(body, PARAMS.entryId))
 	}
 };
 /** 段名 → 那一行；不认识的段名回 `undefined`（调用方抛 404，并带出原路径）。 */
@@ -2432,39 +3012,6 @@ function routeOf(rest) {
 //#region src/api/dispatch.ts
 /** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
 const JSON_BODY_MAX_BYTES = 1048576;
-/** 回环地址的三种写法（IPv4 / IPv6 / IPv4-mapped IPv6）。 */
-const LOOPBACK = [
-	"127.0.0.1",
-	"::1",
-	"::ffff:127.0.0.1"
-];
-/**
-* 桌面壳那条路（asar `/lib/main.js` 的 `forwardWebRequest`）：渲染进程从 `dsh-app://app/` 加载，
-* 页面里对**非静态路径**的请求（`/`、`/index.html`、`/assets/*`、`/plugins/…` 之外的一切——包括
-* 我们这条前缀路由）都由 `protocol.handle("dsh-app")` 转给宿主自己的 web server；转发前它把
-* `host` / `origin` / `cookie` / `sec-fetch-site` 四个头**删掉**、换上一枚宿主自己的 cookie，路径与
-* 查询串原样带走（逐字：`for (const name of ["host","origin","cookie","sec-fetch-site"]) headers.delete(name)`）。
-* ⇒ 桌面版打到我们这条路由上的请求是**没有 `Origin`** 的，`Referer` 则保留（同源请求照常带，
-* 页面就住在 `dsh-app://app/`）。壳自己在上游只放行 `origin ∈ {null, "dsh-app://app"}`。
-*/
-const DESKTOP_APP_SCHEME = "dsh-app:";
-const DESKTOP_APP_HOST = "app";
-/**
-* 「这是桌面壳自己的页面吗」。**必须按 `protocol` + `host` 判，不能比 `URL.origin`**：`dsh-app:`
-* 不是 WHATWG 的 special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`（Node 实测），
-* 拿它跟字面量比永远为假 ⇒ 栅栏会把真机上的每一次请求都挡成 403，所有入口一个都不出现。
-*
-* 这个判据为什么不可能被外人伪造：`Origin` 与 `Referer` 都是 forbidden header，网页改不了，
-* 只能是浏览器/壳自己带上；而 `dsh-app://app` 只可能是桌面壳自己的页面。
-*/
-function isDesktopShellUrl(value) {
-	try {
-		const url = new URL(value);
-		return url.protocol === DESKTOP_APP_SCHEME && url.host === DESKTOP_APP_HOST;
-	} catch {
-		return false;
-	}
-}
 function writeJson(res, status, body) {
 	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
 	res.end(JSON.stringify(body));
@@ -2475,8 +3022,30 @@ function writeOk(res, value) {
 		value
 	});
 }
+/**
+* 二进制响应（`/attachment` 专用）。四道头都是判据不是口味：
+* - `content-type` 由处理函数给（图片按魔数认，文件一律 octet-stream）；
+* - `content-length` 与字节数同源；
+* - `cache-control: private, no-store`：附件可能来自已删除会话，不许被任何中间层留下；
+* - `nosniff` + `attachment` 下载名：字节内容与类型不一致时浏览器不许改猜。
+*
+* **失败不走这里**：处理函数抛出的错误仍由 `writeFailure` 写 JSON 信封（图片的 `onError` 会换成
+* 占位；普通文件走 `<a download>`，没有页面内失败面）。
+*/
+function writeBinary(res, body) {
+	const headers = {
+		"content-type": body.contentType,
+		"content-length": String(body.body.length),
+		"cache-control": "private, no-store",
+		"x-content-type-options": "nosniff"
+	};
+	if (body.filename !== void 0) headers["content-disposition"] = `${body.disposition}; filename*=UTF-8''${encodeURIComponent(body.filename)}`;
+	else if (body.disposition === "attachment") headers["content-disposition"] = "attachment";
+	res.writeHead(200, headers);
+	res.end(body.body);
+}
 /** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表）。
-*  **状态语义（2026-10-17 错误面对齐）**：**请求本身不对**不再伪装成 200——请求体不对 400、方法不对 405、
+*  **状态语义**：**请求本身不对**不再伪装成 200——请求体不对 400、方法不对 405、
 *  未知路由 404、栅栏拒 403（它们不是"一次办成的操作"，是"这条请求不归我办/你没资格办"）。
 *  **操作失败**仍回 200 + 信封。浏览器半先解信封再看状态，所以 4xx 上带的信封照样读得出原文；
 *  `code` 一律折成 `sessiondelete/io`，那三个路由标签（`bad-request` / `bad-method` / `not-found-route`）
@@ -2488,38 +3057,10 @@ function writeFailure(res, error, status) {
 		error: toRemoteFailure(error)
 	});
 }
-/**
-* 同源栅栏（见文件头 ④）。看 `origin` 而不只看 `referer` 的理由：恶意页
-* `<meta name="referrer" content="no-referrer">` 能让 Referer 缺席，但浏览器对跨源请求**总是**发 Origin。
-*
-* 放行的三种形状，各自都是"浏览器/壳自动带上、网页改不了"的那种：
-* ① `Origin` 与 `Host` 同源（浏览器直接打开宿主那行 URL）；② `Origin` 是桌面壳的 `dsh-app://app`
-* （壳自己在上游也只放行这个 origin）；③ `Referer` 是桌面壳的 `dsh-app://app`（**真机那条路**：
-* 壳把 `Origin` 删掉了、只留下 Referer，见 {@link isDesktopShellUrl}）。两者都缺席 = 本机工具 /
-* curl（注释即此承诺）。**恶意网页拿不到 ②③ 里的任何一个**：那两个头都是 forbidden header、
-* 页面伪造不了；而**写口（POST）在任何跨源形态下都必带 Origin** ⇒ 两个头全缺席就等于本机工具。
-* 唯一的缝是跨源 `no-cors` 的 **GET**（Referer 被 `no-referrer` 掐掉、Origin 也不带）——它够得到
-* 那几个 GET（`list` 会先对账写清册，`ping` / `orphans` 才是纯读），而 no-cors 的回包是 opaque、
-* 页面读不出内容 ⇒ 不构成泄露（`orphans` 那份报告也只报数量/字节，不含正文）。
-*/
-function isTrustedRequest(req) {
-	if (!LOOPBACK.includes(req.socket.remoteAddress ?? "")) return false;
-	const host = req.headers.host;
-	const origin = req.headers.origin;
-	if (origin !== void 0 && !isDesktopShellUrl(origin)) try {
-		if (new URL(origin).host !== host) return false;
-	} catch {
-		return false;
-	}
-	const referer = req.headers.referer;
-	if (referer === void 0) return true;
-	if (isDesktopShellUrl(referer)) return true;
-	try {
-		return new URL(referer).host === host;
-	} catch {
-		return false;
-	}
-}
+/** 栅栏拒绝的两种原文：归属不对（跨源 / 重绑 / 头不成形）与远程客户端没带宿主身份。
+*  两者都是 403，但客户端会上屏，原文要能告诉用户下一步做什么。 */
+const UNTRUSTED_MESSAGE = "非受信来源";
+const UNAUTHENTICATED_MESSAGE = "需要宿主的 Web 身份：请用 dsh web 打印的那一行 URL 打开页面后重试";
 /** 流式读 body 并解析成 JSON 对象：空体回 `null`，超限 / 非法 JSON / 不是对象一律抛（→ 400 + 失败信封）。
 *  **请求本身不对**（400）与**那次操作读不到东西**（200 + 信封）是两件事：前者是调用方没组好请求，
 *  后者是盘上没有；把前者也写成 200，代理与日志里就再也分不出这两类。 */
@@ -2552,9 +3093,9 @@ function isPure(purity, body) {
 function readBodyFor(kind, req) {
 	return kind === "json" ? readJsonBody(req) : null;
 }
-function createApiHandler(deps) {
+function createApiHandler(deps, trust) {
 	/**
-	* 到达序串行链（文件头 ⑤）：路由表里 `purity === 'chained'` 的请求一个跑完再放下一个。
+	* 到达序串行链（见文件头）：路由表里 `purity === 'chained'` 的请求一个跑完再放下一个。
 	* `tail` 由构造保证**永不 reject**（每个任务自己的失败留在交回给那次请求的那个 promise 上），
 	* 所以一次失败不会卡死链。
 	*/
@@ -2565,8 +3106,9 @@ function createApiHandler(deps) {
 		return started;
 	};
 	return async function handle(req, res) {
-		if (!isTrustedRequest(req)) {
-			writeFailure(res, /* @__PURE__ */ new Error("非受信来源"), 403);
+		const verdict = judgeRequest(req, trust);
+		if (verdict !== "allowed") {
+			writeFailure(res, /* @__PURE__ */ new Error(verdict === "untrusted" ? UNTRUSTED_MESSAGE : UNAUTHENTICATED_MESSAGE), 403);
 			return;
 		}
 		try {
@@ -2577,14 +3119,40 @@ function createApiHandler(deps) {
 			if (spec === void 0) throw routeError("not-found-route", 404, `未知路由：${req.method ?? "GET"} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
 			requireMethod(req.method ?? "GET", spec.method, rest);
 			const body = await readBodyFor(spec.body, req);
-			const task = () => spec.run(deps, body);
-			writeOk(res, await (isPure(spec.purity, body) ? task() : throughChain(task)));
+			const kind = spec.read;
+			let rowsPromise;
+			const read = { rows() {
+				if (kind === "none") return Promise.reject(/* @__PURE__ */ new Error("route read: none"));
+				rowsPromise ??= kind === "list" ? deps.ledger.list() : deps.ledger.raw();
+				return rowsPromise;
+			} };
+			const task = () => spec.run(deps, body, read, url.searchParams);
+			const result = await (isPure(spec.purity, body) ? task() : throughChain(task));
+			if (spec.response === "binary") writeBinary(res, result);
+			else writeOk(res, result);
 		} catch (error) {
 			writeFailure(res, error);
 		}
 	};
 }
 //#endregion
+//#region src/ports/connection-port.ts
+const HOST_UNAUTHENTICATED = 401;
+/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
+function createConnectionPort(ctx) {
+	return { verdictFor: (req) => {
+		const service = ctx.get("connection");
+		if (service === void 0 || typeof service.requestRejection !== "function") return { kind: "absent" };
+		try {
+			const status = service.requestRejection(req);
+			if (status === void 0) return { kind: "allowed" };
+			return { kind: status === HOST_UNAUTHENTICATED ? "unauthenticated" : "untrusted" };
+		} catch {
+			return { kind: "untrusted" };
+		}
+	} };
+}
+//#endregion
 //#region src/ports/fs-port.ts
 /** 模块级递归：端口方法**解构出来单独调**也不能靠 `this`（`{ sizeOfDir } = port` 会让方法体的
 *  `this` 变成 undefined）。所以端口只做转发，递归在模块作用域里自调。 */
@@ -2605,7 +3173,13 @@ function createFsPort() {
 			await mkdir(p, { recursive: true });
 		},
 		async rename(from, to) {
-			await rename(from, to);
+			if (existsSync(to)) throw new Error(`目标已存在，拒绝覆盖：${to}`);
+			try {
+				await rename(from, to);
+			} catch (error) {
+				if (error.code === "EXDEV") throw new Error(`跨文件系统搬不动（sessions 与 session-trash 需在同一卷）：${from} → ${to}`, { cause: error });
+				throw error;
+			}
 		},
 		async removeDir(p) {
 			await rm(p, {
@@ -2618,10 +3192,30 @@ function createFsPort() {
 			return readdir(p);
 		},
 		async listDirs(p) {
-			return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+			const dirs = [];
+			for (const entry of await readdir(p, { withFileTypes: true })) {
+				if (entry.isDirectory()) {
+					dirs.push(entry.name);
+					continue;
+				}
+				if (!entry.isSymbolicLink()) continue;
+				try {
+					if ((await stat(join(p, entry.name))).isDirectory()) dirs.push(entry.name);
+				} catch {}
+			}
+			return dirs;
+		},
+		async realpath(p) {
+			return realpath(p);
 		},
 		async readFile(p) {
 			return readFile(p);
+		},
+		async statFile(p) {
+			return { size: (await stat(p)).size };
+		},
+		async removeFile(p) {
+			await rm(p, { force: true });
 		}
 	};
 }
@@ -2653,6 +3247,125 @@ function resolveHome(env = process.env, homeDir = homedir()) {
 	return resolve(raw);
 }
 //#endregion
+//#region src/trash/reconcile.ts
+/**
+* 回收站清单的**对账**：以 `session-trash/` 里的条目目录为准，把清单修回一致（CONTEXT.md 的「对账」条）。
+*
+* 手工动回收站**只需要动那一个目录**——多出来的目录在这里被重建出行、目录没了的行在这里被摘掉；
+* `~/.dsh/storages/` 那份清单从此是**内部索引**，不用手碰。
+*
+* 五条口径（都不是口味）：
+* ① **每次真相读都对账**（`src/trash/ledger.ts` 的 `list()`；`GET /list` 的正文就是"对账 + 读"）：挂载、
+*    刷新、别处动过后的自动重读、客户端挂载后的首次列表读全走这条 ⇒ "改完目录不用再做任何事，下一次读就对了"。
+*    pure 读面（`/orphans`、`/detail`）走 `raw()`，不对账——对账会写行，必须排在到达序链上。
+*    代价 = 每次真相读多一次目录枚举（本机 124 条，毫秒级）；**零漂移零写入**（快路直接返回原清单）。
+* ② **回收站根不在 ⇒ 整套跳过、一个字节都不动**：那不是"回收站空了"，是"这块地不在原处"
+*    （人为搬走、盘没挂上）——照常对账会把全部行的元数据一次判没。
+* ③ **重建行只写"文件里真有的事实"**：`id` = 目录名、`sessionId`/`cwd` 读日志 header、
+*    `projectDir` 由 `cwd` 经宿主同名算法 `projectKey` 反推、`deletedAt` 从目录名的时间戳解、
+*    `sizeBytes` 现场量。**文件侧没有副本的三件**按缺省落：`workspaceId: ''`（恢复时跳过挂账本，
+*    落在「未分组」）、`wasArchived: false`（文件侧没有归档事实；旧条目恢复走迁移支）、`title: ''`（详情有日志标题兜底）
+*    ——这是重建的固有代价，不是可以"再读读看"的东西。
+* ④ **认不出 / 读不出的目录：不动、不列**（名字不像条目、目录里没有日志、header 读不出、尺寸量不出，
+*    各跳过各的）。它是"外人放进来的东西"，不是用户动作失败：跳过即静默，绝不为它删目录或抛掉整次读数。
+* ⑤ **幂等**：再跑一遍零写入；崩在任何一步，下一次读清单接着把它修完。
+*
+* 与三个写动词的**串行化不在这里**（那是传输层的事，见 `src/api/dispatch.ts` 的到达序链）：
+* 对账与删除/恢复/彻底删除都是"读清单 + 动文件 + 写清单"的多步，交错跑会互相踩——删除刚把目录搬进
+* 回收站、行还没写上时，对账抢先把这行按目录"重建"出来，随后又被真实行覆盖成降级元数据。
+*/
+/** 目录名是不是一条条目 id（形状契约在 `entry.ts`：`<删除时刻UTC>-<原目录名>`；
+*  原目录名还必须能安全地拼回磁盘路径——带分隔符的名字仍按"外人"跳过，不让一次对账读崩）。 */
+function isEntryId(name) {
+	try {
+		return isSinglePathSegment(parseEntryId(name).sessionDirName);
+	} catch {
+		return false;
+	}
+}
+/**
+* 从一个手工放进回收站的目录重建清单行。**任一件事实拿不到就整体放弃这一条**（回 `undefined`）：
+* 半截行比"不列"更坏——恢复会照它把目录搬去一个错的地方（同 `detail.ts` 那条"半截正文"的口径）。
+*
+* `sessionId` 取日志 header 的 `id`（恢复之后宿主按日志 header 建索引，那才是会话身份）；
+* header 缺席这个字段才回落到目录名里那段原目录名。
+*/
+async function buildEntry(deps, id) {
+	const dir = trashDirOf(id, deps.home);
+	let logName;
+	try {
+		logName = pickSessionLog(await deps.fs.listFiles(dir));
+	} catch {
+		return;
+	}
+	if (logName === void 0) return void 0;
+	let raw;
+	try {
+		raw = await deps.fs.readFile(`${dir}/${logName}`);
+	} catch {
+		return;
+	}
+	let header;
+	try {
+		header = readSessionHeader(raw);
+	} catch {
+		return;
+	}
+	if (header === void 0) return void 0;
+	let sizeBytes;
+	try {
+		sizeBytes = await deps.fs.sizeOfDir(dir);
+	} catch {
+		return;
+	}
+	const { deletedAt, sessionDirName } = parseEntryId(id);
+	const cwd = typeof header.cwd === "string" ? header.cwd : "";
+	return {
+		id,
+		sessionId: typeof header.id === "string" && header.id !== "" ? header.id : sessionDirName,
+		projectDir: cwd === "" ? NO_CWD_PROJECT_DIR : projectKey(cwd),
+		workspaceId: "",
+		wasArchived: false,
+		deletedAt,
+		title: "",
+		sizeBytes
+	};
+}
+/** 对账并回清单——**返回的就是修好之后的那份**（与 `manifest.list()` 同序：最近删除在前）。 */
+async function reconcileTrash(deps) {
+	const rows = await deps.manifest.list();
+	const root = `${deps.home}/${TRASH_DIR_NAME}`;
+	if (!await deps.fs.exists(root)) return rows;
+	const dirIds = /* @__PURE__ */ new Set();
+	for (const name of await deps.fs.listDirs(root)) if (isEntryId(name)) dirIds.add(name);
+	const rowIds = new Set(rows.map((row) => row.id));
+	const drops = rows.filter((row) => !dirIds.has(row.id));
+	const rebuilds = [];
+	for (const id of dirIds) {
+		if (rowIds.has(id)) continue;
+		const entry = await buildEntry(deps, id);
+		if (entry !== void 0) rebuilds.push(entry);
+	}
+	if (drops.length === 0 && rebuilds.length === 0) return rows;
+	for (const row of drops) await deps.manifest.remove(row.id);
+	for (const entry of rebuilds) await deps.manifest.add(entry);
+	return await deps.manifest.list();
+}
+//#endregion
+//#region src/trash/ledger.ts
+function createTrashLedger(raw, fs, home) {
+	return {
+		list: () => reconcileTrash({
+			fs,
+			manifest: raw,
+			home
+		}),
+		raw: () => raw.list(),
+		add: (entry) => raw.add(entry),
+		remove: (id) => raw.remove(id)
+	};
+}
+//#endregion
 //#region src/trash/manifest.ts
 function createStorageManifest(domain) {
 	return {
@@ -2669,7 +3382,7 @@ function createStorageManifest(domain) {
 }
 //#endregion
 //#region src/trash/storage-manifest.ts
-/** 本插件自己的域（CONTEXT.md 的「清册」条：介质落在 `~/.dsh/storages/`）。
+/** 本插件自己的域（CONTEXT.md 的「清册」条：介质落在数据根下的 `storages/`）。
 *
 *  **名字必须带插件专属前缀**：domain 名是 `storageDomain` facility 里的**全局键**，而**一个名字在
 *  一个 facility 里只能 `open()` 一次**（句柄归调用方所有）——别人先占了同名域，本插件会**在激活时**
@@ -2719,7 +3432,7 @@ const trashDomainSpec = defineDomain({
 * 清单的真实绑定：官方 storage domain → `ManifestPort`（`StorageDomainLike` 在动词层保持一种读法）。
 * 域**懒开**且成功句柄只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
 * 插件卸载时关掉句柄并把 `close()` 的落地交回框架（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约；
-* 2026-10-17 起不再 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
+* 不能 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
 *
 * **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
 * 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。
@@ -2770,11 +3483,16 @@ const name = "@xrn1997/dsh-session-delete";
 *   它同样可能晚于本插件激活，写进插件 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` 原文读实，不是猜的。
 *
-* 清单（storage domain 绑定）与数据根各有一个家：`src/trash/storage-manifest.ts`、`src/ports/home.ts`。
+* `connection` 只喂请求栅栏的远程支（`src/api/request-trust.ts` ②），按 `ctx.get` 可选读：
+* 服务缺席时插件照常激活，远程客户端 fail-closed。它不进 `inject`——写进去会让没有 web 组成的
+* profile 整个停在 pending。
+*
+* 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
+* 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
 */
 const inject = [
 	"workspaceRegistry",
@@ -2782,26 +3500,35 @@ const inject = [
 	"webServer"
 ];
 /**
-* 装配顺序：**清单 → 端口 → 动词依赖 → 前缀路由**（`DeleteDeps` 就是前两者的合一）。
+* 装配顺序：**清单 → 端口 → 在场能力 → 动词依赖 → 前缀路由**（`DeleteDeps` 把这些依赖面合成一颗）。
 *
 * 路由用 `ctx.effect` 挂、disposer 归装载它的那根 fiber：插件卸载即摘路由（`register` 返回的
 * disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(kind, path)`
 * 在 `register` 里直接抛（`webserver: duplicate prefix route "…"`），响亮失败而不是悄悄覆盖。
 */
 function apply(ctx) {
+	const fs = createFsPort();
+	const home = resolveHome();
+	const rawManifest = createHostStorageManifest(ctx);
+	const host = createHostPort(ctx);
 	const deps = {
-		fs: createFsPort(),
-		host: createHostPort(ctx),
-		manifest: createHostStorageManifest(ctx),
-		home: resolveHome(),
+		fs,
+		host,
+		ledger: createTrashLedger(rawManifest, fs, home),
+		home,
+		presence: createMemberPresence(host),
 		now: () => Date.now()
 	};
 	const webServer = ctx.webServer;
+	const connection = createConnectionPort(ctx);
 	ctx.effect(() => {
 		const dispose = webServer.register({
 			kind: "prefix",
 			path: SESSION_DELETE_API_PREFIX,
-			handler: createApiHandler(deps)
+			handler: createApiHandler(deps, {
+				bindHost: webServer.host,
+				connection
+			})
 		});
 		return () => {
 			dispose();