@xrn1997/dsh-session-delete 0.2.2 → 0.3.0

package/lib/index.js

@@ -1,8 +1,8 @@
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
 import zlib from "node:zlib";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
 //#region src/shared/wire.ts
 /**
 * 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
@@ -32,7 +32,7 @@ const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
 *  一次 HTTP 带一组 id、逐条回结果；单条就是长度为 1 的批量，仓里不再留第二条执行路径。
 *  - `GET /list`：**对账并读**清单（`session-trash/` 里的目录是准）。
 *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链）——客户端探测用它，不用一次全表读。
-*  - `POST /detail`：单条详情（用 POST 表达一个读：见设计稿 2026-10-15 §3）。
+*  - `POST /detail`：单条详情（用 POST 表达一个读：判据就写在 `src/api/route-table.ts` 那一行的上方）。
 *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
 *  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。
 *  - `GET /orphans`：无主子会话的扫描报告（纯读，2026-10-19）。**清理不在这里**——它是 `/apply` 的
@@ -69,9 +69,9 @@ function isDSHRemoteError(value) {
 	const candidate = value;
 	return candidate.isDSHRemoteError === true && typeof candidate.code === "string";
 }
-/** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见设计稿 §6。 */
+/** 失败码的域。与宿主官方域（`workspace/*`、`session/*`…）不重名，见本文件。 */
 const SESSION_DELETE_ERROR_DOMAIN = "sessiondelete";
-/** 五个**动词码**（设计稿 §6 那张表）。`io` 是唯一兜底。 */
+/** 五个**动词码**（本文件那张表）。`io` 是唯一兜底。 */
 const VERB_CODES$1 = [
 	"live",
 	"not-found",
@@ -93,10 +93,10 @@ const SESSION_DELETE_CODES = {
 const TRASH_DIR_NAME = "session-trash";
 //#endregion
 //#region src/remote/map-error.ts
-/** 插件专属远程域名（设计稿 §6）：与宿主官方域（`workspace/*`、`session/*`、`gateway/*`…）不重名。
+/** 插件专属远程域名（src/shared/wire.ts）：与宿主官方域（`workspace/*`、`session/*`、`gateway/*`…）不重名。
 *  字面量的家在 `shared/wire.ts`（ADR-0003）——浏览器半也按同一个域认码。 */
 const DOMAIN = SESSION_DELETE_ERROR_DOMAIN;
-/** 宿主两条类型化错误 → 我们的码（设计稿 §6 的两行映射）。
+/** 宿主两条类型化错误 → 我们的码（本文件的两行映射）。
 *  类不可 import（跨插件值 import 是红线；且宿主包与运行中的宿主不同代）⇒ 按官方构造器写死的 `this.name` 认。
 *  证据：asar `dsh/node_modules/@deepseek-ai/dsh-workspace/lib/index.js` 原文
 *  `var WorkspaceUnknownSessionError = class extends Error { …; this.name = "WorkspaceUnknownSessionError"; }`
@@ -117,7 +117,7 @@ function hostErrorOf(error) {
 	}
 }
 /** 上屏原文：`Error` 取 `.message`；**带 `message` 字符串的非 Error 抛出物也照取**（否则会退化成
-*  `[object Object]`，把设计稿 §6「`message` 是上屏的原文」这条许诺落空）；其余一律 `String()`。 */
+*  `[object Object]`，把 src/shared/wire.ts「`message` 是上屏的原文」这条许诺落空）；其余一律 `String()`。 */
 function messageOf(error) {
 	if (error instanceof Error) return error.message;
 	if (typeof error === "object" && error !== null) {
@@ -159,7 +159,7 @@ function detailsOf(error) {
 	return ownDetailsOf(error);
 }
 /**
-* 把任意抛出物折成失败信封里的**那三件**（设计稿 §6 唯一那张映射表）。
+* 把任意抛出物折成失败信封里的**那三件**（本文件唯一那张映射表）。
 *
 * - 已经是远程失败（`isDSHRemoteError` 认得的结构标记）⇒ 原样带出它自己的 `code` / `message`，
 *   挂着的 `details` 一起过桥，不再包一层。
@@ -167,7 +167,7 @@ function detailsOf(error) {
 *   把它们折成 `sessiondelete/io` 就是把宿主的判断抹成我们的，客户端拿到的 code 从此不能说真话。
 * - 宿主类型化错误（自身或 `cause` 链上，见 {@link hostErrorOf}）⇒ 映射成 `live` / `not-found`，
 *   并把它自己身上的结构化字段带成 `details`。这一条排在动词码之前：动词会把宿主错误包成笼统的 `io`
-*   并把原错误挂在 cause 上（`verbError('io', …, cause)`），不看进 cause 链，§6 那两行映射永远到不了客户端。
+*   并把原错误挂在 cause 上（`verbError('io', …, cause)`），不看进 cause 链，本文件那两行映射永远到不了客户端。
 * - 动词的 `sessiondelete/<五个码>` ⇒ 原样过桥（`details` 同样带着）。
 * - 其余（别域的怪 code、前缀外的因、非 Error 抛出物）⇒ `io`，message 保留原文。
 *
@@ -216,6 +216,13 @@ function toRemoteFailure(error) {
 const VERB_CODES = VERB_CODES$1;
 /** `sessiondelete/` 这个前缀——拆码用它，别在下面几处各写一遍字面量。 */
 const VERB_CODE_PREFIX = `${SESSION_DELETE_ERROR_DOMAIN}/`;
+/** `error.code` 是不是本仓的动词码（`sessiondelete/<码>`）。**唯一判据**：`journalFailure` 与永久删除
+*  执行器要"已经是动词码就原样抛"时都问这一句。同文件的 `withRollbackFailures` 还要码的后缀，所以它
+*  就地 `slice` 一次——前缀仍只住 `VERB_CODE_PREFIX` 这一处，别在调用点另写一份字面量。 */
+function isVerbCodeError(error) {
+	const raw = error?.code;
+	return typeof raw === "string" && raw.startsWith(VERB_CODE_PREFIX);
+}
 function verbError(code, message, cause, details) {
 	const e = new Error(message);
 	e.code = SESSION_DELETE_CODES[code];
@@ -255,6 +262,76 @@ function withRollbackFailures(error, failures) {
 	return verbError(code, base.includes("；回滚未完成：") ? extra.length > 0 ? `${base}；${extra.join("；")}` : base : `${base}；回滚未完成：${merged.join("；")}`, error, { rollbackFailures: merged });
 }
 //#endregion
+//#region src/ports/agent-handles.ts
+const CAPTURED_AGENT_HANDLES = Symbol.for("dsh-session-delete.captured-agent-handles");
+/** 在 `ctx.agents` 上包一层 `resume` / `create`，把返回的 agent handle 的 dispose 按会话 id 记下。
+*  服务缺席时走 `ctx.inject(['agents'])` **等服务挂上再装**——live profile 的插件激活顺序可能早于
+*  `agents` 服务就绪；只在 apply 时 `get` 一次会让捕获静默缺席（真机症状：重启前在回收站的能冷恢复，
+*  刚删除的会话恢复后旧 agent 拦住 prompt）。形状不符 / 属性不可写都只是**不捕获**，不影响插件激活。
+*
+*  **安装时机**：先 `get('agents')`，没装成再 `inject(['agents'])`（两者只装一次，符号表兜住）。
+*  **symbol 表**：句柄表挂在服务实例的 {@link CAPTURED_AGENT_HANDLES} 上；同一个 agents 服务上的第二次
+*  安装（`get` 与 `inject` 各一次，或第二个 `createHostPort`）看见它就直接共用，不把 wrapper 套第二层。
+*  **读回判据**：cordis 的 traceable 服务代理每次读函数都会新包一层（`get` 里的 `createShadowMethod`），
+*  所以只能看 own property descriptor 的身份；拿 `service[name]` 读回比身份是必然的假警报。
+*/
+function captureAgentHandles(ctx) {
+	let handles = /* @__PURE__ */ new Map();
+	let installed = false;
+	const install = (candidate) => {
+		if (installed) return;
+		const service = candidate;
+		if (service === void 0 || service === null) return;
+		const existing = service[CAPTURED_AGENT_HANDLES];
+		if (existing !== void 0) {
+			handles = existing;
+			installed = true;
+			return;
+		}
+		let wrappedCount = 0;
+		for (const name of ["resume", "create"]) try {
+			const original = service[name];
+			if (typeof original !== "function") continue;
+			const wrapped = function(...args) {
+				const result = Reflect.apply(original, this, args);
+				result.then((value) => {
+					const handle = value;
+					const id = handle?.agent?.id;
+					if (typeof id !== "string" || id.length === 0 || typeof handle?.dispose !== "function") return;
+					handles.set(id, async () => {
+						await handle.dispose();
+					});
+				}, () => void 0);
+				return result;
+			};
+			service[name] = wrapped;
+			if (Object.getOwnPropertyDescriptor(service, name)?.value !== wrapped) throw new Error(`agents.${name} is not writable`);
+			wrappedCount += 1;
+		} catch {}
+		if (wrappedCount === 0) return;
+		try {
+			service[CAPTURED_AGENT_HANDLES] = handles;
+		} catch {}
+		installed = true;
+	};
+	const service = ctx.get("agents");
+	if (service !== void 0 && service !== null) install(service);
+	if (!installed && typeof ctx.inject === "function") try {
+		ctx.inject(["agents"], (child) => {
+			install(child.get("agents"));
+		});
+	} catch {}
+	return { async dispose(sessionId) {
+		const dispose = handles.get(sessionId);
+		if (dispose === void 0) return;
+		try {
+			await dispose();
+		} finally {
+			handles.delete(sessionId);
+		}
+	} };
+}
+//#endregion
 //#region src/ports/host-port.ts
 /** live store 的最小方法面判据（同 `projectionCacheOf` 的手法：按方法面判，不按 constructor.name）。 */
 function liveSessionsOf(ctx) {
@@ -279,7 +356,7 @@ async function filterChildrenOf(sessionQuery, values) {
 *
 * 停下来的条件与代价：**层数**决定宿主调用次数，行数不参与（一层一次，问空即停）。同一条记录只收一次
 * （`seen` 连着根一起记），所以数据里真出现环时结果是"少数一条"，不是把清单读挂死。
-* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostPort.subagentMembers} 那条），
+* 交回的 id 没有 `header.id` 的记录**整条跳过**——身份冒充不起（同 {@link HostCorpusPort.subagentMembersOf} 那条），
 * 而且没有身份就没法往下问，硬数进去只会让它将来被重复计。
 */
 async function descendantsByParent(sessionQuery, roots) {
@@ -337,7 +414,7 @@ function toMember(d) {
 		projectDir: d.projectDir
 	};
 }
-/** `subagentCounts` / `subagentMembers` / `subagentMembersBatch` 共用的一次 BFS。
+/** {@link HostCorpusPort.subagentMembersOf} 的那一次 BFS。
 *  空清单在调用宿主之前就返回（不为一张空表扫全库）。 */
 async function membersFor(sessionQuery, parentIds) {
 	const wanted = [];
@@ -413,7 +490,7 @@ 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}）。 */
+/** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostCorpusPort.subagentMembersOf}）。 */
 function bareSessionId(id) {
 	return id.startsWith("session-") ? id.slice(8) : id;
 }
@@ -453,11 +530,12 @@ function isWorkspaceMissingError(error) {
 *
 * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
 * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
-* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（设计稿 §6 的两行映射）。
+* `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（src/remote/map-error.ts 的两行映射）。
 */
 function createHostPort(ctx) {
 	const host = ctx;
 	const registry = host.workspaceRegistry;
+	const agentHandles = captureAgentHandles(host);
 	return {
 		/** 账本里记着这个会话的工作区：`registry.list()` 的实体 `sessionIds`（该 getter 已按 canonical cwd 过滤过）。 */
 		async workspaceOf(sessionId) {
@@ -473,7 +551,7 @@ function createHostPort(ctx) {
 		*
 		* 「账本里没有这个会话」= **未命中**，回 `undefined`（不是抛）：这正是本方法声明的类型，
 		* 也是 `delete-session.ts` 已经写好的那条分支 `if (!projectDir) throw
-		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ 设计稿 §6 的 `not-found`
+		* verbError('not-found', …)` 的入口。若让它裸抛，那句话永远为假 ⇒ src/shared/wire.ts 的 `not-found`
 		* （「会话目录或账本条目不存在」）在这条最自然的路径上拿不到码，客户端只会看到 `sessiondelete/io`。
 		*
 		* **只吞这一种**：其余错误（真存储故障）照抛，让 `toRemoteFailure` 兜成 `io` 而不是假 `not-found`。
@@ -505,7 +583,7 @@ function createHostPort(ctx) {
 			}
 		},
 		/**
-		* 活跃判据 = 宿主官方那一条（设计稿 §5）：`workspace/session-activity` waterfall 问一次，
+		* 活跃判据 = 宿主官方那一条（本文件）：`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);`
@@ -518,31 +596,39 @@ function createHostPort(ctx) {
 			return registry.archivedSessionIds.includes(sessionId);
 		},
 		/**
-		* 从 `ctx.sessions`（live store）里摘掉一个会话。
+		* 从 `ctx.sessions`（live store）里摘掉会话，并把它的 **agent 一起关掉**（有捕获 handle 时）。
 		*
 		* **为什么需要**：会话列表读面是并集——`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`。
+		* **agent 也必须关**：`ctx.agents` 没有 per-agent dispose；宿主 `AgentService.resume` / `create` 返回的
+		* `AgentHandle` 带宿主自己的外层 teardown（关写句柄、摘 agent/session），但 `SessionController` 只取
+		* `.agent`、把 handle 丢掉。agent handle 捕获（`src/ports/agent-handles.ts`）在 `ctx.agents` 上包一层，
+		* 按会话 id 留住 handle；这里先 `entry.detach()`（摘 session、发 `session/disposed`），再
+		* `await agentHandles.dispose(sessionId)`。
+		* **只摘 session 的后果**：恢复后 `SessionController.resolve` 会先命中那具旧 agent，prompt 被收下、
+		* 日志不再增长，直到宿主重启（2026-10-21 真机复现）。
 		*
-		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 抛 ⇒ `unknown`（**不通告**，
+		* **捕获不到 handle 的 agent**（插件激活前已启动的配置 agent，或 `ctx.agents` 形状变化）只能摘 session；
+		* 这是已知的残留限制，不拿归档当兜底（ADR-0008）。
+		*
+		* **所以判据是三态**：读不到 store / 形状不符（旧版宿主）/ detach 或 dispose 抛 ⇒ `unknown`（**不通告**，
 		* 因为无法断言宿主列表已经干净）；内存里本来没有 ⇒ `not-live`；摘成功 ⇒ `evicted`。
 		* 任何一步都不抛：删除的持久化部分已经完成，这里不该把它翻成失败。
 		*/
 		async evictLive(sessionId) {
 			try {
 				const store = liveSessionsOf(host);
+				const session = store?.get(sessionId);
 				if (store === void 0) return "unknown";
-				const session = store.get(sessionId);
-				if (session === void 0 || session === null) return "not-live";
+				if (session === void 0 || session === null) {
+					await agentHandles.dispose(sessionId);
+					return "not-live";
+				}
 				const entry = store.liveEntryFor(session);
 				if (entry === void 0 || entry === null || typeof entry.detach !== "function") return "unknown";
 				entry.detach();
+				await agentHandles.dispose(sessionId);
 				return "evicted";
 			} catch {
 				return "unknown";
@@ -630,13 +716,13 @@ function createHostPort(ctx) {
 		/** 确保归档：官方 `archiveSession(sessionId)`。归档是 registry **全局**的，与工作区账目无关
 		*  （JSDoc 原文 "its workspace accounting — or lack of one — is irrelevant"），所以 `workspaceId` 不用
 		*  ——未分组的会话没有工作区可传，签名里它是可选的。
-		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，设计稿 §6）。 */
+		*  不带 `stopActivity` ⇒ 有活动即抛 `WorkspaceActiveSessionError`（→ `sessiondelete/live`，src/shared/wire.ts）。 */
 		async archive(sessionId) {
 			await registry.archiveSession(sessionId);
 		},
 		async listSessions() {
 			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.listSessions !== "function") return void 0;
+			if (typeof sessionQuery?.listSessions !== "function") return { available: false };
 			const records = await sessionQuery.listSessions();
 			const out = [];
 			for (const record of records) {
@@ -651,7 +737,10 @@ function createHostPort(ctx) {
 					subagent: record.header?.origin === "subagent"
 				});
 			}
-			return out;
+			return {
+				available: true,
+				value: out
+			};
 		},
 		/**
 		* 官方 `sessionQuery.filterSessions([{kind:'parent', values}])`，不自扫 `~/.dsh/sessions`。
@@ -664,32 +753,26 @@ function createHostPort(ctx) {
 		* （`session-ac07f2bb-…`）、它的子会话写的 `parentSession` 也带，但 v3 那一代的 id 不带 ⇒
 		* 同一个父有两种写法。所以问的时候把一个 id 的两种形状都塞进 `values`，回来按去前缀后的形状归堆，
 		* 最后按**调用方给的那个写法**把键交回去（调用方拿 `entry.sessionId` 直接查得到）。
-		*/
-		async subagentCounts(parentIds) {
-			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.filterSessions !== "function") return {};
-			const members = await membersFor(sessionQuery, parentIds);
-			const counts = {};
-			for (const [id, list] of Object.entries(members)) if (list.length > 0) counts[id] = list.length;
-			return counts;
-		},
-		/**
+		*
 		* 删除要一起带走**整个组**，先得把他们点出来：身份取宿主自己记录里的 `header.id`，项目目录由
 		* `header.cwd` 走同一个 `projectKey`（与 {@link HostPort.projectDirOf} 同一根算法，不另起一套）。
 		* 交回的是**全部后代**——孙代跟着父一起进回收站（issue #1），顺序是逐层往下问出来的（近的先）。
 		* `header.id` 缺席的后代直接跳过——不拿目录名冒充身份（冒充了会把一个来路不明的目录搬进回收站）。
-		* 服务没挂回 `[]` ⇒ 删除照旧只管父，不因此失败（父的删除本来就已经是完整的一件事）。
+		*
+		* **缺席显式化**（见 {@link CorpusRead}）：`sessionQuery` 没挂，或它的 `filterSessions` 缺席 / 不是函数
+		* ⇒ `{ available: false }`，不拿空表冒充"盘上没有后代"——写侧据此决定降级还是响亮失败，不再靠"空表"
+		* 兼表两种意思。
+		* **先判服务、再判空入参**：语料本来就看不见时，"没有后代"这句话不该被说出口（哪怕入参是空的）；
+		* 服务在场时空入参由 `membersFor` 的短路保证零宿主调用。
 		*/
-		async subagentMembers(sessionId) {
-			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.filterSessions !== "function") return [];
-			return ((await membersFor(sessionQuery, [sessionId]))[sessionId] ?? []).map(toMember);
-		},
-		async subagentMembersBatch(parentIds) {
+		async subagentMembersOf(parentIds) {
 			const sessionQuery = host.get("sessionQuery");
-			if (typeof sessionQuery?.filterSessions !== "function") return {};
+			if (typeof sessionQuery?.filterSessions !== "function") return { available: false };
 			const members = await membersFor(sessionQuery, parentIds);
-			return Object.fromEntries(Object.entries(members).map(([id, list]) => [id, list.map(toMember)]));
+			return {
+				available: true,
+				value: Object.fromEntries(Object.entries(members).map(([id, list]) => [id, list.map(toMember)]))
+			};
 		}
 	};
 }
@@ -913,7 +996,8 @@ function frameRanges(raw) {
 *    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
 *    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
 * ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
-*    实测本机 686 个 `.jsonl.zstd` / 92 421 帧**没有一帧切在行中间**（连最后一帧都整行收尾），
+*    本机实测**没有一帧切在行中间**（连最后一帧都整行收尾；绝对帧数随盘上会话数摆动，那份读数
+*    不在这里钉，来历留在 git 历史），
 *    所以旧口径当时并不丢东西；但"逐帧 `split('\n')`"一旦遇上切行就是**静默少一条记录**（半个头
 *    加半个身，两半都解不开 JSON），而少掉的那条正是页面上要跟账的正文。带上余量之后这条不变量
 *    不必再成立，顺带把**跨帧的多字节字符**也解对了——拼接在字节层做，`toString('utf8')` 只看整行。
@@ -1018,7 +1102,7 @@ function readSessionHeader(raw) {
 //#endregion
 //#region src/trash/reconcile.ts
 /**
-* 回收站清单的**对账**：以 `session-trash/` 里的条目目录为准，把清单修回一致（设计稿 2026-10-15 §9）。
+* 回收站清单的**对账**：以 `session-trash/` 里的条目目录为准，把清单修回一致（CONTEXT.md 的「对账」条）。
 *
 * 手工动回收站**只需要动那一个目录**——多出来的目录在这里被重建出行、目录没了的行在这里被摘掉；
 * `~/.dsh/storages/` 那份清单从此是**内部索引**，不用手碰。
@@ -1032,7 +1116,7 @@ function readSessionHeader(raw) {
 * ③ **重建行只写"文件里真有的事实"**：`id` = 目录名、`sessionId`/`cwd` 读日志 header、
 *    `projectDir` 由 `cwd` 经宿主同名算法 `projectKey` 反推、`deletedAt` 从目录名的时间戳解、
 *    `sizeBytes` 现场量。**文件侧没有副本的三件**按缺省落：`workspaceId: ''`（恢复时跳过挂账本，
-*    落在「未分组」）、`wasArchived: false`（恢复按"可见"还原）、`title: ''`（详情有日志标题兜底）
+*    落在「未分组」）、`wasArchived: false`（文件侧没有归档事实；旧条目恢复走迁移支）、`title: ''`（详情有日志标题兜底）
 *    ——这是重建的固有代价，不是可以"再读读看"的东西。
 * ④ **认不出 / 读不出的目录：不动、不列**（名字不像条目、目录里没有日志、header 读不出、尺寸量不出，
 *    各跳过各的）。它是"外人放进来的东西"，不是用户动作失败：跳过即静默，绝不为它删目录或抛掉整次读数。
@@ -1125,7 +1209,7 @@ async function reconcileTrash(deps) {
 * 一次成员移动 = 一串**自带反向动作的步骤**（ADR-0002）。
 *
 * 为什么需要它：`delete-session.ts` 的 `moveOneIn`/`undoOneIn` 与 `restore-session.ts` 的 `restoreOne`
-* （含它的反向闭包）互为镜像，各自手写了三到四段嵌套 `try/catch`：全仓 `rollbackReason(` **22 处**、
+* （含它的反向闭包）互为镜像，各自手写了三到四段嵌套 `try/catch`：迁移前全仓 `rollbackReason(` **22 处**、
 * `withRollbackFailures(` **8 处**。那不是"回滚值得自己的候选"，而是**同一条正反动作对被写了两遍**。
 *
 * 这里独占四件事，三个动词各自只声明"这次要做哪几步、每步怎么退"：
@@ -1179,8 +1263,9 @@ async function attempt(label, run) {
 }
 /**
 * **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
-* `details.rollbackFailures`，绝不让原错误独走（设计稿第十七批）。删除与恢复两个按组走的动词
-* 共用这一处——"相反顺序 + 失败合并"不再各写一遍。
+* `details.rollbackFailures`，绝不让原错误独走（2026-10-19 `f2a7757`；那些失败句子的合并与措辞住
+* `src/verbs/errors.ts`，这里只是唯一的调用方）。删除与恢复两个按组走的动词共用这一处，
+* "相反顺序 + 失败合并"不再各写一遍。
 */
 async function rollbackJournals(journals, error) {
 	const failures = [];
@@ -1194,11 +1279,24 @@ async function rollbackJournals(journals, error) {
 * 换一种拼法会让上屏原文跟着变。
 */
 function journalFailure(step, error) {
-	const raw = error?.code;
-	if (typeof raw === "string" && raw.startsWith(`sessiondelete/`)) return error;
+	if (isVerbCodeError(error)) return error;
 	return verbError("io", `${step.label}：${String(error)}`, error);
 }
 //#endregion
+//#region src/verbs/member-presence.ts
+function createMemberPresence(host) {
+	return {
+		async memberGone(sessionId, facts = {}) {
+			if (facts.backInTrash === false) return;
+			if (await host.evictLive(sessionId) !== "unknown") await host.announceRemoved(sessionId);
+		},
+		async memberBack(sessionId, facts) {
+			if (!facts.diskBack || !facts.workspaceBack) return;
+			await host.announceRestored(sessionId);
+		}
+	};
+}
+//#endregion
 //#region src/verbs/delete-session.ts
 /**
 * 删除 = 移入回收站，**按组走**：用户点掉一条父会话时，宿主的客户端把 `origin:"subagent"` 的孩子
@@ -1211,13 +1309,16 @@ function journalFailure(step, error) {
 * ② **逐个搬**：每个成员是一份 `journal`（`verbs/member-journal.ts`），搬不动时 journal 自己把
 *    这个成员已经做成的步骤退回去。
 * ③ **组级回滚**：某一个成员搬不动时，把**已经搬进去的**那些按相反顺序退回原处（清册行跟着摘、
-*    账本跟着挂、可见性跟着还原），失败照抛——不留"半组在回收站、半组在原地"的世界。
+*    账本跟着挂），失败照抛——不留"半组在回收站、半组在原地"的世界。
 *
 * interface 只有**一个 id**：批量的性质不在这里（同批"已被前一条带走"的判据归 `verbs/batch.ts`）。
+* 结果带回这次真的搬走的整组（`movedSessionIds`）——它是动词交回的内部数据，不再靠回调借用动词的手。
 */
 function deleteSession(deps) {
+	const presence = createMemberPresence(deps.host);
 	return async function deleteSession(sessionId) {
-		const kids = await deps.host.subagentMembers(sessionId);
+		const read = await deps.host.subagentMembersOf([sessionId]);
+		const kids = read.available ? read.value[sessionId] ?? [] : [];
 		const parentProjectDir = await deps.host.projectDirOf(sessionId);
 		if (parentProjectDir === void 0) throw verbError("not-found", `宿主的持久化里没有这个会话：${sessionId}`);
 		const candidates = [{
@@ -1244,7 +1345,7 @@ function deleteSession(deps) {
 		try {
 			for (const member of members) {
 				const isParent = member.sessionId === sessionId;
-				const move = await memberMove(deps, member, deletedAt, isParent ? void 0 : parentEntry.id);
+				const move = await memberMove(deps, presence, member, deletedAt, isParent ? void 0 : parentEntry.id);
 				if (isParent) parentEntry = move.entry;
 				await move.journal.run();
 				done.push(move.journal);
@@ -1252,18 +1353,26 @@ function deleteSession(deps) {
 		} catch (error) {
 			await rollbackJournals(done, error);
 		}
-		return parentEntry;
+		return {
+			entry: parentEntry,
+			movedSessionIds: members.map((member) => member.sessionId)
+		};
 	};
 }
 /**
-* 一个成员要做的步骤（顺序承重，照设计稿 §4 那五触点）：
-* 读现场（两件纯读）→ 归档 → 摘账本 → 搬目录 → 写清册行。
+* 一个成员要做的步骤（顺序承重，那四步就列在下面一行）：
+* 读现场（两件纯读）→ 摘账本 → 搬目录 → 写清册行。搬完之后由 `memberGone` 把活体（session + agent）
+* 真正关掉；**删除不碰归档**——回收站与归档是两套状态，归档只在用户自己归档过时保留。
+*
+* **已知窗口**：摘账本之后、`memberGone` 之前的这一拍，活体会短暂无主（客户端可能把它归入「未分组」）。
+* 这是 ADR-0008 去掉归档后的已知代价；`memberGone` 不能提前到文件/清册写成功之前，否则一次失败回滚
+* 会留下"文件在、agent 已关"的半个世界。窗口与可选修法登记在 ADR-0008 的「边界」。
 *
 * 每一步的反向动作都是"把这件写退回原样"；**清册行是最后一件写**，它失败时 journal 会把目录搬回去、
-* 账本挂回去、可见性还原。清册行的反向动作带一道闸：**回收站目录还没搬回来就不摘那一行**——
-* 留着行至少元数据还在（与旧实现"目录退不回就不摘行"同一条判据）。
+* 账本挂回去。清册行的反向动作带一道闸：**回收站目录还没搬回来就不摘那一行**——留着行至少元数据还在
+* （与旧实现"目录退不回就不摘行"同一条判据）。
 */
-async function memberMove(deps, member, deletedAt, parentEntryId) {
+async function memberMove(deps, presence, member, deletedAt, parentEntryId) {
 	const { sessionId, projectDir } = member;
 	const workspaceId = await deps.host.workspaceOf(sessionId);
 	const sessionDir = sessionDirOf(projectDir, sessionId, deps.home);
@@ -1282,10 +1391,10 @@ async function memberMove(deps, member, deletedAt, parentEntryId) {
 	};
 	/** 目录真的搬进回收站了吗——决定那一步的反向动作有没有东西可退。 */
 	let moved = false;
-	/** 回滚的三件写是否都真正退回原样：目录、账本、可见性。`announceRestored` 只在这三件都成立时发。 */
+	/** 回滚的两件写是否都真正退回原样：目录、账本。两个事实交给成员在场 module 判「归位」通告。
+	*  删除不碰归档集 ⇒ 可见性不是这次删除改过的事实，不进真值表。 */
 	let movedBack = false;
 	let workspaceBack = workspaceId === void 0;
-	let visibleBack = wasArchived;
 	const journal = createJournal([
 		{
 			label: "读取会话现场失败",
@@ -1294,18 +1403,6 @@ async function memberMove(deps, member, deletedAt, parentEntryId) {
 				entry.sizeBytes = await deps.fs.sizeOfDir(sessionDir);
 			}
 		},
-		...wasArchived ? [] : [{
-			label: "归档失败",
-			run: async () => {
-				await deps.host.archive(sessionId, workspaceId);
-			},
-			undo: async () => {
-				return await attempt("可见性还原失败", async () => {
-					await deps.host.unarchive(sessionId);
-					visibleBack = true;
-				});
-			}
-		}],
 		...workspaceId === void 0 ? [] : [{
 			label: "摘账本失败",
 			run: async () => {
@@ -1347,33 +1444,72 @@ async function memberMove(deps, member, deletedAt, parentEntryId) {
 		journal: {
 			async run() {
 				await journal.run();
-				if (await deps.host.evictLive(sessionId) !== "unknown") await deps.host.announceRemoved(sessionId);
+				await presence.memberGone(sessionId);
 			},
-			/** 组级回滚：先把成员自己的步骤按相反顺序退回，再在**三件写都真正回去**时补一条"已恢复"通告。
-			*  这一行此前已经收过 `api-session/removed`；不发"回来了"它就会在客户端消失到重连为止。
-			*  目录没退回、账本没挂回、或可见性没还原 ⇒ 不发——那会是假话（同 restore 侧 `movedBack` 的判据）。 */
+			/** 组级回滚：先把成员自己的步骤按相反顺序退回，再交给成员在场 module 判「三件写都回去了吗」。
+			*  这一行此前已经收过 `api-session/removed`；不发"回来了"它就会在客户端消失到重连为止。 */
 			async undo() {
 				const failures = await journal.undo();
-				if (movedBack && workspaceBack && visibleBack) await deps.host.announceRestored(sessionId).catch(() => {});
+				await presence.memberBack(sessionId, {
+					diskBack: movedBack,
+					workspaceBack
+				});
 				return failures;
 			}
 		}
 	};
 }
 //#endregion
-//#region src/verbs/orphan-subagents.ts
+//#region src/verbs/permanent-removal.ts
+/**
+* 永久删除的**测量、计划与执行**：一次永久删除（`/list` 的只读读数或 purge / orphan-clean 的删除计划）
+* 之前要记下的事实（目录、字节、账本归属），以及拿到计划之后按它动盘的那一步。计划函数**只读**——
+* 写不写由执行器决定，但活体准入在这里就做掉，调用方拿到计划才允许动盘。
+*/
+/** `exists` 与 `sizeOfDir` 之间目录消失（ENOENT）是唯一一种当"不在"的失败：盘没挂、权限、I/O 错误
+*  都不许伪装成"目录没了"，那会让 `/list` 静默少算释放量、让删除计划少一条该删的目录。 */
+function isMissing(error) {
+	return error?.code === "ENOENT";
+}
+/** `exists → sizeOfDir` 的唯一一条度量口径（成员目录与回收站目录共用）：先问在不在，再量字节；
+*  ENOENT 是唯一一种当"不在"的失败，别的错误照旧响亮。别再在调用点各写一遍这段 try/catch。
+*
+*  **已知粒度**：`sizeOfDir` 递归里撞到的 ENOENT 与"目录本身没了"是同一个码，所以目录里某个文件
+*  恰好在这一拍消失时，整条目录会被记成「不在」（`/list` 少算这条、删除计划里没有可删的字节，
+*  而清册行照旧摘——盘上留下目录等下一次 `reconcile` 重建成行，自愈、不丢数据）。复核一次
+*  `exists(dir)` 能把两者分开，却会让「宿主正在写、文件刚被挪走」这类正常竞态把 `/list` 整个打红——
+*  这里选自愈不选响亮。 */
+async function probeDir(deps, dir) {
+	if (!await deps.fs.exists(dir)) return {
+		present: false,
+		bytes: 0
+	};
+	try {
+		return {
+			present: true,
+			bytes: await deps.fs.sizeOfDir(dir)
+		};
+	} catch (error) {
+		if (isMissing(error)) return {
+			present: false,
+			bytes: 0
+		};
+		throw error;
+	}
+}
 /** 成员的盘上目录与字节（扫描、清单装配与 purge 共用这一条路径/存在性/度量口径；
 *  目录缺席回 `undefined`，不拿一份"记录还在、盘上已经没了"的旧读数冒充盘上残留）。 */
 async function measureMemberDir(deps, member) {
 	const dir = sessionDirOf(member.projectDir, member.sessionId, deps.home);
-	if (!await deps.fs.exists(dir)) return void 0;
-	return {
+	const probe = await probeDir(deps, dir);
+	return probe.present ? {
 		dir,
-		bytes: await deps.fs.sizeOfDir(dir)
-	};
+		bytes: probe.bytes
+	} : void 0;
 }
 /** 把一组成员折成"删之前要记下的计划"；目录不在的成员跳过（记录与盘不一致是那条成员自己的事）。
-*  `purge` 的盘上后代与 `orphan-clean` 的整组都走这一处，别再各写一遍 measure + workspaceOf。 */
+*  `purge` 的盘上后代、`orphan-clean` 的整组与 `/list` 的盘上残留都走这一处，别再各写一遍
+*  measure + workspaceOf。 */
 async function planMemberRemovals(deps, members) {
 	const plans = [];
 	for (const member of members) {
@@ -1388,14 +1524,218 @@ async function planMemberRemovals(deps, members) {
 	}
 	return plans;
 }
+/** 量一条回收站行；目录不在回 `present: false` / 0 字节（目录不在不等于清册行不用摘）。 */
+async function measureTrashRow(deps, entry) {
+	const dir = trashDirOf(entry.id, deps.home);
+	const probe = await probeDir(deps, dir);
+	return {
+		entry,
+		dir,
+		present: probe.present,
+		bytes: probe.bytes
+	};
+}
+/**
+* 盘上后代的选择判据（`/list` 与 purge 的删除计划共用这一份）：`subagentMembersOf` 一次问全部父，
+* 再按 `bareSessionId` **排除全部清册 id**（跟着父进来的孩子不按盘上残留再算一遍），同一个 bare id 只认
+* **遍历顺序里第一次**出现的那条（同一个会话在两代宿主里的写法不同）。
+*
+* 语料看不见（`available: false`）⇒ 每个根都按空成员收：`/list` 与 purge 只许静默降级，
+* 盘上残留留给 `GET /orphans` 兜底。
+*
+* 结果按传入父 id 的原序分组、组内保持宿主交回的顺序：全局去重需要顺序，实测那一步可以并行。
+*
+* **单行读数和单行回执可能差一条**：同一个 bare id 若同时挂在两个组根下，全局去重只把它算给遍历
+* 顺序里第一个根；而对某个根单独 purge 时它仍会算进那一组 ⇒ 那条的 `releaseBytes` 与对它 purge 的
+* `freedBytes` 在共享后代上可以不等（全部可见行之和与 `/empty` 的回执仍相等）。数据里有环或两代
+* 写法混杂才会撞上，不为它多开一条口径。
+*/
+async function selectStrandedMembers(host, manifest, parentIds) {
+	const manifestIds = new Set(manifest.map((row) => bareSessionId(row.sessionId)));
+	const read = await host.subagentMembersOf(parentIds);
+	const seen = /* @__PURE__ */ new Set();
+	return parentIds.map((parentId) => {
+		const wanted = [];
+		if (!read.available) return wanted;
+		for (const member of read.value[parentId] ?? []) {
+			const bare = bareSessionId(member.sessionId);
+			if (manifestIds.has(bare) || seen.has(bare)) continue;
+			seen.add(bare);
+			wanted.push(member);
+		}
+		return wanted;
+	});
+}
+/**
+* `/list` 的只读计划：一行 = 一组。释放量与 purge 用同一条口径——回收站目录与成员目录**现测**，
+* 不用清册里记的 `sizeBytes`（那是删除那一刻的事实，盘上早就变了）。
+*
+* 盘上后代经 `selectStrandedMembers` 选出（排除全部清册 id、bare id 全局只算一次）；目录不在的成员
+* 不进 `members`（与 `planMemberRemovals` 同口径）。
+*/
+async function planVisibleTrash(deps, rows, groups) {
+	const candidates = await selectStrandedMembers(deps.host, rows, groups.map((group) => group.root.sessionId));
+	return await Promise.all(groups.map(async ({ root, kids }, index) => {
+		const rootRow = await measureTrashRow(deps, root);
+		const kidRows = await Promise.all(kids.map((kid) => measureTrashRow(deps, kid)));
+		const members = await planMemberRemovals(deps, candidates[index] ?? []);
+		const subagentBytes = kidRows.reduce((total, row) => total + row.bytes, 0);
+		const strandedBytes = members.reduce((total, member) => total + member.bytes, 0);
+		return {
+			root,
+			kids,
+			trash: [rootRow, ...kidRows],
+			members,
+			releaseBytes: rootRow.bytes + subagentBytes + strandedBytes,
+			subagentBytes,
+			strandedBytes,
+			strandedCount: members.length
+		};
+	}));
+}
+/** 活体准入：逐个问，任一在跑就抛 `live`。**计划函数就是执行前的闸**——调用方拿到计划才允许写，
+*  所以这里必须发生在任何写之前（`admission:'none'` 的调用方自己承担这个风险，不进来）。 */
+async function assertNoLive(deps, sessionIds) {
+	for (const sessionId of sessionIds) if (await deps.host.isLive(sessionId)) throw verbError("live", `会话正在运行：${sessionId}`);
+}
+function totalBytes(items) {
+	return items.reduce((total, item) => total + item.bytes, 0);
+}
+/**
+* purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
+*
+* - `trash` 按 targets 原序逐个实测（目录缺席的行 `present:false` / 0 字节，但清册行仍要摘）。
+* - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
+* - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
+*   只摘这一次真要碰的 id。
+* - `admission:'live'` 在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；
+*   任一在跑就整条拒绝，零副作用。
+* - `sessionQuery` 缺席时端口回 `{ available: false }` ⇒ members 为空、不抛（盘上残留留给 `GET /orphans` 兜底）。
+*/
+async function planTrashRemoval(deps, rows, targets, options) {
+	const candidates = (await selectStrandedMembers(deps.host, rows, targets.map((entry) => entry.sessionId))).flat();
+	if (options.admission === "live") await assertNoLive(deps, [...targets.map((entry) => entry.sessionId), ...candidates.map((member) => member.sessionId)]);
+	const trash = await Promise.all(targets.map((entry) => measureTrashRow(deps, entry)));
+	const members = await planMemberRemovals(deps, candidates);
+	return {
+		kind: "trash",
+		trash,
+		members,
+		unarchive: [...targets.map((entry) => entry.sessionId), ...members.map((member) => member.sessionId)],
+		bytes: totalBytes(trash) + totalBytes(members)
+	};
+}
+/**
+* orphan-clean 的删除计划：成员是调用方扫出来的传递闭包（`orphanGroupsOf`）。
+*
+* - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节），`bytes` 只算这些实测值。
+* - `unarchive` 覆盖**全部传入成员**（含目录缺席）：orphan-clean 在删目录之前整批摘归档集，
+*   目录缺席的 id 也可能还挂在归档集里；重试时不会再长出一条幽灵 id。
+* - live 准入覆盖**全部传入成员**（含目录缺席）：它们都在这一组的可见面里，任一在跑就整组拒绝。
+* - 回执由 `kind:'orphan'` 派生：删目录阶段失败时执行器要交回 `{removed, freedBytes, failedSessionId}`。
+*/
+async function planOrphanRemoval(deps, members) {
+	await assertNoLive(deps, members.map((member) => member.sessionId));
+	const present = await planMemberRemovals(deps, members);
+	return {
+		kind: "orphan",
+		trash: [],
+		members: present,
+		unarchive: members.map((member) => member.sessionId),
+		bytes: totalBytes(present)
+	};
+}
+/**
+* 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。
+*
+* 顺序（与迁移前的 purge / orphan-clean 一致）：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
+* （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）。目录删掉就没有
+* "退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
+*
+* 失败形状沿用调用方原来的措辞与结构：
+* - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
+* - `kind:'trash'`（purge）⇒ 同一个标签、不带 details。
+* - orphan-clean 的 unarchive / detach 在旧实现里不包装，这里原样抛出（不改变现有错误形状）。
+*
+* 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
+*/
+async function executeRemoval(deps, plan) {
+	const presence = createMemberPresence(deps.host);
+	let removed = 0;
+	let freedBytes = 0;
+	/** 删除途中失败的唯一出口：标签沿用旧措辞；部分回执只属于 `orphan`（由计划的 `kind` 派生）。
+	*  已经是本仓动词码的错误原样抛（与 `member-journal.ts` 的 `journalFailure` 同一条判据）——
+	*  `not-found` / `live` 之类不许在这里被折成 `io`。 */
+	const fail = (label, error, failedSessionId) => {
+		if (isVerbCodeError(error)) throw error;
+		const details = plan.kind === "orphan" ? {
+			removed,
+			freedBytes,
+			failedSessionId
+		} : void 0;
+		throw verbError("io", `${label}：${String(error)}`, error, details);
+	};
+	/** 退归档集 / 摘账本这一步的失败形状：purge 折成带标签的 `io`；orphan-clean 原样抛。 */
+	const step = async (label, sessionId, run) => {
+		if (plan.kind === "orphan") {
+			await run();
+			return;
+		}
+		try {
+			await run();
+		} catch (error) {
+			fail(label, error, sessionId);
+		}
+	};
+	for (const sessionId of plan.unarchive) await step("取消归档失败", sessionId, () => deps.host.unarchive(sessionId));
+	for (const member of plan.members) {
+		const workspaceId = member.workspaceId;
+		if (workspaceId === void 0) continue;
+		await step("摘账本失败", member.sessionId, () => deps.host.detach(member.sessionId, workspaceId));
+	}
+	for (const row of plan.trash) {
+		if (row.present) {
+			try {
+				await deps.fs.removeDir(row.dir);
+			} catch (error) {
+				fail("删除回收站目录失败", error, row.entry.sessionId);
+			}
+			freedBytes += row.bytes;
+		}
+		try {
+			await deps.manifest.remove(row.entry.id);
+		} catch (error) {
+			fail("删除回收站目录失败", error, row.entry.sessionId);
+		}
+		removed += 1;
+		await presence.memberGone(row.entry.sessionId);
+	}
+	const memberLabel = plan.kind === "trash" ? "删除盘上后代目录失败" : "删除会话目录失败";
+	for (const member of plan.members) {
+		try {
+			await deps.fs.removeDir(member.dir);
+		} catch (error) {
+			fail(memberLabel, error, member.sessionId);
+		}
+		removed += 1;
+		freedBytes += member.bytes;
+		await presence.memberGone(member.sessionId);
+	}
+	return {
+		removed,
+		freedBytes
+	};
+}
+//#endregion
+//#region src/verbs/orphan-subagents.ts
 /**
 * 无主子会话 = `origin:"subagent"`、父**既不在当前语料（live ∪ persisted）也不在回收站清册里**的会话。
 *
 * 为什么清册里的父不算孤儿：那种是 **stranded**——父还在回收站里等着，孩子本该跟着父一起恢复或一起
-* 彻底删除（10-15 稿 §11 的组语义），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
+* 彻底删除（组语义见 `src/trash/groups.ts`），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
 * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
 *
-* 根按**传递闭包**收全部后代（与 `HostPort.subagentCounts` 同一口径：孩子与孙代都算，深度不设上限），
+* 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一口径：孩子与孙代都算，深度不设上限），
 * 同一条记录只归一组（`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
 * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
 */
@@ -1440,12 +1780,13 @@ function orphanGroupsOf(corpus, trashSessionIds) {
 /** 纯读：调用方应先走一次 `/list` 对账（面板的 refresh 就是这样）；本函数不写清单。
 *  写动作 `orphan-clean` 会自己先 reconcile，避免拿一份过期清册判"父没了"。
 *
-*  `listSessions()` 回 `undefined` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
-*  拿 undefined 当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
-*  所以这里按 `io` 响亮失败（AGENTS.md：`undefined` 意味着服务缺席，扫描方不许冒充读数）。 */
+*  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
+*  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
+*  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
 async function loadOrphanGroups(deps) {
-	const corpus = await deps.host.listSessions();
-	if (corpus === void 0) throw verbError("io", "无主子会话扫描需要宿主的 sessionQuery.listSessions");
+	const read = await deps.host.listSessions();
+	if (!read.available) throw verbError("io", "无主子会话扫描需要宿主的 sessionQuery.listSessions");
+	const corpus = read.value;
 	const groups = orphanGroupsOf(corpus, (await deps.manifest.list()).map((entry) => entry.sessionId));
 	const out = [];
 	for (const group of groups) {
@@ -1495,46 +1836,20 @@ function reportOrphans(groups) {
 	};
 }
 /**
-* 清一组：先**整组 live 准入（零写）**，再收集目录/字节/账本归属，再 unarchive → detach → 删目录。
-* 任何 preflight 失败都在第一件写之前抛出；删目录到一半失败时**已删目录不回滚**，失败错误的
-* `details` 带 `{ removed, freedBytes, failedSessionId }` 作为部分回执（不伪装成整组没动）。
-* 删目录之后照 purge 的规矩摘活体并如实通告。不碰投影缓存与附件。
+* 清一组：`planOrphanRemoval`（只读计划，整组 live 准入在一切写之前）→ `executeRemoval`（只写）。
+* 量目录、摘归档集与账本、删目录与成员通告的顺序和失败形状都住 `verbs/permanent-removal.ts`；
+* 这里只把这一组接上去，别在这再长出一段手写步骤（purge 走的是同一条路）。
 *
 * 顺序与删除那一半是**对偶**的，但不是照抄：
-* - 删除要先把会话藏起来（归档）再摘账本，免得中间那一拍它掉进「未分组」；这里目录是**删掉**不是搬走，
-*   藏不藏都不影响可见性 ⇒ 归档集反而是**在写之前整批摘掉**的：失败时目录还在，下一次还能重试，
+* - 删除那一半不再用归档藏会话（ADR-0008）：它摘账本、搬目录，最后才摘活体。这里目录是**删掉**
+*   不是搬走，藏不藏都不影响可见性 ⇒ 归档集反而**在写之前整批摘掉**：失败时目录还在，下一次还能重试，
 *   不会留下"会话没了但还在归档集里挂着"的幽灵 id。
-* - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以不需要删除侧那次
+* - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以这里不需要那次
 *   `wasArchived` 读——这里没有"还原到删除前"的义务。
 * - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
-* - `evictLive` 的三态照 `HostPort.evictLive` 的契约：`unknown` 时**不通告**（发了就是假话），
-*   `evicted` / `not-live` 才发 `api-session/removed`。冷会话没有活体可摘，通告照样必须发。
 */
 async function cleanOrphanGroup(deps, group) {
-	for (const member of group.members) if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
-	const plans = await planMemberRemovals(deps, group.members);
-	for (const member of group.members) await deps.host.unarchive(member.sessionId);
-	for (const plan of plans) if (plan.workspaceId !== void 0) await deps.host.detach(plan.sessionId, plan.workspaceId);
-	let removed = 0;
-	let freedBytes = 0;
-	for (const plan of plans) {
-		try {
-			await deps.fs.removeDir(plan.dir);
-		} catch (error) {
-			throw verbError("io", `删除会话目录失败：${String(error)}`, error, {
-				removed,
-				freedBytes,
-				failedSessionId: plan.sessionId
-			});
-		}
-		removed += 1;
-		freedBytes += plan.bytes;
-		if (await deps.host.evictLive(plan.sessionId) !== "unknown") await deps.host.announceRemoved(plan.sessionId);
-	}
-	return {
-		removed,
-		freedBytes
-	};
+	return await executeRemoval(deps, await planOrphanRemoval(deps, group.members));
 }
 //#endregion
 //#region src/verbs/purge-trash.ts
@@ -1544,75 +1859,20 @@ async function cleanOrphanGroup(deps, group) {
 * 与另外两个动词的关系（ADR-0002）：它的 interface 只有"一个条目 id（或缺席 = 清空）"，
 * 批量的快照与"已被同批前一条带走"的判据不在这里（归 `verbs/batch.ts`）。
 *
-* **这条动词不做回滚**：目录删掉就没有"退回去"这回事（设计稿第十七批：删到一半失败时已删目录不回滚；
+* **这条动词只做两件事：选目标、拿计划交给执行器**。量目录、筛盘上后代、活体准入与"先退归档集、
+* 再摘账本、最后删目录"的顺序都住 `verbs/permanent-removal.ts`——计划只读，执行器只写，计划就是
+* 执行前的闸（别在这里再长出一段手写步骤）。
+*
+* **这条动词不做回滚**：目录删掉就没有"退回去"这回事（2026-10-19 `f2a7757`：删到一半失败时已删目录不回滚；
 * 带部分计数的 `details` 回执只属于 `orphan-clean`，purge 的 `removed` / `freedBytes` 仍只在成功回执里给）。
-* 所以它的 journal 只有正向步骤、没有 `undo`——顺序仍由 journal 统一表达，不再是手写的四段 `try/catch`。
+* 对应地，`kind:'trash'` 的计划失败时执行器只抛那一步的 `io` 与原文、不带 details。
 */
 function purgeTrash(deps) {
 	return async function purgeTrash(entryId, snapshot) {
 		const all = snapshot ?? await deps.manifest.list();
 		const targets = entryId === void 0 ? all : groupOf(all, entryId);
 		if (entryId !== void 0 && targets.length === 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
-		const manifestIds = new Set(targets.map((entry) => bareSessionId(entry.sessionId)));
-		const membersByParent = await deps.host.subagentMembersBatch(targets.map((entry) => entry.sessionId));
-		const seenDisk = /* @__PURE__ */ new Set();
-		/** 先只做准入与去重（全部是读），整组通过后再量目录/账本——任一成员在跑时一件计划都还没做。 */
-		const candidates = [];
-		for (const entry of targets) for (const member of membersByParent[entry.sessionId] ?? []) {
-			const bare = bareSessionId(member.sessionId);
-			if (manifestIds.has(bare) || seenDisk.has(bare)) continue;
-			seenDisk.add(bare);
-			if (await deps.host.isLive(member.sessionId)) throw verbError("live", `会话正在运行：${member.sessionId}`);
-			candidates.push(member);
-		}
-		const diskPlans = await planMemberRemovals(deps, candidates);
-		let freedBytes = 0;
-		let removed = 0;
-		await createJournal([
-			{
-				label: "取消归档失败",
-				run: async () => {
-					for (const entry of targets) await deps.host.unarchive(entry.sessionId);
-					for (const plan of diskPlans) await deps.host.unarchive(plan.sessionId);
-				}
-			},
-			{
-				label: "摘账本失败",
-				run: async () => {
-					for (const plan of diskPlans) if (plan.workspaceId !== void 0) await deps.host.detach(plan.sessionId, plan.workspaceId);
-				}
-			},
-			{
-				label: "删除回收站目录失败",
-				run: async () => {
-					for (const entry of targets) {
-						const dir = trashDirOf(entry.id, deps.home);
-						if (await deps.fs.exists(dir)) {
-							freedBytes += await deps.fs.sizeOfDir(dir);
-							await deps.fs.removeDir(dir);
-						}
-						await deps.manifest.remove(entry.id);
-						removed += 1;
-						if (await deps.host.evictLive(entry.sessionId) !== "unknown") await deps.host.announceRemoved(entry.sessionId);
-					}
-				}
-			},
-			{
-				label: "删除盘上后代目录失败",
-				run: async () => {
-					for (const plan of diskPlans) {
-						await deps.fs.removeDir(plan.dir);
-						removed += 1;
-						freedBytes += plan.bytes;
-						if (await deps.host.evictLive(plan.sessionId) !== "unknown") await deps.host.announceRemoved(plan.sessionId);
-					}
-				}
-			}
-		]).run();
-		return {
-			removed,
-			freedBytes
-		};
+		return await executeRemoval(deps, await planTrashRemoval(deps, all, targets, { admission: "live" }));
 	};
 }
 //#endregion
@@ -1627,7 +1887,7 @@ function purgeTrash(deps) {
 *    预检在写之前，是为了不让"父已经回到 `sessions/`、孩子因为项目目录没了而回不去"这种半组留在外面。
 *    **工作区账本不在这条硬前提里**：宿主的「删除工作区」只删注册、保留日志，记下的工作区没了就按
 *    「未分组」收（判据在 {@link attachableWorkspaceId}），照旧回盘——恢复是加法，不该因为一个可选的账目而失败。
-* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 → 还原可见性 → 摘清册行。
+* ② **逐个恢复**，顺序与删除相反：文件先回来 → 挂账本 →（旧清单迁移）取消归档 → 摘清册行。
 * ③ 中途失败时 journal 把这个成员自己退回回收站；**已经恢复完的**兄弟由整组 catch 按相反顺序一起退回。
 *
 * **通告不在这里**：一次批量只该拉一遍宿主会话表、只发一次 `api-session/added`（2026-10-17 那次
@@ -1635,6 +1895,7 @@ function purgeTrash(deps) {
 * "一个条目 id 进、回收站那一行出"，没有批量专用的开关。
 */
 function restoreSession(deps) {
+	const presence = createMemberPresence(deps.host);
 	return async function restoreSession(entryId, snapshot) {
 		const all = snapshot ?? await deps.manifest.list();
 		const target = all.find((e) => e.id === entryId);
@@ -1649,7 +1910,7 @@ function restoreSession(deps) {
 		const done = [];
 		try {
 			for (const entry of group) {
-				const move = await memberRestore(deps, entry);
+				const move = await memberRestore(deps, presence, entry);
 				await move.journal.run();
 				done.push(move.journal);
 			}
@@ -1659,7 +1920,7 @@ function restoreSession(deps) {
 		return target;
 	};
 }
-/** 放回哪儿：用**删除时记进 entryId 的那段原目录名**，不从 `sessionId` 现推（设计稿 §3）——
+/** 放回哪儿：用**删除时记进 entryId 的那段原目录名**，不从 `sessionId` 现推（CONTEXT.md 的「条目」条）——
 *  因此不依赖宿主当时的目录命名约定（v3 无前缀 / v4 带 `session-` 前缀）。 */
 function restoreTargetDir(deps, entry) {
 	return sessionDirOf(entry.projectDir, parseEntryId(entry.id).sessionDirName, deps.home);
@@ -1685,18 +1946,24 @@ async function isWorkspaceMissing(host, entry) {
 	return entry.workspaceId !== "" && await attachableWorkspaceId(host, entry) === void 0;
 }
 /**
-* 一个成员的恢复步骤（顺序与删除相反）：放回目录 → 挂账本 → 还原可见性 → 摘清册行。
+* 一个成员的恢复步骤（顺序与删除相反）：放回目录 → 挂账本 →（旧清单迁移）取消归档 → 摘清册行。
 *
 * 账本那一步有个**只认端口那句**的兜底：查过之后、挂之前账本被删掉（宿主的「删除工作区」与这次恢复
 * 撞上）⇒ 按未分组收、不回滚；**别的**失败是真故障，照旧抛（吞掉它就等于把一次存储故障伪装成"未分组"）。
 */
-async function memberRestore(deps, entry) {
+async function memberRestore(deps, presence, entry) {
 	const trashDir = trashDirOf(entry.id, deps.home);
 	const sessionDir = restoreTargetDir(deps, entry);
 	const workspaceId = await attachableWorkspaceId(deps.host, entry);
+	/**
+	* **旧清单迁移**：2026-10-21 之前的删除用归档来藏会话，所以那些条目在盘上仍是归档态。
+	* 新删除不再碰归档（回收站与归档解耦）⇒ `wasArchived:false` 且当前**仍**归档的，只可能是旧条目；
+	* 恢复时取消归档。`wasArchived:true` 是用户删除前自己归档的，保持归档态不动。
+	*/
+	const legacyArchived = !entry.wasArchived && await deps.host.isArchived(entry.sessionId);
 	/** 真挂上了账本才记下那个 id——回滚里"摘账本"那一步只对挂过的成员存在。 */
 	let attached = false;
-	/** 组级回滚时，目录真的退回回收站了才通告「已移除」（否则那条通告会骗客户端删掉一行还在盘上的会话）。 */
+	/** 组级回滚时，目录是否真的退回回收站——作为事实交给成员在场 module 判「已移除」通告。 */
 	let movedBack = false;
 	const journal = createJournal([
 		{
@@ -1722,7 +1989,7 @@ async function memberRestore(deps, entry) {
 			},
 			undo: async () => attached ? attempt("摘账本失败", () => deps.host.detach(entry.sessionId, workspaceId)) : []
 		}],
-		...entry.wasArchived ? [] : [{
+		...!legacyArchived ? [] : [{
 			label: "取消归档失败",
 			undoOnFailure: true,
 			run: async () => {
@@ -1742,9 +2009,7 @@ async function memberRestore(deps, entry) {
 		run: () => journal.run(),
 		async undo() {
 			const failures = await journal.undo();
-			if (movedBack) {
-				if (await deps.host.evictLive(entry.sessionId).catch(() => "unknown") !== "unknown") await deps.host.announceRemoved(entry.sessionId).catch(() => {});
-			}
+			await presence.memberGone(entry.sessionId, { backInTrash: movedBack });
 			return failures;
 		}
 	} };
@@ -1825,8 +2090,8 @@ async function applyDelete(deps, ids) {
 	return forEachId("delete", ids, async (sessionId) => {
 		const root = bareSessionId(sessionId);
 		if (carried.has(root)) return null;
-		const entry = await run(sessionId);
-		for (const row of groupOf(await deps.manifest.list(), entry.id)) if (bareSessionId(row.sessionId) !== root) carried.add(bareSessionId(row.sessionId));
+		const { entry, movedSessionIds } = await run(sessionId);
+		for (const movedId of movedSessionIds) carried.add(bareSessionId(movedId));
 		return entry;
 	});
 }
@@ -1863,12 +2128,13 @@ async function applyPurge(deps, ids) {
 		return stats;
 	});
 }
-/** 删除确认框那句「含 N 个子会话」：一次问完整批（`subagentCounts` 本来就是批量口）。
-*  宿主口缺席时它回 `{}`（这里折成 0）；真读失败则整次调用失败，浏览器半按"读不到"把整句不说。 */
+/** 删除确认框那句「含 N 个子会话」：一次问完整批（`subagentMembersOf` 本来就是批量口）。
+*  宿主口缺席（`available:false`）时按 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));
+	const read = await deps.host.subagentMembersOf(wanted);
+	return wanted.map((id) => success(id, "count", read.available ? read.value[id]?.length ?? 0 : 0));
 }
 /**
 * 清一组无主子会话（父已被彻底删掉、孩子还留在 `sessions/` 里的那些）。id 是**根会话 id**——
@@ -2028,7 +2294,7 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 * 清册那一行 → 线上那一行。**显式字面量、不用 `...row`**：线上形状多一个必填字段时，这里编译不过，
 * 于是"线上多了一格却没人填"不可能悄悄发生（`...row` 会把它带过去，看上去一切正常）。
 */
-function toWire(row, readouts = {}) {
+function toWire(row, readouts) {
 	return {
 		id: row.id,
 		sessionId: row.sessionId,
@@ -2038,7 +2304,7 @@ function toWire(row, readouts = {}) {
 		deletedAt: row.deletedAt,
 		title: row.title,
 		sizeBytes: row.sizeBytes,
-		releaseBytes: row.sizeBytes + (readouts.subagentBytes ?? 0) + (readouts.strandedBytes ?? 0),
+		releaseBytes: readouts.releaseBytes,
 		...row.parentEntryId === void 0 ? {} : { parentEntryId: row.parentEntryId },
 		...readouts.subagentCount === void 0 ? {} : { subagentCount: readouts.subagentCount },
 		...readouts.subagentBytes === void 0 ? {} : { subagentBytes: readouts.subagentBytes },
@@ -2052,35 +2318,25 @@ function toWire(row, readouts = {}) {
 * 我们若单列就会冒出一堆点不到的行）；父行不在时孩子自己站出来占一行，否则它既看不见也清不掉。
 * 这些派生值只加在这次回信上，**不落清册**——清册该记的是文件里真有的事实，而"还剩几个孩子"
 * "工作区还在不在"是随盘上随时变的读数。取数失败照抛（响亮失败，不端一份少了这栏的清单当没事发生）。
+*
+* 一组要释放多少、盘上还剩谁**只读计划一处算**（`planVisibleTrash`，与 purge 同一条口径）；
+* 这里不再自己枚举盘上后代，也不碰 `isLive`（活体准入只属于写动词）。
 */
 async function assembleTrashRows(deps, rows) {
 	const groups = visibleGroups(rows);
-	const visible = groups.map((group) => group.root);
-	const [membersByParent, missingByRowId] = await Promise.all([deps.host.subagentMembersBatch(visible.map((row) => row.sessionId)), Promise.all(visible.map(async (row) => [row.id, await isWorkspaceMissing(deps.host, row)]))]);
+	const [planned, missingByRowId] = await Promise.all([planVisibleTrash(deps, rows, groups), Promise.all(groups.map(async ({ root }) => [root.id, await isWorkspaceMissing(deps.host, root)]))]);
 	const gone = new Map(missingByRowId);
-	return await Promise.all(groups.map(async ({ root, kids }) => {
-		const kidsInGroup = new Set(kids.map((kid) => bareSessionId(kid.sessionId)));
-		let count = 0;
-		let bytes = 0;
-		for (const member of membersByParent[root.sessionId] ?? []) {
-			if (kidsInGroup.has(bareSessionId(member.sessionId))) continue;
-			const measured = await measureMemberDir(deps, member);
-			if (measured === void 0) continue;
-			count += 1;
-			bytes += measured.bytes;
-		}
-		const missing = gone.get(root.id) === true;
-		return toWire(root, {
-			...kids.length === 0 ? {} : {
-				subagentCount: kids.length,
-				subagentBytes: kids.reduce((total, kid) => total + kid.sizeBytes, 0)
-			},
-			...count === 0 ? {} : {
-				strandedSubagents: count,
-				strandedBytes: bytes
-			},
-			...missing ? { workspaceMissing: true } : {}
-		});
+	return planned.map(({ root, kids, releaseBytes, subagentBytes, strandedCount, strandedBytes }) => toWire(root, {
+		releaseBytes,
+		...kids.length === 0 ? {} : {
+			subagentCount: kids.length,
+			subagentBytes
+		},
+		...strandedCount === 0 ? {} : {
+			strandedSubagents: strandedCount,
+			strandedBytes
+		},
+		...gone.get(root.id) === true ? { workspaceMissing: true } : {}
 	}));
 }
 //#endregion
@@ -2224,7 +2480,7 @@ function writeOk(res, value) {
 *  未知路由 404、栅栏拒 403（它们不是"一次办成的操作"，是"这条请求不归我办/你没资格办"）。
 *  **操作失败**仍回 200 + 信封。浏览器半先解信封再看状态，所以 4xx 上带的信封照样读得出原文；
 *  `code` 一律折成 `sessiondelete/io`，那三个路由标签（`bad-request` / `bad-method` / `not-found-route`）
-*  是**抛出处给读代码的人看的站点名**，不许冒充 §6 的五个动词码上客户端。 */
+*  是**抛出处给读代码的人看的站点名**，不许冒充 `src/shared/wire.ts` 的五个动词码上客户端。 */
 function writeFailure(res, error, status) {
 	const carried = error?.httpStatus;
 	writeJson(res, status ?? (typeof carried === "number" ? carried : 200), {
@@ -2370,8 +2626,35 @@ function createFsPort() {
 	};
 }
 //#endregion
+//#region src/ports/home.ts
+/**
+* 宿主数据根。官方解析器在 asar `dsh/node_modules/@deepseek-ai/dsh-home-paths/lib/index.js`：
+* `resolveDshHome(configured, env)` 的优先级 = 显式配置 > `$DSH_HOME`（**空白视为未设**，免得非法覆盖把 home
+* 解析成当前工作目录）> `~/.dsh`，并 `resolve()` 规范化、展开 `~/`。
+*
+* **只镜像后两级，且这与平台的同款设施等价**——"显式配置"那一级对插件**不可得**，三条实证：
+*  ① 平台自己的 helper `dshHomePath(...segments)` 逐字是 `join(resolveDshHome(), ...segments)`，
+*     **同样不传 `configured`**；
+*  ② `ctx.profileContext` 按 launcher 原文只装「profile 位置 / 启动 bundle 名 / 调用覆盖 / 遥测开关」，
+*     里面没有数据根；
+*  ③ 宿主自己的服务也不是"问出来"的——它们各自声明 `Config.dshHome`，由**装配那一行的人**填。
+* ⇒ 后果与边界（判据在 `src/verbs/delete-session.ts` 与 `src/verbs/restore-session.ts` 的预检）：显式配置过的
+* profile 上我们算出的根与宿主不一致 ⇒ 文件探测落空 ⇒ 删除/恢复**响亮拒绝、零副作用**（`not-found` /
+* `trash-empty` / `project-missing`）；**不会**动到别的树（sessions 与回收站同源 ⇒ 同卷）。
+* 本机两条路径都因此对得上：桌面版走 `~/.dsh`（实测 profile 在其下），隔离探针靠 `$DSH_HOME`。
+*
+* `homeDir` 只用于测试注入假主目录；默认值仍是 `homedir()`，行为与搬家前一致。
+*/
+function resolveHome(env = process.env, homeDir = homedir()) {
+	const fromEnv = env.DSH_HOME;
+	const raw = fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : join(homeDir, ".dsh");
+	if (raw === "~") return homeDir;
+	if (raw.startsWith("~/") || raw.startsWith("~\\")) return resolve(join(homeDir, raw.slice(2)));
+	return resolve(raw);
+}
+//#endregion
 //#region src/trash/manifest.ts
-function createStorageManifest$1(domain) {
+function createStorageManifest(domain) {
 	return {
 		async list() {
 			return (await domain.readAll()).sort((a, b) => b.deletedAt - a.deletedAt);
@@ -2385,31 +2668,8 @@ function createStorageManifest$1(domain) {
 	};
 }
 //#endregion
-//#region src/index.ts
-const name = "@xrn1997/dsh-session-delete";
-/**
-* 插件依赖：**只写字符串数组**（隔离数据根上实测：写成 `{ required, optional }` 会让插件停在
-* `pending (waiting for services: required, optional)`）。
-*
-* 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。三个**故意不写**的：
-* - `remote`：那是**浏览器半**的服务（asar `dsh-api-gateway/lib/client.js`：`super(ctx, "remote")`），
-*   Node 半挂的是 `ctx.typertGateway`。把它写进 Node 半的 inject 会让插件永远 pending（同 `slots` 那次的形状）。
-* - `sessions` / `sessionProjectionCache`：两者都按 `ctx.get(...)` **可选读**——`sessions` 只给 `evictLive`
-*   用（活跃判据走 waterfall，见设计稿 §5；服务缺席回 `unknown`），`sessionProjectionCache` 是标题的尽力读面。
-*   inject 一个可能没挂的服务 = 整个插件 pending。
-*   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
-*
-* `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
-* 前缀路由，浏览器半同源 fetch 那六个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
-* `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
-* `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
-*/
-const inject = [
-	"workspaceRegistry",
-	"storageDomain",
-	"webServer"
-];
-/** 本插件自己的域（设计稿 §3：介质落在 `~/.dsh/storages/`）。
+//#region src/trash/storage-manifest.ts
+/** 本插件自己的域（CONTEXT.md 的「清册」条：介质落在 `~/.dsh/storages/`）。
 *
 *  **名字必须带插件专属前缀**：domain 名是 `storageDomain` facility 里的**全局键**，而**一个名字在
 *  一个 facility 里只能 `open()` 一次**（句柄归调用方所有）——别人先占了同名域，本插件会**在激活时**
@@ -2464,7 +2724,7 @@ const trashDomainSpec = defineDomain({
 * **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
 * 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。
 */
-function createStorageManifest(ctx) {
+function createHostStorageManifest(ctx) {
 	const host = ctx;
 	let domain;
 	let opening;
@@ -2482,7 +2742,7 @@ function createStorageManifest(ctx) {
 		}
 		return domain.table("entries");
 	};
-	return createStorageManifest$1({
+	return createStorageManifest({
 		readAll: async () => [...(await table()).entries()].map(([, record]) => record),
 		put: async (record) => {
 			await (await table()).put(record.id, record);
@@ -2492,28 +2752,35 @@ function createStorageManifest(ctx) {
 		}
 	});
 }
+//#endregion
+//#region src/index.ts
+const name = "@xrn1997/dsh-session-delete";
 /**
-* 宿主数据根。官方解析器在 asar `dsh/node_modules/@deepseek-ai/dsh-home-paths/lib/index.js`：
-* `resolveDshHome(configured, env)` 的优先级 = 显式配置 > `$DSH_HOME`（**空白视为未设**，免得非法覆盖把 home
-* 解析成当前工作目录）> `~/.dsh`，并 `resolve()` 规范化、展开 `~/`。
+* 插件依赖：**只写字符串数组**（隔离数据根上实测：写成 `{ required, optional }` 会让插件停在
+* `pending (waiting for services: required, optional)`）。
 *
-* **只镜像后两级，且这与平台的同款设施等价**——"显式配置"那一级对插件**不可得**，三条实证：
-*  ① 平台自己的 helper `dshHomePath(...segments)` 逐字是 `join(resolveDshHome(), ...segments)`，
-*     **同样不传 `configured`**；
-*  ② `ctx.profileContext` 按 launcher 原文只装「profile 位置 / 启动 bundle 名 / 调用覆盖 / 遥测开关」，
-*     里面没有数据根；
-*  ③ 宿主自己的服务也不是"问出来"的——它们各自声明 `Config.dshHome`，由**装配那一行的人**填。
-* ⇒ 后果与边界（设计稿 §5）：显式配置过的 profile 上我们算出的根与宿主不一致 ⇒ 文件探测落空 ⇒
-* 删除/恢复以 `not-found` **响亮拒绝、零副作用**；**不会**动到别的树（sessions 与回收站同源 ⇒ 同卷）。
-* 本机两条路径都因此对得上：桌面版走 `~/.dsh`（实测 profile 在其下），隔离探针靠 `$DSH_HOME`。
+* 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。**不进 inject 的**：
+* - `remote`：那是**浏览器半**的服务（asar `dsh-api-gateway/lib/client.js`：`super(ctx, "remote")`），
+*   Node 半挂的是 `ctx.typertGateway`。把它写进 Node 半的 inject 会让插件永远 pending（同 `slots` 那次的形状）。
+* - `sessions` / `sessionProjectionCache`：两者都按 `ctx.get(...)` **可选读**——`sessions` 只给 `evictLive`
+*   用（活跃判据走 waterfall，见 src/ports/host-port.ts；服务缺席回 `unknown`），`sessionProjectionCache` 是标题的尽力读面。
+*   inject 一个可能没挂的服务 = 整个插件 pending。
+*   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
+* - `agents`：只给 handle 捕获用（`ctx.get('agents')`；缺席时 `ctx.inject(['agents'])` 等服务就绪再装）。
+*   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
+*
+* `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
+* 前缀路由，浏览器半同源 fetch 那六个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+* `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
+* `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
+*
+* 清单（storage domain 绑定）与数据根各有一个家：`src/trash/storage-manifest.ts`、`src/ports/home.ts`。
 */
-function resolveHome(env = process.env) {
-	const fromEnv = env.DSH_HOME;
-	const raw = fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), ".dsh");
-	if (raw === "~") return homedir();
-	if (raw.startsWith("~/") || raw.startsWith("~\\")) return resolve(join(homedir(), raw.slice(2)));
-	return resolve(raw);
-}
+const inject = [
+	"workspaceRegistry",
+	"storageDomain",
+	"webServer"
+];
 /**
 * 装配顺序：**清单 → 端口 → 动词依赖 → 前缀路由**（`DeleteDeps` 就是前两者的合一）。
 *
@@ -2525,7 +2792,7 @@ function apply(ctx) {
 	const deps = {
 		fs: createFsPort(),
 		host: createHostPort(ctx),
-		manifest: createStorageManifest(ctx),
+		manifest: createHostStorageManifest(ctx),
 		home: resolveHome(),
 		now: () => Date.now()
 	};
@@ -2542,4 +2809,4 @@ function apply(ctx) {
 	}, "session-delete: /dsh-session-delete-api routes");
 }
 //#endregion
-export { apply, createStorageManifest, inject, name };
+export { apply, inject, name };