@xrn1997/dsh-session-delete 0.1.0 → 0.2.0

package/lib/index.js

@@ -15,7 +15,7 @@ import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 *  ② 跨插件一律 `import type`——本文件干脆没有 import。
 *
 * 信封（`RemoteResult`）与失败形状（`RemoteFailure`）也在这里——**因为它们本来就是两半的共同契约**：
-* Node 半按它产出（`src/api/dispatch.ts` 的失败支就是 `RemoteFailure` 那两件），浏览器半按它判别
+* Node 半按它产出（`src/api/dispatch.ts` 的失败支就是 `RemoteFailure` 那三件），浏览器半按它判别
 * （`src/client/remote.ts` 的 `unwrapRemoteResult` / `failureOf`）。形状取自宿主网关客户端面的原文
 * 「每次 unary 调用 resolve 成 RemoteResult、不为载体问题 reject」，但**它是本仓自己的 wire 契约**，
 * 不是对宿主模块的 import。
@@ -28,19 +28,29 @@ import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 五个端点的段名（相对前缀；`GET list` 读清单，其余四个 `POST` 按 id 取数或写）。 */
+/** 五个段名（相对前缀）。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`：清空回收站（聚合回执，**不**按条回）。 */
 const ROUTES = {
 	list: "/list",
-	delete: "/delete",
-	restore: "/restore",
-	purge: "/purge",
-	/** 单条详情（读回收站目录里那条会话自己的日志）。用 POST 表达一个读：见设计稿 2026-10-15 §3。 */
-	detail: "/detail"
+	/** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
+	ping: "/ping",
+	/** 单条详情（读回收站目录里那条会话自己的日志）。 */
+	detail: "/detail",
+	/** 一组 id 上的同一个动作；删除确认框那句「含 N 个子会话」也走这里（`action: 'count'`，纯读语义）。 */
+	apply: "/apply",
+	/** 清空回收站。 */
+	empty: "/empty"
 };
-/** 请求体字段名：浏览器半发、Node 半读，同名同义（`purge` 的 `entryId` 缺席 = 清空）。 */
+/** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
 const PARAMS = {
-	sessionId: "sessionId",
-	entryId: "entryId"
+	entryId: "entryId",
+	action: "action",
+	ids: "ids"
 };
 /**
 * 进程内判别「这已经是一次失败」——**按标记位认，不按 `instanceof`**（跨 realm / 跨 bundle 都不成立）。
@@ -66,10 +76,18 @@ const VERB_CODES = [
 	"project-missing",
 	"io"
 ];
-function verbError(code, message, cause) {
+function verbError(code, message, cause, details) {
 	const e = new Error(message);
 	e.code = `sessiondelete/${code}`;
-	e.cause = cause;
+	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;
 }
 //#endregion
@@ -85,13 +103,14 @@ const HOST_ERROR_CODE = {
 	WorkspaceUnknownSessionError: "not-found",
 	WorkspaceActiveSessionError: "live"
 };
-/** 错误与它的 `cause` 链上最近的一个宿主类型化错误码（深度有界，链坏掉不递归下去）。 */
-function hostCodeOf(error) {
+/** cause 链上第一个**宿主类型化错误**本身（不只它的名字）——它自己身上的字段还要当 `details` 用。
+*  深度有界（链坏掉不递归下去）；查表必须 `hasOwn`：`in` 会命中 `Object.prototype` 的键。 */
+function hostErrorOf(error) {
 	let current = error;
 	for (let depth = 0; depth < 8; depth++) {
 		if (current === null || typeof current !== "object") return void 0;
 		const name = current.name;
-		if (typeof name === "string" && Object.hasOwn(HOST_ERROR_CODE, name)) return HOST_ERROR_CODE[name];
+		if (typeof name === "string" && Object.hasOwn(HOST_ERROR_CODE, name)) return current;
 		current = current.cause;
 	}
 }
@@ -105,32 +124,86 @@ function messageOf(error) {
 	}
 	return String(error);
 }
+/** 官方 `<域>/<名>` 形状的 code。动词码也是这个形状，所以调用方另要**排除本域**才作数。 */
+const OFFICIAL_CODE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+/** 抛出物**自己身上**挂的结构化字段（rc.2：`WorkspaceActiveSessionError` 带 `sessionId` / `activity`，
+*  `WorkspaceUnknownSessionError` 带 `sessionId`；控制器把它们折进 `RemoteError.details` 才上客户端）。
+*  `activity` 过一遍 JSON 往返再交回：既保住它的结构（官方 schema 是 `Record<string, unknown>`），
+*  也保证信封那一侧 `JSON.stringify` 不会撞上循环引用。
+*  一件都没有 ⇒ `undefined`（不硬造一个空表冒充"带过 details"）。 */
+function ownDetailsOf(error) {
+	if (error === null || typeof error !== "object") return void 0;
+	const out = {};
+	const source = error;
+	for (const key of [
+		"sessionId",
+		"workspaceId",
+		"path"
+	]) if (typeof source[key] === "string") out[key] = source[key];
+	if (source.activity !== void 0) try {
+		out.activity = JSON.parse(JSON.stringify(source.activity));
+	} catch {}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/** 一个可以过线的 details 对象（数组与 null 不算；官方是 `z.record`）。 */
+function isDetailsRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `details` 的来历，就近优先：自己挂着的 `details`（官方 `RemoteError` 那件）→ 自己身上的字段 → 无。 */
+function detailsOf(error) {
+	if (error === null || typeof error !== "object") return void 0;
+	const carried = error.details;
+	if (isDetailsRecord(carried)) return carried;
+	return ownDetailsOf(error);
+}
 /**
-* 把任意抛出物折成失败信封里的**那两件**（设计稿 §6 唯一那张映射表）。
+* 把任意抛出物折成失败信封里的**那三件**（设计稿 §6 唯一那张映射表）。
 *
-* - 已经是远程失败（`isDSHRemoteError` 认得的结构标记）⇒ 原样带出它自己的 `code` / `message`，不再包一层。
-* - 宿主类型化错误（自身或 `cause` 链上，见 {@link HOST_ERROR_CODE}）⇒ 映射成 `live` / `not-found`。
-*   放在动词码之前判：动词把宿主错误包成笼统的 `io` 并把原错误挂在 cause 上（`verbError('io', …, cause)`），
-*   不这样看进 cause 链，§6 那两行映射就永远到不了客户端。
-* - 动词的 `sessiondelete/<五个码>` ⇒ 原样过桥。
-* - 其余（含别域码、前缀外的因、非 Error 抛出物）⇒ `io`，message 保留原文。
+* - 已经是远程失败（`isDSHRemoteError` 认得的结构标记）⇒ 原样带出它自己的 `code` / `message`，
+*   挂着的 `details` 一起过桥，不再包一层。
+* - **带官方形状 code 的抛出物**（`workspace/session-active`、`session/not-found`…）⇒ **原样过桥**。
+*   把它们折成 `sessiondelete/io` 就是把宿主的判断抹成我们的，客户端拿到的 code 从此不能说真话。
+* - 宿主类型化错误（自身或 `cause` 链上，见 {@link hostErrorOf}）⇒ 映射成 `live` / `not-found`，
+*   并把它自己身上的结构化字段带成 `details`。这一条排在动词码之前：动词会把宿主错误包成笼统的 `io`
+*   并把原错误挂在 cause 上（`verbError('io', …, cause)`），不看进 cause 链，§6 那两行映射永远到不了客户端。
+* - 动词的 `sessiondelete/<五个码>` ⇒ 原样过桥（`details` 同样带着）。
+* - 其余（别域的怪 code、前缀外的因、非 Error 抛出物）⇒ `io`，message 保留原文。
 *
-* **返回的是线上形状、不是 `Error`**：这份东西唯一的去处是 `src/api/dispatch.ts` 的失败信封，两种判别
-* （`isDSHRemoteError` 与 {@link HOST_ERROR_CODE}）都只用到 `code` / `message`——造一个真 `Error` 没有消费者，
-* 而本仓的跨插件 import 红线也不许为此去引宿主的 `RemoteError` 类（实例也上不了线：信封只走这两件）。
+* **返回的是线上形状、不是 `Error`**：这份东西唯一的去处是 `src/api/dispatch.ts` 的失败信封
+* （以及 `verbs/apply.ts` 的逐条 `error`），而本仓的跨插件 import 红线也不许为此去引宿主的
+* `RemoteError` 类（实例也上不了线：信封只走这三件）。
 */
 function toRemoteFailure(error) {
-	if (isDSHRemoteError(error)) return {
-		code: error.code,
-		message: String(error.message)
-	};
+	if (isDSHRemoteError(error)) {
+		const carried = error.details;
+		return {
+			code: error.code,
+			message: String(error.message),
+			...isDetailsRecord(carried) ? { details: carried } : {}
+		};
+	}
 	const raw = error?.code;
+	if (typeof raw === "string" && OFFICIAL_CODE.test(raw) && !raw.startsWith(`${DOMAIN}/`)) {
+		const details = detailsOf(error);
+		return {
+			code: raw,
+			message: messageOf(error),
+			...details === void 0 ? {} : { details }
+		};
+	}
 	const reason = typeof raw === "string" && raw.startsWith(`${DOMAIN}/`) ? raw.slice(14) : void 0;
 	const fromVerb = reason !== void 0 && VERB_CODES.includes(reason) ? reason : void 0;
-	const code = hostCodeOf(error) ?? fromVerb ?? "io";
+	const host = hostErrorOf(error);
+	const own = detailsOf(error) ?? (host === void 0 ? void 0 : detailsOf(host));
+	if (host === void 0 && fromVerb === void 0 && typeof raw === "string" && raw.includes("/")) return {
+		code: `${DOMAIN}/io`,
+		message: messageOf(error)
+	};
+	const code = host !== void 0 ? HOST_ERROR_CODE[host.name] : fromVerb ?? "io";
 	return {
 		code: `${DOMAIN}/${code}`,
-		message: messageOf(error)
+		message: messageOf(error),
+		...own === void 0 ? {} : { details: own }
 	};
 }
 //#endregion
@@ -272,6 +345,39 @@ function frameRanges(raw) {
 *    真被切断的尾巴（写一半）仍然**跳过并计数**：绝不因为一行就抛整个读数，前面几百条是真的。
 */
 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;
+		}
+	}
+	return best;
+}
+/**
+* 逐帧走一遍日志，每条记录交给回调。
+*
+* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
+* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
+*/
 function walkSessionLog(raw, onRecord) {
 	const stats = {
 		frames: 0,
@@ -279,6 +385,7 @@ function walkSessionLog(raw, onRecord) {
 		unparsedLines: 0,
 		truncatedTailBytes: 0
 	};
+	let stopped = false;
 	const feed = (line) => {
 		if (line === "") return;
 		let parsed;
@@ -289,11 +396,12 @@ function walkSessionLog(raw, onRecord) {
 			return;
 		}
 		stats.records += 1;
-		onRecord(parsed !== null && typeof parsed === "object" ? parsed : {});
+		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 {
@@ -308,40 +416,33 @@ function walkSessionLog(raw, onRecord) {
 			continue;
 		}
 		carry = merged.subarray(cut + 1);
-		for (const line of merged.subarray(0, cut).toString("utf8").split("\n")) feed(line);
+		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) feed(carry.toString("utf8"));
+	if (carry.length > 0 && !stopped) feed(carry.toString("utf8"));
 	return stats;
 }
-//#endregion
-//#region src/trash/detail.ts
 /**
-* 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（设计稿 2026-10-15 §3）。
-*
-* 三层里的策略层——编解码在 `src/log/*`，这里只回答"给谁看、给多少、算不算失败"。
-*
-* 三条硬口径，都不是口味：
-* ① **寻址只认清册**：`entryId` 先在清单里查，目录一律由 `trashDirOf(record.id, home)` 推 ⇒ 外部
-*    输入进不了文件系统寻址（不给"传个路径就读任意目录"留缝）。
-* ② **正文只认 `source.kind === "user"`**：`user/message` 里绝大多数是宿主注入的上下文
-*    （本机实测一条会话：真实提问 21 条、注入 241 条），不过滤就被淹掉；注入条数照样上线
-*    （`injectedCount`），让"为什么少了这么多条"能与页面上的数字对账。
-* ③ **两个闸是载荷闸，不是读盘闸**：每条 3 000 字符、累计 50 万字符（CJK 最坏 ≈ 1.5 MB UTF-8）。
-*    按 §1 的读数本机一条都触发不了（最大那条正文 806 KB ≈ 27 万字符、442 条消息）⇒ 它们是防异常
-*    膨胀的；**不设"文件太大就拒绝"**，那种阈值只会把真读得出来的正文挡在外面。
-*
-* 计数与正文**同源同判据**：`userMessageCount` 就是进了正文的提问条数、`assistantMessageCount` 就是
-* 有文字的回复条数——不是一套判据算两遍，否则页面上会出现"计数 421、正文 200"这种对不上账的话。
+* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
+* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
+* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
+* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
 */
-/** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
-const PER_MESSAGE_CHAR_CAP = 3e3;
-/** 一次回信的正文总量上限（字符）。 */
-const TOTAL_CHAR_CAP = 5e5;
-const LOG_SUFFIX = ".jsonl.zstd";
+function readSessionHeader(raw) {
+	let header;
+	walkSessionLog(raw, (record) => {
+		if (record.type !== "session") return;
+		header = record;
+		return false;
+	});
+	return header;
+}
 const DEFAULT_LIMITS = {
-	perMessageChars: PER_MESSAGE_CHAR_CAP,
-	totalChars: TOTAL_CHAR_CAP
+	perMessageChars: 3e3,
+	totalChars: 5e5
 };
 /** 一条记录里那些 `content[]` 段的文字拼起来（`\n` 分隔；非 text 段一律不参与）。 */
 function textOf(content) {
@@ -354,8 +455,8 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 		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)).sort();
-		const logName = names.find((n) => n.endsWith(LOG_SUFFIX));
+		const names = await deps.fs.listFiles(dir);
+		const logName = pickSessionLog(names);
 		if (logName === void 0) throw verbError("io", `回收站目录里没有会话日志：${dir}（里面有：${names.join(", ") || "空目录"}）`);
 		let raw;
 		try {
@@ -452,405 +553,176 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 	};
 }
 //#endregion
-//#region src/verbs/delete-session.ts
-function deleteSession(deps) {
-	return async function deleteSession(sessionId) {
-		if (await deps.host.isLive(sessionId)) throw verbError("live", `会话正在运行：${sessionId}`);
-		const projectDir = await deps.host.projectDirOf(sessionId);
-		if (!projectDir) throw verbError("not-found", `宿主的持久化里没有这个会话：${sessionId}`);
-		const workspaceId = await deps.host.workspaceOf(sessionId);
-		const sessionDir = sessionDirOf(projectDir, sessionId, deps.home);
-		if (!await deps.fs.exists(sessionDir)) throw verbError("not-found", `会话目录不存在：${sessionDir}`);
-		const wasArchived = await deps.host.isArchived(sessionId);
-		const deletedAt = deps.now();
-		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);
-		} 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 entry = {
-			id: entryId,
-			sessionId,
-			projectDir,
-			workspaceId: workspaceId ?? "",
-			wasArchived,
-			deletedAt,
-			title,
-			sizeBytes
-		};
-		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);
-		}
-		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);
-		}
-		if (await deps.host.evictLive(sessionId) !== "unknown") await deps.host.announceRemoved(sessionId);
-		return entry;
-	};
-}
-//#endregion
-//#region src/verbs/purge-trash.ts
-function purgeTrash(deps) {
-	return async function purgeTrash(entryId) {
-		const all = await deps.manifest.list();
-		const targets = entryId ? all.filter((e) => e.id === 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);
-			if (await deps.host.evictLive(entry.sessionId) !== "unknown") await deps.host.announceRemoved(entry.sessionId);
-		}
-		return {
-			removed: targets.length,
-			freedBytes
-		};
-	};
+//#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;
 }
-//#endregion
-//#region src/verbs/restore-session.ts
-function restoreSession(deps) {
-	return async function restoreSession(entryId) {
-		const entry = (await deps.manifest.list()).find((e) => e.id === entryId);
-		if (!entry) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		const trashDir = trashDirOf(entry.id, deps.home);
-		const sessionDir = sessionDirOf(entry.projectDir, parseEntryId(entry.id).sessionDirName, 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}`);
-		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);
-		}
-		try {
-			await deps.manifest.remove(entry.id);
-		} 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);
-		}
-		await deps.host.announceRestored(entry.sessionId);
-		return entry;
-	};
+/** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。 */
+async function filterChildrenOf(sessionQuery, values) {
+	return sessionQuery.filterSessions([{
+		kind: "parent",
+		values: [...values].sort()
+	}]);
 }
-//#endregion
-//#region src/api/dispatch.ts
-/** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
-const JSON_BODY_MAX_BYTES = 1048576;
-/** 回环地址的三种写法（IPv4 / IPv6 / IPv4-mapped IPv6）。 */
-const LOOPBACK = [
-	"127.0.0.1",
-	"::1",
-	"::ffff:127.0.0.1"
-];
-/**
-* 桌面壳那条路（asar `/lib/main.js` 的 `forwardWebRequest`）：渲染进程从 `dsh-app://app/` 加载，
-* 页面里对**非静态路径**的请求（`/`、`/index.html`、`/assets/*`、`/plugins/…` 之外的一切——包括
-* 我们这条前缀路由）都由 `protocol.handle("dsh-app")` 转给宿主自己的 web server；转发前它把
-* `host` / `origin` / `cookie` / `sec-fetch-site` 四个头**删掉**、换上一枚宿主自己的 cookie，路径与
-* 查询串原样带走（逐字：`for (const name of ["host","origin","cookie","sec-fetch-site"]) headers.delete(name)`）。
-* ⇒ 桌面版打到我们这条路由上的请求是**没有 `Origin`** 的，`Referer` 则保留（同源请求照常带，
-* 页面就住在 `dsh-app://app/`）。壳自己在上游只放行 `origin ∈ {null, "dsh-app://app"}`。
-*/
-const DESKTOP_APP_SCHEME = "dsh-app:";
-const DESKTOP_APP_HOST = "app";
 /**
-* 「这是桌面壳自己的页面吗」。**必须按 `protocol` + `host` 判，不能比 `URL.origin`**：`dsh-app:`
-* 不是 WHATWG 的 special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`（Node 实测），
-* 拿它跟字面量比永远为假 ⇒ 栅栏会把真机上的每一次请求都挡成 403，四个入口一个都不出现。
+* 从若干根出发**逐层往下**把盘上的后代问出来，交回 `父（bare）→ 孩子` 的索引。
 *
-* 这个判据为什么不可能被外人伪造：`Origin` 与 `Referer` 都是 forbidden header，网页改不了，
-* 只能是浏览器/壳自己带上；而 `dsh-app://app` 只可能是桌面壳自己的页面。
+* 为什么一次问一层而不是官方的 `traceSession`：那条在父已经进回收站时认不出目标
+* （`SESSION_QUERY_SESSION_NOT_FOUND`），而我们要的那批正是"父已经不在宿主列表里之后还剩在盘上的"。
+* `kind:'parent'` 是唯一能按 `header.parentSession` 反着问的一支。
+*
+* 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
+* （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
+* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostPort.subagentMembers} 那条），
+* 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
 */
-function isDesktopShellUrl(value) {
-	try {
-		const url = new URL(value);
-		return url.protocol === DESKTOP_APP_SCHEME && url.host === DESKTOP_APP_HOST;
-	} catch {
-		return false;
+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;
 }
-function writeJson(res, status, body) {
-	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
-	res.end(JSON.stringify(body));
-}
-function writeOk(res, value) {
-	writeJson(res, 200, {
-		ok: true,
-		value
-	});
-}
-/** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表），值就是线上形状本身。 */
-function writeFailure(res, error, status = 200) {
-	writeJson(res, status, {
-		ok: false,
-		error: toRemoteFailure(error)
-	});
+/** 某个根在 `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 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";
 /**
-* 同源栅栏（见文件头 ④）。看 `origin` 而不只看 `referer` 的理由：恶意页
-* `<meta name="referrer" content="no-referrer">` 能让 Referer 缺席，但浏览器对跨源请求**总是**发 Origin。
+* 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
 *
-* 放行的三种形状，各自都是"浏览器/壳自动带上、网页改不了"的那种：
-* ① `Origin` 与 `Host` 同源（浏览器直接打开宿主那行 URL）；② `Origin` 是桌面壳的 `dsh-app://app`
-* （壳自己在上游也只放行这个 origin）；③ `Referer` 是桌面壳的 `dsh-app://app`（**真机那条路**：
-* 壳把 `Origin` 删掉了、只留下 Referer，见 {@link isDesktopShellUrl}）。两者都缺席 = 本机工具 /
-* curl（注释即此承诺）。**恶意网页拿不到 ②③ 里的任何一个**：那两个头都是 forbidden header、
-* 页面伪造不了；而**写口（POST）在任何跨源形态下都必带 Origin** ⇒ 两个头全缺席就等于本机工具。
-* 唯一的缝是跨源 `no-cors` 的 **GET**（Referer 被 `no-referrer` 掐掉、Origin 也不带）——它只够得到
-* 只读的 `list`，而 no-cors 的回包是 opaque、页面读不出内容 ⇒ 不构成泄露。
+* 为什么是镜像而不是 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 isTrustedRequest(req) {
-	if (!LOOPBACK.includes(req.socket.remoteAddress ?? "")) return false;
-	const host = req.headers.host;
-	const origin = req.headers.origin;
-	if (origin !== void 0 && !isDesktopShellUrl(origin)) try {
-		if (new URL(origin).host !== host) return false;
-	} catch {
-		return false;
-	}
-	const referer = req.headers.referer;
-	if (referer === void 0) return true;
-	if (isDesktopShellUrl(referer)) return true;
-	try {
-		return new URL(referer).host === host;
-	} catch {
-		return false;
+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)}--`;
 }
-/** 流式读 body 并解析成 JSON 对象：空体回 `null`，超限 / 非法 JSON / 不是对象一律抛（→ 失败信封）。 */
-async function readJsonBody(req) {
-	const chunks = [];
-	let size = 0;
-	for await (const chunk of req) {
-		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-		size += buf.length;
-		if (size > JSON_BODY_MAX_BYTES) throw new Error(`请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
-		chunks.push(buf);
-	}
-	const text = Buffer.concat(chunks).toString("utf8").trim();
-	if (text === "") return null;
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch (error) {
-		throw new Error(`请求体不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("请求体需为 JSON 对象");
-	return parsed;
+/** 投影缓存服务的最小方法面判据（按方法面判，不按 `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;
 }
-/** 必填的非空字符串字段（缺、空串、类型不对都是**同一句话**：说清是哪个字段）。 */
-function requireString(body, field) {
-	const value = body?.[field];
-	if (typeof value !== "string" || value === "") throw new Error(`请求体需带非空字符串字段 ${field}`);
-	return value;
+/**
+* 「账本里没有这个会话」的判别串——宿主 `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);
 }
-/** `purge` 的 `entryId` 可选（缺席 = 清空），但在场就必须是像样的值——不把 `42` 当成"没带"。 */
-function optionalString(body, field) {
-	const value = body?.[field];
-	if (value === void 0) return void 0;
-	if (typeof value !== "string" || value === "") throw new Error(`字段 ${field} 若在场必须是非空字符串`);
-	return value;
+/** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostPort.subagentCounts}）。 */
+function bareSessionId(id) {
+	return id.startsWith("session-") ? id.slice(8) : id;
 }
-function requireMethod(method, want, route) {
-	if (method !== want) throw new Error(`方法不允许：${method}（${SESSION_DELETE_API_PREFIX}${route} 需 ${want}）`);
+/** 一个 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}`
+	])];
 }
-/** 路由表：段名 → 一个把「方法 + 请求体」变成返回值的处理器。动词在每次调用时才取。 */
-async function dispatch(method, rest, req, deps) {
-	if (rest === ROUTES.list) {
-		requireMethod(method, "GET", ROUTES.list);
-		return await deps.manifest.list();
-	}
-	if (rest === ROUTES.delete) {
-		requireMethod(method, "POST", ROUTES.delete);
-		return await deleteSession(deps)(requireString(await readJsonBody(req), PARAMS.sessionId));
-	}
-	if (rest === ROUTES.restore) {
-		requireMethod(method, "POST", ROUTES.restore);
-		return await restoreSession(deps)(requireString(await readJsonBody(req), PARAMS.entryId));
-	}
-	if (rest === ROUTES.purge) {
-		requireMethod(method, "POST", ROUTES.purge);
-		return await purgeTrash(deps)(optionalString(await readJsonBody(req), PARAMS.entryId));
-	}
-	if (rest === ROUTES.detail) {
-		requireMethod(method, "POST", ROUTES.detail);
-		return await readTrashDetail(deps)(requireString(await readJsonBody(req), PARAMS.entryId));
+/** 宿主会话表的一次取数（`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 [];
 	}
-	throw new Error(`未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
-}
-/** 宿主 `webServer.register({kind:'prefix', path: SESSION_DELETE_API_PREFIX, handler})` 的那个 handler。 */
-function createApiHandler(deps) {
-	return async function handle(req, res) {
-		if (!isTrustedRequest(req)) {
-			writeFailure(res, /* @__PURE__ */ new Error("非受信来源"), 403);
-			return;
-		}
-		try {
-			const url = new URL(req.url ?? "/", "http://dsh.internal");
-			if (!url.pathname.startsWith("/dsh-session-delete-api")) throw new Error(`未知路由：${url.pathname}`);
-			writeOk(res, await dispatch(req.method ?? "GET", url.pathname.slice(23), req, deps));
-		} catch (error) {
-			writeFailure(res, error);
-		}
-	};
-}
-//#endregion
-//#region src/ports/fs-port.ts
-/** 模块级递归：端口方法**解构出来单独调**也不能靠 `this`（`{ sizeOfDir } = port` 会让方法体的
-*  `this` 变成 undefined）。所以端口只做转发，递归在模块作用域里自调。 */
-async function sizeOfDir(p) {
-	let total = 0;
-	for (const e of await readdir(p, { withFileTypes: true })) {
-		const child = join(p, e.name);
-		total += e.isDirectory() ? await sizeOfDir(child) : (await stat(child)).size;
-	}
-	return total;
-}
-function createFsPort() {
-	return {
-		async exists(p) {
-			return existsSync(p);
-		},
-		async ensureDir(p) {
-			await mkdir(p, { recursive: true });
-		},
-		async rename(from, to) {
-			await rename(from, to);
-		},
-		async removeDir(p) {
-			await rm(p, {
-				recursive: true,
-				force: true
-			});
-		},
-		sizeOfDir: (p) => sizeOfDir(p),
-		async listFiles(p) {
-			return readdir(p);
-		},
-		async readFile(p) {
-			return readFile(p);
-		}
-	};
-}
-//#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;
-}
-/** 无 cwd 的会话落在 `<sessions>/_no-cwd/`（asar `dsh-session-persistence-jsonl/lib/index.js`
-*  的 `projectDir(root, cwd)`：`if (cwd === void 0) return join(root, "_no-cwd");`）。 */
-const NO_CWD_PROJECT_DIR = "_no-cwd";
-/**
-* 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
-*
-* 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
-* 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
-* （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
-*
-* 原文（asar `dsh/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`）：
-* `function projectKey(cwd) { … if (ch === "/" || ch === "\\" || ch === ":") { if (!separatorRun) readable += "-"; separatorRun = true; }
-*  else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) { readable += ch; separatorRun = false; }
-*  else { readable += "~" + code.toString(16).toUpperCase().padStart(4, "0"); separatorRun = false; }
-*  return \`--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--\`; }`
-* 调用链：`locate(meta)` → `logPath(root, meta.cwd, meta.id, …)` → `projectDir(root, cwd)` → `projectKey(cwd)`。
-* 本机实测对得上：`D:/develop/GitHub/dsh-session-delete` → `--D-develop-GitHub-dsh-session-delete--`
-* （`~/.dsh/sessions` 下真有这个目录名；`D:/document/deepseek-harness/default-workspace` 同理）。
-*/
-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);
 }
 /**
-* 宿主服务层的**真实绑定**：十二个方法各自把动词层的问题翻成宿主官方服务的调用。
+* 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
 *
 * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
 * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
@@ -970,19 +842,42 @@ function createHostPort(ctx) {
 		* 摘要**取自宿主自己的会话列表**（`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 {
-				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;
-				if (!Array.isArray(items)) return;
-				const summary = items.find((item) => item?.sessionId === sessionId);
-				if (summary === void 0) return;
 				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);
@@ -1005,6 +900,827 @@ function createHostPort(ctx) {
 		*  不带 `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
+			}));
+		}
+	};
+}
+//#endregion
+//#region src/trash/reconcile.ts
+/**
+* 回收站清单的**对账**：以 `session-trash/` 里的条目目录为准，把清单修回一致（设计稿 2026-10-15 §9）。
+*
+* 手工动回收站**只需要动那一个目录**——多出来的目录在这里被重建出行、目录没了的行在这里被摘掉；
+* `~/.dsh/storages/` 那份清单从此是**内部索引**，不用手碰。
+*
+* 五条口径（都不是口味）：
+* ① **每次读清单都对账**（`GET /list` 的正文就是"对账 + 读"）：挂载、刷新、别处动过后的自动重读、
+*    客户端启动探测全走这条 ⇒ "改完目录不用再做任何事，下一次读就对了"。代价 = 每次读多一次目录枚举
+*    （本机 124 条，毫秒级）；**零漂移零写入**（快路直接返回原清单）。
+* ② **回收站根不在 ⇒ 整套跳过、一个字节都不动**：那不是"回收站空了"，是"这块地不在原处"
+*    （人为搬走、盘没挂上）——照常对账会把全部行的元数据一次判没。
+* ③ **重建行只写"文件里真有的事实"**：`id` = 目录名、`sessionId`/`cwd` 读日志 header、
+*    `projectDir` 由 `cwd` 经宿主同名算法 `projectKey` 反推、`deletedAt` 从目录名的时间戳解、
+*    `sizeBytes` 现场量。**文件侧没有副本的三件**按缺省落：`workspaceId: ''`（恢复时跳过挂账本，
+*    落在「未分组」）、`wasArchived: false`（恢复按"可见"还原）、`title: ''`（详情有日志标题兜底）
+*    ——这是重建的固有代价，不是可以"再读读看"的东西。
+* ④ **认不出 / 读不出的目录：不动、不列**（名字不像条目、目录里没有日志、header 读不出、尺寸量不出，
+*    各跳过各的）。它是"外人放进来的东西"，不是用户动作失败：跳过即静默，绝不为它删目录或抛掉整次读数。
+* ⑤ **幂等**：再跑一遍零写入；崩在任何一步，下一次读清单接着把它修完。
+*
+* 与三个写动词的**串行化不在这里**（那是传输层的事，见 `src/api/dispatch.ts` 的到达序链）：
+* 对账与删除/恢复/彻底删除都是"读清单 + 动文件 + 写清单"的多步，交错跑会互相踩——删除刚把目录搬进
+* 回收站、行还没写上时，对账抢先把这行按目录"重建"出来，随后又被真实行覆盖成降级元数据。
+*/
+/** 目录名是不是一条条目 id（形状契约在 `entry.ts`：`<删除时刻UTC>-<原目录名>`）。 */
+function isEntryId(name) {
+	try {
+		parseEntryId(name);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 从一个手工放进回收站的目录重建清单行。**任一件事实拿不到就整体放弃这一条**（回 `undefined`）：
+* 半截行比"不列"更坏——恢复会照它把目录搬去一个错的地方（同 `detail.ts` 那条"半截正文"的口径）。
+*
+* `sessionId` 取日志 header 的 `id`（恢复之后宿主按日志 header 建索引，那才是会话身份）；
+* header 缺席这个字段才回落到目录名里那段原目录名。
+*/
+async function buildEntry(deps, id) {
+	const dir = trashDirOf(id, deps.home);
+	let logName;
+	try {
+		logName = pickSessionLog(await deps.fs.listFiles(dir));
+	} catch {
+		return;
+	}
+	if (logName === void 0) return void 0;
+	let raw;
+	try {
+		raw = await deps.fs.readFile(`${dir}/${logName}`);
+	} catch {
+		return;
+	}
+	let header;
+	try {
+		header = readSessionHeader(raw);
+	} catch {
+		return;
+	}
+	if (header === void 0) return void 0;
+	let sizeBytes;
+	try {
+		sizeBytes = await deps.fs.sizeOfDir(dir);
+	} catch {
+		return;
+	}
+	const { deletedAt, sessionDirName } = parseEntryId(id);
+	const cwd = typeof header.cwd === "string" ? header.cwd : "";
+	return {
+		id,
+		sessionId: typeof header.id === "string" && header.id !== "" ? header.id : sessionDirName,
+		projectDir: cwd === "" ? NO_CWD_PROJECT_DIR : projectKey(cwd),
+		workspaceId: "",
+		wasArchived: false,
+		deletedAt,
+		title: "",
+		sizeBytes
+	};
+}
+/** 对账并回清单——**返回的就是修好之后的那份**（与 `manifest.list()` 同序：最近删除在前）。 */
+async function reconcileTrash(deps) {
+	const rows = await deps.manifest.list();
+	const root = `${deps.home}/session-trash`;
+	if (!await deps.fs.exists(root)) return rows;
+	const dirIds = /* @__PURE__ */ new Set();
+	for (const name of await deps.fs.listDirs(root)) if (isEntryId(name)) dirIds.add(name);
+	const rowIds = new Set(rows.map((row) => row.id));
+	const drops = rows.filter((row) => !dirIds.has(row.id));
+	const rebuilds = [];
+	for (const id of dirIds) {
+		if (rowIds.has(id)) continue;
+		const entry = await buildEntry(deps, id);
+		if (entry !== void 0) rebuilds.push(entry);
+	}
+	if (drops.length === 0 && rebuilds.length === 0) return rows;
+	for (const row of drops) await deps.manifest.remove(row.id);
+	for (const entry of rebuilds) await deps.manifest.add(entry);
+	return await deps.manifest.list();
+}
+//#endregion
+//#region src/verbs/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
+		};
+	};
+}
+//#endregion
+//#region src/verbs/restore-session.ts
+/**
+* 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
+* 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
+*
+* 三段与删除对称：
+* ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
+*    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
+*    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
+* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行 → 通告回来。
+* ③ 中途失败把这个成员自己退回回收站（就地回滚），并把**已经恢复完的**兄弟按相反顺序一起退回，失败照抛。
+*/
+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}`);
+		}
+		const done = [];
+		const restored = [];
+		try {
+			for (const entry of group) {
+				done.push(await restoreOne(deps, entry));
+				restored.push(entry.sessionId);
+			}
+		} catch (error) {
+			for (const undo of done.reverse()) await undo();
+			throw error;
+		}
+		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);
+	}
+	try {
+		await deps.manifest.remove(entry.id);
+	} 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 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(() => {});
+	};
+}
+//#endregion
+//#region src/verbs/delete-session.ts
+/**
+* 删除 = 移入回收站，**按组走**：用户点掉一条父会话时，宿主的客户端把 `origin:"subagent"` 的孩子
+* 整排藏了 ⇒ 那些目录既看不见也继续占着字节（本机实测 41 条父留了 320 个目录 / 74.6 MB）。
+* 所以这里把父在盘上的孩子一起搬进来，各自成目录、各自一行，清册用 `parentEntryId` 记它是谁的孩子。
+*
+* 三段，顺序承重：
+* ① **先点组、先验活体**（一个字节都不写）。任一成员在跑就整组拒绝——不替用户终止正在跑的活，
+*    也绝不允许"父已经搬进回收站、孩子因为在跑而搬不动"这种半套。
+* ② **逐个搬**：每个成员内部沿用原来那套顺序与就地回滚（归档 → 摘账本 → 搬目录 → 写清册），
+*    任何一步失败就把这个成员自己退回原地。
+* ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
+*    账本跟着挂、可见性跟着还原），失败照抛——不留"半组在回收站、半组在原地"的世界。
+*/
+function deleteSession(deps) {
+	return async function deleteSession(sessionId, options = {}) {
+		const kids = await deps.host.subagentMembers(sessionId);
+		const parentProjectDir = await deps.host.projectDirOf(sessionId);
+		if (parentProjectDir === void 0) throw verbError("not-found", `宿主的持久化里没有这个会话：${sessionId}`);
+		const candidates = [{
+			sessionId,
+			projectDir: parentProjectDir
+		}, ...kids.map((k) => ({
+			sessionId: k.sessionId,
+			projectDir: k.projectDir
+		}))];
+		for (const member of candidates) if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
+		const parentDir = sessionDirOf(parentProjectDir, sessionId, deps.home);
+		if (!await deps.fs.exists(parentDir)) throw verbError("not-found", `会话目录不存在：${parentDir}`);
+		const members = [{
+			sessionId,
+			projectDir: parentProjectDir
+		}];
+		for (const kid of kids) if (await deps.fs.exists(sessionDirOf(kid.projectDir, kid.sessionId, deps.home))) members.push({
+			sessionId: kid.sessionId,
+			projectDir: kid.projectDir
+		});
+		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));
+			}
+		} catch (error) {
+			for (const undo of done.reverse()) await undo();
+			throw error;
+		}
+		return parentEntry;
+	};
+}
+/**
+* 搬一个成员进回收站。五件写的顺序照设计稿 §4 那五触点，每一步的失败都**就地**把这个成员自己退回原地：
+* 归档必须先于摘账本（否则中间有一段"无主且可见"的窗口，它会掉进「未分组」），文件在两件纯读之后，
+* 清册行是最后一件写（它失败就把目录挪回去、账本挂回去、可见性还原）。
+*/
+async function moveOneIn(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 entry = {
+		id: entryId,
+		sessionId,
+		projectDir,
+		workspaceId: workspaceId ?? "",
+		wasArchived,
+		deletedAt,
+		title,
+		sizeBytes,
+		...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);
+	}
+	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);
+	}
+	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(() => {});
+}
+//#endregion
+//#region src/verbs/apply.ts
+/**
+* 批量动作（2026-10-17 重构批）：`POST /apply` 的落点——**一组 id 上的同一个动作**。
+*
+* 为什么要这一层：批量恢复 100+ 条的真实成本不在搬文件，在**每条一次的全表读**——旧形状是
+* 浏览器半循环 N 次 HTTP，每次都走「读全量清册 + 预检 + 逐成员通告时再拉一遍宿主会话表」。
+* 这一层把整批抬成一次：清册只读一次、宿主会话表只预取一次、通告一次批量发；
+* 单条动作就是 N=1 的批量，**仓里不再留第二条执行路径**。
+*
+* 三条批量语义（都是接口的一部分，不是实现细节）：
+* ① 输入去重、保持输入顺序（界面上"清单从上往下"的那一份读感）；
+* ② 一条失败不传染下一条——**逐条 try/catch**，失败按 `map-error` 那张表折成信封里的
+*    `{code,message,details?}`；
+* ③ 「已被同批前一条带走」是**幂等成功**，不是失败：恢复一条已经跟着父回来的孩子，
+*    用户要的结果本来就已经达成了（`delete`/`restore` 回 `null`；`purge` 回
+*    `{removed:0,freedBytes:0}`）。
+*/
+function failure(id, action, error) {
+	return {
+		id,
+		action,
+		ok: false,
+		error: toRemoteFailure(error)
+	};
+}
+/** 按动作收窄的成功支（判别联合要的是**字面量**，所以动作参数按 `A` 收，不收成宽化的 `ApplyAction`）。 */
+function success(id, action, value) {
+	return {
+		id,
+		action,
+		ok: true,
+		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、或对账刚摘掉它），必须照样响亮报 `trash-empty`，
+* 不能被"已被带走"这句话掩盖成一次成功。**所以判据是快照的原始形状，不是当前形状**：
+* 原始快照里认得出（它自己、它的父、或它的孩子任一在），而当前快照里已经空了 ⇒ 同批带走的。
+*/
+function takenByEarlierInBatch(original, current, id) {
+	return groupOf(original, id).length > 0 && groupOf(current, id).length === 0;
+}
+function applyActions(deps, action, ids) {
+	switch (action) {
+		case "delete": return applyDelete(deps, ids);
+		case "restore": return applyRestore(deps, ids);
+		case "purge": return applyPurge(deps, ids);
+		case "count": return applyCount(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 = [];
+		try {
+			const entry = await run(sessionId, { onMembers: (sessionIds) => {
+				members = sessionIds;
+			} });
+			for (const id of members) taken.add(id);
+			outcomes.push(success(sessionId, "delete", entry));
+		} catch (error) {
+			outcomes.push(failure(sessionId, "delete", 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;
+		}
+		try {
+			const entry = await run(entryId, {
+				snapshot,
+				suppressAnnounce: true
+			});
+			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));
+		}
+	}
+	if (restored.length > 0) await deps.host.announceRestoredBatch(restored, await deps.host.restoredSummariesOf());
+	return outcomes;
+}
+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));
+		}
+	}
+	return outcomes;
+}
+/** 删除确认框那句「含 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 跑第二遍是"幂等成功"的伪装，不该发生）。 */
+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;
+}
+//#endregion
+//#region src/api/dispatch.ts
+/** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
+const JSON_BODY_MAX_BYTES = 1048576;
+/** 回环地址的三种写法（IPv4 / IPv6 / IPv4-mapped IPv6）。 */
+const LOOPBACK = [
+	"127.0.0.1",
+	"::1",
+	"::ffff:127.0.0.1"
+];
+/**
+* 桌面壳那条路（asar `/lib/main.js` 的 `forwardWebRequest`）：渲染进程从 `dsh-app://app/` 加载，
+* 页面里对**非静态路径**的请求（`/`、`/index.html`、`/assets/*`、`/plugins/…` 之外的一切——包括
+* 我们这条前缀路由）都由 `protocol.handle("dsh-app")` 转给宿主自己的 web server；转发前它把
+* `host` / `origin` / `cookie` / `sec-fetch-site` 四个头**删掉**、换上一枚宿主自己的 cookie，路径与
+* 查询串原样带走（逐字：`for (const name of ["host","origin","cookie","sec-fetch-site"]) headers.delete(name)`）。
+* ⇒ 桌面版打到我们这条路由上的请求是**没有 `Origin`** 的，`Referer` 则保留（同源请求照常带，
+* 页面就住在 `dsh-app://app/`）。壳自己在上游只放行 `origin ∈ {null, "dsh-app://app"}`。
+*/
+const DESKTOP_APP_SCHEME = "dsh-app:";
+const DESKTOP_APP_HOST = "app";
+/**
+* 「这是桌面壳自己的页面吗」。**必须按 `protocol` + `host` 判，不能比 `URL.origin`**：`dsh-app:`
+* 不是 WHATWG 的 special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`（Node 实测），
+* 拿它跟字面量比永远为假 ⇒ 栅栏会把真机上的每一次请求都挡成 403，四个入口一个都不出现。
+*
+* 这个判据为什么不可能被外人伪造：`Origin` 与 `Referer` 都是 forbidden header，网页改不了，
+* 只能是浏览器/壳自己带上；而 `dsh-app://app` 只可能是桌面壳自己的页面。
+*/
+function isDesktopShellUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === DESKTOP_APP_SCHEME && url.host === DESKTOP_APP_HOST;
+	} catch {
+		return false;
+	}
+}
+function writeJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+function writeOk(res, value) {
+	writeJson(res, 200, {
+		ok: true,
+		value
+	});
+}
+/** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表）。
+*  **状态语义（2026-10-17 错误面对齐）**：**请求本身不对**不再伪装成 200——请求体不对 400、方法不对 405、
+*  未知路由 404、栅栏拒 403（它们不是"一次办成的操作"，是"这条请求不归我办/你没资格办"）。
+*  **操作失败**仍回 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), {
+		ok: false,
+		error: toRemoteFailure(error)
+	});
+}
+/**
+* 同源栅栏（见文件头 ④）。看 `origin` 而不只看 `referer` 的理由：恶意页
+* `<meta name="referrer" content="no-referrer">` 能让 Referer 缺席，但浏览器对跨源请求**总是**发 Origin。
+*
+* 放行的三种形状，各自都是"浏览器/壳自动带上、网页改不了"的那种：
+* ① `Origin` 与 `Host` 同源（浏览器直接打开宿主那行 URL）；② `Origin` 是桌面壳的 `dsh-app://app`
+* （壳自己在上游也只放行这个 origin）；③ `Referer` 是桌面壳的 `dsh-app://app`（**真机那条路**：
+* 壳把 `Origin` 删掉了、只留下 Referer，见 {@link isDesktopShellUrl}）。两者都缺席 = 本机工具 /
+* curl（注释即此承诺）。**恶意网页拿不到 ②③ 里的任何一个**：那两个头都是 forbidden header、
+* 页面伪造不了；而**写口（POST）在任何跨源形态下都必带 Origin** ⇒ 两个头全缺席就等于本机工具。
+* 唯一的缝是跨源 `no-cors` 的 **GET**（Referer 被 `no-referrer` 掐掉、Origin 也不带）——它只够得到
+* 只读的 `list`，而 no-cors 的回包是 opaque、页面读不出内容 ⇒ 不构成泄露。
+*/
+function isTrustedRequest(req) {
+	if (!LOOPBACK.includes(req.socket.remoteAddress ?? "")) return false;
+	const host = req.headers.host;
+	const origin = req.headers.origin;
+	if (origin !== void 0 && !isDesktopShellUrl(origin)) try {
+		if (new URL(origin).host !== host) return false;
+	} catch {
+		return false;
+	}
+	const referer = req.headers.referer;
+	if (referer === void 0) return true;
+	if (isDesktopShellUrl(referer)) return true;
+	try {
+		return new URL(referer).host === host;
+	} catch {
+		return false;
+	}
+}
+/** 流式读 body 并解析成 JSON 对象：空体回 `null`，超限 / 非法 JSON / 不是对象一律抛（→ 400 + 失败信封）。
+*  **请求本身不对**（400）与**那次操作读不到东西**（200 + 信封）是两件事：前者是调用方没组好请求，
+*  后者是盘上没有；把前者也写成 200，代理与日志里就再也分不出这两类。 */
+async function readJsonBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += buf.length;
+		if (size > JSON_BODY_MAX_BYTES) throw routeError("bad-request", 400, `请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
+		chunks.push(buf);
+	}
+	const text = Buffer.concat(chunks).toString("utf8").trim();
+	if (text === "") return null;
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw routeError("bad-request", 400, "请求体需为 JSON 对象");
+		return parsed;
+	} catch (error) {
+		if (error instanceof SyntaxError) throw routeError("bad-request", 400, `请求体不是合法 JSON：${error.message}`);
+		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}`);
+}
+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 createApiHandler(deps) {
+	/**
+	* 到达序串行链（文件头 ⑤）：`list`（含对账）与三个写动词一个跑完再放下一个。`tail` 由构造保证
+	* **永不 reject**（每个任务自己的失败留在交回给那次请求的那个 promise 上），所以一次失败不会卡死链。
+	*/
+	let tail = Promise.resolve();
+	const throughChain = (task) => {
+		const started = tail.then(task);
+		tail = started.then(() => void 0, () => void 0);
+		return started;
+	};
+	return async function handle(req, res) {
+		if (!isTrustedRequest(req)) {
+			writeFailure(res, /* @__PURE__ */ new Error("非受信来源"), 403);
+			return;
+		}
+		try {
+			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)));
+		} catch (error) {
+			writeFailure(res, error);
+		}
+	};
+}
+//#endregion
+//#region src/ports/fs-port.ts
+/** 模块级递归：端口方法**解构出来单独调**也不能靠 `this`（`{ sizeOfDir } = port` 会让方法体的
+*  `this` 变成 undefined）。所以端口只做转发，递归在模块作用域里自调。 */
+async function sizeOfDir(p) {
+	let total = 0;
+	for (const e of await readdir(p, { withFileTypes: true })) {
+		const child = join(p, e.name);
+		total += e.isDirectory() ? await sizeOfDir(child) : (await stat(child)).size;
+	}
+	return total;
+}
+function createFsPort() {
+	return {
+		async exists(p) {
+			return existsSync(p);
+		},
+		async ensureDir(p) {
+			await mkdir(p, { recursive: true });
+		},
+		async rename(from, to) {
+			await rename(from, to);
+		},
+		async removeDir(p) {
+			await rm(p, {
+				recursive: true,
+				force: true
+			});
+		},
+		sizeOfDir: (p) => sizeOfDir(p),
+		async listFiles(p) {
+			return readdir(p);
+		},
+		async listDirs(p) {
+			return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+		},
+		async readFile(p) {
+			return readFile(p);
 		}
 	};
 }
@@ -1038,7 +1754,7 @@ const name = "@xrn1997/dsh-session-delete";
 *   它取不到时 `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` 原文读实，不是猜的。
 */
@@ -1075,7 +1791,9 @@ 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` 的接口逐项）。 */
+/** `TrashEntry` 里**每条记录都必须有**的那几格（`src/trash/entry.ts` 接口的非可选字段）。
+*  **可选字段不在这里**：`parentEntryId`（级联那批加的）缺席是合法的——老行没有它，缺了就是"没有父"；
+*  校验器只管这几格的类型，其余键**原样带走**（`parse` 交回的就是 `raw` 本身）⇒ 新字段照旧存得住。 */
 const TRASH_ENTRY_FIELDS = {
 	id: "string",
 	sessionId: "string",
@@ -1106,18 +1824,30 @@ const trashDomainSpec = defineDomain({
 });
 /**
 * 清单的真实绑定：官方 storage domain → `ManifestPort`（`StorageDomainLike` 在动词层保持一种读法）。
-* 域**懒开**且只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
-* 插件卸载时关掉句柄（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约）。
+* 域**懒开**且成功句柄只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
+* 插件卸载时关掉句柄并把 `close()` 的落地交回框架（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约；
+* 2026-10-17 起不再 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
+*
+* **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
+* 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。
 */
 function createStorageManifest(ctx) {
 	const host = ctx;
+	let domain;
 	let opening;
-	ctx.effect(() => () => {
-		opening?.then((handle) => handle.close()).catch(() => {});
+	ctx.effect(() => async () => {
+		await ((opening !== void 0 ? await opening.catch(() => void 0) : void 0) ?? domain)?.close();
 	}, "session-delete.manifest");
 	const table = async () => {
-		opening ??= host.storageDomain.open(trashDomainSpec);
-		return (await opening).table("entries");
+		if (domain === void 0) {
+			opening ??= host.storageDomain.open(trashDomainSpec);
+			try {
+				domain = await opening;
+			} finally {
+				opening = void 0;
+			}
+		}
+		return domain.table("entries");
 	};
 	return createStorageManifest$1({
 		readAll: async () => [...(await table()).entries()].map(([, record]) => record),