@xrn1997/dsh-session-delete 0.1.1 → 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,20 +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` **对账并读**清单——`session-trash/` 里的目录是准，其余四个
-*  `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 都不成立）。
@@ -67,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
@@ -86,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;
 	}
 }
@@ -106,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
@@ -273,8 +345,33 @@ function frameRanges(raw) {
 *    真被切断的尾巴（写一半）仍然**跳过并计数**：绝不因为一行就抛整个读数，前面几百条是真的。
 */
 const NEWLINE = 10;
-/** 会话日志的文件名后缀（`session.vN.jsonl.zstd`）。详情与回收站对账都按它挑日志，名字只有这一处家。 */
-const SESSION_LOG_SUFFIX = ".jsonl.zstd";
+/**
+* 宿主给每一代日志的词法（逐字取自 `@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;
+}
 /**
 * 逐帧走一遍日志，每条记录交给回调。
 *
@@ -358,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(SESSION_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 {
@@ -464,6 +561,74 @@ function liveSessionsOf(ctx) {
 	if (typeof store.get !== "function" || typeof store.liveEntryFor !== "function") return void 0;
 	return store;
 }
+/** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。 */
+async function filterChildrenOf(sessionQuery, values) {
+	return sessionQuery.filterSessions([{
+		kind: "parent",
+		values: [...values].sort()
+	}]);
+}
+/**
+* 从若干根出发**逐层往下**把盘上的后代问出来，交回 `父（bare）→ 孩子` 的索引。
+*
+* 为什么一次问一层而不是官方的 `traceSession`：那条在父已经进回收站时认不出目标
+* （`SESSION_QUERY_SESSION_NOT_FOUND`），而我们要的那批正是"父已经不在宿主列表里之后还剩在盘上的"。
+* `kind:'parent'` 是唯一能按 `header.parentSession` 反着问的一支。
+*
+* 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
+* （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
+* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostPort.subagentMembers} 那条），
+* 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
+*/
+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);
+		}
+		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` 重建条目）共用这一个字面量。 */
@@ -529,8 +694,35 @@ const NO_SUCH_SESSION = "session persistence holds no such session";
 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 [];
+	}
+}
 /**
-* 宿主服务层的**真实绑定**：十二个方法各自把动词层的问题翻成宿主官方服务的调用。
+* 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
 *
 * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
 * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
@@ -650,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);
@@ -685,6 +900,47 @@ 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
+			}));
 		}
 	};
 }
@@ -735,7 +991,7 @@ async function buildEntry(deps, id) {
 	const dir = trashDirOf(id, deps.home);
 	let logName;
 	try {
-		logName = (await deps.fs.listFiles(dir)).find((name) => name.endsWith(SESSION_LOG_SUFFIX));
+		logName = pickSessionLog(await deps.fs.listFiles(dir));
 	} catch {
 		return;
 	}
@@ -793,74 +1049,11 @@ async function reconcileTrash(deps) {
 	return await deps.manifest.list();
 }
 //#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;
+	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) {
@@ -872,6 +1065,8 @@ function purgeTrash(deps) {
 				});
 			}
 			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 {
@@ -882,43 +1077,361 @@ function purgeTrash(deps) {
 }
 //#endregion
 //#region src/verbs/restore-session.ts
+/**
+* 恢复 = 把删除那次**按原路退回**，而且按组走：当年是按组一起搬进来的（父 + 它在盘上的孩子），
+* 只回父就会在回收站里留下一堆点不到的孩子行——清单只列父行，那些行既看不见也清不掉。
+*
+* 三段与删除对称：
+* ① **预检整组**（一个字节都不写）：每个成员的回收站目录与项目目录都得在。缺席的判据与原来一致
+*    （回收站目录不在 = `trash-empty`；原项目目录不在 = `project-missing`，且绝不静默建目录）。
+*    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
+* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行 → 通告回来。
+* ③ 中途失败把这个成员自己退回回收站（就地回滚），并把**已经恢复完的**兄弟按相反顺序一起退回，失败照抛。
+*/
 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);
+	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
 		});
-		if (entry.workspaceId !== "") try {
-			await deps.host.attach(entry.sessionId, entry.workspaceId);
+		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) {
-			await deps.fs.rename(sessionDir, trashDir).catch(() => {});
-			throw verbError("io", `挂回账本失败：${String(error)}`, error);
+			for (const undo of done.reverse()) await undo();
+			throw error;
 		}
-		if (!entry.wasArchived) try {
-			await deps.host.unarchive(entry.sessionId);
+		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) {
-			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);
+			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 {
-			await deps.manifest.remove(entry.id);
+			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) {
-			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);
+			outcomes.push(failure(entryId, "restore", error));
 		}
-		await deps.host.announceRestored(entry.sessionId);
-		return entry;
-	};
+	}
+	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
@@ -967,9 +1480,16 @@ function writeOk(res, value) {
 		value
 	});
 }
-/** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表），值就是线上形状本身。 */
-function writeFailure(res, error, status = 200) {
-	writeJson(res, status, {
+/** 失败信封：码与原文都来自 `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)
 	});
@@ -1005,68 +1525,136 @@ function isTrustedRequest(req) {
 		return false;
 	}
 }
-/** 流式读 body 并解析成 JSON 对象：空体回 `null`，超限 / 非法 JSON / 不是对象一律抛（→ 失败信封）。 */
+/** 流式读 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 new Error(`请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
+		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;
-	let parsed;
 	try {
-		parsed = JSON.parse(text);
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw routeError("bad-request", 400, "请求体需为 JSON 对象");
+		return parsed;
 	} catch (error) {
-		throw new Error(`请求体不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
+		if (error instanceof SyntaxError) throw routeError("bad-request", 400, `请求体不是合法 JSON：${error.message}`);
+		throw error;
 	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("请求体需为 JSON 对象");
-	return parsed;
 }
 /** 必填的非空字符串字段（缺、空串、类型不对都是**同一句话**：说清是哪个字段）。 */
 function requireString(body, field) {
 	const value = body?.[field];
-	if (typeof value !== "string" || value === "") throw new Error(`请求体需带非空字符串字段 ${field}`);
+	if (typeof value !== "string" || value === "") throw routeError("bad-request", 400, `请求体需带非空字符串字段 ${field}`);
 	return value;
 }
-/** `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} 若在场必须是非空字符串`);
+/** `/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 new Error(`方法不允许：${method}（${SESSION_DELETE_API_PREFIX}${route} 需 ${want}）`);
+	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 }
+		};
+	});
 }
-/** 路由表：段名 → 一个把「方法 + 请求体」变成返回值的处理器。动词在每次调用时才取。 */
-async function dispatch(method, rest, req, deps) {
+/** 路由表：段名 → 一个把「方法 + 预读好的请求体」变成返回值的处理器。动词在每次调用时才取。
+*  `body` 由 {@link purityOf} 读一次交下来——同一条请求的流不能被消费两遍。 */
+async function dispatch(method, rest, body, deps) {
 	if (rest === ROUTES.list) {
 		requireMethod(method, "GET", ROUTES.list);
-		return await reconcileTrash(deps);
+		return assembleTrashRows(deps, await reconcileTrash(deps));
 	}
-	if (rest === ROUTES.delete) {
-		requireMethod(method, "POST", ROUTES.delete);
-		return await deleteSession(deps)(requireString(await readJsonBody(req), PARAMS.sessionId));
+	if (rest === ROUTES.ping) {
+		requireMethod(method, "GET", ROUTES.ping);
+		return "pong";
 	}
-	if (rest === ROUTES.restore) {
-		requireMethod(method, "POST", ROUTES.restore);
-		return await restoreSession(deps)(requireString(await readJsonBody(req), PARAMS.entryId));
+	if (rest === ROUTES.apply) {
+		requireMethod(method, "POST", ROUTES.apply);
+		return await applyActions(deps, requireAction(body), requireIdArray(body));
 	}
-	if (rest === ROUTES.purge) {
-		requireMethod(method, "POST", ROUTES.purge);
-		return await purgeTrash(deps)(optionalString(await readJsonBody(req), PARAMS.entryId));
+	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(await readJsonBody(req), PARAMS.entryId));
+		return await readTrashDetail(deps)(requireString(body, PARAMS.entryId));
 	}
-	throw new Error(`未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
+	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
+	};
 }
-/** 宿主 `webServer.register({kind:'prefix', path: SESSION_DELETE_API_PREFIX, handler})` 的那个 handler。 */
 function createApiHandler(deps) {
 	/**
 	* 到达序串行链（文件头 ⑤）：`list`（含对账）与三个写动词一个跑完再放下一个。`tail` 由构造保证
@@ -1085,10 +1673,11 @@ function createApiHandler(deps) {
 		}
 		try {
 			const url = new URL(req.url ?? "/", "http://dsh.internal");
-			if (!url.pathname.startsWith("/dsh-session-delete-api")) throw new Error(`未知路由：${url.pathname}`);
+			if (!url.pathname.startsWith("/dsh-session-delete-api")) throw routeError("not-found-route", 404, `未知路由：${url.pathname}`);
 			const rest = url.pathname.slice(23);
-			const task = () => dispatch(req.method ?? "GET", rest, req, deps);
-			writeOk(res, await (rest === ROUTES.detail ? task() : throughChain(task)));
+			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);
 		}
@@ -1165,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` 原文读实，不是猜的。
 */
@@ -1202,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",
@@ -1233,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),