@xrn1997/dsh-session-delete 0.0.1 → 0.1.1

package/lib/index.js

@@ -1,10 +1,11 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import zlib from "node:zlib";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 //#region src/shared/wire.ts
 /**
-* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、四个端点段、请求字段名**——
+* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、五个端点段、请求字段名**——
 * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
 * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
 *
@@ -27,12 +28,15 @@ import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
 * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 四个端点的段名（相对前缀；`GET list` 读、其余三个 `POST` 写）。 */
+/** 五个端点的段名（相对前缀；`GET list` **对账并读**清单——`session-trash/` 里的目录是准，其余四个
+*  `POST` 按 id 取数或写）。 */
 const ROUTES = {
 	list: "/list",
 	delete: "/delete",
 	restore: "/restore",
-	purge: "/purge"
+	purge: "/purge",
+	/** 单条详情（读回收站目录里那条会话自己的日志）。用 POST 表达一个读：见设计稿 2026-10-15 §3。 */
+	detail: "/detail"
 };
 /** 请求体字段名：浏览器半发、Node 半读，同名同义（`purge` 的 `entryId` 缺席 = 清空）。 */
 const PARAMS = {
@@ -156,6 +160,639 @@ function trashDirOf(entryId, home) {
 	return `${home}/session-trash/${entryId}`;
 }
 //#endregion
+//#region src/log/zstd-frames.ts
+const MAGIC = [
+	40,
+	181,
+	47,
+	253
+];
+/** magic(4) + Frame_Header_Descriptor(1) 之后第一个字节的偏移。 */
+const AFTER_DESCRIPTOR = 5;
+const BLOCK_HEADER_BYTES = 3;
+const BLOCK_LAST = 1;
+const BLOCK_TYPE_SHIFT = 1;
+const BLOCK_SIZE_SHIFT = 3;
+const BLOCK_SIZE_MASK = 2097151;
+const BLOCK_RAW = 0;
+const BLOCK_RLE = 1;
+const BLOCK_COMRESSED = 2;
+/** 规范（RFC 8878 表 4）里 3 是 **Reserved**，不是"未压缩块"：见到就抛，别照 Raw 吞块体。 */
+const BLOCK_RESERVED = 3;
+/** descriptor 各字段的取值 → 字段字节数（zstd 帧头的两张尺寸表）。 */
+const DID_SIZES = [
+	0,
+	1,
+	2,
+	4
+];
+const FCS_SIZES_SINGLE = [
+	1,
+	2,
+	4,
+	8
+];
+const FCS_SIZES_MULTI = [
+	0,
+	2,
+	4,
+	8
+];
+/** 实测的帧尾长度（校验和位置；bit5 没置位也照样带，见文件头注）。 */
+const FRAME_TAIL_BYTES = 4;
+function isMagicAt(raw, at) {
+	return MAGIC.every((byte, i) => raw[at + i] === byte);
+}
+function readUint24LE(raw, at) {
+	return raw[at] | raw[at + 1] << 8 | raw[at + 2] << 16;
+}
+/** 块体之后有没有那 4 字节尾巴：只有"跳过它之后仍是帧头或到 EOF"才认。 */
+function withFrameTail(raw, at) {
+	const afterTail = at + FRAME_TAIL_BYTES;
+	if (afterTail <= raw.length && (afterTail === raw.length || isMagicAt(raw, afterTail))) return afterTail;
+	return at;
+}
+/**
+* 把 `raw` 切成帧区间。
+* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
+*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
+*/
+function frameRanges(raw) {
+	const ranges = [];
+	let at = 0;
+	while (at < raw.length) {
+		if (!isMagicAt(raw, at)) throw new Error(`zstd 帧头缺席：偏移 ${at} 处不是 magic（前面第 ${ranges.length} 帧的边界算歪了？）`);
+		const descriptor = raw[at + 4];
+		if (descriptor === void 0) throw new Error(`zstd 帧头不完整：偏移 ${at} 之后不足 ${AFTER_DESCRIPTOR} 字节`);
+		const fcsFlag = descriptor & 3;
+		const singleSegment = descriptor >> 2 & 1;
+		const didFlag = descriptor >> 6 & 3;
+		let cursor = at + AFTER_DESCRIPTOR;
+		if (!singleSegment) cursor += 1;
+		cursor += DID_SIZES[didFlag];
+		cursor += (singleSegment ? FCS_SIZES_SINGLE : FCS_SIZES_MULTI)[fcsFlag];
+		for (;;) {
+			const blockHeader = readUint24LE(raw, cursor);
+			cursor += BLOCK_HEADER_BYTES;
+			if (cursor > raw.length) throw new Error(`zstd 块头越界：帧起于 ${at}，读到偏移 ${cursor}（文件长 ${raw.length}）`);
+			const blockType = blockHeader >> BLOCK_TYPE_SHIFT & 3;
+			const blockSize = blockHeader >> BLOCK_SIZE_SHIFT & BLOCK_SIZE_MASK;
+			if (blockType === BLOCK_RESERVED) throw new Error(`zstd 保留块类型：帧起于 ${at}，偏移 ${cursor - BLOCK_HEADER_BYTES} 的块头 type=3（规范 Reserved，对面解不开）`);
+			if (blockType === BLOCK_RAW || blockType === BLOCK_COMRESSED) cursor += blockSize;
+			else if (blockType === BLOCK_RLE) cursor += 1;
+			if (blockHeader & BLOCK_LAST) break;
+		}
+		cursor = withFrameTail(raw, cursor);
+		if (cursor !== raw.length && !isMagicAt(raw, cursor)) throw new Error(`zstd 帧边界算歪了：帧起于 ${at}，算到 ${cursor}，那里既不是下一帧帧头也不是 EOF`);
+		ranges.push({
+			start: at,
+			end: cursor
+		});
+		at = cursor;
+	}
+	return ranges;
+}
+//#endregion
+//#region src/log/session-log.ts
+/**
+* 会话日志（`session.vN.jsonl.zstd`）的**逐帧读法**：帧边界交给 `zstd-frames.ts`，这一层只做
+* 「帧 → 明文 → 一行一条 JSON」的解码，并把每条记录原样交给回调。
+*
+* **策略不在这里**（哪些 `type` 算正文、截断到多少字、算不算失败）——那是 `src/trash/detail.ts` 的事。
+* 这一层只懂编解码，所以它能被单独验穿。
+*
+* 两条实测决定的口径：
+* ① **必须逐帧**：Node 的 `zstdDecompressSync` 与 `createZstdDecompress()` 都只给第一帧（见
+*    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
+*    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
+* ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
+*    实测本机 686 个 `.jsonl.zstd` / 92 421 帧**没有一帧切在行中间**（连最后一帧都整行收尾），
+*    所以旧口径当时并不丢东西；但"逐帧 `split('\n')`"一旦遇上切行就是**静默少一条记录**（半个头
+*    加半个身，两半都解不开 JSON），而少掉的那条正是页面上要跟账的正文。带上余量之后这条不变量
+*    不必再成立，顺带把**跨帧的多字节字符**也解对了——拼接在字节层做，`toString('utf8')` 只看整行。
+*    真被切断的尾巴（写一半）仍然**跳过并计数**：绝不因为一行就抛整个读数，前面几百条是真的。
+*/
+const NEWLINE = 10;
+/** 会话日志的文件名后缀（`session.vN.jsonl.zstd`）。详情与回收站对账都按它挑日志，名字只有这一处家。 */
+const SESSION_LOG_SUFFIX = ".jsonl.zstd";
+/**
+* 逐帧走一遍日志，每条记录交给回调。
+*
+* 回调返回 `false` = **提前停机**（后面的帧不再解——`readSessionHeader` 只要第一行）。
+* 停机后 `stats` 只是停机前那部分，别拿来做全量对账。
+*/
+function walkSessionLog(raw, onRecord) {
+	const stats = {
+		frames: 0,
+		records: 0,
+		unparsedLines: 0,
+		truncatedTailBytes: 0
+	};
+	let stopped = false;
+	const feed = (line) => {
+		if (line === "") return;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			stats.unparsedLines += 1;
+			return;
+		}
+		stats.records += 1;
+		if (onRecord(parsed !== null && typeof parsed === "object" ? parsed : {}) === false) stopped = true;
+	};
+	/** 上一帧没闭合的那一行。**存字节不存字符**：切在多字节字符中间的帧要拼回完整才解得对。 */
+	let carry = Buffer.alloc(0);
+	for (const { start, end } of frameRanges(raw)) {
+		if (stopped) break;
+		stats.frames += 1;
+		let plain;
+		try {
+			plain = zlib.zstdDecompressSync(raw.subarray(start, end));
+		} catch (error) {
+			throw new Error(`回收站日志第 ${stats.frames} 帧解压失败：${String(error)}`);
+		}
+		const merged = carry.length === 0 ? plain : Buffer.concat([carry, plain]);
+		const cut = merged.lastIndexOf(NEWLINE);
+		if (cut === -1) {
+			carry = merged;
+			continue;
+		}
+		carry = merged.subarray(cut + 1);
+		for (const line of merged.subarray(0, cut).toString("utf8").split("\n")) {
+			feed(line);
+			if (stopped) break;
+		}
+	}
+	stats.truncatedTailBytes = carry.length;
+	if (carry.length > 0 && !stopped) feed(carry.toString("utf8"));
+	return stats;
+}
+/**
+* 日志的 **header**：格式事实是"第一行即 header"（`type: 'session'`，含 `id` 与 `cwd`，v3/v4 均如此，
+* AGENTS.md 有实测背书）——这里按 `type === 'session'` 找**第一条**这样的记录并就地停机
+* （不要求它恰是第一个可解析行：坏一行前缀不该让整条日志判不出身份）。
+* 找不到（空日志 / 全是别种记录）回 `undefined`；帧坏了照抛——那是"读不出来"，与"没有 header"是两件事。
+*/
+function readSessionHeader(raw) {
+	let header;
+	walkSessionLog(raw, (record) => {
+		if (record.type !== "session") return;
+		header = record;
+		return false;
+	});
+	return header;
+}
+const DEFAULT_LIMITS = {
+	perMessageChars: 3e3,
+	totalChars: 5e5
+};
+/** 一条记录里那些 `content[]` 段的文字拼起来（`\n` 分隔；非 text 段一律不参与）。 */
+function textOf(content) {
+	if (!Array.isArray(content)) return "";
+	return content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n").trim();
+}
+function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
+	return async function readTrashDetail(entryId) {
+		const record = (await deps.manifest.list()).find((e) => e.id === entryId);
+		if (record === void 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
+		const dir = trashDirOf(record.id, deps.home);
+		if (!await deps.fs.exists(dir)) throw verbError("io", `回收站目录不在：${dir}`);
+		const names = (await deps.fs.listFiles(dir)).sort();
+		const logName = names.find((n) => n.endsWith(SESSION_LOG_SUFFIX));
+		if (logName === void 0) throw verbError("io", `回收站目录里没有会话日志：${dir}（里面有：${names.join(", ") || "空目录"}）`);
+		let raw;
+		try {
+			raw = await deps.fs.readFile(`${dir}/${logName}`);
+		} catch (error) {
+			throw verbError("io", `读会话日志失败：${String(error)}`, error);
+		}
+		const detail = {
+			entryId: record.id,
+			cwd: "",
+			createdAt: 0,
+			lastActivity: 0,
+			logTitle: "",
+			models: [],
+			turnCount: 0,
+			userMessageCount: 0,
+			assistantMessageCount: 0,
+			toolCallCount: 0,
+			injectedCount: 0,
+			messages: [],
+			omittedByPayloadCap: 0
+		};
+		const models = /* @__PURE__ */ new Set();
+		let usedChars = 0;
+		let capped = false;
+		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停。 */
+		function push(role, time, text) {
+			if (capped) {
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			const truncated = text.length > limits.perMessageChars;
+			const kept = truncated ? text.slice(0, limits.perMessageChars) : text;
+			if (usedChars + kept.length > limits.totalChars) {
+				capped = true;
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			usedChars += kept.length;
+			detail.messages.push({
+				role,
+				time,
+				text: kept,
+				truncated
+			});
+		}
+		try {
+			walkSessionLog(raw, (r) => {
+				if (typeof r.time === "number" && r.time > detail.lastActivity) detail.lastActivity = r.time;
+				const data = r.data ?? {};
+				switch (r.type) {
+					case "session":
+						if (typeof r.cwd === "string") detail.cwd = r.cwd;
+						if (typeof r.createdAt === "number") detail.createdAt = r.createdAt;
+						return;
+					case "session/title":
+						if (typeof data.title === "string") detail.logTitle = data.title;
+						return;
+					case "turn/start":
+						detail.turnCount += 1;
+						return;
+					case "tool/call":
+						detail.toolCallCount += 1;
+						return;
+					case "user/message": {
+						if ((data.source ?? {}).kind !== "user") {
+							detail.injectedCount += 1;
+							return;
+						}
+						const text = textOf(data.content);
+						if (text === "") return;
+						detail.userMessageCount += 1;
+						push("user", r.time ?? 0, text);
+						return;
+					}
+					case "assistant/message": {
+						const message = data.message ?? {};
+						const source = message.source ?? {};
+						if (typeof source.model === "string") models.add(source.model);
+						const text = textOf(message.content);
+						if (text === "") return;
+						detail.assistantMessageCount += 1;
+						push("assistant", r.time ?? 0, text);
+						return;
+					}
+					default: return;
+				}
+			});
+		} catch (error) {
+			throw verbError("io", error instanceof Error ? `读回收站日志失败：${error.message}` : `读回收站日志失败：${String(error)}`, error);
+		}
+		detail.models = [...models];
+		return detail;
+	};
+}
+//#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");`）。
+*  `projectDirOf` 与回收站对账（`src/trash/reconcile.ts` 重建条目）共用这一个字面量。 */
+const NO_CWD_PROJECT_DIR = "_no-cwd";
+/**
+* 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
+*
+* 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
+* 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
+* （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
+*
+* 原文（asar `dsh/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`）：
+* `function projectKey(cwd) { … if (ch === "/" || ch === "\\" || ch === ":") { if (!separatorRun) readable += "-"; separatorRun = true; }
+*  else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) { readable += ch; separatorRun = false; }
+*  else { readable += "~" + code.toString(16).toUpperCase().padStart(4, "0"); separatorRun = false; }
+*  return \`--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--\`; }`
+* 调用链：`locate(meta)` → `logPath(root, meta.cwd, meta.id, …)` → `projectDir(root, cwd)` → `projectKey(cwd)`。
+* 本机实测对得上：`D:/develop/GitHub/dsh-session-delete` → `--D-develop-GitHub-dsh-session-delete--`
+* （`~/.dsh/sessions` 下真有这个目录名；`D:/document/deepseek-harness/default-workspace` 同理）。
+*
+* **两个调用方共用这一份**：`projectDirOf`（删除时定位会话目录）与回收站对账的重建路径
+* （手工放进回收站的目录，从日志 header 的 `cwd` 反推它原本属于哪个项目目录）——算法只有这一处家。
+*/
+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` 上，
+* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（设计稿 §6 的两行映射）。
+*/
+function createHostPort(ctx) {
+	const host = ctx;
+	const registry = host.workspaceRegistry;
+	return {
+		/** 账本里记着这个会话的工作区：`registry.list()` 的实体 `sessionIds`（该 getter 已按 canonical cwd 过滤过）。 */
+		async workspaceOf(sessionId) {
+			return registry.list().find((workspace) => workspace.sessionIds.includes(sessionId))?.id;
+		},
+		/**
+		* 原生 cwd → 宿主项目目录名（`projectKey`）；没有 cwd 时按宿主约定落到 `_no-cwd`。
+		*
+		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
+		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
+		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ 设计稿 §6 的 `not-found`
+		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
+		*
+		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
+		*/
+		async projectDirOf(sessionId) {
+			let header;
+			try {
+				header = await registry.readSessionHeader(sessionId);
+			} catch (error) {
+				if (isUnknownSession(error)) return void 0;
+				throw error;
+			}
+			return header.cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(header.cwd);
+		},
+		/**
+		* 标题：走官方**投影缓存**读面（`title` 投影单元的 `wire.view` 值就是标题文本本身：
+		* 单元定义原文 `{ key: "title", stateVersion: 1, wire: { view: (state) => state } }`，
+		* 所以 `values.title` 是 `string | null`）。
+		* 契约：**尽力取、取不到返回空串、绝不因此让删除失败** ⇒ 这里吞掉一切异常。
+		*/
+		async titleOf(sessionId) {
+			try {
+				const header = await registry.readSessionHeader(sessionId);
+				const cache = projectionCacheOf(host);
+				const title = (cache?.cachedSnapshot(header, ["title"]) ?? cache?.cachedPredecessorTitle(header))?.values.title;
+				return typeof title === "string" ? title : "";
+			} catch {
+				return "";
+			}
+		},
+		/**
+		* 活跃判据 = 宿主官方那一条（设计稿 §5）：`workspace/session-activity` waterfall 问一次，
+		* **空数组 = 无活动**；与宿主自己的 `archiveSession` 准入同源，不自创第二套。
+		* asar 原文：`const activity = await this.ctx.waterfall('workspace/session-activity', { sessionId }, () => Promise.resolve([]));
+		* if (activity.length > 0) throw new WorkspaceActiveSessionError(sessionId, activity);`
+		*/
+		async isLive(sessionId) {
+			return (await host.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]))).length > 0;
+		},
+		/** registry 全局归档集（数组，`state.archivedSessionIds`）。 */
+		async isArchived(sessionId) {
+			return registry.archivedSessionIds.includes(sessionId);
+		},
+		/**
+		* 从 `ctx.sessions`（live store）里摘掉一个会话。
+		*
+		* **为什么需要**：会话列表读面是并集——`sessionQuery.listSessions()` = 磁盘上的持久化 ∪ `ctx.sessions` 里的活体
+		* （见设计稿 §4 末）。搬走文件只清掉一侧；本机运行期打开过的会话是活体，列表照样把它交出来，
+		* 于是"删了还在"（真机实测：文件已进回收站、账本已摘，侧栏仍留着那一行）。
+		*
+		* **这是未声明为契约的内部入口**（设计稿 §4 末记了这次偏离）：`liveEntryFor` / `entry.detach()` 是 store
+		* 给**会话 owner**（agent 的 effect 链）用的，宿主自己的控制器 `createOrAdopt` 只取 `agents.create()`
+		* 返回的 `.agent`、把带 `dispose` 的 handle 丢掉了，`ctx.agents` 也没有 `liveEntryFor` 那样的入口
+		* （会话 store 有、agent store 没有，逐成员面核过）⇒ 只能摘到"会话"这一层，上面那具 agent 摘不到，
+		* 它之后若走到 `flush(session)` 会撞 `liveEntryFor` 抛 `session "…" is not live in this store`。
+		*
+		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 抛 ⇒ `unknown`（**不通告**，
+		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
+		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
+		*/
+		async evictLive(sessionId) {
+			try {
+				const store = liveSessionsOf(host);
+				if (store === void 0) return "unknown";
+				const session = store.get(sessionId);
+				if (session === void 0 || session === null) return "not-live";
+				const entry = store.liveEntryFor(session);
+				if (entry === void 0 || entry === null || typeof entry.detach !== "function") return "unknown";
+				entry.detach();
+				return "evicted";
+			} catch {
+				return "unknown";
+			}
+		},
+		/**
+		* 通告客户端"这个会话没了"。
+		*
+		* **为什么需要**：客户端那一行只由两条路更新——重连时的整表重列（`handleConnected` → `refreshList`），
+		* 或宿主转发的 `api-session/*` 事件。删除一个**冷**会话时宿主不会发任何事件（`session/disposed` 只在摘掉
+		* 活体时才有），所以那一行会一直挂到下次重连为止（真机实测就是这个形状）。
+		*
+		* **为什么这样发是对的**：`api-session/removed` 是宿主**自己声明并转发**的事件
+		* （asar `dsh-api-remotes/lib/remote-events.js` 的 `API_REMOTE_FORWARDED_EVENTS` 里
+		* `{ event: "api-session/removed", mode: "emit" }`；转发器就是 `ctx.on(event, …)` 的普通监听者）；
+		* 我们不带 carrier 地 emit ⇒ 全量派发到它（见 {@link HostCtxLike.emit}）⇒ 客户端
+		* `ctx.remote.$on("api-session/removed", …)` 收到后 `recordMutation({kind:'remove'})` + `handleRemoved()`。
+		* **只在"宿主列表确实已经不含它"时调用**（调用方按 {@link EvictionOutcome} 判）：这条通告在语义上是**如实**
+		* 的，不是障眼法。
+		*/
+		async announceRemoved(sessionId) {
+			try {
+				host.emit("api-session/removed", sessionId);
+			} catch {}
+		},
+		/**
+		* 通告客户端"这个会话回来了"（恢复用）。
+		*
+		* 摘要**取自宿主自己的会话列表**（`ctx.sessionController.list()`），不自己造一行：客户端 `handleSessionAdded`
+		* 要的是宿主 `summaryFor` 那套形状（sessionId / updatedAt / blank / projections…），照抄宿主的那一份最可靠。
+		* 取不到（控制器缺席 / 列表里没有它 / 抛错）就**一条都不发**——恢复本身已经完成，只是要等下次重连才上屏。
+		*/
+		async announceRestored(sessionId) {
+			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 {}
+		},
+		/** 官方 `unarchiveSession(sessionId)`：未归档是幂等 no-op。 */
+		async unarchive(sessionId) {
+			await registry.unarchiveSession(sessionId);
+		},
+		/** 摘账本：实体方法 `detachSession`（顶层没有）；未知工作区**响亮失败**，不静默当成功。 */
+		async detach(sessionId, workspaceId) {
+			const workspace = registry.get(workspaceId);
+			if (workspace === void 0) throw new Error(`workspace not found (detach): ${workspaceId}`);
+			await workspace.detachSession(sessionId);
+		},
+		/** 挂账本：实体方法 `attachSession`（顶层没有）。 */
+		async attach(sessionId, workspaceId) {
+			const workspace = registry.get(workspaceId);
+			if (workspace === void 0) throw new Error(`workspace not found (attach): ${workspaceId}`);
+			await workspace.attachSession(sessionId);
+		},
+		/** 确保归档：官方 `archiveSession(sessionId)`。归档是 registry **全局**的，与工作区账目无关
+		*  （JSDoc 原文 "its workspace accounting — or lack of one — is irrelevant"），所以 `workspaceId` 不用
+		*  ——未分组的会话没有工作区可传，签名里它是可选的。
+		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，设计稿 §6）。 */
+		async archive(sessionId) {
+			await registry.archiveSession(sessionId);
+		}
+	};
+}
+//#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 = (await deps.fs.listFiles(dir)).find((name) => name.endsWith(SESSION_LOG_SUFFIX));
+	} 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/delete-session.ts
 function deleteSession(deps) {
 	return async function deleteSession(sessionId) {
@@ -409,7 +1046,7 @@ function requireMethod(method, want, route) {
 async function dispatch(method, rest, req, deps) {
 	if (rest === ROUTES.list) {
 		requireMethod(method, "GET", ROUTES.list);
-		return await deps.manifest.list();
+		return await reconcileTrash(deps);
 	}
 	if (rest === ROUTES.delete) {
 		requireMethod(method, "POST", ROUTES.delete);
@@ -423,10 +1060,24 @@ async function dispatch(method, rest, req, deps) {
 		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));
+	}
 	throw new Error(`未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
 }
 /** 宿主 `webServer.register({kind:'prefix', path: SESSION_DELETE_API_PREFIX, handler})` 的那个 handler。 */
 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);
@@ -435,7 +1086,9 @@ 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}`);
-			writeOk(res, await dispatch(req.method ?? "GET", url.pathname.slice(23), req, deps));
+			const rest = url.pathname.slice(23);
+			const task = () => dispatch(req.method ?? "GET", rest, req, deps);
+			writeOk(res, await (rest === ROUTES.detail ? task() : throughChain(task)));
 		} catch (error) {
 			writeFailure(res, error);
 		}
@@ -470,235 +1123,15 @@ function createFsPort() {
 				force: true
 			});
 		},
-		sizeOfDir: (p) => sizeOfDir(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` 上，
-* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（设计稿 §6 的两行映射）。
-*/
-function createHostPort(ctx) {
-	const host = ctx;
-	const registry = host.workspaceRegistry;
-	return {
-		/** 账本里记着这个会话的工作区：`registry.list()` 的实体 `sessionIds`（该 getter 已按 canonical cwd 过滤过）。 */
-		async workspaceOf(sessionId) {
-			return registry.list().find((workspace) => workspace.sessionIds.includes(sessionId))?.id;
-		},
-		/**
-		* 原生 cwd → 宿主项目目录名（`projectKey`）；没有 cwd 时按宿主约定落到 `_no-cwd`。
-		*
-		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
-		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
-		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ 设计稿 §6 的 `not-found`
-		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
-		*
-		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
-		*/
-		async projectDirOf(sessionId) {
-			let header;
-			try {
-				header = await registry.readSessionHeader(sessionId);
-			} catch (error) {
-				if (isUnknownSession(error)) return void 0;
-				throw error;
-			}
-			return header.cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(header.cwd);
-		},
-		/**
-		* 标题：走官方**投影缓存**读面（`title` 投影单元的 `wire.view` 值就是标题文本本身：
-		* 单元定义原文 `{ key: "title", stateVersion: 1, wire: { view: (state) => state } }`，
-		* 所以 `values.title` 是 `string | null`）。
-		* 契约：**尽力取、取不到返回空串、绝不因此让删除失败** ⇒ 这里吞掉一切异常。
-		*/
-		async titleOf(sessionId) {
-			try {
-				const header = await registry.readSessionHeader(sessionId);
-				const cache = projectionCacheOf(host);
-				const title = (cache?.cachedSnapshot(header, ["title"]) ?? cache?.cachedPredecessorTitle(header))?.values.title;
-				return typeof title === "string" ? title : "";
-			} catch {
-				return "";
-			}
-		},
-		/**
-		* 活跃判据 = 宿主官方那一条（设计稿 §5）：`workspace/session-activity` waterfall 问一次，
-		* **空数组 = 无活动**；与宿主自己的 `archiveSession` 准入同源，不自创第二套。
-		* asar 原文：`const activity = await this.ctx.waterfall('workspace/session-activity', { sessionId }, () => Promise.resolve([]));
-		* if (activity.length > 0) throw new WorkspaceActiveSessionError(sessionId, activity);`
-		*/
-		async isLive(sessionId) {
-			return (await host.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]))).length > 0;
-		},
-		/** registry 全局归档集（数组，`state.archivedSessionIds`）。 */
-		async isArchived(sessionId) {
-			return registry.archivedSessionIds.includes(sessionId);
-		},
-		/**
-		* 从 `ctx.sessions`（live store）里摘掉一个会话。
-		*
-		* **为什么需要**：会话列表读面是并集——`sessionQuery.listSessions()` = 磁盘上的持久化 ∪ `ctx.sessions` 里的活体
-		* （见设计稿 §4 末）。搬走文件只清掉一侧；本机运行期打开过的会话是活体，列表照样把它交出来，
-		* 于是"删了还在"（真机实测：文件已进回收站、账本已摘，侧栏仍留着那一行）。
-		*
-		* **这是未声明为契约的内部入口**（设计稿 §4 末记了这次偏离）：`liveEntryFor` / `entry.detach()` 是 store
-		* 给**会话 owner**（agent 的 effect 链）用的，宿主自己的控制器 `createOrAdopt` 只取 `agents.create()`
-		* 返回的 `.agent`、把带 `dispose` 的 handle 丢掉了，`ctx.agents` 也没有 `liveEntryFor` 那样的入口
-		* （会话 store 有、agent store 没有，逐成员面核过）⇒ 只能摘到"会话"这一层，上面那具 agent 摘不到，
-		* 它之后若走到 `flush(session)` 会撞 `liveEntryFor` 抛 `session "…" is not live in this store`。
-		*
-		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 抛 ⇒ `unknown`（**不通告**，
-		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
-		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
-		*/
-		async evictLive(sessionId) {
-			try {
-				const store = liveSessionsOf(host);
-				if (store === void 0) return "unknown";
-				const session = store.get(sessionId);
-				if (session === void 0 || session === null) return "not-live";
-				const entry = store.liveEntryFor(session);
-				if (entry === void 0 || entry === null || typeof entry.detach !== "function") return "unknown";
-				entry.detach();
-				return "evicted";
-			} catch {
-				return "unknown";
-			}
-		},
-		/**
-		* 通告客户端"这个会话没了"。
-		*
-		* **为什么需要**：客户端那一行只由两条路更新——重连时的整表重列（`handleConnected` → `refreshList`），
-		* 或宿主转发的 `api-session/*` 事件。删除一个**冷**会话时宿主不会发任何事件（`session/disposed` 只在摘掉
-		* 活体时才有），所以那一行会一直挂到下次重连为止（真机实测就是这个形状）。
-		*
-		* **为什么这样发是对的**：`api-session/removed` 是宿主**自己声明并转发**的事件
-		* （asar `dsh-api-remotes/lib/remote-events.js` 的 `API_REMOTE_FORWARDED_EVENTS` 里
-		* `{ event: "api-session/removed", mode: "emit" }`；转发器就是 `ctx.on(event, …)` 的普通监听者）；
-		* 我们不带 carrier 地 emit ⇒ 全量派发到它（见 {@link HostCtxLike.emit}）⇒ 客户端
-		* `ctx.remote.$on("api-session/removed", …)` 收到后 `recordMutation({kind:'remove'})` + `handleRemoved()`。
-		* **只在"宿主列表确实已经不含它"时调用**（调用方按 {@link EvictionOutcome} 判）：这条通告在语义上是**如实**
-		* 的，不是障眼法。
-		*/
-		async announceRemoved(sessionId) {
-			try {
-				host.emit("api-session/removed", sessionId);
-			} catch {}
-		},
-		/**
-		* 通告客户端"这个会话回来了"（恢复用）。
-		*
-		* 摘要**取自宿主自己的会话列表**（`ctx.sessionController.list()`），不自己造一行：客户端 `handleSessionAdded`
-		* 要的是宿主 `summaryFor` 那套形状（sessionId / updatedAt / blank / projections…），照抄宿主的那一份最可靠。
-		* 取不到（控制器缺席 / 列表里没有它 / 抛错）就**一条都不发**——恢复本身已经完成，只是要等下次重连才上屏。
-		*/
-		async announceRestored(sessionId) {
-			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 {}
-		},
-		/** 官方 `unarchiveSession(sessionId)`：未归档是幂等 no-op。 */
-		async unarchive(sessionId) {
-			await registry.unarchiveSession(sessionId);
-		},
-		/** 摘账本：实体方法 `detachSession`（顶层没有）；未知工作区**响亮失败**，不静默当成功。 */
-		async detach(sessionId, workspaceId) {
-			const workspace = registry.get(workspaceId);
-			if (workspace === void 0) throw new Error(`workspace not found (detach): ${workspaceId}`);
-			await workspace.detachSession(sessionId);
+		sizeOfDir: (p) => sizeOfDir(p),
+		async listFiles(p) {
+			return readdir(p);
 		},
-		/** 挂账本：实体方法 `attachSession`（顶层没有）。 */
-		async attach(sessionId, workspaceId) {
-			const workspace = registry.get(workspaceId);
-			if (workspace === void 0) throw new Error(`workspace not found (attach): ${workspaceId}`);
-			await workspace.attachSession(sessionId);
+		async listDirs(p) {
+			return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
 		},
-		/** 确保归档：官方 `archiveSession(sessionId)`。归档是 registry **全局**的，与工作区账目无关
-		*  （JSDoc 原文 "its workspace accounting — or lack of one — is irrelevant"），所以 `workspaceId` 不用
-		*  ——未分组的会话没有工作区可传，签名里它是可选的。
-		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，设计稿 §6）。 */
-		async archive(sessionId) {
-			await registry.archiveSession(sessionId);
+		async readFile(p) {
+			return readFile(p);
 		}
 	};
 }
@@ -732,7 +1165,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` 原文读实，不是猜的。
 */