@xrn1997/dsh-session-delete 0.2.0 → 0.2.2

package/lib/index.js

@@ -5,7 +5,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 //#region src/shared/wire.ts
 /**
-* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、五个端点段、请求字段名**——
+* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
 * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
 * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
 *
@@ -28,13 +28,15 @@ import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 五个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
+/** 六个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
 *  一次 HTTP 带一组 id、逐条回结果；单条就是长度为 1 的批量，仓里不再留第二条执行路径。
 *  - `GET /list`：**对账并读**清单（`session-trash/` 里的目录是准）。
 *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链）——客户端探测用它，不用一次全表读。
 *  - `POST /detail`：单条详情（用 POST 表达一个读：见设计稿 2026-10-15 §3）。
-*  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count`），逐条回 `ApplyOutcome`。
-*  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。 */
+*  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
+*  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。
+*  - `GET /orphans`：无主子会话的扫描报告（纯读，2026-10-19）。**清理不在这里**——它是 `/apply` 的
+*    第五个动作，这一段只负责"有多少、在哪、多大"。 */
 const ROUTES = {
 	list: "/list",
 	/** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
@@ -44,7 +46,9 @@ const ROUTES = {
 	/** 一组 id 上的同一个动作；删除确认框那句「含 N 个子会话」也走这里（`action: 'count'`，纯读语义）。 */
 	apply: "/apply",
 	/** 清空回收站。 */
-	empty: "/empty"
+	empty: "/empty",
+	/** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
+	orphans: "/orphans"
 };
 /** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
 const PARAMS = {
@@ -65,35 +69,33 @@ function isDSHRemoteError(value) {
 	const candidate = value;
 	return candidate.isDSHRemoteError === true && typeof candidate.code === "string";
 }
-//#endregion
-//#region src/verbs/errors.ts
-/** 五个码（设计稿 §6 的表）。**唯一定义处**：`remote/map-error.ts` 从这份数组反推它的 `Code`，
-*  免得"加了一个码只在一边加"让两张表各自漂移（漂移的后果是那个码静默降级成 `io`）。 */
-const VERB_CODES = [
+/** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见设计稿 §6。 */
+const SESSION_DELETE_ERROR_DOMAIN = "sessiondelete";
+/** 五个**动词码**（设计稿 §6 那张表）。`io` 是唯一兜底。 */
+const VERB_CODES$1 = [
 	"live",
 	"not-found",
 	"trash-empty",
 	"project-missing",
 	"io"
 ];
-function verbError(code, message, cause, details) {
-	const e = new Error(message);
-	e.code = `sessiondelete/${code}`;
-	if (cause !== void 0) e.cause = cause;
-	if (details !== void 0) e.details = details;
-	return e;
-}
-/** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
-function routeError(code, httpStatus, message) {
-	const e = verbError("io", message);
-	e.code = `sessiondelete/${code}`;
-	e.httpStatus = httpStatus;
-	return e;
-}
+const SESSION_DELETE_CODES = {
+	live: "sessiondelete/live",
+	"not-found": "sessiondelete/not-found",
+	"trash-empty": "sessiondelete/trash-empty",
+	"project-missing": "sessiondelete/project-missing",
+	io: "sessiondelete/io",
+	"bad-method": "sessiondelete/bad-method",
+	"not-found-route": "sessiondelete/not-found-route",
+	"bad-request": "sessiondelete/bad-request"
+};
+/** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
+const TRASH_DIR_NAME = "session-trash";
 //#endregion
 //#region src/remote/map-error.ts
-/** 插件专属远程域名（设计稿 §6）：与宿主官方域（`workspace/*`、`session/*`、`gateway/*`…）不重名。 */
-const DOMAIN = "sessiondelete";
+/** 插件专属远程域名（设计稿 §6）：与宿主官方域（`workspace/*`、`session/*`、`gateway/*`…）不重名。
+*  字面量的家在 `shared/wire.ts`（ADR-0003）——浏览器半也按同一个域认码。 */
+const DOMAIN = SESSION_DELETE_ERROR_DOMAIN;
 /** 宿主两条类型化错误 → 我们的码（设计稿 §6 的两行映射）。
 *  类不可 import（跨插件值 import 是红线；且宿主包与运行中的宿主不同代）⇒ 按官方构造器写死的 `this.name` 认。
 *  证据：asar `dsh/node_modules/@deepseek-ai/dsh-workspace/lib/index.js` 原文
@@ -170,7 +172,7 @@ function detailsOf(error) {
 * - 其余（别域的怪 code、前缀外的因、非 Error 抛出物）⇒ `io`，message 保留原文。
 *
 * **返回的是线上形状、不是 `Error`**：这份东西唯一的去处是 `src/api/dispatch.ts` 的失败信封
-* （以及 `verbs/apply.ts` 的逐条 `error`），而本仓的跨插件 import 红线也不许为此去引宿主的
+* （以及 `verbs/batch.ts` 的逐条 `error`），而本仓的跨插件 import 红线也不许为此去引宿主的
 * `RemoteError` 类（实例也上不了线：信封只走这三件）。
 */
 function toRemoteFailure(error) {
@@ -192,7 +194,7 @@ function toRemoteFailure(error) {
 		};
 	}
 	const reason = typeof raw === "string" && raw.startsWith(`${DOMAIN}/`) ? raw.slice(14) : void 0;
-	const fromVerb = reason !== void 0 && VERB_CODES.includes(reason) ? reason : void 0;
+	const fromVerb = reason !== void 0 && VERB_CODES$1.includes(reason) ? reason : void 0;
 	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 {
@@ -207,742 +209,811 @@ function toRemoteFailure(error) {
 	};
 }
 //#endregion
-//#region src/trash/entry.ts
-const pad = (n, w = 2) => String(n).padStart(w, "0");
-function makeEntryId(deletedAt, sessionDirName) {
-	const d = new Date(deletedAt);
-	return `${`${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`}-${sessionDirName}`;
-}
-const ENTRY_ID_RE = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-(.+)$/;
-/** `makeEntryId` 的逆。时间戳按 UTC 拆字段再 `Date.UTC` 合回——不交给 `Date.parse`
-*  去猜（`20260930T130500Z` 不是任何被承认的日期格式，猜出来的是 NaN）。 */
-function parseEntryId(id) {
-	const m = ENTRY_ID_RE.exec(id);
-	if (!m) throw new Error(`bad entry id: ${id}`);
-	const [, y, mo, d, h, mi, s, sessionDirName] = m;
-	return {
-		deletedAt: Date.UTC(+y, +mo - 1, +d, +h, +mi, +s),
-		sessionDirName
-	};
+//#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}/`;
+function verbError(code, message, cause, details) {
+	const e = new Error(message);
+	e.code = SESSION_DELETE_CODES[code];
+	if (cause !== void 0) e.cause = cause;
+	if (details !== void 0) e.details = details;
+	return e;
 }
-function sessionDirOf(projectDir, sessionDirName, home) {
-	return `${home}/sessions/${projectDir}/${sessionDirName}`;
+/** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
+function routeError(code, httpStatus, message) {
+	const e = verbError("io", message);
+	e.code = SESSION_DELETE_CODES[code];
+	e.httpStatus = httpStatus;
+	return e;
 }
-function trashDirOf(entryId, home) {
-	return `${home}/session-trash/${entryId}`;
+/** 一条回滚步骤失败的**标签句**：label 说的是"这一步在退什么"，原文带出**那一步抛的东西**
+*  （`Error` 取 message，其余一律 `String()`；对象带 `message` 的差异归 `map-error.messageOf` 管）。
+*  调用方不许另抄这份格式——那样 details 里的句子会随各处 catch 变形，界面上就变成"同一个失败三个说法"。 */
+function rollbackReason(label, error) {
+	return `${label}：${error instanceof Error ? error.message : String(error)}`;
+}
+/** 内层错误已经挂着的回滚失败（成员自己的就地回滚失败时会有）。组级 catch 再包一次时不能丢。 */
+function carriedRollbackFailures(error) {
+	const raw = error?.details?.rollbackFailures;
+	return Array.isArray(raw) ? raw.filter((item) => typeof item === "string") : [];
+}
+/** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
+*  没有可继承的就落 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 carried = carriedRollbackFailures(error);
+	const merged = [.../* @__PURE__ */ new Set([...carried, ...failures])];
+	const base = error instanceof Error ? error.message : String(error);
+	const extra = failures.filter((failure) => !carried.includes(failure));
+	return verbError(code, base.includes("；回滚未完成：") ? extra.length > 0 ? `${base}；${extra.join("；")}` : base : `${base}；回滚未完成：${merged.join("；")}`, error, { rollbackFailures: merged });
 }
 //#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;
+//#region src/ports/host-port.ts
+/** live store 的最小方法面判据（同 `projectionCacheOf` 的手法：按方法面判，不按 constructor.name）。 */
+function liveSessionsOf(ctx) {
+	const store = ctx.get("sessions");
+	if (store === void 0 || store === null) return void 0;
+	if (typeof store.get !== "function" || typeof store.liveEntryFor !== "function") return void 0;
+	return store;
 }
-/** 块体之后有没有那 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;
+/** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。 */
+async function filterChildrenOf(sessionQuery, values) {
+	return sessionQuery.filterSessions([{
+		kind: "parent",
+		values: [...values].sort()
+	}]);
 }
 /**
-* 把 `raw` 切成帧区间。
-* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
-*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
+* 从若干根出发**逐层往下**把盘上的后代问出来，交回 `父（bare）→ 孩子` 的索引。
+*
+* 为什么一次问一层而不是官方的 `traceSession`：那条在父已经进回收站时认不出目标
+* （`SESSION_QUERY_SESSION_NOT_FOUND`），而我们要的那批正是"父已经不在宿主列表里之后还剩在盘上的"。
+* `kind:'parent'` 是唯一能按 `header.parentSession` 反着问的一支。
+*
+* 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
+* （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
+* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostPort.subagentMembers} 那条），
+* 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
 */
-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;
+async function descendantsByParent(sessionQuery, roots) {
+	const children = /* @__PURE__ */ new Map();
+	const seen = new Set(roots.map(bareSessionId));
+	let frontier = [...seen];
+	while (frontier.length > 0) {
+		const values = [];
+		for (const bare of frontier) for (const shape of sessionIdShapes(bare)) if (!values.includes(shape)) values.push(shape);
+		const next = [];
+		for (const record of await filterChildrenOf(sessionQuery, values)) {
+			const id = record.header?.id;
+			const parent = record.header?.parentSession;
+			if (typeof id !== "string" || id.length === 0) continue;
+			if (typeof parent !== "string" || parent.length === 0) continue;
+			const bare = bareSessionId(id);
+			if (seen.has(bare)) continue;
+			seen.add(bare);
+			const cwd = record.header?.cwd;
+			const descendant = {
+				id,
+				bare,
+				projectDir: cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(cwd)
+			};
+			const parentBare = bareSessionId(parent);
+			const siblings = children.get(parentBare);
+			if (siblings === void 0) children.set(parentBare, [descendant]);
+			else siblings.push(descendant);
+			next.push(bare);
 		}
-		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;
+		frontier = next;
 	}
-	return ranges;
+	return children;
 }
-//#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）而不是整条。
-* ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
-*    实测本机 686 个 `.jsonl.zstd` / 92 421 帧**没有一帧切在行中间**（连最后一帧都整行收尾），
-*    所以旧口径当时并不丢东西；但"逐帧 `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;
-/**
-* 同一个会话目录里**可以并存多代日志**（宿主换代时把老代留在原地当历史语料，本机实测 7 个目录如此），
-* 而新代是老代的**迁移后超集**（实测：`firstTs` 与开头那条提问完全相同、记录更多、末尾更晚）
-* ⇒ 要读的是版本号最大的那一代，读旧代 = 读到一份截了尾巴的快照；把几代拼起来 = 重复计数。
-*
-* 明文（无 `.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;
+/** 某个根在 `descendantsByParent` 那棵树里的全部后代（深度不设上限，同一条只收一次）。 */
+function subtreeOf(children, rootBare) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set([rootBare]);
+	let frontier = [rootBare];
+	while (frontier.length > 0) {
+		const next = [];
+		for (const bare of frontier) for (const kid of children.get(bare) ?? []) {
+			if (seen.has(kid.bare)) continue;
+			seen.add(kid.bare);
+			out.push(kid);
+			next.push(kid.bare);
 		}
+		frontier = next;
 	}
-	return best;
+	return out;
+}
+function toMember(d) {
+	return {
+		sessionId: d.id,
+		projectDir: d.projectDir
+	};
+}
+/** `subagentCounts` / `subagentMembers` / `subagentMembersBatch` 共用的一次 BFS。
+*  空清单在调用宿主之前就返回（不为一张空表扫全库）。 */
+async function membersFor(sessionQuery, parentIds) {
+	const wanted = [];
+	for (const id of parentIds) if (id.length > 0 && !wanted.includes(id)) wanted.push(id);
+	if (wanted.length === 0) return {};
+	const children = await descendantsByParent(sessionQuery, wanted);
+	const out = {};
+	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` 重建条目）共用这一个字面量。 */
+const NO_CWD_PROJECT_DIR = "_no-cwd";
 /**
-* 逐帧走一遍日志，每条记录交给回调。
+* 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
 *
-* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
-* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
+* 为什么是镜像而不是 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` 反推它原本属于哪个项目目录）——算法只有这一处家。
 */
-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;
+function projectKey(cwd) {
+	let readable = "";
+	let separatorRun = false;
+	for (let i = 0; i < cwd.length; i++) {
+		const code = cwd.charCodeAt(i);
+		const ch = String.fromCharCode(code);
+		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)}--`;
+}
+/** 投影缓存服务的最小方法面判据（按方法面判，不按 `constructor.name` 判）。 */
+function projectionCacheOf(ctx) {
+	const cache = ctx.get("sessionProjectionCache");
+	if (cache === void 0 || cache === null) return void 0;
+	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` 走。
+*/
+const NO_SUCH_SESSION = "session persistence holds no such session";
+/** 只认上面那一句；其余（含非 Error 抛出物）一律**不算未命中**。 */
+function isUnknownSession(error) {
+	return error instanceof Error && error.message.includes(NO_SUCH_SESSION);
+}
+/** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostPort.subagentCounts}）。 */
+function bareSessionId(id) {
+	return id.startsWith("session-") ? id.slice(8) : id;
+}
+/** 一个 id 的全部可能写法，原写法在前：`session-x` → `[session-x, x]`；`x` → `[x, session-x]`。 */
+function sessionIdShapes(id) {
+	const bare = bareSessionId(id);
+	return [.../* @__PURE__ */ new Set([
+		id,
+		bare,
+		`session-${bare}`
+	])];
+}
+/** 宿主会话表的一次取数（`ctx.sessionController.list()` 的两种返回形状都折成数组）。
+*  服务没挂 / 形状不对 / 抛错 ⇒ 空表——**这条不替宿主兜错误**：调用方拿空表的语义都是"少发一条通告"，
+*  不是"恢复失败"。 */
+async function controllerItems(host) {
+	try {
+		const controller = host.get("sessionController");
+		if (controller === void 0 || controller === null || typeof controller.list !== "function") return [];
+		const listed = await controller.list();
+		const items = Array.isArray(listed) ? listed : listed?.items;
+		return Array.isArray(items) ? items : [];
+	} catch {
+		return [];
+	}
+}
+/** 账本里没有那个工作区时 {@link HostPort.attach} / {@link HostPort.detach} 抛的原话开头。
+*  **原话与判据同住这里**：抛它的是这个端口，认它的也是端口给的那句，调用方不许另抄一份字符串。 */
+const WORKSPACE_MISSING_MESSAGE = "workspace not found";
+/** 这次失败是不是"账本里没那个工作区"（而不是另有故障）。恢复侧靠它把两种失败分开：
+*  前者按「未分组」收，后者照旧回滚报 `io`——不给真故障静默改归属的机会。 */
+function isWorkspaceMissingError(error) {
+	return error instanceof Error && error.message.startsWith(WORKSPACE_MISSING_MESSAGE);
+}
+/**
+* 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
+*
+* 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
+* 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
+* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（设计稿 §6 的两行映射）。
+*/
+function createHostPort(ctx) {
+	const host = ctx;
+	const registry = host.workspaceRegistry;
+	return {
+		/** 账本里记着这个会话的工作区：`registry.list()` 的实体 `sessionIds`（该 getter 已按 canonical cwd 过滤过）。 */
+		async workspaceOf(sessionId) {
+			return registry.list().find((workspace) => workspace.sessionIds.includes(sessionId))?.id;
+		},
+		/** 账本里还有这个工作区吗：`registry.get(id)` 是 `this.entities.get(id)` 的直通（同步 Map 查找），
+		*  未知 id 回 `undefined` ⇒ 这里只做一次判别，不抛。 */
+		async workspaceExists(workspaceId) {
+			return registry.get(workspaceId) !== void 0;
+		},
+		/**
+		* 原生 cwd → 宿主项目目录名（`projectKey`）；没有 cwd 时按宿主约定落到 `_no-cwd`。
+		*
+		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
+		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
+		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ 设计稿 §6 的 `not-found`
+		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
+		*
+		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
+		*/
+		async projectDirOf(sessionId) {
+			let header;
+			try {
+				header = await registry.readSessionHeader(sessionId);
+			} catch (error) {
+				if (isUnknownSession(error)) return void 0;
+				throw error;
+			}
+			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);
+				const cache = projectionCacheOf(host);
+				const title = (cache?.cachedSnapshot(header, ["title"]) ?? cache?.cachedPredecessorTitle(header))?.values.title;
+				return typeof title === "string" ? title : "";
+			} catch {
+				return "";
+			}
+		},
+		/**
+		* 活跃判据 = 宿主官方那一条（设计稿 §5）：`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);`
+		*/
+		async isLive(sessionId) {
+			return (await host.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]))).length > 0;
+		},
+		/** registry 全局归档集（数组，`state.archivedSessionIds`）。 */
+		async isArchived(sessionId) {
+			return registry.archivedSessionIds.includes(sessionId);
+		},
+		/**
+		* 从 `ctx.sessions`（live store）里摘掉一个会话。
+		*
+		* **为什么需要**：会话列表读面是并集——`sessionQuery.listSessions()` = 磁盘上的持久化 ∪ `ctx.sessions` 里的活体
+		* （见设计稿 §4 末）。搬走文件只清掉一侧；本机运行期打开过的会话是活体，列表照样把它交出来，
+		* 于是"删了还在"（真机实测：文件已进回收站、账本已摘，侧栏仍留着那一行）。
+		*
+		* **这是未声明为契约的内部入口**（设计稿 §4 末记了这次偏离）：`liveEntryFor` / `entry.detach()` 是 store
+		* 给**会话 owner**（agent 的 effect 链）用的，宿主自己的控制器 `createOrAdopt` 只取 `agents.create()`
+		* 返回的 `.agent`、把带 `dispose` 的 handle 丢掉了，`ctx.agents` 也没有 `liveEntryFor` 那样的入口
+		* （会话 store 有、agent store 没有，逐成员面核过）⇒ 只能摘到"会话"这一层，上面那具 agent 摘不到，
+		* 它之后若走到 `flush(session)` 会撞 `liveEntryFor` 抛 `session "…" is not live in this store`。
+		*
+		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 抛 ⇒ `unknown`（**不通告**，
+		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
+		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
+		*/
+		async evictLive(sessionId) {
+			try {
+				const store = liveSessionsOf(host);
+				if (store === void 0) return "unknown";
+				const session = store.get(sessionId);
+				if (session === void 0 || session === null) return "not-live";
+				const entry = store.liveEntryFor(session);
+				if (entry === void 0 || entry === null || typeof entry.detach !== "function") return "unknown";
+				entry.detach();
+				return "evicted";
+			} catch {
+				return "unknown";
+			}
+		},
+		/**
+		* 通告客户端"这个会话没了"。
+		*
+		* **为什么需要**：客户端那一行只由两条路更新——重连时的整表重列（`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} 判）：这条通告在语义上是**如实**
+		* 的，不是障眼法。
+		*/
+		async announceRemoved(sessionId) {
+			try {
+				host.emit("api-session/removed", sessionId);
+			} catch {}
+		},
+		/**
+		* 通告客户端"这个会话回来了"。
+		*
+		* 摘要**取自宿主自己的会话列表**（`ctx.sessionController.list()`），不自己造一行：客户端 `handleSessionAdded`
+		* 要的是宿主 `summaryFor` 那套形状（sessionId / updatedAt / blank / projections…），照抄宿主的那一份最可靠。
+		* 取不到（控制器缺席 / 列表里没有它 / 抛错）就**一条都不发**。
+		*
+		* **这一条单条路是删除组回滚用的**：成员已经收过 `api-session/removed`，退回 `sessions/` 之后要补一条
+		* "added"，否则客户端那一行要等到重连才回来。正常恢复走 {@link announceRestoredBatch} + 一次预取——
+		* 100 条的批量用单条路就是 100 遍全表扫，那正是 2026-10-17 那次"恢复很慢"的头号来源。
+		*/
+		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 = [];
+			for (const item of await controllerItems(host)) {
+				const sessionId = item?.sessionId;
+				if (typeof sessionId === "string") out.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) {
+				const summary = summaries.find((item) => item.sessionId === id)?.summary;
+				if (summary === void 0) continue;
+				try {
+					host.emit("api-session/added", JSON.parse(JSON.stringify(summary)));
+				} catch {}
+			}
+		},
+		/** 官方 `unarchiveSession(sessionId)`：未归档是幂等 no-op。 */
+		async unarchive(sessionId) {
+			await registry.unarchiveSession(sessionId);
+		},
+		/** 摘账本：实体方法 `detachSession`（顶层没有）；未知工作区**响亮失败**，不静默当成功。 */
+		async detach(sessionId, workspaceId) {
+			const workspace = registry.get(workspaceId);
+			if (workspace === void 0) throw new Error(`${WORKSPACE_MISSING_MESSAGE} (detach): ${workspaceId}`);
+			await workspace.detachSession(sessionId);
+		},
+		/** 挂账本：实体方法 `attachSession`（顶层没有）。 */
+		async attach(sessionId, workspaceId) {
+			const workspace = registry.get(workspaceId);
+			if (workspace === void 0) throw new Error(`${WORKSPACE_MISSING_MESSAGE} (attach): ${workspaceId}`);
+			await workspace.attachSession(sessionId);
+		},
+		/** 确保归档：官方 `archiveSession(sessionId)`。归档是 registry **全局**的，与工作区账目无关
+		*  （JSDoc 原文 "its workspace accounting — or lack of one — is irrelevant"），所以 `workspaceId` 不用
+		*  ——未分组的会话没有工作区可传，签名里它是可选的。
+		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，设计稿 §6）。 */
+		async archive(sessionId) {
+			await registry.archiveSession(sessionId);
+		},
+		async listSessions() {
+			const sessionQuery = host.get("sessionQuery");
+			if (typeof sessionQuery?.listSessions !== "function") return void 0;
+			const records = await sessionQuery.listSessions();
+			const out = [];
+			for (const record of records) {
+				const id = record.header?.id;
+				if (typeof id !== "string" || id === "") continue;
+				const parent = record.header?.parentSession;
+				const cwd = record.header?.cwd;
+				out.push({
+					sessionId: id,
+					...typeof parent === "string" && parent !== "" ? { parentSessionId: parent } : {},
+					projectDir: cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(cwd),
+					subagent: record.header?.origin === "subagent"
+				});
+			}
+			return out;
+		},
+		/**
+		* 官方 `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` 直接查得到）。
+		*/
+		async subagentCounts(parentIds) {
+			const sessionQuery = host.get("sessionQuery");
+			if (typeof sessionQuery?.filterSessions !== "function") return {};
+			const members = await membersFor(sessionQuery, parentIds);
+			const counts = {};
+			for (const [id, list] of Object.entries(members)) if (list.length > 0) counts[id] = list.length;
+			return counts;
+		},
+		/**
+		* 删除要一起带走**整个组**，先得把他们点出来：身份取宿主自己记录里的 `header.id`，项目目录由
+		* `header.cwd` 走同一个 `projectKey`（与 {@link HostPort.projectDirOf} 同一根算法，不另起一套）。
+		* 交回的是**全部后代**——孙代跟着父一起进回收站（issue #1），顺序是逐层往下问出来的（近的先）。
+		* `header.id` 缺席的后代直接跳过——不拿目录名冒充身份（冒充了会把一个来路不明的目录搬进回收站）。
+		* 服务没挂回 `[]` ⇒ 删除照旧只管父，不因此失败（父的删除本来就已经是完整的一件事）。
+		*/
+		async subagentMembers(sessionId) {
+			const sessionQuery = host.get("sessionQuery");
+			if (typeof sessionQuery?.filterSessions !== "function") return [];
+			return ((await membersFor(sessionQuery, [sessionId]))[sessionId] ?? []).map(toMember);
+		},
+		async subagentMembersBatch(parentIds) {
+			const sessionQuery = host.get("sessionQuery");
+			if (typeof sessionQuery?.filterSessions !== "function") return {};
+			const members = await membersFor(sessionQuery, parentIds);
+			return Object.fromEntries(Object.entries(members).map(([id, list]) => [id, list.map(toMember)]));
 		}
-		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;
-		}
+}
+//#endregion
+//#region src/trash/groups.ts
+/** 这些孩子的父。 */
+function kidsOf(rows, parentId) {
+	return rows.filter((row) => row.parentEntryId === parentId);
+}
+/**
+* 清单露面的一行 = 组根，按清册原序。孩子折进根那一行（宿主的客户端本来就把 `origin:"subagent"`
+* 的行整排藏了 ⇒ 我们若单列就会冒出一堆点不到的行）。
+*
+* 折不进去的那两种孩子（父行不在 / 父行自己也是孩子）**自己站出来占一行**——那正是
+* `visibleGroups` 与 `groupOf` 共用同一条判据的地方。
+*/
+function visibleGroups(rows) {
+	const byId = new Map(rows.map((row) => [row.id, row]));
+	const kidsByRoot = /* @__PURE__ */ new Map();
+	const folded = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (row.parentEntryId === void 0) continue;
+		const parent = byId.get(row.parentEntryId);
+		if (parent === void 0 || parent.parentEntryId !== void 0) continue;
+		folded.add(row.id);
+		const siblings = kidsByRoot.get(parent.id);
+		if (siblings === void 0) kidsByRoot.set(parent.id, [row]);
+		else siblings.push(row);
 	}
-	stats.truncatedTailBytes = carry.length;
-	if (carry.length > 0 && !stopped) feed(carry.toString("utf8"));
-	return stats;
+	return rows.filter((row) => !folded.has(row.id)).map((root) => ({
+		root,
+		kids: kidsByRoot.get(root.id) ?? []
+	}));
 }
 /**
-* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
-* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
-* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
-* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
+* 一条 id 所属的整组。三种形状，三个答案：
+* - **组根** ⇒ 它自己 + 它接住的孩子（UI 点的是父那一行，删除/恢复/彻底删除都按整组走）；
+* - **孩子**（自己记着 `parentEntryId`）⇒ **只回它自己**。清单不单独列它，只有手工/降级路径会点到这里；
+* - **清册里没有这一条 id，但还有孩子指向它**（父行已被别的路径摘掉）⇒ 那一批孩子；仍然没有 ⇒ 空数组，
+*   调用方据此报 `trash-empty` / 判"已被同批前一条带走"。
 */
-function readSessionHeader(raw) {
-	let header;
-	walkSessionLog(raw, (record) => {
-		if (record.type !== "session") return;
-		header = record;
-		return false;
-	});
-	return header;
+function groupOf(rows, id) {
+	const root = rows.find((row) => row.id === id);
+	if (root !== void 0) return root.parentEntryId === void 0 ? [root, ...kidsOf(rows, id)] : [root];
+	return kidsOf(rows, id);
 }
-const DEFAULT_LIMITS = {
-	perMessageChars: 3e3,
-	totalChars: 5e5
+/**
+* 「这条是被**同批前一条**带走的，还是整批开始前就没有？」
+*
+* 幂等语义只属于前者：后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它）必须照样响亮报
+* `trash-empty`，不能被"已被带走"这句话掩盖成成功。**所以判据是快照的原始形状，不是当前形状**：
+* 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+*/
+function takenByEarlierInBatch(original, current, id) {
+	return groupOf(original, id).length > 0 && groupOf(current, id).length === 0;
+}
+//#endregion
+//#region src/trash/entry.ts
+/**
+* 清册里**每条记录都必须有**的那几格（`TrashEntry` 的非可选字段）——运行期校验器与「文件里真有的事实」
+* 共用这一份清单。
+*
+* **可选字段不在这里**：`parentEntryId`（级联那批加的）缺席是合法的——老行没有它，缺了就是"没有父"；
+* 校验器只管这几格的类型，其余键**原样带走**（`parse` 交回的就是 `raw` 本身）⇒ 新字段照旧存得住。
+*
+* 键集与接口由 `tests/wire-shape.test.ts` 双向钉住：接口加一个必填字段而这里没跟 ⇒ 测试红。
+*/
+const REQUIRED_ENTRY_FIELDS = {
+	id: "string",
+	sessionId: "string",
+	projectDir: "string",
+	workspaceId: "string",
+	wasArchived: "boolean",
+	deletedAt: "number",
+	title: "string",
+	sizeBytes: "number"
 };
-/** 一条记录里那些 `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();
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+function makeEntryId(deletedAt, sessionDirName) {
+	const d = new Date(deletedAt);
+	return `${`${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`}-${sessionDirName}`;
 }
-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 dir = trashDirOf(record.id, deps.home);
-		if (!await deps.fs.exists(dir)) throw verbError("io", `回收站目录不在：${dir}`);
-		const names = await deps.fs.listFiles(dir);
-		const logName = pickSessionLog(names);
-		if (logName === void 0) throw verbError("io", `回收站目录里没有会话日志：${dir}（里面有：${names.join(", ") || "空目录"}）`);
-		let raw;
-		try {
-			raw = await deps.fs.readFile(`${dir}/${logName}`);
-		} catch (error) {
-			throw verbError("io", `读会话日志失败：${String(error)}`, error);
-		}
-		const detail = {
-			entryId: record.id,
-			cwd: "",
-			createdAt: 0,
-			lastActivity: 0,
-			logTitle: "",
-			models: [],
-			turnCount: 0,
-			userMessageCount: 0,
-			assistantMessageCount: 0,
-			toolCallCount: 0,
-			injectedCount: 0,
-			messages: [],
-			omittedByPayloadCap: 0
-		};
-		const models = /* @__PURE__ */ new Set();
-		let usedChars = 0;
-		let capped = false;
-		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停。 */
-		function push(role, time, text) {
-			if (capped) {
-				detail.omittedByPayloadCap += 1;
-				return;
-			}
-			const truncated = text.length > limits.perMessageChars;
-			const kept = truncated ? text.slice(0, limits.perMessageChars) : text;
-			if (usedChars + kept.length > limits.totalChars) {
-				capped = true;
-				detail.omittedByPayloadCap += 1;
-				return;
-			}
-			usedChars += kept.length;
-			detail.messages.push({
-				role,
-				time,
-				text: kept,
-				truncated
-			});
-		}
-		try {
-			walkSessionLog(raw, (r) => {
-				if (typeof r.time === "number" && r.time > detail.lastActivity) detail.lastActivity = r.time;
-				const data = r.data ?? {};
-				switch (r.type) {
-					case "session":
-						if (typeof r.cwd === "string") detail.cwd = r.cwd;
-						if (typeof r.createdAt === "number") detail.createdAt = r.createdAt;
-						return;
-					case "session/title":
-						if (typeof data.title === "string") detail.logTitle = data.title;
-						return;
-					case "turn/start":
-						detail.turnCount += 1;
-						return;
-					case "tool/call":
-						detail.toolCallCount += 1;
-						return;
-					case "user/message": {
-						if ((data.source ?? {}).kind !== "user") {
-							detail.injectedCount += 1;
-							return;
-						}
-						const text = textOf(data.content);
-						if (text === "") return;
-						detail.userMessageCount += 1;
-						push("user", r.time ?? 0, text);
-						return;
-					}
-					case "assistant/message": {
-						const message = data.message ?? {};
-						const source = message.source ?? {};
-						if (typeof source.model === "string") models.add(source.model);
-						const text = textOf(message.content);
-						if (text === "") return;
-						detail.assistantMessageCount += 1;
-						push("assistant", r.time ?? 0, text);
-						return;
-					}
-					default: return;
-				}
-			});
-		} catch (error) {
-			throw verbError("io", error instanceof Error ? `读回收站日志失败：${error.message}` : `读回收站日志失败：${String(error)}`, error);
-		}
-		detail.models = [...models];
-		return detail;
+const ENTRY_ID_RE = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-(.+)$/;
+/** `makeEntryId` 的逆。时间戳按 UTC 拆字段再 `Date.UTC` 合回——不交给 `Date.parse`
+*  去猜（`20260930T130500Z` 不是任何被承认的日期格式，猜出来的是 NaN）。 */
+function parseEntryId(id) {
+	const m = ENTRY_ID_RE.exec(id);
+	if (!m) throw new Error(`bad entry id: ${id}`);
+	const [, y, mo, d, h, mi, s, sessionDirName] = m;
+	return {
+		deletedAt: Date.UTC(+y, +mo - 1, +d, +h, +mi, +s),
+		sessionDirName
 	};
 }
+/** 路径里的每一段都必须是**单段**：这一层不信宿主的 `header.id` 与清册，破坏性动词直接删目录。
+*  `/`、`\`、`.`、`..` 与 NUL 都能把递归删除带出 `sessions/` / `session-trash/`。 */
+function isSinglePathSegment(value) {
+	return value !== "" && value !== "." && value !== ".." && !/[\\/\0]/u.test(value);
+}
+function assertSingleSegment(value, label, allowEmpty = false) {
+	if (value === "") {
+		if (allowEmpty) return;
+		throw new Error(`${label} 不能为空`);
+	}
+	if (!isSinglePathSegment(value)) throw new Error(`${label} 不是单段路径：${value}`);
+}
+/** `sessionDirName` 允许空串：恢复的预检用它取**项目根**（`sessions/<projectDir>`），不是会话目录。 */
+function sessionDirOf(projectDir, sessionDirName, home) {
+	assertSingleSegment(projectDir, "项目目录名");
+	assertSingleSegment(sessionDirName, "会话目录名", true);
+	return `${home}/sessions/${projectDir}/${sessionDirName}`;
+}
+function trashDirOf(entryId, home) {
+	assertSingleSegment(entryId, "回收站条目 id");
+	return `${home}/${TRASH_DIR_NAME}/${entryId}`;
+}
 //#endregion
-//#region src/ports/host-port.ts
-/** live store 的最小方法面判据（同 `projectionCacheOf` 的手法：按方法面判，不按 constructor.name）。 */
-function liveSessionsOf(ctx) {
-	const store = ctx.get("sessions");
-	if (store === void 0 || store === null) return void 0;
-	if (typeof store.get !== "function" || typeof store.liveEntryFor !== "function") return void 0;
-	return store;
+//#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);
 }
-/** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。 */
-async function filterChildrenOf(sessionQuery, values) {
-	return sessionQuery.filterSessions([{
-		kind: "parent",
-		values: [...values].sort()
-	}]);
+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;
 }
 /**
-* 从若干根出发**逐层往下**把盘上的后代问出来，交回 `父（bare）→ 孩子` 的索引。
-*
-* 为什么一次问一层而不是官方的 `traceSession`：那条在父已经进回收站时认不出目标
-* （`SESSION_QUERY_SESSION_NOT_FOUND`），而我们要的那批正是"父已经不在宿主列表里之后还剩在盘上的"。
-* `kind:'parent'` 是唯一能按 `header.parentSession` 反着问的一支。
-*
-* 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
-* （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
-* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostPort.subagentMembers} 那条），
-* 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
+* 把 `raw` 切成帧区间。
+* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
+*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
 */
-async function descendantsByParent(sessionQuery, roots) {
-	const children = /* @__PURE__ */ new Map();
-	const seen = new Set(roots.map(bareSessionId));
-	let frontier = [...seen];
-	while (frontier.length > 0) {
-		const values = [];
-		for (const bare of frontier) for (const shape of sessionIdShapes(bare)) if (!values.includes(shape)) values.push(shape);
-		const next = [];
-		for (const record of await filterChildrenOf(sessionQuery, values)) {
-			const id = record.header?.id;
-			const parent = record.header?.parentSession;
-			if (typeof id !== "string" || id.length === 0) continue;
-			if (typeof parent !== "string" || parent.length === 0) continue;
-			const bare = bareSessionId(id);
-			if (seen.has(bare)) continue;
-			seen.add(bare);
-			const cwd = record.header?.cwd;
-			const descendant = {
-				id,
-				bare,
-				projectDir: cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(cwd)
-			};
-			const parentBare = bareSessionId(parent);
-			const siblings = children.get(parentBare);
-			if (siblings === void 0) children.set(parentBare, [descendant]);
-			else siblings.push(descendant);
-			next.push(bare);
-		}
-		frontier = next;
-	}
-	return children;
-}
-/** 某个根在 `descendantsByParent` 那棵树里的全部后代（深度不设上限，同一条只收一次）。 */
-function subtreeOf(children, rootBare) {
-	const out = [];
-	const seen = /* @__PURE__ */ new Set([rootBare]);
-	let frontier = [rootBare];
-	while (frontier.length > 0) {
-		const next = [];
-		for (const bare of frontier) for (const kid of children.get(bare) ?? []) {
-			if (seen.has(kid.bare)) continue;
-			seen.add(kid.bare);
-			out.push(kid);
-			next.push(kid.bare);
+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;
 		}
-		frontier = next;
+		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 out;
+	return ranges;
 }
-/** 无 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` 重建条目）共用这一个字面量。 */
-const NO_CWD_PROJECT_DIR = "_no-cwd";
+//#endregion
+//#region src/log/session-log.ts
 /**
-* 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
+* 会话日志（`session.vN.jsonl.zstd`）的**逐帧读法**：帧边界交给 `zstd-frames.ts`，这一层只做
+* 「帧 → 明文 → 一行一条 JSON」的解码，并把每条记录原样交给回调。
 *
-* 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
-* 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
-* （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
+* **策略不在这里**（哪些 `type` 算正文、截断到多少字、算不算失败）——那是 `src/trash/detail.ts` 的事。
+* 这一层只懂编解码，所以它能被单独验穿。
 *
-* 原文（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` 同理）。
+* 两条实测决定的口径：
+* ① **必须逐帧**：Node 的 `zstdDecompressSync` 与 `createZstdDecompress()` 都只给第一帧（见
+*    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
+*    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
+* ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
+*    实测本机 686 个 `.jsonl.zstd` / 92 421 帧**没有一帧切在行中间**（连最后一帧都整行收尾），
+*    所以旧口径当时并不丢东西；但"逐帧 `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;
+/**
+* 同一个会话目录里**可以并存多代日志**（宿主换代时把老代留在原地当历史语料，本机实测 7 个目录如此），
+* 而新代是老代的**迁移后超集**（实测：`firstTs` 与开头那条提问完全相同、记录更多、末尾更晚）
+* ⇒ 要读的是版本号最大的那一代，读旧代 = 读到一份截了尾巴的快照；把几代拼起来 = 重复计数。
 *
-* **两个调用方共用这一份**：`projectDirOf`（删除时定位会话目录）与回收站对账的重建路径
-* （手工放进回收站的目录，从日志 header 的 `cwd` 反推它原本属于哪个项目目录）——算法只有这一处家。
+* 明文（无 `.zstd`）不在此列：本插件的读法逐帧解 zstd，明文得走另一条解码路。
 */
-function projectKey(cwd) {
-	let readable = "";
-	let separatorRun = false;
-	for (let i = 0; i < cwd.length; i++) {
-		const code = cwd.charCodeAt(i);
-		const ch = String.fromCharCode(code);
-		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;
+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 `--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--`;
-}
-/** 投影缓存服务的最小方法面判据（按方法面判，不按 `constructor.name` 判）。 */
-function projectionCacheOf(ctx) {
-	const cache = ctx.get("sessionProjectionCache");
-	if (cache === void 0 || cache === null) return void 0;
-	if (typeof cache.cachedSnapshot !== "function" || typeof cache.cachedPredecessorTitle !== "function") return void 0;
-	return cache;
+	return best;
 }
 /**
-* 「账本里没有这个会话」的判别串——宿主 `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` 走。
+* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
+* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
 */
-const NO_SUCH_SESSION = "session persistence holds no such session";
-/** 只认上面那一句；其余（含非 Error 抛出物）一律**不算未命中**。 */
-function isUnknownSession(error) {
-	return error instanceof Error && error.message.includes(NO_SUCH_SESSION);
-}
-/** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostPort.subagentCounts}）。 */
-function bareSessionId(id) {
-	return id.startsWith("session-") ? id.slice(8) : id;
-}
-/** 一个 id 的全部可能写法，原写法在前：`session-x` → `[session-x, x]`；`x` → `[x, session-x]`。 */
-function sessionIdShapes(id) {
-	const bare = bareSessionId(id);
-	return [.../* @__PURE__ */ new Set([
-		id,
-		bare,
-		`session-${bare}`
-	])];
-}
-/** 宿主会话表的一次取数（`ctx.sessionController.list()` 的两种返回形状都折成数组）。
-*  服务没挂 / 形状不对 / 抛错 ⇒ 空表——**这条不替宿主兜错误**：调用方拿空表的语义都是"少发一条通告"，
-*  不是"恢复失败"。 */
-async function controllerItems(host) {
-	try {
-		const controller = host.get("sessionController");
-		if (controller === void 0 || controller === null || typeof controller.list !== "function") return [];
-		const listed = await controller.list();
-		const items = Array.isArray(listed) ? listed : listed?.items;
-		return Array.isArray(items) ? items : [];
-	} catch {
-		return [];
+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;
 }
 /**
-* 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
-*
-* 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
-* 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
-* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（设计稿 §6 的两行映射）。
+* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
+* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
+* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
+* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
 */
-function createHostPort(ctx) {
-	const host = ctx;
-	const registry = host.workspaceRegistry;
-	return {
-		/** 账本里记着这个会话的工作区：`registry.list()` 的实体 `sessionIds`（该 getter 已按 canonical cwd 过滤过）。 */
-		async workspaceOf(sessionId) {
-			return registry.list().find((workspace) => workspace.sessionIds.includes(sessionId))?.id;
-		},
-		/**
-		* 原生 cwd → 宿主项目目录名（`projectKey`）；没有 cwd 时按宿主约定落到 `_no-cwd`。
-		*
-		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
-		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
-		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ 设计稿 §6 的 `not-found`
-		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
-		*
-		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
-		*/
-		async projectDirOf(sessionId) {
-			let header;
-			try {
-				header = await registry.readSessionHeader(sessionId);
-			} catch (error) {
-				if (isUnknownSession(error)) return void 0;
-				throw error;
-			}
-			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);
-				const cache = projectionCacheOf(host);
-				const title = (cache?.cachedSnapshot(header, ["title"]) ?? cache?.cachedPredecessorTitle(header))?.values.title;
-				return typeof title === "string" ? title : "";
-			} catch {
-				return "";
-			}
-		},
-		/**
-		* 活跃判据 = 宿主官方那一条（设计稿 §5）：`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);`
-		*/
-		async isLive(sessionId) {
-			return (await host.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]))).length > 0;
-		},
-		/** registry 全局归档集（数组，`state.archivedSessionIds`）。 */
-		async isArchived(sessionId) {
-			return registry.archivedSessionIds.includes(sessionId);
-		},
-		/**
-		* 从 `ctx.sessions`（live store）里摘掉一个会话。
-		*
-		* **为什么需要**：会话列表读面是并集——`sessionQuery.listSessions()` = 磁盘上的持久化 ∪ `ctx.sessions` 里的活体
-		* （见设计稿 §4 末）。搬走文件只清掉一侧；本机运行期打开过的会话是活体，列表照样把它交出来，
-		* 于是"删了还在"（真机实测：文件已进回收站、账本已摘，侧栏仍留着那一行）。
-		*
-		* **这是未声明为契约的内部入口**（设计稿 §4 末记了这次偏离）：`liveEntryFor` / `entry.detach()` 是 store
-		* 给**会话 owner**（agent 的 effect 链）用的，宿主自己的控制器 `createOrAdopt` 只取 `agents.create()`
-		* 返回的 `.agent`、把带 `dispose` 的 handle 丢掉了，`ctx.agents` 也没有 `liveEntryFor` 那样的入口
-		* （会话 store 有、agent store 没有，逐成员面核过）⇒ 只能摘到"会话"这一层，上面那具 agent 摘不到，
-		* 它之后若走到 `flush(session)` 会撞 `liveEntryFor` 抛 `session "…" is not live in this store`。
-		*
-		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 抛 ⇒ `unknown`（**不通告**，
-		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
-		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
-		*/
-		async evictLive(sessionId) {
-			try {
-				const store = liveSessionsOf(host);
-				if (store === void 0) return "unknown";
-				const session = store.get(sessionId);
-				if (session === void 0 || session === null) return "not-live";
-				const entry = store.liveEntryFor(session);
-				if (entry === void 0 || entry === null || typeof entry.detach !== "function") return "unknown";
-				entry.detach();
-				return "evicted";
-			} catch {
-				return "unknown";
-			}
-		},
-		/**
-		* 通告客户端"这个会话没了"。
-		*
-		* **为什么需要**：客户端那一行只由两条路更新——重连时的整表重列（`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} 判）：这条通告在语义上是**如实**
-		* 的，不是障眼法。
-		*/
-		async announceRemoved(sessionId) {
-			try {
-				host.emit("api-session/removed", sessionId);
-			} catch {}
-		},
-		/**
-		* 通告客户端"这个会话回来了"（恢复用）。
-		*
-		* 摘要**取自宿主自己的会话列表**（`ctx.sessionController.list()`），不自己造一行：客户端 `handleSessionAdded`
-		* 要的是宿主 `summaryFor` 那套形状（sessionId / updatedAt / blank / projections…），照抄宿主的那一份最可靠。
-		* 取不到（控制器缺席 / 列表里没有它 / 抛错）就**一条都不发**——恢复本身已经完成，只是要等下次重连才上屏。
-		*
-		* **单条路各拉一次表**；批量走 {@link HostPort.announceRestoredBatch} + 一次预取（见 {@link restoredSummariesOf}），
-		* 100 条的批量恢复用这条就是 100 遍全表扫——那是 2026-10-17 那次"恢复很慢"的头号来源。
-		*/
-		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 = [];
-			for (const item of await controllerItems(host)) {
-				const sessionId = item?.sessionId;
-				if (typeof sessionId === "string") out.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) {
-				const summary = summaries.find((item) => item.sessionId === id)?.summary;
-				if (summary === void 0) continue;
-				try {
-					host.emit("api-session/added", JSON.parse(JSON.stringify(summary)));
-				} catch {}
-			}
-		},
-		/** 官方 `unarchiveSession(sessionId)`：未归档是幂等 no-op。 */
-		async unarchive(sessionId) {
-			await registry.unarchiveSession(sessionId);
-		},
-		/** 摘账本：实体方法 `detachSession`（顶层没有）；未知工作区**响亮失败**，不静默当成功。 */
-		async detach(sessionId, workspaceId) {
-			const workspace = registry.get(workspaceId);
-			if (workspace === void 0) throw new Error(`workspace not found (detach): ${workspaceId}`);
-			await workspace.detachSession(sessionId);
-		},
-		/** 挂账本：实体方法 `attachSession`（顶层没有）。 */
-		async attach(sessionId, workspaceId) {
-			const workspace = registry.get(workspaceId);
-			if (workspace === void 0) throw new Error(`workspace not found (attach): ${workspaceId}`);
-			await workspace.attachSession(sessionId);
-		},
-		/** 确保归档：官方 `archiveSession(sessionId)`。归档是 registry **全局**的，与工作区账目无关
-		*  （JSDoc 原文 "its workspace accounting — or lack of one — is irrelevant"），所以 `workspaceId` 不用
-		*  ——未分组的会话没有工作区可传，签名里它是可选的。
-		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，设计稿 §6）。 */
-		async archive(sessionId) {
-			await registry.archiveSession(sessionId);
-		},
-		/**
-		* 官方 `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` 直接查得到）。
-		*/
-		async subagentCounts(parentIds) {
-			const wanted = [];
-			for (const id of parentIds) if (id.length > 0 && !wanted.includes(id)) wanted.push(id);
-			if (wanted.length === 0) return {};
-			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.filterSessions !== "function") return {};
-			const children = await descendantsByParent(sessionQuery, wanted);
-			const counts = {};
-			for (const id of wanted) {
-				const n = subtreeOf(children, bareSessionId(id)).length;
-				if (n > 0) counts[id] = n;
-			}
-			return counts;
-		},
-		/**
-		* 删除要一起带走**整个组**，先得把他们点出来：身份取宿主自己记录里的 `header.id`，项目目录由
-		* `header.cwd` 走同一个 `projectKey`（与 {@link HostPort.projectDirOf} 同一根算法，不另起一套）。
-		* 交回的是**全部后代**——孙代跟着父一起进回收站（issue #1），顺序是逐层往下问出来的（近的先）。
-		* `header.id` 缺席的后代直接跳过——不拿目录名冒充身份（冒充了会把一个来路不明的目录搬进回收站）。
-		* 服务没挂回 `[]` ⇒ 删除照旧只管父，不因此失败（父的删除本来就已经是完整的一件事）。
-		*/
-		async subagentMembers(sessionId) {
-			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.filterSessions !== "function") return [];
-			return subtreeOf(await descendantsByParent(sessionQuery, [sessionId]), bareSessionId(sessionId)).map((d) => ({
-				sessionId: d.id,
-				projectDir: d.projectDir
-			}));
-		}
-	};
+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
@@ -971,11 +1042,11 @@ function createHostPort(ctx) {
 * 对账与删除/恢复/彻底删除都是"读清单 + 动文件 + 写清单"的多步，交错跑会互相踩——删除刚把目录搬进
 * 回收站、行还没写上时，对账抢先把这行按目录"重建"出来，随后又被真实行覆盖成降级元数据。
 */
-/** 目录名是不是一条条目 id（形状契约在 `entry.ts`：`<删除时刻UTC>-<原目录名>`）。 */
+/** 目录名是不是一条条目 id（形状契约在 `entry.ts`：`<删除时刻UTC>-<原目录名>`；
+*  原目录名还必须能安全地拼回磁盘路径——带分隔符的名字仍按"外人"跳过，不让一次对账读崩）。 */
 function isEntryId(name) {
 	try {
-		parseEntryId(name);
-		return true;
+		return isSinglePathSegment(parseEntryId(name).sessionDirName);
 	} catch {
 		return false;
 	}
@@ -1031,7 +1102,7 @@ async function buildEntry(deps, id) {
 /** 对账并回清单——**返回的就是修好之后的那份**（与 `manifest.list()` 同序：最近删除在前）。 */
 async function reconcileTrash(deps) {
 	const rows = await deps.manifest.list();
-	const root = `${deps.home}/session-trash`;
+	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);
@@ -1042,120 +1113,90 @@ async function reconcileTrash(deps) {
 		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/purge-trash.ts
-function purgeTrash(deps) {
-	return async function purgeTrash(entryId, snapshot) {
-		const all = snapshot ?? await deps.manifest.list();
-		const targets = entryId ? all.filter((e) => e.id === entryId || e.parentEntryId === entryId) : [...all];
-		if (entryId && targets.length === 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		let freedBytes = 0;
-		for (const entry of targets) {
-			const dir = trashDirOf(entry.id, deps.home);
-			if (await deps.fs.exists(dir)) {
-				freedBytes += await deps.fs.sizeOfDir(dir);
-				await deps.fs.removeDir(dir).catch((error) => {
-					throw verbError("io", `删除回收站目录失败：${String(error)}`, error);
-				});
-			}
-			await deps.manifest.remove(entry.id);
-			const at = all.indexOf(entry);
-			if (at >= 0) all.splice(at, 1);
-			if (await deps.host.evictLive(entry.sessionId) !== "unknown") await deps.host.announceRemoved(entry.sessionId);
-		}
-		return {
-			removed: targets.length,
-			freedBytes
-		};
-	};
+	}
+	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/restore-session.ts
+//#region src/verbs/member-journal.ts
 /**
-* 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
-* 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
+* 一次成员移动 = 一串**自带反向动作的步骤**（ADR-0002）。
 *
-* 三段与删除对称：
-* ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
-*    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
-*    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
-* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行 → 通告回来。
-* ③ 中途失败把这个成员自己退回回收站（就地回滚），并把**已经恢复完的**兄弟按相反顺序一起退回，失败照抛。
+* 为什么需要它：`delete-session.ts` 的 `moveOneIn`/`undoOneIn` 与 `restore-session.ts` 的 `restoreOne`
+* （含它的反向闭包）互为镜像，各自手写了三到四段嵌套 `try/catch`：全仓 `rollbackReason(` **22 处**、
+* `withRollbackFailures(` **8 处**。那不是"回滚值得自己的候选"，而是**同一条正反动作对被写了两遍**。
+*
+* 这里独占四件事，三个动词各自只声明"这次要做哪几步、每步怎么退"：
+* ① **相反顺序**退化（最后做成的先退）；
+* ② 一步失败时把**已经做成的**那些退回去；
+* ③ 失败收集：某一步退不干净时**不让原错误独走**（`details.rollbackFailures`，见 `verbs/errors.ts`）；
+* ④ **非原子步骤**：`undoOnFailure` 让"这一步自己失败了"也跑它的反向动作（例如"取消归档"半做完了，
+*    得先把会话重新藏回去）。
+*
+* 边界：它只服务"成员在 `sessions/` 与 `session-trash/` 之间搬"这一件事。做成通用撤销框架就会吸进
+* 不属于它的知识（谁该通告、通告几次、哪些失败算成功）。
 */
-function restoreSession(deps) {
-	return async function restoreSession(entryId, options = {}) {
-		const all = options.snapshot ?? await deps.manifest.list();
-		const target = all.find((e) => e.id === entryId);
-		if (!target) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		const group = target.parentEntryId === void 0 ? [target, ...all.filter((e) => e.parentEntryId === target.id)] : [target];
-		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}`);
+/** 已经把某个前缀做成了的 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());
 		}
-		const done = [];
-		const restored = [];
-		try {
-			for (const entry of group) {
-				done.push(await restoreOne(deps, entry));
-				restored.push(entry.sessionId);
+		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);
 			}
-		} catch (error) {
-			for (const undo of done.reverse()) await undo();
-			throw error;
+		},
+		undo() {
+			return undoAll();
 		}
-		if (options.suppressAnnounce !== true) await deps.host.announceRestoredBatch(restored);
-		return target;
 	};
 }
-/** 放回哪儿：用**删除时记进 entryId 的那段原目录名**，不从 `sessionId` 现推（设计稿 §3）——
-*  因此不依赖宿主当时的目录命名约定（v3 无前缀 / v4 带 `session-` 前缀）。 */
-function restoreTargetDir(deps, entry) {
-	return sessionDirOf(entry.projectDir, parseEntryId(entry.id).sessionDirName, deps.home);
-}
-/** 恢复一个成员，交回它的反向动作。 */
-async function restoreOne(deps, entry) {
-	const trashDir = trashDirOf(entry.id, deps.home);
-	const sessionDir = restoreTargetDir(deps, entry);
-	await deps.fs.rename(trashDir, sessionDir).catch((error) => {
-		throw verbError("io", `放回会话目录失败：${String(error)}`, error);
-	});
-	if (entry.workspaceId !== "") try {
-		await deps.host.attach(entry.sessionId, entry.workspaceId);
-	} catch (error) {
-		await deps.fs.rename(sessionDir, trashDir).catch(() => {});
-		throw verbError("io", `挂回账本失败：${String(error)}`, error);
-	}
-	if (!entry.wasArchived) try {
-		await deps.host.unarchive(entry.sessionId);
-	} catch (error) {
-		await deps.host.archive(entry.sessionId, entry.workspaceId || void 0).catch(() => {});
-		if (entry.workspaceId !== "") await deps.host.detach(entry.sessionId, entry.workspaceId).catch(() => {});
-		await deps.fs.rename(sessionDir, trashDir).catch(() => {});
-		throw verbError("io", `取消归档失败：${String(error)}`, error);
-	}
+/** 跑一步反向动作并把它自己的失败收成一条原因（不抛：这些失败由调用方汇总成 `rollbackFailures`）。 */
+async function attempt(label, run) {
 	try {
-		await deps.manifest.remove(entry.id);
+		await run();
+		return [];
 	} catch (error) {
-		if (!entry.wasArchived) await deps.host.archive(entry.sessionId, entry.workspaceId || void 0).catch(() => {});
-		if (entry.workspaceId !== "") await deps.host.detach(entry.sessionId, entry.workspaceId).catch(() => {});
-		await deps.fs.rename(sessionDir, trashDir).catch(() => {});
-		throw verbError("io", `摘回收站条目失败：${String(error)}`, error);
+		return [rollbackReason(label, error)];
 	}
-	return async () => {
-		await deps.manifest.add(entry).catch(() => {});
-		if (!entry.wasArchived) await deps.host.archive(entry.sessionId, entry.workspaceId || void 0).catch(() => {});
-		if (entry.workspaceId !== "") await deps.host.detach(entry.sessionId, entry.workspaceId).catch(() => {});
-		await deps.fs.rename(sessionDir, trashDir).catch(() => {});
-		if (await deps.host.evictLive(entry.sessionId).catch(() => "unknown") !== "unknown") await deps.host.announceRemoved(entry.sessionId).catch(() => {});
-	};
+}
+/**
+* **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
+* `details.rollbackFailures`，绝不让原错误独走（设计稿第十七批）。删除与恢复两个按组走的动词
+* 共用这一处——"相反顺序 + 失败合并"不再各写一遍。
+*/
+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) {
+	const raw = error?.code;
+	if (typeof raw === "string" && raw.startsWith(`sessiondelete/`)) return error;
+	return verbError("io", `${step.label}：${String(error)}`, error);
 }
 //#endregion
 //#region src/verbs/delete-session.ts
@@ -1167,13 +1208,15 @@ async function restoreOne(deps, entry) {
 * 三段，顺序承重：
 * ① **先点组、先验活体**（一个字节都不写）。任一成员在跑就整组拒绝——不替用户终止正在跑的活，
 *    也绝不允许"父已经搬进回收站、孩子因为在跑而搬不动"这种半套。
-* ② **逐个搬**：每个成员内部沿用原来那套顺序与就地回滚（归档 → 摘账本 → 搬目录 → 写清册），
-*    任何一步失败就把这个成员自己退回原地。
+* ② **逐个搬**：每个成员是一份 `journal`（`verbs/member-journal.ts`），搬不动时 journal 自己把
+*    这个成员已经做成的步骤退回去。
 * ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
 *    账本跟着挂、可见性跟着还原），失败照抛——不留"半组在回收站、半组在原地"的世界。
+*
+* interface 只有**一个 id**：批量的性质不在这里（同批"已被前一条带走"的判据归 `verbs/batch.ts`）。
 */
 function deleteSession(deps) {
-	return async function deleteSession(sessionId, options = {}) {
+	return async function deleteSession(sessionId) {
 		const kids = await deps.host.subagentMembers(sessionId);
 		const parentProjectDir = await deps.host.projectDirOf(sessionId);
 		if (parentProjectDir === void 0) throw verbError("not-found", `宿主的持久化里没有这个会话：${sessionId}`);
@@ -1195,111 +1238,538 @@ function deleteSession(deps) {
 			sessionId: kid.sessionId,
 			projectDir: kid.projectDir
 		});
-		options.onMembers?.(members.map((member) => member.sessionId));
 		const deletedAt = deps.now();
 		const done = [];
 		let parentEntry;
 		try {
 			for (const member of members) {
 				const isParent = member.sessionId === sessionId;
-				const entry = await moveOneIn(deps, member, deletedAt, isParent ? void 0 : parentEntry.id);
-				if (isParent) parentEntry = entry;
-				done.push(() => undoOneIn(deps, entry));
+				const move = await memberMove(deps, member, deletedAt, isParent ? void 0 : parentEntry.id);
+				if (isParent) parentEntry = move.entry;
+				await move.journal.run();
+				done.push(move.journal);
 			}
 		} catch (error) {
-			for (const undo of done.reverse()) await undo();
-			throw error;
+			await rollbackJournals(done, error);
 		}
 		return parentEntry;
 	};
 }
 /**
-* 搬一个成员进回收站。五件写的顺序照设计稿 §4 那五触点，每一步的失败都**就地**把这个成员自己退回原地：
-* 归档必须先于摘账本（否则中间有一段"无主且可见"的窗口，它会掉进「未分组」），文件在两件纯读之后，
-* 清册行是最后一件写（它失败就把目录挪回去、账本挂回去、可见性还原）。
+* 一个成员要做的步骤（顺序承重，照设计稿 §4 那五触点）：
+* 读现场（两件纯读）→ 归档 → 摘账本 → 搬目录 → 写清册行。
+*
+* 每一步的反向动作都是"把这件写退回原样"；**清册行是最后一件写**，它失败时 journal 会把目录搬回去、
+* 账本挂回去、可见性还原。清册行的反向动作带一道闸：**回收站目录还没搬回来就不摘那一行**——
+* 留着行至少元数据还在（与旧实现"目录退不回就不摘行"同一条判据）。
 */
-async function moveOneIn(deps, member, deletedAt, parentEntryId) {
+async function memberMove(deps, member, deletedAt, parentEntryId) {
 	const { sessionId, projectDir } = member;
 	const workspaceId = await deps.host.workspaceOf(sessionId);
 	const sessionDir = sessionDirOf(projectDir, sessionId, deps.home);
 	const wasArchived = await deps.host.isArchived(sessionId);
-	const entryId = makeEntryId(deletedAt, sessionId);
-	const trashDir = trashDirOf(entryId, deps.home);
-	let title;
-	let sizeBytes;
-	try {
-		title = await deps.host.titleOf(sessionId);
-		sizeBytes = await deps.fs.sizeOfDir(sessionDir);
-	} catch (error) {
-		throw verbError("io", `读取会话现场失败：${String(error)}`, error);
-	}
-	if (!wasArchived) try {
-		await deps.host.archive(sessionId, workspaceId ?? void 0);
-	} catch (error) {
-		throw verbError("io", `归档失败：${String(error)}`, error);
-	}
-	if (workspaceId !== void 0) try {
-		await deps.host.detach(sessionId, workspaceId);
-	} catch (error) {
-		if (!wasArchived) await deps.host.unarchive(sessionId).catch(() => {});
-		throw verbError("io", `摘账本失败：${String(error)}`, error);
-	}
+	const trashDir = trashDirOf(makeEntryId(deletedAt, sessionId), deps.home);
 	const entry = {
-		id: entryId,
+		id: makeEntryId(deletedAt, sessionId),
 		sessionId,
 		projectDir,
 		workspaceId: workspaceId ?? "",
 		wasArchived,
 		deletedAt,
-		title,
-		sizeBytes,
+		title: "",
+		sizeBytes: 0,
 		...parentEntryId === void 0 ? {} : { parentEntryId }
 	};
-	try {
-		await deps.fs.ensureDir(`${deps.home}/session-trash`);
-		await deps.fs.rename(sessionDir, trashDir);
-	} catch (error) {
-		if (workspaceId !== void 0) await deps.host.attach(sessionId, workspaceId).catch(() => {});
-		if (!wasArchived) await deps.host.unarchive(sessionId).catch(() => {});
-		throw verbError("io", `移动会话目录失败：${String(error)}`, error);
+	/** 目录真的搬进回收站了吗——决定那一步的反向动作有没有东西可退。 */
+	let moved = false;
+	/** 回滚的三件写是否都真正退回原样：目录、账本、可见性。`announceRestored` 只在这三件都成立时发。 */
+	let movedBack = false;
+	let workspaceBack = workspaceId === void 0;
+	let visibleBack = wasArchived;
+	const journal = createJournal([
+		{
+			label: "读取会话现场失败",
+			run: async () => {
+				entry.title = await deps.host.titleOf(sessionId);
+				entry.sizeBytes = await deps.fs.sizeOfDir(sessionDir);
+			}
+		},
+		...wasArchived ? [] : [{
+			label: "归档失败",
+			run: async () => {
+				await deps.host.archive(sessionId, workspaceId);
+			},
+			undo: async () => {
+				return await attempt("可见性还原失败", async () => {
+					await deps.host.unarchive(sessionId);
+					visibleBack = true;
+				});
+			}
+		}],
+		...workspaceId === void 0 ? [] : [{
+			label: "摘账本失败",
+			run: async () => {
+				await deps.host.detach(sessionId, workspaceId);
+			},
+			undo: async () => {
+				return await attempt("账本挂回失败", async () => {
+					await deps.host.attach(sessionId, workspaceId);
+					workspaceBack = true;
+				});
+			}
+		}],
+		{
+			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);
+				}
+			},
+			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;
+			}
+		}
+	]);
+	return {
+		entry,
+		journal: {
+			async run() {
+				await journal.run();
+				if (await deps.host.evictLive(sessionId) !== "unknown") await deps.host.announceRemoved(sessionId);
+			},
+			/** 组级回滚：先把成员自己的步骤按相反顺序退回，再在**三件写都真正回去**时补一条"已恢复"通告。
+			*  这一行此前已经收过 `api-session/removed`；不发"回来了"它就会在客户端消失到重连为止。
+			*  目录没退回、账本没挂回、或可见性没还原 ⇒ 不发——那会是假话（同 restore 侧 `movedBack` 的判据）。 */
+			async undo() {
+				const failures = await journal.undo();
+				if (movedBack && workspaceBack && visibleBack) await deps.host.announceRestored(sessionId).catch(() => {});
+				return failures;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/verbs/orphan-subagents.ts
+/** 成员的盘上目录与字节（扫描、清单装配与 purge 共用这一条路径/存在性/度量口径；
+*  目录缺席回 `undefined`，不拿一份"记录还在、盘上已经没了"的旧读数冒充盘上残留）。 */
+async function measureMemberDir(deps, member) {
+	const dir = sessionDirOf(member.projectDir, member.sessionId, deps.home);
+	if (!await deps.fs.exists(dir)) return void 0;
+	return {
+		dir,
+		bytes: await deps.fs.sizeOfDir(dir)
+	};
+}
+/** 把一组成员折成"删之前要记下的计划"；目录不在的成员跳过（记录与盘不一致是那条成员自己的事）。
+*  `purge` 的盘上后代与 `orphan-clean` 的整组都走这一处，别再各写一遍 measure + workspaceOf。 */
+async function planMemberRemovals(deps, members) {
+	const plans = [];
+	for (const member of members) {
+		const measured = await measureMemberDir(deps, member);
+		if (measured === void 0) continue;
+		const workspaceId = await deps.host.workspaceOf(member.sessionId);
+		plans.push({
+			sessionId: member.sessionId,
+			...measured,
+			...workspaceId === void 0 ? {} : { workspaceId }
+		});
 	}
-	try {
-		await deps.manifest.add(entry);
-	} catch (error) {
-		await deps.fs.rename(trashDir, sessionDir).catch(() => {});
-		if (workspaceId !== void 0) await deps.host.attach(sessionId, workspaceId).catch(() => {});
-		if (!wasArchived) await deps.host.unarchive(sessionId).catch(() => {});
-		throw verbError("io", `登记回收站条目失败：${String(error)}`, error);
+	return plans;
+}
+/**
+* 无主子会话 = `origin:"subagent"`、父**既不在当前语料（live ∪ persisted）也不在回收站清册里**的会话。
+*
+* 为什么清册里的父不算孤儿：那种是 **stranded**——父还在回收站里等着，孩子本该跟着父一起恢复或一起
+* 彻底删除（10-15 稿 §11 的组语义），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
+* 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
+*
+* 根按**传递闭包**收全部后代（与 `HostPort.subagentCounts` 同一口径：孩子与孙代都算，深度不设上限），
+* 同一条记录只归一组（`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
+* 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
+*/
+function orphanGroupsOf(corpus, trashSessionIds) {
+	const known = /* @__PURE__ */ new Set();
+	for (const session of corpus) known.add(bareSessionId(session.sessionId));
+	for (const id of trashSessionIds) known.add(bareSessionId(id));
+	const children = /* @__PURE__ */ new Map();
+	for (const session of corpus) {
+		const parent = session.parentSessionId;
+		if (parent === void 0) continue;
+		const key = bareSessionId(parent);
+		const list = children.get(key);
+		if (list === void 0) children.set(key, [session]);
+		else list.push(session);
+	}
+	const claimed = /* @__PURE__ */ new Set();
+	const groups = [];
+	for (const session of corpus) {
+		const parent = session.parentSessionId;
+		if (!session.subagent || parent === void 0) continue;
+		if (known.has(bareSessionId(parent))) continue;
+		if (claimed.has(bareSessionId(session.sessionId))) continue;
+		const members = [];
+		const queue = [session];
+		for (let i = 0; i < queue.length; i += 1) {
+			const current = queue[i];
+			const id = bareSessionId(current.sessionId);
+			if (claimed.has(id)) continue;
+			claimed.add(id);
+			members.push(current);
+			for (const child of children.get(id) ?? []) queue.push(child);
+		}
+		groups.push({
+			root: session,
+			parentSessionId: parent,
+			members
+		});
+	}
+	return groups;
+}
+/** 纯读：调用方应先走一次 `/list` 对账（面板的 refresh 就是这样）；本函数不写清单。
+*  写动作 `orphan-clean` 会自己先 reconcile，避免拿一份过期清册判"父没了"。
+*
+*  `listSessions()` 回 `undefined` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
+*  拿 undefined 当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
+*  所以这里按 `io` 响亮失败（AGENTS.md：`undefined` 意味着服务缺席，扫描方不许冒充读数）。 */
+async function loadOrphanGroups(deps) {
+	const corpus = await deps.host.listSessions();
+	if (corpus === void 0) throw verbError("io", "无主子会话扫描需要宿主的 sessionQuery.listSessions");
+	const groups = orphanGroupsOf(corpus, (await deps.manifest.list()).map((entry) => entry.sessionId));
+	const out = [];
+	for (const group of groups) {
+		const members = [];
+		for (const member of group.members) {
+			const measured = await measureMemberDir(deps, member);
+			members.push({
+				sessionId: member.sessionId,
+				projectDir: member.projectDir,
+				bytes: measured?.bytes ?? 0
+			});
+		}
+		out.push({
+			root: members[0],
+			parentSessionId: group.parentSessionId,
+			members
+		});
+	}
+	return out;
+}
+/** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
+*  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
+function reportOrphans(groups) {
+	const projects = /* @__PURE__ */ new Map();
+	let totalSessions = 0;
+	let totalBytes = 0;
+	for (const group of groups) for (const member of group.members) {
+		totalSessions += 1;
+		totalBytes += member.bytes;
+		const row = projects.get(member.projectDir) ?? {
+			sessions: 0,
+			bytes: 0
+		};
+		row.sessions += 1;
+		row.bytes += member.bytes;
+		projects.set(member.projectDir, row);
 	}
-	if (await deps.host.evictLive(sessionId) !== "unknown") await deps.host.announceRemoved(sessionId);
-	return entry;
-}
-/** 把一个**已经搬进去**的成员退回删除前：目录 → 账本 → 可见性 → 清册行 → 通告回来。 */
-async function undoOneIn(deps, entry) {
-	const sessionDir = sessionDirOf(entry.projectDir, entry.sessionId, deps.home);
-	await deps.fs.rename(trashDirOf(entry.id, deps.home), sessionDir).catch(() => {});
-	if (entry.workspaceId !== "") await deps.host.attach(entry.sessionId, entry.workspaceId).catch(() => {});
-	if (!entry.wasArchived) await deps.host.unarchive(entry.sessionId).catch(() => {});
-	await deps.manifest.remove(entry.id).catch(() => {});
-	await deps.host.announceRestored(entry.sessionId).catch(() => {});
+	return {
+		roots: groups.map((group) => group.root.sessionId),
+		totalSessions,
+		totalBytes,
+		missingParents: new Set(groups.map((group) => bareSessionId(group.parentSessionId))).size,
+		groups: [...projects].map(([projectDir, value]) => ({
+			projectDir,
+			...value
+		})).sort((a, b) => b.bytes - a.bytes)
+	};
+}
+/**
+* 清一组：先**整组 live 准入（零写）**，再收集目录/字节/账本归属，再 unarchive → detach → 删目录。
+* 任何 preflight 失败都在第一件写之前抛出；删目录到一半失败时**已删目录不回滚**，失败错误的
+* `details` 带 `{ removed, freedBytes, failedSessionId }` 作为部分回执（不伪装成整组没动）。
+* 删目录之后照 purge 的规矩摘活体并如实通告。不碰投影缓存与附件。
+*
+* 顺序与删除那一半是**对偶**的，但不是照抄：
+* - 删除要先把会话藏起来（归档）再摘账本，免得中间那一拍它掉进「未分组」；这里目录是**删掉**不是搬走，
+*   藏不藏都不影响可见性 ⇒ 归档集反而是**在写之前整批摘掉**的：失败时目录还在，下一次还能重试，
+*   不会留下"会话没了但还在归档集里挂着"的幽灵 id。
+* - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以不需要删除侧那次
+*   `wasArchived` 读——这里没有"还原到删除前"的义务。
+* - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
+* - `evictLive` 的三态照 `HostPort.evictLive` 的契约：`unknown` 时**不通告**（发了就是假话），
+*   `evicted` / `not-live` 才发 `api-session/removed`。冷会话没有活体可摘，通告照样必须发。
+*/
+async function cleanOrphanGroup(deps, group) {
+	for (const member of group.members) if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
+	const plans = await planMemberRemovals(deps, group.members);
+	for (const member of group.members) await deps.host.unarchive(member.sessionId);
+	for (const plan of plans) if (plan.workspaceId !== void 0) await deps.host.detach(plan.sessionId, plan.workspaceId);
+	let removed = 0;
+	let freedBytes = 0;
+	for (const plan of plans) {
+		try {
+			await deps.fs.removeDir(plan.dir);
+		} catch (error) {
+			throw verbError("io", `删除会话目录失败：${String(error)}`, error, {
+				removed,
+				freedBytes,
+				failedSessionId: plan.sessionId
+			});
+		}
+		removed += 1;
+		freedBytes += plan.bytes;
+		if (await deps.host.evictLive(plan.sessionId) !== "unknown") await deps.host.announceRemoved(plan.sessionId);
+	}
+	return {
+		removed,
+		freedBytes
+	};
+}
+//#endregion
+//#region src/verbs/purge-trash.ts
+/**
+* 彻底删除：从回收站里**真的**抹掉一条（或整组、或整站），并连带那些"还留在盘上、没被带走"的后代。
+*
+* 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
+* 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
+*
+* **这条动词不做回滚**：目录删掉就没有"退回去"这回事（设计稿第十七批：删到一半失败时已删目录不回滚；
+* 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
+* 所以它的 journal 只有正向步骤、没有 `undo`——顺序仍由 journal 统一表达，不再是手写的四段 `try/catch`。
+*/
+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}`);
+		const manifestIds = new Set(targets.map((entry) => bareSessionId(entry.sessionId)));
+		const membersByParent = await deps.host.subagentMembersBatch(targets.map((entry) => entry.sessionId));
+		const seenDisk = /* @__PURE__ */ new Set();
+		/** 先只做准入与去重（全部是读），整组通过后再量目录/账本——任一成员在跑时一件计划都还没做。 */
+		const candidates = [];
+		for (const entry of targets) for (const member of membersByParent[entry.sessionId] ?? []) {
+			const bare = bareSessionId(member.sessionId);
+			if (manifestIds.has(bare) || seenDisk.has(bare)) continue;
+			seenDisk.add(bare);
+			if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
+			candidates.push(member);
+		}
+		const diskPlans = await planMemberRemovals(deps, candidates);
+		let freedBytes = 0;
+		let removed = 0;
+		await createJournal([
+			{
+				label: "取消归档失败",
+				run: async () => {
+					for (const entry of targets) await deps.host.unarchive(entry.sessionId);
+					for (const plan of diskPlans) await deps.host.unarchive(plan.sessionId);
+				}
+			},
+			{
+				label: "摘账本失败",
+				run: async () => {
+					for (const plan of diskPlans) if (plan.workspaceId !== void 0) await deps.host.detach(plan.sessionId, plan.workspaceId);
+				}
+			},
+			{
+				label: "删除回收站目录失败",
+				run: async () => {
+					for (const entry of targets) {
+						const dir = trashDirOf(entry.id, deps.home);
+						if (await deps.fs.exists(dir)) {
+							freedBytes += await deps.fs.sizeOfDir(dir);
+							await deps.fs.removeDir(dir);
+						}
+						await deps.manifest.remove(entry.id);
+						removed += 1;
+						if (await deps.host.evictLive(entry.sessionId) !== "unknown") await deps.host.announceRemoved(entry.sessionId);
+					}
+				}
+			},
+			{
+				label: "删除盘上后代目录失败",
+				run: async () => {
+					for (const plan of diskPlans) {
+						await deps.fs.removeDir(plan.dir);
+						removed += 1;
+						freedBytes += plan.bytes;
+						if (await deps.host.evictLive(plan.sessionId) !== "unknown") await deps.host.announceRemoved(plan.sessionId);
+					}
+				}
+			}
+		]).run();
+		return {
+			removed,
+			freedBytes
+		};
+	};
+}
+//#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 进、回收站那一行出"，没有批量专用的开关。
+*/
+function restoreSession(deps) {
+	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);
+		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, entry);
+				await move.journal.run();
+				done.push(move.journal);
+			}
+		} catch (error) {
+			await rollbackJournals(done, error);
+		}
+		return target;
+	};
+}
+/** 放回哪儿：用**删除时记进 entryId 的那段原目录名**，不从 `sessionId` 现推（设计稿 §3）——
+*  因此不依赖宿主当时的目录命名约定（v3 无前缀 / v4 带 `session-` 前缀）。 */
+function restoreTargetDir(deps, entry) {
+	return sessionDirOf(entry.projectDir, parseEntryId(entry.id).sessionDirName, deps.home);
+}
+/**
+* 这一次恢复**到底挂不挂账本**：交出能挂的那个 `workspaceId`，挂不了就 `undefined`。
+*
+* 两种缺席是同一件事：空串 = 删除时它就没有账目（「未分组」的会话）；非空但账本里已经没它 =
+* 宿主的「删除工作区」只删注册、保留目录与每一份日志，那些会话之后本来就在「未分组」下。
+* 恢复不该为了挂一个不存在的账本把整条退回回收站。
+*
+* 判据**只有这一处**：`memberRestore` 拿它决定挂不挂，`GET /list` 拿它决定行上那句「原工作区已不存在，
+* 恢复后归入未分组」说不说。两边各问一遍就会有一天一个说、一个不挂。
+*/
+async function attachableWorkspaceId(host, entry) {
+	if (entry.workspaceId === "") return void 0;
+	return await host.workspaceExists(entry.workspaceId) ? entry.workspaceId : void 0;
+}
+/** 这一条记着的工作区**是不是已经没了**（区别于"删除时它就没有账目"的空串）——清单行据此决定
+*  要不要在点之前说那句「原工作区已不存在，恢复后归入未分组」。由 {@link attachableWorkspaceId}
+*  派生，不另起一份判据：那样会有一天一个说、一个不挂。 */
+async function isWorkspaceMissing(host, entry) {
+	return entry.workspaceId !== "" && await attachableWorkspaceId(host, entry) === void 0;
+}
+/**
+* 一个成员的恢复步骤（顺序与删除相反）：放回目录 → 挂账本 → 还原可见性 → 摘清册行。
+*
+* 账本那一步有个**只认端口那句**的兜底：查过之后、挂之前账本被删掉（宿主的「删除工作区」与这次恢复
+* 撞上）⇒ 按未分组收、不回滚；**别的**失败是真故障，照旧抛（吞掉它就等于把一次存储故障伪装成"未分组"）。
+*/
+async function memberRestore(deps, entry) {
+	const trashDir = trashDirOf(entry.id, deps.home);
+	const sessionDir = restoreTargetDir(deps, entry);
+	const workspaceId = await attachableWorkspaceId(deps.host, entry);
+	/** 真挂上了账本才记下那个 id——回滚里"摘账本"那一步只对挂过的成员存在。 */
+	let attached = false;
+	/** 组级回滚时，目录真的退回回收站了才通告「已移除」（否则那条通告会骗客户端删掉一行还在盘上的会话）。 */
+	let movedBack = false;
+	const journal = createJournal([
+		{
+			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;
+			}
+		},
+		...workspaceId === void 0 ? [] : [{
+			label: "挂回账本失败",
+			run: async () => {
+				try {
+					await deps.host.attach(entry.sessionId, workspaceId);
+					attached = true;
+				} catch (error) {
+					if (!isWorkspaceMissingError(error) || await deps.host.workspaceExists(workspaceId)) throw error;
+				}
+			},
+			undo: async () => attached ? attempt("摘账本失败", () => deps.host.detach(entry.sessionId, workspaceId)) : []
+		}],
+		...entry.wasArchived ? [] : [{
+			label: "取消归档失败",
+			undoOnFailure: true,
+			run: async () => {
+				await deps.host.unarchive(entry.sessionId);
+			},
+			undo: () => attempt("重新归档失败", () => deps.host.archive(entry.sessionId, workspaceId))
+		}],
+		{
+			label: "摘回收站条目失败",
+			run: async () => {
+				await deps.manifest.remove(entry.id);
+			},
+			undo: () => attempt("清册行写回失败", () => deps.manifest.add(entry))
+		}
+	]);
+	return { journal: {
+		run: () => journal.run(),
+		async undo() {
+			const failures = await journal.undo();
+			if (movedBack) {
+				if (await deps.host.evictLive(entry.sessionId).catch(() => "unknown") !== "unknown") await deps.host.announceRemoved(entry.sessionId).catch(() => {});
+			}
+			return failures;
+		}
+	} };
 }
 //#endregion
-//#region src/verbs/apply.ts
+//#region src/verbs/batch.ts
 /**
-* 批量动作（2026-10-17 重构批）：`POST /apply` 的落点——**一组 id 上的同一个动作**。
+* **「这一批」的唯一拥有者**（ADR-0002）：`POST /apply` 的落点——一组 id 上的同一个动作。
+*
+* 五个动作：`delete` / `restore` / `purge` / `count` / `orphan-clean`。
 *
-* 为什么要这一层：批量恢复 100+ 条的真实成本不在搬文件，在**每条一次的全表读**——旧形状是
-* 浏览器半循环 N 次 HTTP，每次都走「读全量清册 + 预检 + 逐成员通告时再拉一遍宿主会话表」。
-* 这一层把整批抬成一次：清册只读一次、宿主会话表只预取一次、通告一次批量发；
-* 单条动作就是 N=1 的批量，**仓里不再留第二条执行路径**。
+* 为什么批量要有自己的 module：批量是**请求**的性质，不是某一条动词的性质。此前它长在三个动词的
+* interface 上（`onMembers` / `snapshot` / `suppressAnnounce`），于是每个动词都得知道"我是第几个、
+* 前面的兄弟带走了谁"，同一个事实还有三种机制（回调、调用方 `taken` 集合、动词就地收缩数组）。
 *
-* 三条批量语义（都是接口的一部分，不是实现细节）：
-* ① 输入去重、保持输入顺序（界面上"清单从上往下"的那一份读感）；
-* ② 一条失败不传染下一条——**逐条 try/catch**，失败按 `map-error` 那张表折成信封里的
-*    `{code,message,details?}`；
-* ③ 「已被同批前一条带走」是**幂等成功**，不是失败：恢复一条已经跟着父回来的孩子，
-*    用户要的结果本来就已经达成了（`delete`/`restore` 回 `null`；`purge` 回
-*    `{removed:0,freedBytes:0}`）。
+* 这一层独占四件（每条批量语义都在这里）：
+* ① **去重保序**：输入顺序就是界面"清单从上往下"的读感；
+* ② **清册快照**：整批只读一次"最初的样子"，用来判断"已被同批前一条带走"；
+* ③ **逐条信封**：一条失败不传染下一条，失败按 `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` 的装配、与三个动词同一条。
 */
 function failure(id, action, error) {
 	return {
@@ -1318,21 +1788,118 @@ function success(id, action, value) {
 		value
 	};
 }
-/** 清册快照里"这条 id 还认得出一个组吗"：父行在、或它是某个还在的父亲的孩子，都算在。 */
-function groupOf(snapshot, id) {
-	const root = snapshot.find((e) => e.id === id);
-	if (root !== void 0) return root.parentEntryId === void 0 ? [root, ...snapshot.filter((e) => e.parentEntryId === id)] : [root];
-	const kids = snapshot.filter((e) => e.parentEntryId === id);
-	return kids.length > 0 ? kids : [];
+/** 去重且保持输入顺序（重复 id 跑第二遍是"幂等成功"的伪装，不该发生）。 */
+function unique(ids) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const id of ids) {
+		if (seen.has(id)) continue;
+		seen.add(id);
+		out.push(id);
+	}
+	return out;
+}
+/**
+* 一条 id 一条结果：**这是批量唯一的形式**（单条就是长度为 1 的批量，仓里不留第二条执行路径）。
+* 动词只收一个 id、只吐一条结果；`try/catch` 在这一处，失败不传染下一条。
+*/
+async function forEachId(action, ids, run) {
+	const outcomes = [];
+	for (const id of unique(ids)) try {
+		outcomes.push(success(id, action, await run(id)));
+	} catch (error) {
+		outcomes.push(failure(id, action, error));
+	}
+	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();
+	return forEachId("delete", ids, async (sessionId) => {
+		const root = bareSessionId(sessionId);
+		if (carried.has(root)) return null;
+		const entry = await run(sessionId);
+		for (const row of groupOf(await deps.manifest.list(), entry.id)) if (bareSessionId(row.sessionId) !== root) carried.add(bareSessionId(row.sessionId));
+		return entry;
+	});
+}
+/** 「这条是不是被同批前一条带走了」：原始快照里认得出、当前快照里已经空了。
+*  **收缩归这一层**（动词只拿只读快照）——`apply` 整批只读一次清册，`takenByEarlierInBatch` 不比它多读。 */
+async function applyRestore(deps, ids) {
+	const original = await deps.manifest.list();
+	const current = [...original];
+	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);
+		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());
+	return outcomes;
+}
+async function applyPurge(deps, ids) {
+	const original = await deps.manifest.list();
+	const current = [...original];
+	const run = purgeTrash(deps);
+	return forEachId("purge", ids, async (entryId) => {
+		if (takenByEarlierInBatch(original, current, entryId)) return {
+			removed: 0,
+			freedBytes: 0
+		};
+		const group = groupOf(current, entryId);
+		const stats = await run(entryId, current);
+		shrink(current, group);
+		return stats;
+	});
+}
+/** 删除确认框那句「含 N 个子会话」：一次问完整批（`subagentCounts` 本来就是批量口）。
+*  宿主口缺席时它回 `{}`（这里折成 0）；真读失败则整次调用失败，浏览器半按"读不到"把整句不说。 */
+async function applyCount(deps, ids) {
+	const wanted = unique(ids);
+	const counts = await deps.host.subagentCounts(wanted);
+	return wanted.map((id) => success(id, "count", counts[id] ?? 0));
 }
 /**
-* 「这条是被**同批前一条**带走的，还是整批开始前就没有？」——幂等语义只属于前者。
-* 后来者本来就不在清册里（用户点了条幽灵 id、或对账刚摘掉它），必须照样响亮报 `trash-empty`，
-* 不能被"已被带走"这句话掩盖成一次成功。**所以判据是快照的原始形状，不是当前形状**：
-* 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+* 清一组无主子会话（父已被彻底删掉、孩子还留在 `sessions/` 里的那些）。id 是**根会话 id**——
+* 界面先 `GET /orphans` 拿 `roots` 再原样带回来，所以这里的 `not-found` 说的是"这句话已经过期了"
+* （父又被人放回回收站、组已被上一个请求带走，或另一处已经把目录清掉），不是"用户打错了一个 id"。
+* 根 id 两边都去 `session-` 前缀再比：报告原样回传是正常路径，外部调用带另一种写法也认。
+*
+* **这是写动作，排在到达序链上**，而且**先对账再扫**（2026-10-19）：判"父没了"用的是清册，而刚被人
+* 手工搬进 `session-trash/` 的那一格目录此刻可能还没有对应行——不对账就会把"父还在回收站里等着"的
+* 一组当成孤儿**直接删盘**，替用户做了一个没人点过的决定（那种组该跟着父恢复或彻底删除）。
+* 对账写在动词这一侧而不是只写在路由里，为的是 `apply` 的批量入口只有一个：链上的排队与这份快照
+* 谁也别想只占一半。
 */
-function takenByEarlierInBatch(original, current, id) {
-	return groupOf(original, id).length > 0 && groupOf(current, id).length === 0;
+async function applyOrphanClean(deps, ids) {
+	await reconcileTrash(deps);
+	const groups = await loadOrphanGroups(deps);
+	const byRoot = new Map(groups.map((group) => [bareSessionId(group.root.sessionId), group]));
+	const outcomes = [];
+	for (const id of unique(ids)) {
+		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;
 }
 function applyActions(deps, action, ids) {
 	switch (action) {
@@ -1340,98 +1907,270 @@ function applyActions(deps, action, ids) {
 		case "restore": return applyRestore(deps, ids);
 		case "purge": return applyPurge(deps, ids);
 		case "count": return applyCount(deps, ids);
+		case "orphan-clean": return applyOrphanClean(deps, ids);
 	}
 }
-async function applyDelete(deps, ids) {
-	const run = deleteSession(deps);
-	const outcomes = [];
-	const taken = /* @__PURE__ */ new Set();
-	for (const sessionId of unique(ids)) {
-		if (taken.has(sessionId)) {
-			outcomes.push(success(sessionId, "delete", null));
-			continue;
-		}
-		let members = [];
+const DEFAULT_LIMITS = {
+	perMessageChars: 3e3,
+	totalChars: 5e5
+};
+/** 一条记录里那些 `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();
+}
+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 dir = trashDirOf(record.id, deps.home);
+		if (!await deps.fs.exists(dir)) throw verbError("io", `回收站目录不在：${dir}`);
+		const names = await deps.fs.listFiles(dir);
+		const logName = pickSessionLog(names);
+		if (logName === void 0) throw verbError("io", `回收站目录里没有会话日志：${dir}（里面有：${names.join(", ") || "空目录"}）`);
+		let raw;
 		try {
-			const entry = await run(sessionId, { onMembers: (sessionIds) => {
-				members = sessionIds;
-			} });
-			for (const id of members) taken.add(id);
-			outcomes.push(success(sessionId, "delete", entry));
+			raw = await deps.fs.readFile(`${dir}/${logName}`);
 		} catch (error) {
-			outcomes.push(failure(sessionId, "delete", error));
+			throw verbError("io", `读会话日志失败：${String(error)}`, error);
 		}
-	}
-	return outcomes;
-}
-async function applyRestore(deps, ids) {
-	const snapshot = await deps.manifest.list();
-	const original = [...snapshot];
-	const run = restoreSession(deps);
-	const outcomes = [];
-	const restored = [];
-	for (const entryId of unique(ids)) {
-		const group = groupOf(snapshot, entryId);
-		if (group.length === 0 && takenByEarlierInBatch(original, snapshot, entryId)) {
-			outcomes.push(success(entryId, "restore", null));
-			continue;
+		const detail = {
+			entryId: record.id,
+			cwd: "",
+			createdAt: 0,
+			lastActivity: 0,
+			logTitle: "",
+			models: [],
+			turnCount: 0,
+			userMessageCount: 0,
+			assistantMessageCount: 0,
+			toolCallCount: 0,
+			injectedCount: 0,
+			messages: [],
+			omittedByPayloadCap: 0
+		};
+		const models = /* @__PURE__ */ new Set();
+		let usedChars = 0;
+		let capped = false;
+		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停。 */
+		function push(role, time, text) {
+			if (capped) {
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			const truncated = text.length > limits.perMessageChars;
+			const kept = truncated ? text.slice(0, limits.perMessageChars) : text;
+			if (usedChars + kept.length > limits.totalChars) {
+				capped = true;
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			usedChars += kept.length;
+			detail.messages.push({
+				role,
+				time,
+				text: kept,
+				truncated
+			});
 		}
 		try {
-			const entry = await run(entryId, {
-				snapshot,
-				suppressAnnounce: true
+			walkSessionLog(raw, (r) => {
+				if (typeof r.time === "number" && r.time > detail.lastActivity) detail.lastActivity = r.time;
+				const data = r.data ?? {};
+				switch (r.type) {
+					case "session":
+						if (typeof r.cwd === "string") detail.cwd = r.cwd;
+						if (typeof r.createdAt === "number") detail.createdAt = r.createdAt;
+						return;
+					case "session/title":
+						if (typeof data.title === "string") detail.logTitle = data.title;
+						return;
+					case "turn/start":
+						detail.turnCount += 1;
+						return;
+					case "tool/call":
+						detail.toolCallCount += 1;
+						return;
+					case "user/message": {
+						if ((data.source ?? {}).kind !== "user") {
+							detail.injectedCount += 1;
+							return;
+						}
+						const text = textOf(data.content);
+						if (text === "") return;
+						detail.userMessageCount += 1;
+						push("user", r.time ?? 0, text);
+						return;
+					}
+					case "assistant/message": {
+						const message = data.message ?? {};
+						const source = message.source ?? {};
+						if (typeof source.model === "string") models.add(source.model);
+						const text = textOf(message.content);
+						if (text === "") return;
+						detail.assistantMessageCount += 1;
+						push("assistant", r.time ?? 0, text);
+						return;
+					}
+					default: return;
+				}
 			});
-			restored.push(...(group.length > 0 ? group : [entry]).map((e) => e.sessionId));
-			for (const member of group.length > 0 ? group : [entry]) {
-				const at = snapshot.indexOf(member);
-				if (at >= 0) snapshot.splice(at, 1);
-			}
-			outcomes.push(success(entryId, "restore", entry));
 		} catch (error) {
-			outcomes.push(failure(entryId, "restore", error));
+			throw verbError("io", error instanceof Error ? `读回收站日志失败：${error.message}` : `读回收站日志失败：${String(error)}`, error);
 		}
-	}
-	if (restored.length > 0) await deps.host.announceRestoredBatch(restored, await deps.host.restoredSummariesOf());
-	return outcomes;
+		detail.models = [...models];
+		return detail;
+	};
 }
-async function applyPurge(deps, ids) {
-	const snapshot = await deps.manifest.list();
-	const original = [...snapshot];
-	const run = purgeTrash(deps);
-	const outcomes = [];
-	for (const entryId of unique(ids)) {
-		if (groupOf(snapshot, entryId).length === 0 && takenByEarlierInBatch(original, snapshot, entryId)) {
-			outcomes.push(success(entryId, "purge", {
-				removed: 0,
-				freedBytes: 0
-			}));
-			continue;
-		}
-		try {
-			outcomes.push(success(entryId, "purge", await run(entryId, snapshot)));
-		} catch (error) {
-			outcomes.push(failure(entryId, "purge", error));
+//#endregion
+//#region src/api/trash-rows.ts
+/**
+* 清册那一行 → 线上那一行。**显式字面量、不用 `...row`**：线上形状多一个必填字段时，这里编译不过，
+* 于是"线上多了一格却没人填"不可能悄悄发生（`...row` 会把它带过去，看上去一切正常）。
+*/
+function toWire(row, readouts = {}) {
+	return {
+		id: row.id,
+		sessionId: row.sessionId,
+		projectDir: row.projectDir,
+		workspaceId: row.workspaceId,
+		wasArchived: row.wasArchived,
+		deletedAt: row.deletedAt,
+		title: row.title,
+		sizeBytes: row.sizeBytes,
+		releaseBytes: row.sizeBytes + (readouts.subagentBytes ?? 0) + (readouts.strandedBytes ?? 0),
+		...row.parentEntryId === void 0 ? {} : { parentEntryId: row.parentEntryId },
+		...readouts.subagentCount === void 0 ? {} : { subagentCount: readouts.subagentCount },
+		...readouts.subagentBytes === void 0 ? {} : { subagentBytes: readouts.subagentBytes },
+		...readouts.strandedSubagents === void 0 ? {} : { strandedSubagents: readouts.strandedSubagents },
+		...readouts.strandedBytes === void 0 ? {} : { strandedBytes: readouts.strandedBytes },
+		...readouts.workspaceMissing === void 0 ? {} : { workspaceMissing: readouts.workspaceMissing }
+	};
+}
+/**
+* 把清册的全部行装配成「一行 = 一组」：孩子折进父那一行、不单独列（宿主的客户端本来就藏孩子，
+* 我们若单列就会冒出一堆点不到的行）；父行不在时孩子自己站出来占一行，否则它既看不见也清不掉。
+* 这些派生值只加在这次回信上，**不落清册**——清册该记的是文件里真有的事实，而"还剩几个孩子"
+* "工作区还在不在"是随盘上随时变的读数。取数失败照抛（响亮失败，不端一份少了这栏的清单当没事发生）。
+*/
+async function assembleTrashRows(deps, rows) {
+	const groups = visibleGroups(rows);
+	const visible = groups.map((group) => group.root);
+	const [membersByParent, missingByRowId] = await Promise.all([deps.host.subagentMembersBatch(visible.map((row) => row.sessionId)), Promise.all(visible.map(async (row) => [row.id, await isWorkspaceMissing(deps.host, row)]))]);
+	const gone = new Map(missingByRowId);
+	return await Promise.all(groups.map(async ({ root, kids }) => {
+		const kidsInGroup = new Set(kids.map((kid) => bareSessionId(kid.sessionId)));
+		let count = 0;
+		let bytes = 0;
+		for (const member of membersByParent[root.sessionId] ?? []) {
+			if (kidsInGroup.has(bareSessionId(member.sessionId))) continue;
+			const measured = await measureMemberDir(deps, member);
+			if (measured === void 0) continue;
+			count += 1;
+			bytes += measured.bytes;
 		}
-	}
-	return outcomes;
+		const missing = gone.get(root.id) === true;
+		return toWire(root, {
+			...kids.length === 0 ? {} : {
+				subagentCount: kids.length,
+				subagentBytes: kids.reduce((total, kid) => total + kid.sizeBytes, 0)
+			},
+			...count === 0 ? {} : {
+				strandedSubagents: count,
+				strandedBytes: bytes
+			},
+			...missing ? { workspaceMissing: true } : {}
+		});
+	}));
 }
-/** 删除确认框那句「含 N 个子会话」：一次问完整批（`subagentCounts` 本来就是批量口）。
-*  宿主口缺席时它回 `{}`（这里折成 0）；真读失败则整次调用失败，浏览器半按"读不到"把整句不说。 */
-async function applyCount(deps, ids) {
-	const wanted = unique(ids);
-	const counts = await deps.host.subagentCounts(wanted);
-	return wanted.map((id) => success(id, "count", counts[id] ?? 0));
+//#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`（两半的共同契约），这张表只回答"怎么处理"。
+*/
+/** 必填的非空字符串字段（缺、空串、类型不对都是**同一句话**：说清是哪个字段）。 */
+function requireString(body, field) {
+	const value = body?.[field];
+	if (typeof value !== "string" || value === "") throw routeError("bad-request", 400, `请求体需带非空字符串字段 ${field}`);
+	return value;
 }
-/** 去重且保持输入顺序（重复 id 跑第二遍是"幂等成功"的伪装，不该发生）。 */
-function unique(ids) {
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const id of ids) {
-		if (seen.has(id)) continue;
-		seen.add(id);
-		out.push(id);
+const APPLY_ACTIONS = Object.keys({
+	delete: true,
+	restore: true,
+	purge: true,
+	count: true,
+	"orphan-clean": true
+});
+/** `/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(" / ")} 之一`);
+	return value;
+}
+/** `/apply` 的 id 组：必须是非空字符串数组（空数组不是"什么都不做"，是调用方自己没组好）。 */
+function requireIdArray(body) {
+	const value = body?.[PARAMS.ids];
+	if (!Array.isArray(value) || value.length === 0 || value.some((id) => typeof id !== "string" || id === "")) throw routeError("bad-request", 400, `请求体需带 ${PARAMS.ids}：非空字符串组成的非空数组`);
+	return value;
+}
+/**
+* 六个段名各一行。`Record<段名, RouteSpec>` 是闸：`wire.ts` 加了段名而这里没加，编译不过。
+*/
+const ROUTE_TABLE = {
+	[ROUTES.list]: {
+		method: "GET",
+		body: "none",
+		purity: "chained",
+		run: async (deps) => assembleTrashRows(deps, await reconcileTrash(deps))
+	},
+	[ROUTES.ping]: {
+		method: "GET",
+		body: "none",
+		purity: "pure",
+		run: async () => "pong"
+	},
+	[ROUTES.orphans]: {
+		method: "GET",
+		body: "none",
+		purity: "pure",
+		run: async (deps) => reportOrphans(await loadOrphanGroups(deps))
+	},
+	[ROUTES.apply]: {
+		method: "POST",
+		body: "json",
+		purity: (body) => body?.[PARAMS.action] === "count" ? "pure" : "chained",
+		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);
+			return await purgeTrash(deps)(void 0, rows);
+		}
+	},
+	[ROUTES.detail]: {
+		method: "POST",
+		body: "json",
+		purity: "pure",
+		run: async (deps, body) => readTrashDetail(deps)(requireString(body, PARAMS.entryId))
 	}
-	return out;
+};
+/** 段名 → 那一行；不认识的段名回 `undefined`（调用方抛 404，并带出原路径）。 */
+function routeOf(rest) {
+	return ROUTE_TABLE[rest];
 }
 //#endregion
 //#region src/api/dispatch.ts
@@ -1457,7 +2196,7 @@ const DESKTOP_APP_HOST = "app";
 /**
 * 「这是桌面壳自己的页面吗」。**必须按 `protocol` + `host` 判，不能比 `URL.origin`**：`dsh-app:`
 * 不是 WHATWG 的 special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`（Node 实测），
-* 拿它跟字面量比永远为假 ⇒ 栅栏会把真机上的每一次请求都挡成 403，四个入口一个都不出现。
+* 拿它跟字面量比永远为假 ⇒ 栅栏会把真机上的每一次请求都挡成 403，所有入口一个都不出现。
 *
 * 这个判据为什么不可能被外人伪造：`Origin` 与 `Referer` 都是 forbidden header，网页改不了，
 * 只能是浏览器/壳自己带上；而 `dsh-app://app` 只可能是桌面壳自己的页面。
@@ -1483,10 +2222,9 @@ function writeOk(res, value) {
 /** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表）。
 *  **状态语义（2026-10-17 错误面对齐）**：**请求本身不对**不再伪装成 200——请求体不对 400、方法不对 405、
 *  未知路由 404、栅栏拒 403（它们不是"一次办成的操作"，是"这条请求不归我办/你没资格办"）。
-*  **操作失败**仍回 200 + 信封（口径 ③ 不变：盘上没有、原目录已不在、会话在跑……都是办完了才知道的结果）。
-*  浏览器半先解信封再看状态，所以 4xx 上带的信封照样读得出原文；`code` 一律折成 `sessiondelete/io`，
-*  那三个路由标签（`bad-request` / `bad-method` / `not-found-route`）是**抛出处给读代码的人看的站点名**，
-*  不许冒充 §6 的五个动词码上客户端。 */
+*  **操作失败**仍回 200 + 信封。浏览器半先解信封再看状态，所以 4xx 上带的信封照样读得出原文；
+*  `code` 一律折成 `sessiondelete/io`，那三个路由标签（`bad-request` / `bad-method` / `not-found-route`）
+*  是**抛出处给读代码的人看的站点名**，不许冒充 §6 的五个动词码上客户端。 */
 function writeFailure(res, error, status) {
 	const carried = error?.httpStatus;
 	writeJson(res, status ?? (typeof carried === "number" ? carried : 200), {
@@ -1504,8 +2242,9 @@ function writeFailure(res, error, status) {
 * 壳把 `Origin` 删掉了、只留下 Referer，见 {@link isDesktopShellUrl}）。两者都缺席 = 本机工具 /
 * curl（注释即此承诺）。**恶意网页拿不到 ②③ 里的任何一个**：那两个头都是 forbidden header、
 * 页面伪造不了；而**写口（POST）在任何跨源形态下都必带 Origin** ⇒ 两个头全缺席就等于本机工具。
-* 唯一的缝是跨源 `no-cors` 的 **GET**（Referer 被 `no-referrer` 掐掉、Origin 也不带）——它只够得到
-* 只读的 `list`，而 no-cors 的回包是 opaque、页面读不出内容 ⇒ 不构成泄露。
+* 唯一的缝是跨源 `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;
@@ -1548,117 +2287,20 @@ async function readJsonBody(req) {
 		throw error;
 	}
 }
-/** 必填的非空字符串字段（缺、空串、类型不对都是**同一句话**：说清是哪个字段）。 */
-function requireString(body, field) {
-	const value = body?.[field];
-	if (typeof value !== "string" || value === "") throw routeError("bad-request", 400, `请求体需带非空字符串字段 ${field}`);
-	return value;
-}
-/** `/apply` 的动作：认不得的一律点名拒掉，不折成"空批量"糊弄过去。 */
-const APPLY_ACTIONS = [
-	"delete",
-	"restore",
-	"purge",
-	"count"
-];
-function requireAction(body) {
-	const value = body?.[PARAMS.action];
-	if (typeof value !== "string" || !APPLY_ACTIONS.includes(value)) throw routeError("bad-request", 400, `批量动作不认识：需是 ${APPLY_ACTIONS.join(" / ")} 之一`);
-	return value;
-}
-/** `/apply` 的 id 组：必须是非空字符串数组（空数组不是"什么都不做"，是调用方自己没组好）。 */
-function requireIdArray(body) {
-	const value = body?.[PARAMS.ids];
-	if (!Array.isArray(value) || value.length === 0 || value.some((id) => typeof id !== "string" || id === "")) throw routeError("bad-request", 400, `请求体需带 ${PARAMS.ids}：非空字符串组成的非空数组`);
-	return value;
-}
 function requireMethod(method, want, route) {
 	if (method !== want) throw routeError("bad-method", 405, `方法不允许：${method}（${SESSION_DELETE_API_PREFIX}${route} 需 ${want}）`);
 }
-/**
-* 把清册的全部行装配成「一行 = 一组」：孩子折进父那一行、不单独列（宿主的客户端本来就藏孩子，
-* 我们若单列就会冒出一堆点不到的行）；父行不在时孩子自己站出来占一行，否则它既看不见也清不掉。
-* 三个只读数只加在这次回信上，**不落清册**——清册该记的是
-* 文件里真有的事实，而"还剩几个孩子"是随盘上随时变的一个数。取数失败照抛（响亮失败，不端一份
-* 少了这栏的清单当没事发生）。
-*/
-async function assembleTrashRows(deps, rows) {
-	const byId = new Map(rows.map((row) => [row.id, row]));
-	const foldedInto = /* @__PURE__ */ new Map();
-	const kidsByParent = /* @__PURE__ */ new Map();
-	for (const row of rows) {
-		if (row.parentEntryId === void 0) continue;
-		const parent = byId.get(row.parentEntryId);
-		if (parent === void 0 || parent.parentEntryId !== void 0) continue;
-		foldedInto.set(row.id, parent.id);
-		const siblings = kidsByParent.get(parent.id);
-		if (siblings === void 0) kidsByParent.set(parent.id, [row]);
-		else siblings.push(row);
-	}
-	const visible = rows.filter((row) => !foldedInto.has(row.id));
-	const stranded = await deps.host.subagentCounts(visible.map((row) => row.sessionId));
-	return visible.map((row) => {
-		const kids = kidsByParent.get(row.id);
-		const left = stranded[row.sessionId];
-		if (kids === void 0 && left === void 0) return row;
-		return {
-			...row,
-			...kids === void 0 ? {} : {
-				subagentCount: kids.length,
-				subagentBytes: kids.reduce((total, kid) => total + kid.sizeBytes, 0)
-			},
-			...left === void 0 ? {} : { strandedSubagents: left }
-		};
-	});
-}
-/** 路由表：段名 → 一个把「方法 + 预读好的请求体」变成返回值的处理器。动词在每次调用时才取。
-*  `body` 由 {@link purityOf} 读一次交下来——同一条请求的流不能被消费两遍。 */
-async function dispatch(method, rest, body, deps) {
-	if (rest === ROUTES.list) {
-		requireMethod(method, "GET", ROUTES.list);
-		return assembleTrashRows(deps, await reconcileTrash(deps));
-	}
-	if (rest === ROUTES.ping) {
-		requireMethod(method, "GET", ROUTES.ping);
-		return "pong";
-	}
-	if (rest === ROUTES.apply) {
-		requireMethod(method, "POST", ROUTES.apply);
-		return await applyActions(deps, requireAction(body), requireIdArray(body));
-	}
-	if (rest === ROUTES.empty) {
-		requireMethod(method, "POST", ROUTES.empty);
-		return await purgeTrash(deps)();
-	}
-	if (rest === ROUTES.detail) {
-		requireMethod(method, "POST", ROUTES.detail);
-		return await readTrashDetail(deps)(requireString(body, PARAMS.entryId));
-	}
-	throw routeError("not-found-route", 404, `未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
+function isPure(purity, body) {
+	return typeof purity === "function" ? purity(body) === "pure" : purity === "pure";
 }
-async function purityOf(req, rest) {
-	if (rest === ROUTES.ping) return {
-		pure: true,
-		body: null
-	};
-	if (rest === ROUTES.detail) return {
-		pure: true,
-		body: await readJsonBody(req)
-	};
-	if (rest !== ROUTES.apply) return {
-		pure: false,
-		body: null
-	};
-	const body = await readJsonBody(req);
-	return {
-		pure: body?.[PARAMS.action] === "count",
-		body
-	};
+function readBodyFor(kind, req) {
+	return kind === "json" ? readJsonBody(req) : null;
 }
 function createApiHandler(deps) {
 	/**
-	* 到达序串行链（文件头 ⑤）：`list`（含对账）与三个写动词一个跑完再放下一个。`tail` 由构造保证
-	* **永不 reject**（每个任务自己的失败留在交回给那次请求的那个 promise 上），所以一次失败不会卡死链。
+	* 到达序串行链（文件头 ⑤）：路由表里 `purity === 'chained'` 的请求一个跑完再放下一个。
+	* `tail` 由构造保证**永不 reject**（每个任务自己的失败留在交回给那次请求的那个 promise 上），
+	* 所以一次失败不会卡死链。
 	*/
 	let tail = Promise.resolve();
 	const throughChain = (task) => {
@@ -1675,9 +2317,12 @@ function createApiHandler(deps) {
 			const url = new URL(req.url ?? "/", "http://dsh.internal");
 			if (!url.pathname.startsWith("/dsh-session-delete-api")) throw routeError("not-found-route", 404, `未知路由：${url.pathname}`);
 			const rest = url.pathname.slice(23);
-			const { pure, body } = await purityOf(req, rest);
-			const task = () => dispatch(req.method ?? "GET", rest, body, deps);
-			writeOk(res, await (pure ? task() : throughChain(task)));
+			const spec = routeOf(rest);
+			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)));
 		} catch (error) {
 			writeFailure(res, error);
 		}
@@ -1749,12 +2394,13 @@ const name = "@xrn1997/dsh-session-delete";
 * 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。三个**故意不写**的：
 * - `remote`：那是**浏览器半**的服务（asar `dsh-api-gateway/lib/client.js`：`super(ctx, "remote")`），
 *   Node 半挂的是 `ctx.typertGateway`。把它写进 Node 半的 inject 会让插件永远 pending（同 `slots` 那次的形状）。
-* - `sessions` / `sessionProjectionCache`：前者本实现不用（活跃判据走 waterfall，见设计稿 §5）；后者是**可选**服务，
-*   官方消费方也按可选读（`ctx.get('sessionProjectionCache')?.…`），inject 一个可能没挂的服务 = 整个插件 pending。
+* - `sessions` / `sessionProjectionCache`：两者都按 `ctx.get(...)` **可选读**——`sessions` 只给 `evictLive`
+*   用（活跃判据走 waterfall，见设计稿 §5；服务缺席回 `unknown`），`sessionProjectionCache` 是标题的尽力读面。
+*   inject 一个可能没挂的服务 = 整个插件 pending。
 *   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
 *
 * `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` 原文读实，不是猜的。
 */
@@ -1791,19 +2437,6 @@ function defineDomain(spec) {
 	for (const table of Object.keys(spec.tables)) if (!UNIT_NAME_RE.test(table)) throw new Error(`domain '${spec.name}' table name '${table}' must match ${UNIT_NAME_RE}`);
 	return spec;
 }
-/** `TrashEntry` 里**每条记录都必须有**的那几格（`src/trash/entry.ts` 接口的非可选字段）。
-*  **可选字段不在这里**：`parentEntryId`（级联那批加的）缺席是合法的——老行没有它，缺了就是"没有父"；
-*  校验器只管这几格的类型，其余键**原样带走**（`parse` 交回的就是 `raw` 本身）⇒ 新字段照旧存得住。 */
-const TRASH_ENTRY_FIELDS = {
-	id: "string",
-	sessionId: "string",
-	projectDir: "string",
-	workspaceId: "string",
-	wasArchived: "boolean",
-	deletedAt: "number",
-	title: "string",
-	sizeBytes: "number"
-};
 /**
 * 回收站清单的域声明。
 *
@@ -1818,7 +2451,7 @@ const trashDomainSpec = defineDomain({
 	invalidRecords: "backup-and-skip",
 	tables: { entries: domainTable({ parse(raw) {
 		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new TypeError("session trash entry record must be a plain object");
-		for (const [field, kind] of Object.entries(TRASH_ENTRY_FIELDS)) if (typeof raw[field] !== kind) throw new TypeError(`session trash entry record field "${field}" must be a ${kind}`);
+		for (const [field, kind] of Object.entries(REQUIRED_ENTRY_FIELDS)) if (typeof raw[field] !== kind) throw new TypeError(`session trash entry record field "${field}" must be a ${kind}`);
 		return raw;
 	} }) }
 });