@xrn1997/dsh-session-delete 0.5.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
 /**
@@ -12,13 +11,18 @@ import { homedir } from "node:os";
 * 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
 */
 /**
-* 插件专属前缀。
+* 插件专属前缀（九段相对它命名）。
 *
-* 为什么必须带插件名：宿主 web server 的 `register({kind:'prefix', path})` 对**重复的 (kind, path)
-* 直接抛错**（`dsh-host-webserver` 原文 `webserver: duplicate ${route.kind} route "${route.path}"`），
-* 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
+* 为什么必须带插件名：宿主 `connection.fetch.register` 对**重复的精确路径**直接抛错
+* （`connection: exact Fetch route "…" is already registered`），撞了就是整棵插件树 boot 失败——
+* 所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
+/**
+* 唯一的取数基础路径：宿主 `/api` + 插件前缀。九段 exact Fetch 路由、客户端探测与附件 URL
+* 都从它起；`SESSION_DELETE_API_PREFIX` 只作为段名的相对前缀与错误原文。
+*/
+const OFFICIAL_SESSION_DELETE_API_PREFIX = `/api${SESSION_DELETE_API_PREFIX}`;
 /** 九个段名（相对前缀）。**每项 `{ path, method }` 两键**：某段用什么方法也是线上形状的一部分
 *  （ADR-0003），家就在这一张表——路由记录（`src/api/route-table.ts`）逐行投影（`ROUTES.x.method`），
 *  浏览器半的 GET 段同样投影、写段把 `ROUTES.x.method` 交给 `src/client/remote.ts` 的 `post()`，
@@ -91,7 +95,14 @@ const PARAMS = {
 	ids: "ids",
 	attachmentId: "id",
 	attachmentKind: "kind",
-	attachmentName: "name"
+	attachmentName: "name",
+	/** 图片引用的媒体类型 / 宽高：只给宿主 `attachments.readImage` 做引用校验，不参与路径拼接。 */
+	attachmentMediaType: "mediaType",
+	/** 字节数：图片支与文件支都带——它是宿主读面的引用一部分，并先过 `maxAttachmentBytes` 闸
+	*  （别为一张已知超限的图让宿主整份读出来）。 */
+	attachmentBytes: "bytes",
+	attachmentWidth: "width",
+	attachmentHeight: "height"
 };
 /**
 * 进程内判别「这已经是一次失败」——**按标记位认，不按 `instanceof`**（跨 realm / 跨 bundle 都不成立）。
@@ -146,6 +157,57 @@ function verbCodeOf(error) {
 /** 回收站目录名（相对宿主数据根）。Node 半拼路径，浏览器半在页脚念它——同一个字面量。 */
 const TRASH_DIR_NAME = "session-trash";
 //#endregion
+//#region src/verbs/errors.ts
+/** 失败的**结构与措辞**。码本身、码的前缀读法与动词词表都住在 `shared/wire.ts`（ADR-0003）：
+*  浏览器半也要认它们，它们属于两半共同的契约，不属于 Node 半。这里只做动词抛错与回滚措辞。 */
+function verbError(code, message, cause, details) {
+	const e = new Error(message);
+	e.code = SESSION_DELETE_CODES[code];
+	if (cause !== void 0) e.cause = cause;
+	if (details !== void 0) e.details = details;
+	return e;
+}
+/** `trash-empty` 的原文：有具体条目就点名那个 id，拿不到时只报通用那句。 */
+function trashEmpty(entryId) {
+	return verbError("trash-empty", entryId === void 0 ? "回收站里没有这一条" : `回收站里没有这一条：${entryId}`);
+}
+/** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
+function routeError(code, httpStatus, message) {
+	const e = verbError("io", message);
+	e.code = SESSION_DELETE_CODES[code];
+	e.httpStatus = httpStatus;
+	return e;
+}
+/** 一条回滚步骤失败的**标签句**：label 说的是"这一步在退什么"，原文带出**那一步抛的东西**
+*  （`Error` 取 message，其余一律 `String()`；对象带 `message` 的差异归 `map-error.messageOf` 管）。
+*  调用方不许另抄这份格式——那样 details 里的句子会随各处 catch 变形，界面上就变成"同一个失败三个说法"。 */
+function rollbackReason(label, error) {
+	return `${label}：${error instanceof Error ? error.message : String(error)}`;
+}
+/** 内层错误已经挂着的回滚失败（成员自己的就地回滚失败时会有）。组级 catch 再包一次时不能丢。 */
+function carriedRollbackFailures(error) {
+	const raw = error?.details?.rollbackFailures;
+	return Array.isArray(raw) ? raw.filter((item) => typeof item === "string") : [];
+}
+/** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
+*  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
+*  两份失败都得在 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));
+	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
 /** 宿主两条类型化错误 → 我们的码（本文件的两行映射）。
 *  类不可 import（跨插件值 import 是红线；且宿主包与运行中的宿主不同代）⇒ 按官方构造器写死的 `this.name` 认。
@@ -266,134 +328,6 @@ function toRemoteFailure(error) {
 	};
 }
 //#endregion
-//#region src/verbs/errors.ts
-/** 失败的**结构与措辞**。码本身、码的前缀读法与动词词表都住在 `shared/wire.ts`（ADR-0003）：
-*  浏览器半也要认它们，它们属于两半共同的契约，不属于 Node 半。这里只做动词抛错与回滚措辞。 */
-function verbError(code, message, cause, details) {
-	const e = new Error(message);
-	e.code = SESSION_DELETE_CODES[code];
-	if (cause !== void 0) e.cause = cause;
-	if (details !== void 0) e.details = details;
-	return e;
-}
-/** `trash-empty` 的原文：有具体条目就点名那个 id，拿不到时只报通用那句。 */
-function trashEmpty(entryId) {
-	return verbError("trash-empty", entryId === void 0 ? "回收站里没有这一条" : `回收站里没有这一条：${entryId}`);
-}
-/** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
-function routeError(code, httpStatus, message) {
-	const e = verbError("io", message);
-	e.code = SESSION_DELETE_CODES[code];
-	e.httpStatus = httpStatus;
-	return e;
-}
-/** 一条回滚步骤失败的**标签句**：label 说的是"这一步在退什么"，原文带出**那一步抛的东西**
-*  （`Error` 取 message，其余一律 `String()`；对象带 `message` 的差异归 `map-error.messageOf` 管）。
-*  调用方不许另抄这份格式——那样 details 里的句子会随各处 catch 变形，界面上就变成"同一个失败三个说法"。 */
-function rollbackReason(label, error) {
-	return `${label}：${error instanceof Error ? error.message : String(error)}`;
-}
-/** 内层错误已经挂着的回滚失败（成员自己的就地回滚失败时会有）。组级 catch 再包一次时不能丢。 */
-function carriedRollbackFailures(error) {
-	const raw = error?.details?.rollbackFailures;
-	return Array.isArray(raw) ? raw.filter((item) => typeof item === "string") : [];
-}
-/** 原错误保留，回滚失败作为 `details.rollbackFailures` 上线；码仍按原错误的动词码，
-*  没有可继承的就落 io。**内层的回滚失败要并进来**：一个成员自己退失败、兄弟也退失败时，
-*  两份失败都得在 details 里，消息也不能出现第二个「回滚未完成」。 */
-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 });
-}
-//#endregion
-//#region src/api/request-trust.ts
-/** 桌面壳那条路（asar `/lib/main.js` 的 `forwardWebRequest`）：渲染进程从 `dsh-app://app/` 加载，
-*  转发前把 `host` / `origin` / `cookie` / `sec-fetch-site` 删掉、换上一枚宿主自己的 cookie，
-*  `Referer` 保留。判据按 `protocol` + `host` 比，**不能比 `URL.origin`**（`dsh-app:` 不是 WHATWG
-*  special scheme，`new URL('dsh-app://app/').origin` 是字符串 `"null"`）。 */
-const DESKTOP_APP_SCHEME = "dsh-app:";
-const DESKTOP_APP_HOST = "app";
-/** 回环 socket 的三种写法（IPv4 / IPv6 / IPv4-mapped IPv6）。 */
-const LOOPBACK_SOCKETS = [
-	"127.0.0.1",
-	"::1",
-	"::ffff:127.0.0.1"
-];
-function isDesktopShellUrl(value) {
-	try {
-		const url = new URL(value);
-		return url.protocol === DESKTOP_APP_SCHEME && url.host === DESKTOP_APP_HOST;
-	} catch {
-		return false;
-	}
-}
-/** 裸 authority（`host` / `host:port`）按给定 scheme 解析；解析不了回 `undefined`。 */
-function parseAuthority(authority, scheme = "http:") {
-	try {
-		return new URL(`${scheme}//${authority}`);
-	} catch {
-		return;
-	}
-}
-/** 与宿主 `isLoopbackHostname` 同口径：`localhost`、`[::1]`、任意 127/8。 */
-function isLoopbackHostname(hostname) {
-	if (hostname === "localhost" || hostname === "[::1]") return true;
-	const parts = hostname.split(".");
-	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
-}
-/** Host 是不是本部署的 bind 字面量：忽略端口与 `%zone`（zone 是接口选择器，不是地址文本）。 */
-function isBindAddress(hostUrl, bindHost) {
-	if (bindHost === void 0) return false;
-	const zoneAt = bindHost.indexOf("%");
-	const address = zoneAt === -1 ? bindHost : bindHost.slice(0, zoneAt);
-	const bindUrl = parseAuthority(address.includes(":") ? `[${address}]` : address);
-	return bindUrl !== void 0 && bindUrl.hostname === hostUrl.hostname;
-}
-/** 携带 authority 的头（Origin / Referer）是否与 Host 同 authority：按这个头自己的 scheme 归一
-*  默认端口（`http://x:80` 与 Host `x` 是同一个 authority）。 */
-function isSameAuthority(value, hostHeader) {
-	let url;
-	try {
-		url = new URL(value);
-	} catch {
-		return false;
-	}
-	const scheme = url.protocol === "https:" ? "https:" : url.protocol === "http:" ? "http:" : void 0;
-	if (scheme === void 0) return false;
-	const hostUrl = parseAuthority(hostHeader, scheme);
-	return hostUrl !== void 0 && url.host === hostUrl.host;
-}
-/** 头栅栏：`sec-fetch-site` / Origin / Referer 三条，任何客户端都要过。 */
-function passesHeaderFence(headers, host) {
-	if (headers["sec-fetch-site"] === "cross-site") return false;
-	const origin = headers.origin;
-	if (origin !== void 0 && !isDesktopShellUrl(origin) && !isSameAuthority(origin, host)) return false;
-	const referer = headers.referer;
-	if (referer !== void 0 && !isDesktopShellUrl(referer) && !isSameAuthority(referer, host)) return false;
-	return true;
-}
-/**
-* 这条请求归不归本插件办。`untrusted` = 归属不对（跨源 / 重绑 / 头不成形）；`unauthenticated` =
-* 归属对但远程客户端没带宿主身份（原文会提示用 `dsh web` 打印的 URL 打开）。
-*
-* 远程支的两个失败裁决由端口翻译宿主的区分（401 = 缺身份、403 = 归属不对）。身份层缺席（端口报
-* `absent`）一律按归属不对处理：那时没有可换的身份，不能让原文提示用户去补一个不存在的东西。
-*/
-function judgeRequest(req, facts) {
-	const host = req.headers.host;
-	if (host === void 0 || !passesHeaderFence(req.headers, host)) return "untrusted";
-	const hostUrl = parseAuthority(host);
-	if (hostUrl === void 0) return "untrusted";
-	if ((isLoopbackHostname(hostUrl.hostname) || isBindAddress(hostUrl, facts.bindHost)) && LOOPBACK_SOCKETS.includes(req.socket.remoteAddress ?? "")) return "allowed";
-	const verdict = facts.connection.verdictFor(req);
-	if (verdict.kind === "allowed") return "allowed";
-	return verdict.kind === "unauthenticated" ? "unauthenticated" : "untrusted";
-}
-//#endregion
 //#region src/domain/closure.ts
 /** 会话 id 去掉 `session-` 前缀后的形状：同一个会话在两代宿主里写法不同（v3 代 id 不带前缀、
 *  现行代带），归堆、成组、去重一律按这个形状比——两边都归一，不赌调用方传的是哪一代写法。 */
@@ -452,6 +386,9 @@ function firstByBare(members) {
 * 已被前一组收走的那条，连同它整支子树都不再出现在这一组里——后代在那一组已被全部认领，所以
 * 「丢掉已认领的」与「不走进已认领的那支」交回的是同一个集合。环上的代价是「少数一条」，
 * 不是把一次扫描挂死。组序与成员序都按语料原序。
+*
+* 后代也必须是 subagent 起源：普通 fork 的 `parentSession` 只是来源记录，它不进组、也不穿过它收孩子
+* （否则从 subagent 分出去的分支会被当成孤儿永久删掉）。
 */
 function orphanRootsOf(corpus, known) {
 	const knownBares = /* @__PURE__ */ new Set();
@@ -460,6 +397,7 @@ function orphanRootsOf(corpus, known) {
 	for (const session of corpus) {
 		const parent = session.parentSessionId;
 		if (parent === void 0) continue;
+		if (!session.subagent) continue;
 		const key = bareSessionId(parent);
 		const list = children.get(key);
 		if (list === void 0) children.set(key, [session]);
@@ -990,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,
@@ -1234,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}`);
@@ -1415,8 +1439,6 @@ async function imageIdsOfDir(deps, dir) {
 		};
 	}
 }
-/** 单个 JSON 引用源的扫描上限；超过就记成不可读（fail closed），**不许当作"没有引用"跳过**。 */
-const MAX_JSON_REF_BYTES = 10485760;
 /** 读全部剩余引用源；任何一处读不出都记进 `unreadable`。 */
 async function collectRemainingImageRefs(deps, input) {
 	const exclude = new Set(input.excludeDirs);
@@ -1439,6 +1461,7 @@ async function collectRemainingImageRefs(deps, input) {
 	if (await deps.fs.exists(trashRoot)) for (const name of await deps.fs.listDirs(trashRoot)) await visit(`${trashRoot}/${name}`);
 	const scanJson = async (root) => {
 		if (!await deps.fs.exists(root)) return;
+		const maxJsonRefBytes = deps.config.maxJsonRefBytes;
 		const stack = [root];
 		const seen = /* @__PURE__ */ new Set();
 		while (stack.length > 0) {
@@ -1452,8 +1475,8 @@ async function collectRemainingImageRefs(deps, input) {
 					if (!name.endsWith(".json")) continue;
 					const file = `${dir}/${name}`;
 					const stat = await deps.fs.statFile(file);
-					if (stat.size > MAX_JSON_REF_BYTES) {
-						unreadable.push(`${file}: JSON 引用源 ${stat.size} 字节超过扫描上限 ${MAX_JSON_REF_BYTES} 字节，未扫描`);
+					if (stat.size > maxJsonRefBytes) {
+						unreadable.push(`${file}: JSON 引用源 ${stat.size} 字节超过扫描上限 ${maxJsonRefBytes} 字节，未扫描`);
 						continue;
 					}
 					const text = (await deps.fs.readFile(file)).toString("utf8");
@@ -1472,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 失败 ⇒ 只跳过那一部分，其余照常。
@@ -1494,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;
@@ -1538,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` 自己推导出来的那一条路径」：计划是数据，手搭的/被改过的条目
@@ -1590,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;
@@ -1666,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` 整个打红——
@@ -1880,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`），不在这里另写一份。
 */
@@ -1910,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();
@@ -1922,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
@@ -1975,8 +2062,9 @@ async function executeRemoval(deps, plan) {
 * 彻底删除（组语义见 `src/trash/groups.ts`），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
 * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
 *
-* 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
-* `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限），同一条记录只归一组
+* 根按**传递闭包**收全部 subagent 后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
+* `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限；普通 fork 不是成员、
+* 也不穿过它收后代），同一条记录只归一组
 * （`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
 * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
 */
@@ -2147,7 +2235,25 @@ function liveSessionsOf(ctx) {
 	if (typeof store.get !== "function" || typeof store.liveEntryFor !== "function") return void 0;
 	return store;
 }
-/** 官方的「这些父的孩子」那一支：`kind:'parent'` 的判据逐字是 `values.includes(record.header.parentSession ?? null)`。 */
+/**
+* 会话 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 标记（宿主归档闸、归档
+*  准入、持久化找子日志三处一致），所以调用方必须再按 origin 筛一遍。 */
 async function filterChildrenOf(sessionQuery, values) {
 	return sessionQuery.filterSessions([{
 		kind: "parent",
@@ -2174,10 +2280,11 @@ async function descendantsByParent(sessionQuery, roots) {
 			const parent = record.header?.parentSession;
 			if (typeof id !== "string" || id.length === 0) continue;
 			if (typeof parent !== "string" || parent.length === 0) continue;
+			if (record.header?.origin !== "subagent") continue;
 			const bare = bareSessionId(id);
 			if (seen.has(bare)) continue;
 			seen.add(bare);
-			const cwd = record.header?.cwd;
+			const cwd = record.header.cwd;
 			const descendant = {
 				sessionId: id,
 				projectDir: cwd === void 0 ? NO_CWD_PROJECT_DIR : projectKey(cwd)
@@ -2238,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()` 的两种返回形状都折成数组）。
 *  服务没挂 / 形状不对 / 抛错 ⇒ 空表——**这条不替宿主兜错误**：调用方拿空表的语义都是"少发一条通告"，
 *  不是"恢复失败"。 */
@@ -2287,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 : "";
@@ -3138,8 +3233,42 @@ function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
 	};
 }
 //#endregion
+//#region src/ports/attachments-port.ts
+/** 服务在 `available()` 之后消失/形状变了：调用方可以退回直接 fs，而不是把这次读取判成 io。 */
+var AttachmentsUnavailableError = class extends Error {
+	constructor(message = "attachments service absent") {
+		super(message);
+		this.name = "AttachmentsUnavailableError";
+	}
+};
+/** 每次调用惰性解析服务：插件与 `attachments` 的激活顺序没有承诺。 */
+function createAttachmentsPort(ctx) {
+	const serviceOf = () => {
+		try {
+			const service = ctx.get("attachments");
+			if (service === void 0 || service === null) return void 0;
+			if (typeof service.readImage !== "function" || typeof service.readFileStream !== "function") return void 0;
+			return service;
+		} catch {
+			return;
+		}
+	};
+	return {
+		available: () => serviceOf() !== void 0,
+		async readImage(ref) {
+			const service = serviceOf();
+			if (service === void 0) throw new AttachmentsUnavailableError();
+			return await service.readImage(ref);
+		},
+		async *readFileStream(ref) {
+			const service = serviceOf();
+			if (service === void 0) throw new AttachmentsUnavailableError();
+			yield* service.readFileStream(ref);
+		}
+	};
+}
+//#endregion
 //#region src/api/attachment.ts
-const MAX_ATTACHMENT_BYTES = 20971520;
 const PNG_MAGIC = Buffer.from([
 	137,
 	80,
@@ -3150,6 +3279,21 @@ const PNG_MAGIC = Buffer.from([
 	26,
 	10
 ]);
+const IMAGE_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
+function isImageMediaType(value) {
+	return value !== null && IMAGE_MEDIA_TYPES.includes(value);
+}
+/** 引用里的正整数字段（bytes / width / height）；缺、空、非整数、非正数都当"元数据不够"，退回直接 fs。 */
+function positiveInt(value) {
+	if (value === null || value === "") return void 0;
+	const parsed = Number(value);
+	return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
 /** 按魔数认图片类型；认不出回 `undefined`（调用方按未知字节处理，不猜）。 */
 function sniffImage(bytes) {
 	if (bytes.length >= PNG_MAGIC.length && bytes.subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC)) return "image/png";
@@ -3164,63 +3308,185 @@ function sniffImage(bytes) {
 * 否则 `encodeURIComponent` 会在写头时抛）。
 */
 function safeFilename(name, fallback) {
-	const raw = name === null || name === "" ? fallback : name;
+	const raw = name === null || name === void 0 || name === "" ? fallback : name;
 	const base = Array.from(raw).slice(0, 120).join("").replace(/[\\/:*?"<>|\u0000-\u001f\uD800-\uDFFF]/gu, "_").replace(/\.\./gu, "_");
 	return base === "" ? fallback : base;
 }
-async function readAttachmentResponse(deps, query) {
+/** 引用里的短 id：错误文案与下载名兜底共用，别让 `sha256:` 前缀的切片散在各处。 */
+function shortId(id) {
+	return id.slice(7, 19);
+}
+/** 普通文件的下载响应；图片认不出类型时也走这一支。 */
+function downloadResponse(body, filename) {
+	return {
+		body,
+		contentType: "application/octet-stream",
+		disposition: "attachment",
+		filename
+	};
+}
+/** 服务读取/校验失败按 io 上屏，不 fallback 直接 fs：宿主读 `files/.../<name>` 别名并做摘要/元数据
+*  校验，直接 fs 读 `file-objects/...` 对象；绕过会跳过宿主的校验（ADR-0035 边界）。 */
+function attachmentsIoError(id, error) {
+	throw verbError("io", `读取附件失败：${id}（${String(error)}）`, error);
+}
+/** 同一道上限：声明字节、磁盘字节、服务返回字节都从这里过。 */
+function assertWithinLimit(id, observed, maxBytes) {
+	if (observed > maxBytes) throw verbError("io", `附件超过 ${maxBytes} 字节上限：${id}（${observed} 字节）`);
+}
+/** 流式读超过上限：没有"实际总字节"，原文用 `>上限`。 */
+function streamOverflow(id, maxBytes) {
+	throw verbError("io", `附件超过 ${maxBytes} 字节上限：${id}（>${maxBytes} 字节）`);
+}
+/** 服务路径要的引用元数据；任一字段不够就回 `undefined`（调用方退回直接 fs，不拿半截 ref 去猜）。 */
+function imageServiceRef(id, query) {
+	const mediaType = query.get(PARAMS.attachmentMediaType);
+	const bytes = positiveInt(query.get(PARAMS.attachmentBytes));
+	const width = positiveInt(query.get(PARAMS.attachmentWidth));
+	const height = positiveInt(query.get(PARAMS.attachmentHeight));
+	if (!isImageMediaType(mediaType) || bytes === void 0 || width === void 0 || height === void 0) return void 0;
+	const name = query.get(PARAMS.attachmentName);
+	return {
+		attachmentId: id,
+		mediaType,
+		bytes,
+		width,
+		height,
+		...name === null || name === "" ? {} : { name }
+	};
+}
+function fileServiceRef(id, query) {
+	const bytes = positiveInt(query.get(PARAMS.attachmentBytes));
+	const name = query.get(PARAMS.attachmentName);
+	if (bytes === void 0 || name === null || name === "") return void 0;
+	return {
+		attachmentId: id,
+		name,
+		bytes
+	};
+}
+function parseServiceRef(id, kind, query) {
+	if (kind === "image") {
+		const ref = imageServiceRef(id, query);
+		return ref === void 0 ? void 0 : {
+			kind: "image",
+			ref
+		};
+	}
+	const ref = fileServiceRef(id, query);
+	return ref === void 0 ? void 0 : {
+		kind: "file",
+		ref
+	};
+}
+/** query 只解析一次：id/kind 的 400 闸与两套引用元数据都在这里收口。 */
+function parseAttachmentRequest(query) {
 	const id = query.get(PARAMS.attachmentId);
 	const kind = query.get(PARAMS.attachmentKind);
 	if (!isAttachmentId(id)) throw routeError("bad-request", 400, `附件 id 需为 sha256:<64 位小写 hex>：${String(id)}`);
 	if (kind !== "image" && kind !== "file") throw routeError("bad-request", 400, `附件 kind 只认 image / file：${String(kind)}`);
-	const path = attachmentPathOf(deps.home, kind, id);
+	const name = query.get(PARAMS.attachmentName);
+	return {
+		id,
+		kind,
+		name: name === null || name === "" ? void 0 : name,
+		serviceRef: parseServiceRef(id, kind, query)
+	};
+}
+async function readImageViaAttachments(deps, ref, maxBytes) {
+	assertWithinLimit(ref.attachmentId, ref.bytes, maxBytes);
+	let stored;
+	try {
+		stored = await deps.attachments.readImage(ref);
+	} catch (error) {
+		if (error instanceof AttachmentsUnavailableError) return void 0;
+		attachmentsIoError(ref.attachmentId, error);
+	}
+	const body = Buffer.from(stored.data);
+	assertWithinLimit(ref.attachmentId, body.length, maxBytes);
+	return {
+		body,
+		contentType: stored.ref.mediaType,
+		disposition: "inline"
+	};
+}
+/** 普通文件走宿主服务的分块读；超限在累计处停下，不把整份字节读进内存。 */
+async function readFileViaAttachments(deps, ref, maxBytes) {
+	assertWithinLimit(ref.attachmentId, ref.bytes, maxBytes);
+	const chunks = [];
+	let total = 0;
+	let tooLarge = false;
+	try {
+		for await (const chunk of deps.attachments.readFileStream(ref)) {
+			const buffer = Buffer.from(chunk);
+			total += buffer.length;
+			if (total > maxBytes) {
+				tooLarge = true;
+				break;
+			}
+			chunks.push(buffer);
+		}
+	} catch (error) {
+		if (error instanceof AttachmentsUnavailableError) return void 0;
+		attachmentsIoError(ref.attachmentId, error);
+	}
+	if (tooLarge) streamOverflow(ref.attachmentId, maxBytes);
+	return downloadResponse(Buffer.concat(chunks), safeFilename(ref.name, shortId(ref.attachmentId)));
+}
+/** 服务优先的唯一入口；`undefined` = 服务缺席 / 元数据不够 / 服务中途消失，调用方退回直接 fs。 */
+async function readViaAttachments(deps, request, maxBytes) {
+	if (request.serviceRef === void 0) return void 0;
+	if (!deps.attachments.available()) return void 0;
+	const serviceRef = request.serviceRef;
+	return serviceRef.kind === "image" ? readImageViaAttachments(deps, serviceRef.ref, maxBytes) : readFileViaAttachments(deps, serviceRef.ref, maxBytes);
+}
+/** 旧宿主 / 元数据不够：退回直接 fs（路径仍只由 id 与 kind 推导）。 */
+async function readViaFs(deps, request, maxBytes) {
+	const path = attachmentPathOf(deps.home, request.kind, request.id);
 	let size;
 	try {
 		size = (await deps.fs.statFile(path)).size;
 	} catch (error) {
-		throw verbError("io", `附件不在：${id}（${String(error)}）`, error);
+		throw verbError("io", `附件不在：${request.id}（${String(error)}）`, error);
 	}
-	if (size > MAX_ATTACHMENT_BYTES) throw verbError("io", `附件超过 ${MAX_ATTACHMENT_BYTES} 字节上限：${id}（${size} 字节）`);
+	assertWithinLimit(request.id, size, maxBytes);
 	const bytes = await deps.fs.readFile(path);
-	if (bytes.length > MAX_ATTACHMENT_BYTES) throw verbError("io", `附件超过 ${MAX_ATTACHMENT_BYTES} 字节上限：${id}（${bytes.length} 字节）`);
-	if (kind === "file") return {
-		body: bytes,
-		contentType: "application/octet-stream",
-		disposition: "attachment",
-		filename: safeFilename(query.get(PARAMS.attachmentName), id.slice(7, 19))
-	};
+	assertWithinLimit(request.id, bytes.length, maxBytes);
+	if (request.kind === "file") return downloadResponse(bytes, safeFilename(request.name, shortId(request.id)));
 	const contentType = sniffImage(bytes);
-	if (contentType === void 0) return {
-		body: bytes,
-		contentType: "application/octet-stream",
-		disposition: "attachment",
-		filename: safeFilename(query.get(PARAMS.attachmentName), `${id.slice(7, 19)}.bin`)
-	};
+	if (contentType === void 0) return downloadResponse(bytes, safeFilename(request.name, `${shortId(request.id)}.bin`));
 	return {
 		body: bytes,
 		contentType,
 		disposition: "inline"
 	};
 }
+async function readAttachmentResponse(deps, query) {
+	const request = parseAttachmentRequest(query);
+	const maxBytes = deps.config.maxAttachmentBytes;
+	const served = await readViaAttachments(deps, request, maxBytes);
+	if (served !== void 0) return served;
+	return readViaFs(deps, request, maxBytes);
+}
 //#endregion
 //#region src/api/attachment-orphans.ts
 /**
 * 孤儿附件的报告段：`GET /attachment-orphans`。
 *
 * 报告把扫描计划折成数量/字节 + 对象清单（`id`/`bytes`，供设置页预览缩略图；最多
-* `ORPHAN_PREVIEW_LIMIT` 条，清理不受预览条数限制）。扫描跳过（引用源或对象列表读不出）时
-* **报告必须失败**——回一份 0 会让界面说"没有孤儿"，而这类失败恰恰是"不知道"，不是"没有"。
+* `src/config.ts` 的 `orphanPreviewLimit`（默认 200，ADR-0037），清理不受预览条数限制）。
+* 扫描跳过（引用源或对象列表读不出）时**报告必须失败**——回一份 0 会让界面说"没有孤儿"，
+* 而这类失败恰恰是"不知道"，不是"没有"。
 * 清理是 `POST /attachment-clean`，由路由直接接到 `cleanOrphanImageAttachments`。
 */
-/** 预览清单的上限：与详情附件的载荷闸同一量级。数量与字节仍按全量报告。 */
-const ORPHAN_PREVIEW_LIMIT = 200;
 async function reportAttachmentOrphans(deps) {
 	const plan = await scanOrphanImageAttachments(deps);
 	if (plan.skipped !== void 0) throw verbError("io", plan.skipped);
+	const limit = deps.config.orphanPreviewLimit;
 	return {
 		count: plan.entries.length,
 		totalBytes: plan.bytes,
-		items: plan.entries.slice(0, ORPHAN_PREVIEW_LIMIT).map((entry) => ({
+		items: plan.entries.slice(0, limit).map((entry) => ({
 			attachmentId: entry.id,
 			bytes: entry.bytes
 		}))
@@ -3356,13 +3622,14 @@ const ROUTE_TABLE = {
 		run: async () => "pong"
 	},
 	[ROUTES.attachment.path]: {
-		slice: "core",
+		slice: "attachment",
 		method: ROUTES.attachment.method,
 		body: "none",
 		purity: "pure",
 		read: "none",
 		response: "binary",
-		run: async (deps, _body, _read, query) => readAttachmentResponse(deps, query)
+		fetchGate: "same-origin",
+		run: async (deps, query) => readAttachmentResponse(deps, query)
 	},
 	[ROUTES.attachmentOrphans.path]: {
 		slice: "core",
@@ -3434,95 +3701,37 @@ function routeOf(rest) {
 }
 //#endregion
 //#region src/api/dispatch.ts
-/** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
-const JSON_BODY_MAX_BYTES = 1048576;
-function writeJson(res, status, body) {
-	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
-	res.end(JSON.stringify(body));
-}
-function writeOk(res, value) {
-	writeJson(res, 200, {
-		ok: true,
-		value
-	});
-}
 /**
-* 二进制响应（`/attachment` 专用）。四道头都是判据不是口味：
-* - `content-type` 由处理函数给（图片按魔数认，文件一律 octet-stream）；
-* - `content-length` 与字节数同源；
-* - `cache-control: private, no-store`：附件可能来自已删除会话，不许被任何中间层留下；
-* - `nosniff` + `attachment` 下载名：字节内容与类型不一致时浏览器不许改猜。
+* /dsh-session-delete-api 的分发核心：只负责路由记录的执行。
+*
+* 传输适配器只有 `src/api/connection-route.ts` 一个：九段注册到宿主 `connection.fetch.register`
+* 的 exact Fetch 路由（`Request` / `Response`），Host/Origin/浏览器认证由宿主 `/api` bridge 完成
+* （ADR-0033）。`Request` 的字节闸 / JSON 解析、`Response` 的头与失败信封都归适配器；
+* 这里只收已经解析好的请求，做查表 → 按段注入窄面 → 跑处理 → 回结果。
+*
+* 纯度、body 声明、读面与方法仍住 `src/api/route-table.ts` 与 `src/shared/wire.ts`；这里只按判据执行。
 *
-* **失败不走这里**：处理函数抛出的错误仍由 `writeFailure` 写 JSON 信封（图片的 `onError` 会换成
-* 占位；普通文件走 `<a download>`，没有页面内失败面）。
+* - 请求本身不对用 4xx（400 请求体 / 405 方法 / 404 未知路由）；操作失败回 200 + {ok:false,error}。
+*   浏览器半先解信封，再看状态。宿主 exact route 已在 handler 之前把未声明方法 / 路径回 404，
+*   所以 405 / 未知路由 404 只在适配器直调时可达（`tests/connection-route.test.ts` 钉防御分支）。
+* - `purity` 为 chained 的请求串行执行，避免读清册/动文件/写清册交错；整个进程共用一条到达序链。
 */
-function writeBinary(res, body) {
-	const headers = {
-		"content-type": body.contentType,
-		"content-length": String(body.body.length),
-		"cache-control": "private, no-store",
-		"x-content-type-options": "nosniff"
-	};
-	if (body.filename !== void 0) headers["content-disposition"] = `${body.disposition}; filename*=UTF-8''${encodeURIComponent(body.filename)}`;
-	else if (body.disposition === "attachment") headers["content-disposition"] = "attachment";
-	res.writeHead(200, headers);
-	res.end(body.body);
-}
-/** 失败信封：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表）。
-*  **状态语义**：**请求本身不对**不再伪装成 200——请求体不对 400、方法不对 405、
-*  未知路由 404、栅栏拒 403（它们不是"一次办成的操作"，是"这条请求不归我办/你没资格办"）。
-*  **操作失败**仍回 200 + 信封。浏览器半先解信封再看状态，所以 4xx 上带的信封照样读得出原文；
-*  `code` 一律折成 `sessiondelete/io`，那三个路由标签（`bad-request` / `bad-method` / `not-found-route`）
-*  是**抛出处给读代码的人看的站点名**，不许冒充 `src/shared/wire.ts` 的五个动词码上客户端。 */
-function writeFailure(res, error, status) {
-	const carried = error?.httpStatus;
-	writeJson(res, status ?? (typeof carried === "number" ? carried : 200), {
-		ok: false,
-		error: toRemoteFailure(error)
-	});
-}
-/** 栅栏拒绝的两种原文：归属不对（跨源 / 重绑 / 头不成形）与远程客户端没带宿主身份。
-*  两者都是 403，但客户端会上屏，原文要能告诉用户下一步做什么。 */
-const UNTRUSTED_MESSAGE = "非受信来源";
-const UNAUTHENTICATED_MESSAGE = "需要宿主的 Web 身份：请用 dsh web 打印的那一行 URL 打开页面后重试";
-/** 流式读 body 并解析成 JSON 对象：空体回 `null`，超限 / 非法 JSON / 不是对象一律抛（→ 400 + 失败信封）。
-*  **请求本身不对**（400）与**那次操作读不到东西**（200 + 信封）是两件事：前者是调用方没组好请求，
-*  后者是盘上没有；把前者也写成 200，代理与日志里就再也分不出这两类。 */
-async function readJsonBody(req) {
-	const chunks = [];
-	let size = 0;
-	for await (const chunk of req) {
-		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-		size += buf.length;
-		if (size > JSON_BODY_MAX_BYTES) throw routeError("bad-request", 400, `请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
-		chunks.push(buf);
-	}
-	const text = Buffer.concat(chunks).toString("utf8").trim();
-	if (text === "") return null;
-	try {
-		const parsed = JSON.parse(text);
-		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw routeError("bad-request", 400, "请求体需为 JSON 对象");
-		return parsed;
-	} catch (error) {
-		if (error instanceof SyntaxError) throw routeError("bad-request", 400, `请求体不是合法 JSON：${error.message}`);
-		throw error;
-	}
-}
 function requireMethod(method, want, route) {
 	if (method !== want) throw routeError("bad-method", 405, `方法不允许：${method}（${SESSION_DELETE_API_PREFIX}${route} 需 ${want}）`);
 }
+/** 段名的 404 与方法的 405 只在这里判一次；空段名按插件前缀显示，避免 404 原文出现一个空串。 */
+function resolveRoute(method, rest) {
+	const spec = routeOf(rest);
+	if (spec === void 0) throw routeError("not-found-route", 404, `未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
+	requireMethod(method, spec.method, rest);
+	return spec;
+}
 function isPure(purity, body) {
 	return typeof purity === "function" ? purity(body) === "pure" : purity === "pure";
 }
-function readBodyFor(kind, req) {
-	return kind === "json" ? readJsonBody(req) : null;
-}
 /**
 * 全量面按行收窄（ADR-0032）：组合根装出的 {@link DeleteDeps} 只交给 `/apply`；每一段只拿到
-* 自己声明的那一格（路由表的 `slice`）。收窄是**运行期事实**，不是类型投影：`core` 拿到的是
-* 新建的 `CoreFsPort` 面，`removeDir` / `removeFile` 根本不在对象上；`now` 也不在 `core` / `removal`
-* 上。三格逐行 `satisfies` 是闸：全量面必须结构满足每一格；`coreOf` 的 fs 字面量又逼着
-* `CoreFsPort` 新增方法时同步补进来——漏了编译不过，而不是等某个段的 `run` 静默拿到超面。
+* 自己声明的那一格（路由表的 `slice`）。收窄是**运行期事实**，不是类型投影。
 */
 function coreOf(full) {
 	return {
@@ -3540,7 +3749,8 @@ function coreOf(full) {
 		host: full.host,
 		ledger: full.ledger,
 		home: full.home,
-		presence: full.presence
+		presence: full.presence,
+		config: full.config
 	};
 }
 /** `removal` 保留删除能力，但不带会话删除的时钟；`full` 只给 `/apply`。 */
@@ -3550,25 +3760,32 @@ function removalOf(full) {
 		host: full.host,
 		ledger: full.ledger,
 		home: full.home,
-		presence: full.presence
+		presence: full.presence,
+		config: full.config
 	};
 }
-/** 三格只建一次：收窄对象在 handler 构造期固定，请求路径只做引用选择。 */
+/** 四格只建一次：收窄对象在 dispatcher 构造期固定，请求路径只做引用选择。 */
 function slicesOf(full) {
+	const core = coreOf(full);
 	return {
-		core: coreOf(full),
+		core,
 		removal: removalOf(full),
-		full
+		full,
+		attachment: {
+			...core,
+			attachments: full.attachments
+		}
 	};
 }
-/** 按行选格：`spec.slice` 与三格的键同域，查表结果的类型由 `S` 直接给出。 */
+/** 按行选格：`spec.slice` 与 {@link SliceDeps} 的键同域，查表结果的类型由 `S` 直接给出。 */
 function depsFor(spec, slices) {
 	return slices[spec.slice];
 }
-function createApiHandler(deps, trust) {
+/** 路由执行器：查段 → 方法闸 → 读面 → 处理；返回归一结果。组合根只建一次。 */
+function createDispatcher(deps) {
 	const slices = slicesOf(deps);
 	/**
-	* 到达序串行链（见文件头）：路由表里 `purity === 'chained'` 的请求一个跑完再放下一个。
+	* 到达序串行链：`purity === 'chained'` 的请求一个跑完再放下一个。
 	* `tail` 由构造保证**永不 reject**（每个任务自己的失败留在交回给那次请求的那个 promise 上），
 	* 所以一次失败不会卡死链。
 	*/
@@ -3578,120 +3795,275 @@ function createApiHandler(deps, trust) {
 		tail = started.then(() => void 0, () => void 0);
 		return started;
 	};
-	return async function handle(req, res) {
-		const verdict = judgeRequest(req, trust);
-		if (verdict !== "allowed") {
-			writeFailure(res, /* @__PURE__ */ new Error(verdict === "untrusted" ? UNTRUSTED_MESSAGE : UNAUTHENTICATED_MESSAGE), 403);
-			return;
-		}
-		try {
-			const url = new URL(req.url ?? "/", "http://dsh.internal");
-			if (!url.pathname.startsWith("/dsh-session-delete-api")) throw routeError("not-found-route", 404, `未知路由：${url.pathname}`);
-			const rest = url.pathname.slice(23);
-			const spec = routeOf(rest);
-			if (spec === void 0) throw routeError("not-found-route", 404, `未知路由：${req.method ?? "GET"} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
-			requireMethod(req.method ?? "GET", spec.method, rest);
-			const body = await readBodyFor(spec.body, req);
-			const kind = spec.read;
-			let rowsPromise;
-			const read = { rows() {
-				if (kind === "none") return Promise.reject(/* @__PURE__ */ new Error("route read: none"));
-				rowsPromise ??= kind === "list" ? deps.ledger.list() : deps.ledger.raw();
-				return rowsPromise;
-			} };
-			const task = () => spec.run(depsFor(spec, slices), body, read, url.searchParams);
-			const result = await (isPure(spec.purity, body) ? task() : throughChain(task));
-			if (spec.response === "binary") writeBinary(res, result);
-			else writeOk(res, result);
-		} catch (error) {
-			writeFailure(res, error);
-		}
+	return async function dispatch(input) {
+		const spec = resolveRoute(input.method, input.rest);
+		const kind = spec.read;
+		let rowsPromise;
+		const read = { rows() {
+			if (kind === "none") return Promise.reject(/* @__PURE__ */ new Error("route read: none"));
+			rowsPromise ??= kind === "list" ? deps.ledger.list() : deps.ledger.raw();
+			return rowsPromise;
+		} };
+		const rowDeps = depsFor(spec, slices);
+		const task = () => spec.response === "binary" ? spec.run(rowDeps, input.search) : spec.run(rowDeps, input.body, read);
+		const result = await (isPure(spec.purity, input.body) ? task() : throughChain(task));
+		if (spec.response === "binary") return {
+			kind: "binary",
+			body: result
+		};
+		return {
+			kind: "json",
+			status: 200,
+			body: {
+				ok: true,
+				value: result
+			}
+		};
 	};
 }
 //#endregion
-//#region src/ports/connection-port.ts
-const HOST_UNAUTHENTICATED = 401;
-/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
-function createConnectionPort(ctx) {
-	return { verdictFor: (req) => {
-		const service = ctx.get("connection");
-		if (service === void 0 || typeof service.requestRejection !== "function") return { kind: "absent" };
+//#region src/api/connection-route.ts
+/**
+* 现代宿主的 exact Fetch 路由适配器：把九段注册到 `connection.fetch.register`，
+* 由宿主 `/api` bridge 做 Host/Origin/浏览器认证（ADR-0033）。
+*
+* 为什么路径必须带 `/api`：宿主 `assertFetchRoute` 用 `endpointFromPath('/api', path)` 校验，
+* 不带 `/api/` 前缀会在注册时直接抛错。`request.url` 会被 bridge 重写成 `http://dsh.internal/...`，
+* 这里只取 `pathname` / `searchParams`，不依赖外部 origin。
+*
+* 这条路由**不重复宿主的鉴权**：Host/Origin/浏览器认证在 handler 之前已经由宿主完成；只有路由记录
+* 声明了 `fetchGate` 的段（`/attachment`）再判一次同源取数（`isSameOriginFetch`）——那是字节 oracle
+* 的收口，不是身份。插件的 4xx（请求体 / 方法）与 200 操作失败信封在这里落地——`createDispatcher`
+* 只抛带 `httpStatus` 的请求错误。401/403 是宿主的纯文本响应，客户端负责映射。适配器拥有 wire 机制：
+* body 字节闸、JSON 解析、二进制头与失败信封。
+*/
+/** 请求体字节上限：这条通道只收几个 id，1MiB 是"够用且不给自己开一条内存放大器"的量级。 */
+const JSON_BODY_MAX_BYTES = 1048576;
+/** 请求体文本 → JSON 对象；空体 `null`；非对象 / 非法 JSON 抛 400。 */
+function parseJsonBody(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return null;
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw routeError("bad-request", 400, "请求体需为 JSON 对象");
+		return parsed;
+	} catch (error) {
+		if (error instanceof SyntaxError) throw routeError("bad-request", 400, `请求体不是合法 JSON：${error.message}`);
+		throw error;
+	}
+}
+/**
+* 二进制响应的四道头（`/attachment` 专用）。判据不是口味：类型由处理函数给、长度与字节同源、
+* 不许任何中间层留下已删除会话的附件、字节与声明类型不一致时浏览器不许改猜。
+*/
+function binaryHeaders(body) {
+	const headers = {
+		"content-type": body.contentType,
+		"content-length": String(body.body.length),
+		"cache-control": "private, no-store",
+		"x-content-type-options": "nosniff"
+	};
+	if (body.filename !== void 0) headers["content-disposition"] = `${body.disposition}; filename*=UTF-8''${encodeURIComponent(body.filename)}`;
+	else if (body.disposition === "attachment") headers["content-disposition"] = "attachment";
+	return headers;
+}
+/**
+* 失败的落地：码与原文都来自 `toRemoteFailure`（本插件唯一的错误映射表）。
+* 状态语义：**请求本身不对**不伪装成 200——请求体 400、方法 405、未知路由 404；
+* **操作失败**回 200 + 信封。`code` 一律折成 `sessiondelete/io`，路由站点名不冒充动词码。
+*/
+function failureResult(error, status) {
+	const carried = error?.httpStatus;
+	return {
+		kind: "json",
+		status: status ?? (typeof carried === "number" ? carried : 200),
+		body: {
+			ok: false,
+			error: toRemoteFailure(error)
+		}
+	};
+}
+/**
+* 同源取数闸（ADR-0033 边界收口）：附件字节能被任意页面当 `<img>` 渲染，而宿主 cookie 的
+* `SameSite=Strict` 按 **site** 判——同 IP 不同端口仍会带上。宿主 `/api` 只拦 `cross-site` 与
+* authority 不符的 `Origin`，这一格补在插件这一侧：
+* - `Sec-Fetch-Site` 为 `same-site` / `cross-site` ⇒ 拒；
+* - http(s) 的 `Origin` / `Referer` 与 `Host` 不同 authority ⇒ 拒（覆盖不发送 Fetch Metadata 的代次）；
+* - 桌面壳的 `dsh-app:` 来源与三头全缺的非浏览器客户端放行——桌面转发器已摘掉
+*   `host` / `origin` / `sec-fetch-site`，「摘干净」不是不可信。
+*
+* `Host` 依赖的是宿主 bridge 保留原始请求头（它只改写 `request.url`）；真机与
+* `tests/api.test.ts` 的 `node:http` 桥都钉住这一条：同源 `Referer` 能对上 `Host`。
+*/
+function isSameOriginFetch(request) {
+	const site = request.headers.get("sec-fetch-site");
+	if (site === "same-origin") return true;
+	if (site === "same-site" || site === "cross-site") return false;
+	const host = request.headers.get("host");
+	for (const name of ["origin", "referer"]) {
+		const value = request.headers.get(name);
+		if (value === null) continue;
+		let source;
 		try {
-			const status = service.requestRejection(req);
-			if (status === void 0) return { kind: "allowed" };
-			return { kind: status === HOST_UNAUTHENTICATED ? "unauthenticated" : "untrusted" };
+			source = new URL(value);
 		} catch {
-			return { kind: "untrusted" };
+			return false;
 		}
-	} };
+		if (source.protocol !== "http:" && source.protocol !== "https:" && source.protocol !== "dsh-app:") return false;
+		if (source.protocol === "dsh-app:") continue;
+		if (host === null || !isSameAuthority(source, host)) return false;
+	}
+	return true;
 }
-//#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;
+/** 按来源的协议解析 `Host`，两侧都过 WHATWG 归一（默认端口、大小写）后比 authority。 */
+function isSameAuthority(source, host) {
+	try {
+		return new URL(`${source.protocol}//${host}`).host === source.host;
+	} catch {
+		return false;
 	}
-	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;
+/** 边读边数：宿主按 `requestBody: 'buffered'` 已预读整段，这里仍守插件侧的 1 MiB 逻辑闸；
+*  超限即停，不再把读到的分片拼成更大的字符串。 */
+async function readRequestJson(request) {
+	const declared = Number(request.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > 1048576) throw routeError("bad-request", 400, `请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
+	const stream = request.body;
+	if (stream === null) return null;
+	const reader = stream.getReader();
+	const chunks = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > 1048576) {
+				await reader.cancel();
+				throw routeError("bad-request", 400, `请求体超过 ${JSON_BODY_MAX_BYTES} 字节上限`);
 			}
-		},
-		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;
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return parseJsonBody(Buffer.concat(chunks).toString("utf8"));
+}
+function toResponse(result) {
+	if (result.kind === "binary") return new Response(new Uint8Array(result.body.body), {
+		status: 200,
+		headers: binaryHeaders(result.body)
+	});
+	return new Response(JSON.stringify(result.body), {
+		status: result.status,
+		headers: {
+			"content-type": "application/json; charset=utf-8",
+			"cache-control": "private, no-store"
+		}
+	});
+}
+/**
+* 注册九段 exact Fetch 路由。返回一个组合 disposer；调用方把它挂在自己的 effect 上。
+* `connection` 是插件的硬依赖（web UI / 桌面端都装 `client-connection`）；`fetch.register`
+* 缺席属于宿主形状漂移，直接抛——静默返回空 disposer 会让插件「在但没有入口」。
+* `dispatch` 与分发器同源。
+*/
+function registerConnectionRoutes(service, dispatch) {
+	const fetchService = service.fetch;
+	if (fetchService === void 0 || typeof fetchService.register !== "function") throw new Error("session-delete: connection.fetch.register 不可用");
+	const disposers = [];
+	const disposeAll = async () => {
+		for (const dispose of [...disposers].reverse()) try {
+			await dispose();
+		} catch {}
+	};
+	try {
+		for (const [routePath, spec] of Object.entries(ROUTE_TABLE)) {
+			const path = `${OFFICIAL_SESSION_DELETE_API_PREFIX}${routePath}`;
+			disposers.push(fetchService.register({
+				path,
+				methods: [spec.method],
+				requestBody: "buffered",
+				fetch: async (request) => {
+					if (spec.fetchGate === "same-origin" && !isSameOriginFetch(request)) return toResponse(failureResult(routeError("bad-request", 403, "附件只允许同源页面读取")));
+					try {
+						const body = spec.body === "json" ? await readRequestJson(request) : null;
+						return toResponse(await dispatch({
+							method: request.method,
+							rest: routePath,
+							search: new URL(request.url).searchParams,
+							body
+						}));
+					} catch (error) {
+						return toResponse(failureResult(error));
+					}
 				}
-				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 });
+			}));
 		}
+	} catch (error) {
+		for (const dispose of [...disposers].reverse()) dispose().catch(() => void 0);
+		throw error;
+	}
+	return disposeAll;
+}
+//#endregion
+//#region src/config.ts
+const DEFAULT_CONFIG = Object.freeze({
+	orphanPreviewLimit: 200,
+	maxAttachmentBytes: 20971520,
+	maxJsonRefBytes: 10485760
+});
+const LIMITS = {
+	orphanPreviewLimit: {
+		min: 1,
+		max: 1e4
+	},
+	maxAttachmentBytes: {
+		min: 1,
+		max: 209715200
+	},
+	maxJsonRefBytes: {
+		min: 1,
+		max: 104857600
+	}
+};
+function intField(input, key, range) {
+	const value = input[key];
+	if (value === void 0) return DEFAULT_CONFIG[key];
+	if (typeof value !== "number" || !Number.isInteger(value) || value < range.min || value > range.max) throw new Error(`配置项 ${key} 需为 ${range.min}..${range.max} 的整数`);
+	return value;
+}
+/**
+* 把 patch 里的 `config` 归一成完整配置：缺省取默认值，未知键 / 非整数 / 越界都抛。
+* 抛错会让插件激活失败（响亮），而不是悄悄用半套配置跑。
+*/
+function normalizeConfig(value) {
+	if (value === void 0 || value === null) return DEFAULT_CONFIG;
+	if (typeof value !== "object" || Array.isArray(value)) throw new Error("配置需为对象");
+	const input = value;
+	const known = new Set(Object.keys(LIMITS));
+	for (const key of Object.keys(input)) if (!known.has(key)) throw new Error(`未知配置项：${key}`);
+	return {
+		orphanPreviewLimit: intField(input, "orphanPreviewLimit", LIMITS.orphanPreviewLimit),
+		maxAttachmentBytes: intField(input, "maxAttachmentBytes", LIMITS.maxAttachmentBytes),
+		maxJsonRefBytes: intField(input, "maxJsonRefBytes", LIMITS.maxJsonRefBytes)
 	};
 }
+/**
+* 插件 Config：Cordis 接受 Standard Schema，`~standard.validate` 交回归一后的配置。
+* 宿主在激活前校验；`apply` 再归一一次（同一份事实，不会漂）。
+*/
+const Config = { "~standard": {
+	version: 1,
+	vendor: "dsh-session-delete",
+	validate(value) {
+		try {
+			return { value: normalizeConfig(value) };
+		} catch (error) {
+			return { issues: [{ message: error instanceof Error ? error.message : String(error) }] };
+		}
+	}
+} };
 //#endregion
 //#region src/ports/home.ts
 /**
@@ -3950,21 +4322,19 @@ 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。
 *
-* `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` 原文读实，不是猜的。
-*
-* `connection` 只喂请求栅栏的远程支（`src/api/request-trust.ts` ②），按 `ctx.get` 可选读：
-* 服务缺席时插件照常激活，远程客户端 fail-closed。它不进 `inject`——写进去会让没有 web 组成的
-* profile 整个停在 pending。
+* `connection` 是浏览器半取数通道的唯一承载者：九段注册到 `connection.fetch.register` 的
+* `/api/dsh-session-delete-api/*`，Host/Origin/浏览器认证由宿主 `/api` bridge 完成（ADR-0033）。
+* 支持面是 web UI 与桌面端，二者的标准组合都装 `client-connection`；服务缺席时插件停在 pending
+* ——可见的激活失败，而不是静默地没有入口。`webServer` 不再直接使用：exact route 仍由宿主的
+* `connection` 挂在其 `/api` 前缀上，插件不需要自己碰物理服务器。
 *
 * 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
 * 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
@@ -3972,16 +4342,18 @@ const name = "@xrn1997/dsh-session-delete";
 const inject = [
 	"workspaceRegistry",
 	"storageDomain",
-	"webServer"
+	"connection"
 ];
 /**
-* 装配顺序：**清单 → 端口 → 在场能力 → 动词依赖 → 前缀路由**（`DeleteDeps` 把这些依赖面合成一颗）。
+* 装配顺序：**配置归一 → 清单 → 端口 → 在场能力 → 动词依赖 → 分发器 → exact Fetch 路由**
+* （`DeleteDeps` 把这些依赖面合成一颗；`config` 是归一后的只读快照）。
 *
 * 路由用 `ctx.effect` 挂、disposer 归装载它的那根 fiber：插件卸载即摘路由（`register` 返回的
-* disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(kind, path)`
-* 在 `register` 里直接抛（`webserver: duplicate prefix route "…"`），响亮失败而不是悄悄覆盖。
+* disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(path, method)`
+* 在 `connection.fetch.register` 里直接抛，响亮失败而不是悄悄覆盖。
 */
-function apply(ctx) {
+function apply(ctx, rawConfig) {
+	const config = normalizeConfig(rawConfig);
 	const fs = createFsPort();
 	const home = resolveHome();
 	const rawManifest = createHostStorageManifest(ctx);
@@ -3992,23 +4364,17 @@ function apply(ctx) {
 		ledger: createTrashLedger(rawManifest, fs, home),
 		home,
 		presence: createMemberPresence(host),
+		config,
+		attachments: createAttachmentsPort(ctx),
 		now: () => Date.now()
 	};
-	const webServer = ctx.webServer;
-	const connection = createConnectionPort(ctx);
+	const connection = ctx.get("connection");
+	if (connection === void 0) throw new Error("session-delete: connection 服务缺席");
+	const dispatch = createDispatcher(deps);
 	ctx.effect(() => {
-		const dispose = webServer.register({
-			kind: "prefix",
-			path: SESSION_DELETE_API_PREFIX,
-			handler: createApiHandler(deps, {
-				bindHost: webServer.host,
-				connection
-			})
-		});
-		return () => {
-			dispose();
-		};
-	}, "session-delete: /dsh-session-delete-api routes");
+		const dispose = registerConnectionRoutes(connection, dispatch);
+		return () => dispose();
+	}, "session-delete: /api exact Fetch routes");
 }
 //#endregion
-export { apply, inject, name };
+export { Config, apply, inject, name };