@xrn1997/dsh-session-delete 0.6.0 → 0.6.1

package/lib/index.js

@@ -1,7 +1,6 @@
 import path, { join, resolve } from "node:path";
-import zlib from "node:zlib";
-import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
+import zlib from "node:zlib";
 import { homedir } from "node:os";
 //#region src/shared/wire.ts
 /**
@@ -192,14 +191,21 @@ function carriedRollbackFailures(error) {
 }
 /** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
 *  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
-*  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。 */
+*  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。
+*  **原错误 details 的其余键原样保留**：孤儿清理的部分回执（`removed` / `freedBytes` /
+*  `failedSessionId`）就挂在它上面，整份替换会把已经发生的删除报成 0。 */
 function withRollbackFailures(error, failures) {
 	const code = verbCodeOf(error) ?? "io";
 	const carried = carriedRollbackFailures(error);
 	const merged = [.../* @__PURE__ */ new Set([...carried, ...failures])];
 	const base = error instanceof Error ? error.message : String(error);
 	const extra = failures.filter((failure) => !carried.includes(failure));
-	return verbError(code, base.includes("；回滚未完成：") ? extra.length > 0 ? `${base}；${extra.join("；")}` : base : `${base}；回滚未完成：${merged.join("；")}`, error, { rollbackFailures: merged });
+	const message = base.includes("；回滚未完成：") ? extra.length > 0 ? `${base}；${extra.join("；")}` : base : `${base}；回滚未完成：${merged.join("；")}`;
+	const priorDetails = error?.details;
+	return verbError(code, message, error, {
+		...priorDetails,
+		rollbackFailures: merged
+	});
 }
 //#endregion
 //#region src/remote/map-error.ts
@@ -922,6 +928,92 @@ async function memberMove(deps, presence, member, deletedAt, parentEntryId) {
 	};
 }
 //#endregion
+//#region src/ports/fs-port.ts
+/**
+* **缺席**只认 ENOENT 与 ENOTDIR（"路径中间有一截不是目录"与"不存在"是同一种回答）。
+*
+* EACCES / EIO / ELOOP / 断挂载**不是缺席**：这些读数说明"我们看不见"，不是"那里没有"。
+* 破坏性动作（删目录、删附件对象、按"没有引用"清共享图）据此做决定，把读不出折成没有
+* 就是数据消失；ADR-0039 是这条判据的裁决。
+*/
+function isAbsentPath(error) {
+	const code = error?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+/** 模块级递归：端口方法**解构出来单独调**也不能靠 `this`（`{ sizeOfDir } = port` 会让方法体的
+*  `this` 变成 undefined）。所以端口只做转发，递归在模块作用域里自调。 */
+async function sizeOfDir(p) {
+	let total = 0;
+	for (const e of await readdir(p, { withFileTypes: true })) {
+		const child = join(p, e.name);
+		total += e.isDirectory() ? await sizeOfDir(child) : (await stat(child)).size;
+	}
+	return total;
+}
+/** 路径在不在：只有缺席两种错误回 `false`，其余读错误照抛。`exists` 与 `rename` 的目标检查共用。 */
+async function pathPresent(p) {
+	try {
+		await stat(p);
+		return true;
+	} catch (error) {
+		if (isAbsentPath(error)) return false;
+		throw error;
+	}
+}
+function createFsPort() {
+	return {
+		exists: pathPresent,
+		async ensureDir(p) {
+			await mkdir(p, { recursive: true });
+		},
+		async rename(from, to) {
+			if (await pathPresent(to)) throw new Error(`目标已存在，拒绝覆盖：${to}`);
+			try {
+				await rename(from, to);
+			} catch (error) {
+				if (error.code === "EXDEV") throw new Error(`跨文件系统搬不动（sessions 与 session-trash 需在同一卷）：${from} → ${to}`, { cause: error });
+				throw error;
+			}
+		},
+		async removeDir(p) {
+			await rm(p, {
+				recursive: true,
+				force: true
+			});
+		},
+		sizeOfDir: (p) => sizeOfDir(p),
+		async listFiles(p) {
+			return readdir(p);
+		},
+		async listDirs(p) {
+			const dirs = [];
+			for (const entry of await readdir(p, { withFileTypes: true })) {
+				if (entry.isDirectory()) {
+					dirs.push(entry.name);
+					continue;
+				}
+				if (!entry.isSymbolicLink()) continue;
+				try {
+					if ((await stat(join(p, entry.name))).isDirectory()) dirs.push(entry.name);
+				} catch {}
+			}
+			return dirs;
+		},
+		async realpath(p) {
+			return realpath(p);
+		},
+		async readFile(p) {
+			return readFile(p);
+		},
+		async statFile(p) {
+			return { size: (await stat(p)).size };
+		},
+		async removeFile(p) {
+			await rm(p, { force: true });
+		}
+	};
+}
+//#endregion
 //#region src/log/zstd-frames.ts
 const MAGIC = [
 	40,
@@ -1166,10 +1258,10 @@ function isRecord(value) {
 function numberOf(value) {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
 }
-/** `statFile` / `readFile` / `sizeOfDir` 里只有 ENOENT 能当"不在"；权限、盘挂、I/O 错误都必须露成读不出。 */
-function isMissing(error) {
-	return error?.code === "ENOENT";
-}
+/** 路径缺席的判据只有一处：`src/ports/fs-port.ts` 的 `isAbsentPath`（ENOENT / ENOTDIR）。
+*  `statFile` / `readFile` / `sizeOfDir` 的读错误里，"不在"只认这两枚；权限、盘挂、I/O 错误
+*  都必须露成读不出（ADR-0039），别在这里另写一份只有 ENOENT 的抄本。 */
+const isMissing = isAbsentPath;
 /** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
 function attachmentPathOf(home, kind, id) {
 	if (!isAttachmentId(id)) throw new Error(`附件 id 形状不对：${id}`);
@@ -1403,6 +1495,32 @@ async function collectRemainingImageRefs(deps, input) {
 	};
 }
 /**
+* 剩余引用扫描的 fail-closed 收口（独占计划 / 执行期复核 / 孤儿扫描三处共用同一形状）：扫描抛错或
+* 任一引用源读不出都回 `reason`，读得出才交引用集——「读不出」绝不折成「没有引用」（ADR-0020；
+* 缺席判据见 ADR-0039）。`reasonLabel` 只补"这次是为什么扫"的前半句，后半句是读数原文。
+*/
+async function remainingRefsFailClosed(deps, excludeDirs, reasonLabel) {
+	try {
+		const refs = await collectRemainingImageRefs(deps, {
+			sessionRoot: `${deps.home}/sessions`,
+			excludeDirs
+		});
+		if (refs.unreadable.length > 0) return {
+			ok: false,
+			reason: `${reasonLabel}：${refs.unreadable[0]}`
+		};
+		return {
+			ok: true,
+			refs
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `${reasonLabel}：${String(error)}`
+		};
+	}
+}
+/**
 * 独占计划：候选 = 本次被删会话日志里的图片 id；剩余引用 = 活动会话 + 全部未删 `session-trash`
 * 目录 + storages/cache。
 * 剩余引用源读不出 ⇒ 整体跳过；候选日志读不出 / 附件对象 stat 失败 ⇒ 只跳过那一部分，其余照常。
@@ -1425,24 +1543,13 @@ async function planImageAttachmentRemoval(deps, removedDirs) {
 		bytes: 0,
 		...skipReasons.length > 0 ? { skipped: skipReasons.join("；") } : {}
 	};
-	let remaining;
-	try {
-		remaining = await collectRemainingImageRefs(deps, {
-			sessionRoot: `${deps.home}/sessions`,
-			excludeDirs: removedDirs
-		});
-	} catch (error) {
-		return {
-			entries: [],
-			bytes: 0,
-			skipped: `读不到剩余引用源，无法证明独占：${String(error)}`
-		};
-	}
-	if (remaining.unreadable.length > 0) return {
+	const scanned = await remainingRefsFailClosed(deps, removedDirs, "读不到剩余引用源，无法证明独占");
+	if (!scanned.ok) return {
 		entries: [],
 		bytes: 0,
-		skipped: `读不到剩余引用源，无法证明独占：${remaining.unreadable[0]}`
+		skipped: scanned.reason
 	};
+	const remaining = scanned.refs;
 	const entries = [];
 	let bytes = 0;
 	let unreadableObjects = 0;
@@ -1469,6 +1576,31 @@ async function planImageAttachmentRemoval(deps, removedDirs) {
 	};
 }
 /**
+* 执行期复核：计划与真删对象之间隔着一整趟目录删除（秒级），这期间别的会话可能把同一张图
+* （内容寻址 ⇒ 同一个 sha256 id）再引用一次，或派生存储新写一条引用。计划是数据、会过期；
+* 删对象之前用同一套剩余引用扫描再判一次，**只删这一刻仍无引用的那些**（ADR-0041）。
+*
+* 调用时机：会话 / 回收站目录已经删掉之后、`executeImageAttachmentRemoval` 之前——那时被删的
+* 引用源已经不在了，扫到的就是真正的"剩余"。读不出照旧 fail closed：回空计划 + `skipped`，
+* 宁可留下孤儿也不删共享。空计划直接返回（不为零删付一次全 home 扫描）。
+*/
+async function recheckImageRemovalExclusivity(deps, plan) {
+	if (plan.entries.length === 0) return plan;
+	const scanned = await remainingRefsFailClosed(deps, [], "读不到剩余引用源，无法复核独占");
+	if (!scanned.ok) return {
+		entries: [],
+		bytes: 0,
+		skipped: plan.skipped === void 0 ? scanned.reason : `${plan.skipped}；${scanned.reason}`
+	};
+	const remaining = scanned.refs;
+	const entries = plan.entries.filter((entry) => !remaining.ids.has(entry.id));
+	return {
+		entries,
+		bytes: entries.reduce((total, entry) => total + entry.bytes, 0),
+		...plan.skipped === void 0 ? {} : { skipped: plan.skipped }
+	};
+}
+/**
 * 逐文件删；ENOENT 由端口的 `force` 吞掉；其他错误计数并继续。
 *
 * 删除动作只认「`home` + `id` 自己推导出来的那一条路径」：计划是数据，手搭的/被改过的条目
@@ -1521,24 +1653,13 @@ const OBJECT_NAME = /^[0-9a-f]{64}$/u;
 * 对象列表或 stat 读不出同样整份跳过：报告宁可失败，也不给一份"少算了一些"的清理计划。
 */
 async function scanOrphanImageAttachments(deps) {
-	let remaining;
-	try {
-		remaining = await collectRemainingImageRefs(deps, {
-			sessionRoot: `${deps.home}/sessions`,
-			excludeDirs: []
-		});
-	} catch (error) {
-		return {
-			entries: [],
-			bytes: 0,
-			skipped: `读不到引用源，无法判定孤儿附件：${String(error)}`
-		};
-	}
-	if (remaining.unreadable.length > 0) return {
+	const scanned = await remainingRefsFailClosed(deps, [], "读不到引用源，无法判定孤儿附件");
+	if (!scanned.ok) return {
 		entries: [],
 		bytes: 0,
-		skipped: `读不到引用源，无法判定孤儿附件：${remaining.unreadable[0]}`
+		skipped: scanned.reason
 	};
+	const remaining = scanned.refs;
 	const objectsRoot = `${deps.home}/attachments/v1/objects`;
 	const entries = [];
 	let bytes = 0;
@@ -1597,9 +1718,9 @@ async function cleanOrphanImageAttachments(deps) {
 * purge / orphan-clean 的删除计划（{@link planMemberRemovals}）才付——executor 摘账本要用它。
 */
 /** `exists → sizeOfDir` 的唯一一条度量口径（成员目录与回收站目录共用）：先问在不在，再量字节；
-*  ENOENT 是唯一一种当"不在"的失败，别的错误照旧响亮。别再在调用点各写一遍这段 try/catch。
+*  缺席（ENOENT / ENOTDIR）才是"不在"，别的错误照旧响亮（ADR-0039）。别再在调用点各写一遍这段 try/catch。
 *
-*  **已知粒度**：`sizeOfDir` 递归里撞到的 ENOENT 与"目录本身没了"是同一个码，所以目录里某个文件
+*  **已知粒度**：`sizeOfDir` 递归里撞到的缺席与"目录本身没了"是同一个码，所以目录里某个文件
 *  恰好在这一拍消失时，整条目录会被记成「不在」（`/list` 少算这条、删除计划里没有可删的字节，
 *  而清册行照旧摘——盘上留下目录等下一次 `reconcile` 重建成行，自愈、不丢数据）。复核一次
 *  `exists(dir)` 能把两者分开，却会让「宿主正在写、文件刚被挪走」这类正常竞态把 `/list` 整个打红——
@@ -1811,15 +1932,20 @@ async function planOrphanRemoval(deps, members) {
 *
 * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
 * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
-* 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
-*
-* 附件清理排在**所有会话目录删完之后**：对象只在会话真的没了之后才动；单文件失败只进
-* `attachments.failed`，不影响（也不回滚）会话删除的回执。
+* 目录删掉就没有"退回去"这回事，中途失败**不回滚目录**；已经删掉的由下面的计数器如实交回。
+* **归档态回滚**：`unarchive` 排在所有删除之前（免得留下"会话没了、归档集还挂着"的幽灵 id），
+* 所以中途失败时目录还在、归档位却已经摘了。失败出口把**目录还在**的那些（这一趟没删掉、也不是计划时
+* 就缺席）按删除前的读数重新归档（`isArchived` 先读过一次，不是按 `wasArchived` 猜）；目录不在的跳过
+* ——那时恢复归档只会造幽灵 id。
+* 回滚自己的失败走 `details.rollbackFailures`，不让它把原错误吞掉（ADR-0040）。
+* **附件计划在执行期复核**：计划到删对象之间的窗口里新增的引用会让计划过期；删对象前用同一套
+* 剩余引用扫描重判一次，只删这一刻仍无引用的对象（ADR-0041）。
 *
 * 失败形状：
 * - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
 * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details；
-* - orphan-clean 的 unarchive / detach 原样抛出。
+* - orphan-clean 的归档实况预读 / unarchive / detach 原样抛出；
+* - 归档态回滚不干净时，原错误带 `details.rollbackFailures`（码仍按原错误的动词码）。
 *
 * 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
 */
@@ -1841,7 +1967,7 @@ async function executeRemoval(deps, plan) {
 		} : void 0;
 		throw verbError("io", `${label}：${String(error)}`, error, details);
 	};
-	/** 退归档集 / 摘账本这一步的失败形状：purge 折成带标签的 `io`；orphan-clean 原样抛。 */
+	/** 归档实况预读 / 退归档集 / 摘账本这一步的失败形状：purge 折成带标签的 `io`；orphan-clean 原样抛。 */
 	const step = async (label, sessionId, run) => {
 		if (plan.kind === "orphan") {
 			await run();
@@ -1853,49 +1979,79 @@ async function executeRemoval(deps, plan) {
 			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) {
+	const archivedBefore = /* @__PURE__ */ new Set();
+	for (const sessionId of plan.unarchive) await step("读取归档状态失败", sessionId, async () => {
+		if (await deps.host.isArchived(sessionId)) archivedBefore.add(sessionId);
+	});
+	/** 走到过 `unarchive` 这一步的 id（含失败那一条）：失败时按它回滚。 */
+	const unarchived = [];
+	/** 计划时目录还在的 id：只有这些会话还有本体可挂归档。计划时就缺席的行 / 成员也在 `unarchive`
+	*  名单里（那一步顺带清幽灵 id），但没有目录可回滚。 */
+	const onDisk = /* @__PURE__ */ new Set([...plan.trash.filter((row) => row.present).map((row) => row.entry.sessionId), ...plan.members.map((member) => member.sessionId)]);
+	/** 目录已经真删掉的 id：没有归档态可放回去，跳过——否则会在 registry 里留下幽灵 id。 */
+	const deleted = /* @__PURE__ */ new Set();
+	try {
+		for (const sessionId of plan.unarchive) {
+			unarchived.push(sessionId);
+			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);
+				}
+				deleted.add(row.entry.sessionId);
+				freedSoFar += row.bytes;
+			}
 			try {
-				await deps.fs.removeDir(row.dir);
+				await deps.ledger.remove(row.entry.id);
 			} catch (error) {
-				fail("删除回收站目录失败", error, row.entry.sessionId);
+				fail("摘除回收站条目失败", error, row.entry.sessionId);
 			}
-			freedSoFar += row.bytes;
+			removed += 1;
+			await presence.memberGone(row.entry.sessionId);
 		}
-		try {
-			await deps.ledger.remove(row.entry.id);
-		} catch (error) {
-			fail("摘除回收站条目失败", error, 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);
+			}
+			deleted.add(member.sessionId);
+			removed += 1;
+			freedSoFar += member.bytes;
+			await presence.memberGone(member.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);
+		const attachmentPlan = await recheckImageRemovalExclusivity(deps, plan.attachments);
+		const attachments = await executeImageAttachmentRemoval(deps, attachmentPlan);
+		return {
+			removed,
+			freedBytes: plan.bytes,
+			attachments: {
+				...attachments,
+				...attachmentPlan.skipped === void 0 ? {} : { skipped: attachmentPlan.skipped }
+			}
+		};
+	} catch (error) {
+		const rollbackFailures = [];
+		for (const sessionId of [...unarchived].reverse()) {
+			if (!archivedBefore.has(sessionId) || deleted.has(sessionId) || !onDisk.has(sessionId)) continue;
+			try {
+				await deps.host.archive(sessionId);
+			} catch (rollbackError) {
+				rollbackFailures.push(rollbackReason("恢复归档失败", rollbackError));
+			}
 		}
-		removed += 1;
-		freedSoFar += member.bytes;
-		await presence.memberGone(member.sessionId);
+		throw rollbackFailures.length === 0 ? error : withRollbackFailures(error, rollbackFailures);
 	}
-	const attachments = await executeImageAttachmentRemoval(deps, plan.attachments);
-	return {
-		removed,
-		freedBytes: plan.bytes,
-		attachments: {
-			...attachments,
-			...plan.attachments.skipped === void 0 ? {} : { skipped: plan.attachments.skipped }
-		}
-	};
 }
 //#endregion
 //#region src/verbs/orphan-subagents.ts
@@ -2079,6 +2235,21 @@ function liveSessionsOf(ctx) {
 	if (typeof store.get !== "function" || typeof store.liveEntryFor !== "function") return void 0;
 	return store;
 }
+/**
+* 会话 header 的**公开**读面：live `sessions.get(id).header` 优先（保留宿主原来的优先级），
+* 否则 `sessionPersistence.stat(id).header`。未知会话回 `undefined`；需要落到持久化时服务缺席 /
+* 形状不符抛错，由调用方决定是响亮失败（projectDirOf）还是降级（titleOf 的空串）。
+*/
+async function headerOf(host, sessionId) {
+	const store = liveSessionsOf(host);
+	if (store !== void 0) try {
+		const live = store.get(sessionId);
+		if (live?.header !== void 0) return live.header;
+	} catch {}
+	const persistence = host.get("sessionPersistence");
+	if (persistence === void 0 || persistence === null || typeof persistence.stat !== "function") throw new Error("session-delete: sessionPersistence 服务缺席");
+	return (await persistence.stat(sessionId))?.header;
+}
 /** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。
 *  它只按 `parentSession` 原样匹配，**不是**子会话分类器：旧宿主（≤0.2.1-rc.5）的普通 fork 也写
 *  `parentSession`，0.2.2-alpha.2 起才不写。子会话的判据是 `origin` 的 subagent 标记（宿主归档闸、归档
@@ -2174,15 +2345,6 @@ function projectionCacheOf(ctx) {
 	if (typeof cache.cachedSnapshot !== "function" || typeof cache.cachedPredecessorTitle !== "function") return void 0;
 	return cache;
 }
-/** 宿主 `readSessionHeader` 对未知会话抛的是裸 `Error`，只认这句；真存储故障照抛，不能折成未命中。
-*  出处：asar `dsh-workspace/lib/types/index.js` 的
-*  `cannot validate session '${id}': session persistence holds no such session`。
-*  同文件有类型的近似句是 `WorkspaceUnknownSessionError`（`hold` 无 `s`），不会误伤。 */
-const NO_SUCH_SESSION = "session persistence holds no such session";
-/** 只认上面那一句；其余（含非 Error 抛出物）一律**不算未命中**。 */
-function isUnknownSession(error) {
-	return error instanceof Error && error.message.includes(NO_SUCH_SESSION);
-}
 /** 宿主会话表的一次取数（`ctx.sessionController.list()` 的两种返回形状都折成数组）。
 *  服务没挂 / 形状不对 / 抛错 ⇒ 空表——**这条不替宿主兜错误**：调用方拿空表的语义都是"少发一条通告"，
 *  不是"恢复失败"。 */
@@ -2223,23 +2385,20 @@ function createHostPort(ctx) {
 		},
 		/**
 		* cwd → 宿主项目目录名；没有 cwd 落到 `_no-cwd`。
-		* 账本里没有这个会话回 `undefined`（未命中，不是故障）；真存储故障照抛。
+		* header 走公开面（live `sessions` → `sessionPersistence.stat`）；未知会话回 `undefined`
+		* （未命中，不是故障）；服务缺席/真存储故障照抛。
 		* 未命中由 `delete-session.ts` 折成 `not-found`，真故障留 `io`——两者不能混。
 		*/
 		async projectDirOf(sessionId) {
-			let header;
-			try {
-				header = await registry.readSessionHeader(sessionId);
-			} catch (error) {
-				if (isUnknownSession(error)) return void 0;
-				throw error;
-			}
+			const header = await headerOf(host, sessionId);
+			if (header === void 0) return void 0;
 			return header.cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(header.cwd);
 		},
-		/** 标题走宿主投影缓存；尽力取，取不到返回空串，绝不因此让删除失败。 */
+		/** 标题走宿主投影缓存；header 来自公开的 live/持久化读面，尽力取，取不到返回空串。 */
 		async titleOf(sessionId) {
 			try {
-				const header = await registry.readSessionHeader(sessionId);
+				const header = await headerOf(host, sessionId);
+				if (header === void 0) return "";
 				const cache = projectionCacheOf(host);
 				const title = (cache?.cachedSnapshot(header, ["title"]) ?? cache?.cachedPredecessorTitle(header))?.values.title;
 				return typeof title === "string" ? title : "";
@@ -3797,7 +3956,10 @@ function toResponse(result) {
 	});
 	return new Response(JSON.stringify(result.body), {
 		status: result.status,
-		headers: { "content-type": "application/json; charset=utf-8" }
+		headers: {
+			"content-type": "application/json; charset=utf-8",
+			"cache-control": "private, no-store"
+		}
 	});
 }
 /**
@@ -3903,73 +4065,6 @@ const Config = { "~standard": {
 	}
 } };
 //#endregion
-//#region src/ports/fs-port.ts
-/** 模块级递归：端口方法**解构出来单独调**也不能靠 `this`（`{ sizeOfDir } = port` 会让方法体的
-*  `this` 变成 undefined）。所以端口只做转发，递归在模块作用域里自调。 */
-async function sizeOfDir(p) {
-	let total = 0;
-	for (const e of await readdir(p, { withFileTypes: true })) {
-		const child = join(p, e.name);
-		total += e.isDirectory() ? await sizeOfDir(child) : (await stat(child)).size;
-	}
-	return total;
-}
-function createFsPort() {
-	return {
-		async exists(p) {
-			return existsSync(p);
-		},
-		async ensureDir(p) {
-			await mkdir(p, { recursive: true });
-		},
-		async rename(from, to) {
-			if (existsSync(to)) throw new Error(`目标已存在，拒绝覆盖：${to}`);
-			try {
-				await rename(from, to);
-			} catch (error) {
-				if (error.code === "EXDEV") throw new Error(`跨文件系统搬不动（sessions 与 session-trash 需在同一卷）：${from} → ${to}`, { cause: error });
-				throw error;
-			}
-		},
-		async removeDir(p) {
-			await rm(p, {
-				recursive: true,
-				force: true
-			});
-		},
-		sizeOfDir: (p) => sizeOfDir(p),
-		async listFiles(p) {
-			return readdir(p);
-		},
-		async listDirs(p) {
-			const dirs = [];
-			for (const entry of await readdir(p, { withFileTypes: true })) {
-				if (entry.isDirectory()) {
-					dirs.push(entry.name);
-					continue;
-				}
-				if (!entry.isSymbolicLink()) continue;
-				try {
-					if ((await stat(join(p, entry.name))).isDirectory()) dirs.push(entry.name);
-				} catch {}
-			}
-			return dirs;
-		},
-		async realpath(p) {
-			return realpath(p);
-		},
-		async readFile(p) {
-			return readFile(p);
-		},
-		async statFile(p) {
-			return { size: (await stat(p)).size };
-		},
-		async removeFile(p) {
-			await rm(p, { force: true });
-		}
-	};
-}
-//#endregion
 //#region src/ports/home.ts
 /**
 * 宿主数据根。官方解析器在 asar `dsh/node_modules/@deepseek-ai/dsh-home-paths/lib/index.js`：
@@ -4227,10 +4322,11 @@ const name = "@xrn1997/dsh-session-delete";
 * 三项都是在隔离数据根上实测注入成功、且本插件真正用到的宿主服务。**不进 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` 返回空串，正是契约允许的降级。
+* - `sessions` / `sessionProjectionCache` / `sessionPersistence`：都按 `ctx.get(...)` **可选读**——
+*   `sessions` 给 `evictLive` 和 live header 用（活跃判据走 waterfall，见 src/ports/host-port.ts；
+*   服务缺席回 `unknown`），`sessionProjectionCache` 是标题的投影读面，`sessionPersistence` 是
+*   `projectDirOf` / `titleOf` 的公开 header 读面（workspaceRegistry 硬注入它，标准组合必有）。
+*   inject 一个可能没挂的服务 = 整个插件 pending；标题取不到时 `titleOf` 返回空串，正是契约允许的降级。
 * - `agents`：只给 handle 捕获用（`ctx.get('agents')`；缺席时 `ctx.inject(['agents'])` 等服务就绪再装）。
 *   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
 *

package/lib/types/client/api-base.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 取数路径的挂载点：官方 `/api` 前缀 + **当前文档所在的目录**。
+ *
+ * 为什么不能写死根绝对路径：宿主自己的客户端模块按「app-directory-relative form」下发 bundle 与
+ * chunk 描述符，浏览器在**自己的挂载点**下解析（`dsh-client-modules` README 原文：*"which a browser
+ * document resolves under its own mount"*）；同一个部署可以被反代到 `/dsh/`，此时 `/api/...` 会打到
+ * 反代根、而不是宿主。路由注册侧仍然必须写 `/api/...`（宿主 `connection.fetch.register` 用
+ * `endpointFromPath('/api', path)` 校验），所以本文件只给**浏览器半**投影一层挂载点前缀。
+ *
+ * 根部署（`http://host/`）下 `mountPathOf` 返回空串，拼出来的 URL 与旧版逐字相同；只有挂载部署才
+ * 多出 `/dsh` 这一段。目录取自 `new URL('.', baseURI)`：页面是 `/dsh/`、`/dsh/index.html` 都归到
+ * `/dsh/`；`about:blank` 这类不透明 base 退回根路径（此时相对地址本来也无法成立）。
+ */
+/** `baseURI` 所在目录的路径，去掉尾斜杠；根路径回空串。 */
+export declare function mountPathOf(baseURI: string): string;
+/** 一段相对段名 → 宿主 `/api` 前缀 + 挂载点。`path` 以 `/` 开头，与 `ROUTES` 的形状一致。 */
+export declare function apiPathOf(path: string, baseURI: string): string;
+/** 当前文档的取数路径；Node 侧（无 `document`）退回根路径。 */
+export declare function apiPath(path: string): string;

package/lib/types/client/context-menu-actions.d.ts

@@ -0,0 +1,47 @@
+import type { Translate } from './copy.js';
+interface MenuTarget {
+    readonly sessionId: string;
+    readonly displayTitle: string;
+}
+export interface MenuActionLike {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    icon?: {
+        key: string;
+    };
+    danger?: boolean;
+    separatorBefore?: boolean;
+    afterContent?: boolean;
+    run: () => void | Promise<void>;
+}
+export interface ObservableSnapshotLike<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+interface SessionsStateLike {
+    byId?: Record<string, {
+        running?: boolean;
+    } | undefined>;
+}
+export interface SessionsServiceLike {
+    list?: ObservableSnapshotLike<SessionsStateLike>;
+}
+export interface MenuContributionLike {
+    id: string;
+    target: 'session';
+    order: number;
+    observe?: (target: MenuTarget) => readonly ObservableSnapshotLike<unknown>[];
+    resolve: (target: MenuTarget) => readonly MenuActionLike[] | Promise<readonly MenuActionLike[]>;
+}
+export interface ContextMenusLike {
+    register(contribution: MenuContributionLike): () => void;
+}
+export declare const ICON_BATCH = "xrn1997.session-delete.batch-select";
+export declare const ICON_DELETE = "xrn1997.session-delete.delete";
+/**
+ * 造 0.2.2+ 的会话菜单贡献。order 700 落在内置 Archive(600) 之后；两行都是 `afterContent`，
+ * 所以它们与 Archive 一起排掉 legacy 组件行，恢复「归档在多选/删除之前」。
+ */
+export declare function createSessionMenuContribution(t: Translate, sessionList?: ObservableSnapshotLike<SessionsStateLike>): MenuContributionLike;
+export {};