dsh-remote-bridge 2.5.1 → 2.5.2

package/lib/index.js

@@ -1,9 +1,9 @@
 import path, { join, sep } from "node:path";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
-import { execFile, spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFile, spawn } from "node:child_process";
 import os, { homedir, hostname, networkInterfaces } from "node:os";
+import { createReadStream, mkdirSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { pipeline } from "node:stream/promises";
 import { isIP } from "node:net";
@@ -46,6 +46,23 @@ function asApiError(error) {
 //#endregion
 //#region src/host/image-handoff.ts
 /**
+* 图片交接的「识图路径」：目录名从哪来、图片怎么被安全地端到浏览器面前。
+*
+* 两件事合在一个模块里，因为它们是同一个概念的里外两面：
+*
+* 1. **设置**（`识图路径`）：纯文本模型发图时，图片落在「会话工作目录 + <识图路径>」下。
+*    出厂默认是 [DEFAULT_HANDOFF_SUBDIR]，设置面板里把这一栏**只读**展示（用户要求：
+*    「当前默认（不能改）」），真正可编辑的是那个目录名本身，存在 settings 表里。
+* 2. **只读路由**（从 dsh-image-paths 0.3.1 并进来的那半边）：浏览器 `<img>` 不能带
+*    Authorization 头，所以走不了版本化 REST 的鉴权通道。这条路由改用「回环 + 同源 +
+*    裸文件名白名单 + 字节自证」的模型；**目录不由客户端给**，而是按会话工作目录由宿主
+*    自己推出（与写盘用的是同一个解析），于是「指一个路径去读本地文件」这件事在参数
+*    层面就不成立 —— 这是比 image-paths 原版更紧的一步。
+*
+* 威胁模型与 image-paths 一致：webserver 绑回环，跨站请求拒绝，返回的每个字节都先过了
+* 「文件名白名单 + 扩展名声明 + 内容自证 + 体积上限」四道闸。
+*/
+/**
 * 交接目录的**出厂默认**。
 *
 * 设置面板里「当前默认」那一栏展示的就是这个字面量，且是只读的 —— 它是这份代码的
@@ -222,6 +239,17 @@ function sameOrigin(req) {
 		return false;
 	}
 }
+/**
+* 内容是够与文件名里的哈希一致。
+*
+* 文件名形如 `<64 hex>.<ext>`（`HANDOFF_FILE_NAME` 已保证），取前 64 字符当期望值。
+* `message` 前缀（`sha256:`）不需要处理 —— 白名单正则里没有冒号。
+*/
+function contentMatchesName(bytes, name) {
+	const expected = name.slice(0, 64).toLowerCase();
+	if (!/^[0-9a-f]{64}$/.test(expected)) return false;
+	return createHash("sha256").update(bytes).digest("hex") === expected;
+}
 /** 用一段纯文本说出拒绝理由：不回显调用方给的路径，也不做任何目录列举。 */
 function refuse(res, status, reason) {
 	const body = `${reason}\n`;
@@ -285,6 +313,10 @@ function createImageRouteHandler(options) {
 			refuse(res, 415, "content does not match the file extension");
 			return;
 		}
+		if (!contentMatchesName(image.bytes, name)) {
+			refuse(res, 404, "no such handoff image");
+			return;
+		}
 		res.writeHead(200, {
 			"content-type": sniffed,
 			"content-length": String(image.bytes.byteLength),
@@ -372,9 +404,12 @@ var FixedWindowLimiter = class {
 *
 * @param req - 待判定的请求。
 * @param options.tunnelActive - 是否有我们自管的隧道在运行；缺省视为没有。
-* @param options.allowTunnelMode - 仅用于「隧道状态」这类**只读、无副作用**的端点：
-*   让它们豁免判据 0（否则隧道一开，面板连「隧道开着」这件事都读不到），
-*   判据 1/2/3 仍然全部生效。**其他任何 `/manage` 端点都不许传这个选项。**
+* @param options.allowTunnelMode - 仅用于「隧道状态」与「停止隧道」端点：让它们豁免判据 0
+*   （否则隧道一开，面板连「隧道开着」都读不到，也无法体面地把隧道停掉），判据 1/2/3
+*   仍然全部生效。其中 `cloudflare/stop` 是**唯一**豁免的写操作 —— 它的唯一效果就是把
+*   管理面重新锁上（重新拉回判据 0），且判据 1 仍挡住任何经隧道/代理的调用，所以对真实
+*   隧道来源（必带 cf-* 头）不可利用；放行它不构成任何提权。**其他任何 `/manage` 端点
+*   （尤其 config/text）都不许传这个选项。**
 */
 function adminRefusal(req, options = {}) {
 	if (options.tunnelActive === true && options.allowTunnelMode !== true) return {
@@ -394,6 +429,10 @@ function adminRefusal(req, options = {}) {
 		message: "This operation is available only from the local machine."
 	};
 }
+/** 是否存在任何转发头（`adminRefusal` 判据 1 的公开形态，供测试与文档断言复用）。 */
+function hasForwardingHeader(req) {
+	return FORWARDING_HEADERS.some((name) => headerPresent(req, name));
+}
 /**
 * 「这个请求不是本机直连」的**全部**证据头。
 *
@@ -429,16 +468,63 @@ function headerPresent(req, name) {
 	if (Array.isArray(raw)) return raw.some((value) => value.trim() !== "");
 	return raw.trim() !== "";
 }
+/**
+* 判定一条请求属于哪一类对端。纯函数（除 `tunnelActive` 探针外不碰任何状态），
+* 供限流分桶与测试直接调用。
+*
+* @param req - 待分类的请求。
+* @param options.tunnelActive - 隧道是否在跑；缺省视为没有。
+*/
+function classifyPeer(req) {
+	if (hasForwardingHeader(req)) return "tunnelled";
+	return "local";
+}
 var AuthService = class {
 	database;
 	options;
-	authFailures = new FixedWindowLimiter(20, 3e5);
-	pairingAttempts = new FixedWindowLimiter(10, 6e5);
-	requests = new FixedWindowLimiter(120, 6e4);
+	/**
+	* 两个「按对端分类」分开计的桶（键 = `<class>:<remoteAddress>`）。
+	*
+	* 阈值刻意**两边一致**：分桶的目的是「互不连坐」，不是「给本机开后门」。
+	* 如果本机侧更宽，那它就成了一条「怎么把自己伪装成本机」的动机 —— 而伪装是免费的
+	* （不发头即可），于是更宽的那一侧等于被取消。
+	* 阈值相等时，攻击者伪装成 local 只会消耗 local 配额，**没有额外收益**。
+	*
+	* `requests`：120/60s。`authFailures`：20/5min。
+	*/
+	authFailuresByPeer = {
+		local: new FixedWindowLimiter(20, 3e5),
+		tunnelled: new FixedWindowLimiter(20, 3e5)
+	};
+	/** 配对兑换：本机与隧道分开。隧道侧公网暴力尝试不该锁死本机的配对。 */
+	pairingAttemptsByPeer = {
+		local: new FixedWindowLimiter(10, 6e5),
+		tunnelled: new FixedWindowLimiter(10, 6e5)
+	};
+	requestsByPeer = {
+		local: new FixedWindowLimiter(120, 6e4),
+		tunnelled: new FixedWindowLimiter(120, 6e4)
+	};
 	constructor(database, options = {}) {
 		this.database = database;
 		this.options = options;
 	}
+	/** 这套服务当前的对端分类（`tunnelActive` 走 fail-closed 探针）。 */
+	peerOf(req) {
+		return classifyPeer(req);
+	}
+	/** 按对端取请求配额桶。 */
+	requestLimiter(req) {
+		return this.requestsByPeer[this.peerOf(req)];
+	}
+	/** 按对端取认证失败桶。 */
+	failureLimiter(req) {
+		return this.authFailuresByPeer[this.peerOf(req)];
+	}
+	/** 按对端取配对尝试桶（`router.ts` 的 exchange 端点用）。 */
+	pairingLimiter(req) {
+		return this.pairingAttemptsByPeer[this.peerOf(req)];
+	}
 	/**
 	* 隧道是否在跑。探针抛错时**按「在跑」处理**（fail closed）：探针读的是我们自己
 	* 对象上的 getter，它抛错意味着状态不可知；状态不可知时放行管理面正是这次修复要
@@ -455,24 +541,26 @@ var AuthService = class {
 	}
 	principal(req, options = {}) {
 		const remote = requestAddress(req);
-		this.requests.consume(remote);
+		const peer = this.peerOf(req);
+		const key = `${peer}:${remote}`;
+		this.requestsByPeer[peer].consume(key);
 		if (options.allowAdmin === true && req.headers["x-dsh-workspace-admin"] === "1") {
 			const refusal = adminRefusal(req, { tunnelActive: this.tunnelRunning() });
 			if (refusal !== void 0) {
-				this.authFailures.consume(remote);
+				this.authFailuresByPeer[peer].consume(key);
 				throw new ApiError(403, refusal.code, refusal.message);
 			}
 			return ADMIN_PRINCIPAL;
 		}
 		const authorization = req.headers.authorization;
 		if (authorization === void 0 || !authorization.startsWith("Bearer ")) {
-			this.authFailures.consume(remote);
+			this.authFailuresByPeer[peer].consume(key);
 			throw new ApiError(401, "AUTH_REQUIRED", "A valid Bearer token is required.");
 		}
 		const token = authorization.slice(7).trim();
 		const device = token === "" ? void 0 : this.database.authenticate(token);
 		if (device === void 0) {
-			this.authFailures.consume(remote);
+			this.authFailuresByPeer[peer].consume(key);
 			throw new ApiError(401, "TOKEN_INVALID", "The device token is invalid or revoked.");
 		}
 		return {
@@ -550,14 +638,27 @@ function archSuffix(platform = process.platform, arch = process.arch) {
 		default: throw new Error(`cloudflared 尚不支持 ${process.arch} 架构。`);
 	}
 }
-const OFFICIAL_BASE = `https://github.com/cloudflare/cloudflared/releases/download/2024.11.1/cloudflared-`;
+/**
+* cloudflared 的**唯一**版本号（导出给测试与配置文本用）。
+*
+* ⚠️ 「钉版本」必须只有一处事实来源：2.5.1 及之前 GitHub 基线钉 `2024.11.1`，
+* 而 deb 兜底 URL 里写死了另一个版本 `2026.10.1` —— 同一个函数对「装哪个版本」
+* 给出两个不同答案，等于**没有钉住**。现在 deb URL 也从这里派生。
+*/
+const CLOUDFLARED_VERSION = "2024.11.1";
+const OFFICIAL_BASE = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-`;
 /**
 * 官方 deb 兜底仓库（GitHub 被墙时回退）。
+*
 * `pkg.cloudflare.com` 是 Cloudflare 官方仓库，实测在 GitHub 直连被墙的机器上可达可用
-* （见 PITFALLS §国内下载 cloudflared 必须择源）。版本比 GitHub 默认新（2026.10.1），
-* 仅在官方 GitHub 失败时兜底，不改变「默认先 GitHub」的语义。
+* （见 PITFALLS §国内下载 cloudflared 必须择源）。仅在官方 GitHub 失败时兜底，
+* 不改变「默认先 GitHub」的语义。
+*
+* 版本**从 `CLOUDFLARED_VERSION` 派生**，不再写死第二个版本号。
 */
-const DEB_FALLBACK_URL = "https://pkg.cloudflare.com/cloudflared/pool/main/c/cloudflared/cloudflared_2026.10.1_amd64.deb";
+function debFallbackUrl(debArch) {
+	return `https://pkg.cloudflare.com/cloudflared/pool/main/c/cloudflared/cloudflared_${CLOUDFLARED_VERSION}_${debArch}.deb`;
+}
 async function downloadHttps(url, ms, onProgress) {
 	const mod = url.startsWith("http:") ? await import("node:http") : await import("node:https");
 	return await new Promise((resolve, reject) => {
@@ -591,6 +692,60 @@ async function downloadHttps(url, ms, onProgress) {
 function statusOk(code) {
 	return typeof code === "number" && code >= 200 && code < 300;
 }
+/**
+* 校验下载到的字节是否匹配期望的 SHA-256。
+*
+* 大小写不敏感、允许 `sha256:` 前缀（常见发行格式）。**长度不对一律 false** ——
+* 不做「宽松接受」：一个 3 字符的期望值只可能是配置错误，接受它就是放弃校验。
+*/
+function verifySha256(bytes, expectedHex) {
+	const normalized = expectedHex.trim().replace(/^sha256:/i, "").toLowerCase();
+	if (!/^[0-9a-f]{64}$/.test(normalized)) return false;
+	return createHash("sha256").update(bytes).digest("hex") === normalized;
+}
+/**
+* 期望的校验和：读 `CLOUDFLARED_SHA256` 环境变量。
+*
+* 空串/纯空白视为**没有声明**（返回 undefined）—— 否则「随手 export 一个空值」
+* 会让所有下载都被判成不匹配。
+*/
+function expectedSha256From() {
+	const raw = process.env.CLOUDFLARED_SHA256?.trim() ?? "";
+	return raw === "" ? void 0 : raw;
+}
+/**
+* 把下载/解包错误**脱敏**成可以对外（与本机日志）说的一行字。
+*
+* ## 为什么需要它
+*
+* 底层错误有三类敏感残留：
+* 1. **完整 URL** —— `downloadHttps` 的 `` `下载失败：${url}（${cause.message}）` ``，
+*    而镜像 URL 可能带 token（`https://mirror/token/...`）；
+* 2. **绝对路径** —— `execFile('dpkg-deb', ...)` 的错误形如
+*    `Command failed: dpkg-deb -x /home/user/.../x.deb /home/user/.../dir`；
+* 3. 两者都可能被 `router.ts` 原样塞进 502 响应体。
+*
+* ## 取舍
+*
+* 保留**可诊断的线索**（host 名、文件名），去掉**不该外传的部分**（完整 URL、目录）。
+* 一句话：能说「哪个源、哪个文件」；不能说「你家目录长什么样、URL 里那个 token 是什么」。
+*/
+function sanitizeDownloadError(message) {
+	let safe = message;
+	safe = safe.replace(/https?:\/\/[^\s）)（("']+/gi, (raw) => {
+		try {
+			return `host:${new URL(raw).host}`;
+		} catch {
+			return "host:unknown";
+		}
+	});
+	safe = safe.replace(/(?:[A-Za-z]:)?(?:\/[^\s:：/（）()]+)+\/?/g, (raw) => {
+		const trimmed = raw.replace(/[\/]+$/, "");
+		const base = trimmed.split(/[\\/]/).pop() ?? trimmed;
+		return base === "" ? trimmed : base;
+	});
+	return safe;
+}
 /** 环境变量注入的下载源配置；空则回退官方。 */
 function mirrorBase() {
 	return process.env.CLOUDFLARED_MIRROR?.trim() ?? "";
@@ -641,14 +796,14 @@ async function ensureCloudflared(dataDir, report) {
 	const existing = path.join(dataDir, "cloudflared");
 	report?.({
 		stage: "locating",
-		label: "定位本机二进制…",
+		labelKey: "tunnelStageLocating",
 		percent: null
 	});
 	try {
 		if ((await stat(existing)).isFile()) {
 			report?.({
 				stage: "locating",
-				label: "已找到本机二进制，直接复用",
+				labelKey: "tunnelStageBinaryFound",
 				percent: 100
 			});
 			return existing;
@@ -662,14 +817,15 @@ async function ensureCloudflared(dataDir, report) {
 		url: downloadUrlFor(),
 		deb: false
 	}, {
-		url: DEB_FALLBACK_URL,
+		url: debFallbackUrl("amd64"),
 		deb: true
 	}];
+	const expected = expectedSha256From();
 	const errors = [];
 	for (const { url, deb } of candidates) {
 		report?.({
 			stage: "downloading",
-			label: `正在下载 cloudflared（${deb ? "官方 deb 仓库" : "官方 GitHub"}）…`,
+			labelKey: deb ? "tunnelStageDownloadDeb" : "tunnelStageDownloadGithub",
 			percent: null
 		});
 		try {
@@ -680,7 +836,11 @@ async function ensureCloudflared(dataDir, report) {
 					const all = (total / 1024 / 1024).toFixed(1);
 					report?.({
 						stage: "downloading",
-						label: `正在下载 cloudflared… ${mb}/${all} MB`,
+						labelKey: "tunnelStageDownloadProgress",
+						labelParams: {
+							mb,
+							all
+						},
 						percent
 					});
 				}
@@ -689,17 +849,26 @@ async function ensureCloudflared(dataDir, report) {
 				errors.push(`HTTP ${res.status}`);
 				continue;
 			}
+			if (expected !== void 0 && !verifySha256(res.body, expected)) {
+				errors.push("SHA-256 mismatch");
+				continue;
+			}
+			if (expected === void 0) report?.({
+				stage: "downloading",
+				labelKey: "tunnelStageDownloadUnverified",
+				percent: 100
+			});
 			if (deb) {
 				report?.({
 					stage: "unpacking",
-					label: "解包官方 deb 并提取二进制…",
+					labelKey: "tunnelStageUnpackDeb",
 					percent: null
 				});
 				return writeFromDeb(dataDir, res.body, url);
 			}
 			report?.({
 				stage: "unpacking",
-				label: "写入二进制并赋予执行权限…",
+				labelKey: "tunnelStageWriteBinary",
 				percent: null
 			});
 			const tmp = path.join(dataDir, `.cloudflared.tmp-${process.pid}`);
@@ -708,15 +877,24 @@ async function ensureCloudflared(dataDir, report) {
 			await rename(tmp, existing);
 			return existing;
 		} catch (cause) {
-			errors.push(cause instanceof Error ? cause.message : String(cause));
+			errors.push(sanitizeDownloadError(cause instanceof Error ? cause.message : String(cause)));
 		}
 	}
-	const tried = candidates.map((c) => c.url).join("\n  ");
-	throw new Error(`下载 cloudflared 失败：\n  ${tried}\n原因：${errors.join("；")}`);
+	const triedHosts = [...new Set(candidates.map((c) => {
+		try {
+			return new URL(c.url).host;
+		} catch {
+			return "unknown";
+		}
+	}))].join(", ");
+	throw new Error(`下载 cloudflared 失败（已尝试 ${candidates.length} 个源：${triedHosts}）` + (errors.length === 0 ? "" : `；原因：${errors.join("；")}`));
 }
 /**
 * 从 `.deb` 包字节中提取 `usr/bin/cloudflared`，原子落到 `dataDir/cloudflared`。
 * 不调用系统 `dpkg -i`（避免污染包数据库），只做解包 + 提取。
+*
+* 失败时抛出的错误**已脱敏**：`execFile` 的原始错误含两个绝对路径
+* （deb 与解包目录），直接外传会泄露本机目录结构。
 */
 async function writeFromDeb(dataDir, debBuffer, url) {
 	await mkdir(dataDir, { recursive: true });
@@ -730,11 +908,18 @@ async function writeFromDeb(dataDir, debBuffer, url) {
 				"-x",
 				debPath,
 				extractDir
-			], (err) => err ? reject(err) : resolve());
+			], (err) => {
+				if (err === null) {
+					resolve();
+					return;
+				}
+				reject(new Error(sanitizeDownloadError(`dpkg-deb 解包失败：${err.message}`)));
+			});
 		});
 		const inner = path.join(extractDir, "usr", "bin", "cloudflared");
 		const out = path.join(dataDir, "cloudflared");
 		const bin = await readFile(inner);
+		if (bin.byteLength === 0) throw new Error("解包后的 cloudflared 为空文件");
 		await writeFile(out, bin);
 		await chmod(out, 493);
 		return out;
@@ -752,10 +937,12 @@ var CloudflaredTunnelManager = class {
 	url = null;
 	channel = null;
 	errorText = void 0;
+	errorKey = void 0;
+	errorParams = void 0;
 	listeners = [];
 	activity = {
 		stage: "idle",
-		label: "",
+		labelKey: "",
 		percent: null
 	};
 	/** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
@@ -771,7 +958,7 @@ var CloudflaredTunnelManager = class {
 	clearActivity() {
 		this.activity = {
 			stage: "idle",
-			label: "",
+			labelKey: "",
 			percent: null
 		};
 		this.emit();
@@ -794,21 +981,31 @@ var CloudflaredTunnelManager = class {
 			channel: this.channel,
 			url: this.url,
 			running: this.tunnelActive,
-			...this.errorText === void 0 ? {} : { error: this.errorText }
+			...this.errorText === void 0 ? {} : { error: this.errorText },
+			...this.errorKey === void 0 ? {} : { errorKey: this.errorKey },
+			...this.errorParams === void 0 ? {} : { errorParams: this.errorParams }
 		};
 	}
 	/** 订阅状态变化；返回取消函数。 */
 	onStatus(cb) {
 		this.listeners.push(cb);
-		return () => {
-			this.listeners = this.listeners.filter((fn) => fn !== cb);
-		};
+		return () => this.offStatus(cb);
+	}
+	/** 取消一个状态订阅（onStatus 返回的函数与 waitForUrl 共用）。 */
+	offStatus(cb) {
+		this.listeners = this.listeners.filter((fn) => fn !== cb);
 	}
 	emit() {
 		for (const fn of this.listeners) fn();
 	}
-	setError(message) {
+	/**
+	* 记录一次错误。`error` 保留脱敏后的短消息（兜底/日志），
+	* `errorKey` + `errorParams` 供客户端本地化（优先级 errorKey > error）。
+	*/
+	setError(errorKey, message, errorParams) {
 		this.errorText = message;
+		this.errorKey = errorKey;
+		this.errorParams = errorParams;
 		this.emit();
 	}
 	/**
@@ -817,11 +1014,13 @@ var CloudflaredTunnelManager = class {
 	* @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
 	*/
 	async startQuick(exe, port) {
-		if (this.process !== null && !this.process.killed) throw new Error("隧道已经在运行中，请先停止。");
+		if (this.process !== null && !this.process.killed) throw new Error("Tunnel is already running; stop it first.");
 		this.errorText = void 0;
+		this.errorKey = void 0;
+		this.errorParams = void 0;
 		this.reportActivity({
 			stage: "starting",
-			label: "正在启动 cloudflared 隧道…",
+			labelKey: "tunnelStageStarting",
 			percent: null
 		});
 		const child = spawn(exe, [
@@ -853,13 +1052,52 @@ var CloudflaredTunnelManager = class {
 			this.channel = null;
 			this.emit();
 			if (wasThis) {
-				if (this.url === null) this.setError(`cloudflared 退出（code=${code ?? "?"}, signal=${signal ?? "?"}），未拿到隧道地址。`);
+				if (this.url === null) this.setError("tunnelErrorExited", `cloudflared exited (code=${code ?? "?"}, signal=${signal ?? "?"}) without a tunnel URL.`, {
+					code: String(code ?? "?"),
+					signal: String(signal ?? "?")
+				});
 				this.url = null;
 				if (this.channel === null) this.clearActivity();
 			}
 		});
 		return this.publicState;
 	}
+	/**
+	* 等待子进程把随机域名打印到 stdout（spawn 后 `url` 通常还要几秒才有）。
+	*
+	* 存在的理由（2.5.2）：`POST /manage/cloudflare/create` 发生在隧道**起来之前**，
+	* 此刻管理面还没被判据 0 关门；一旦在这次请求里等出地址并顺带出令牌配置文本，
+	* 客户端就不必在隧道运行后再打一次 `/manage/config/text`（那时必然 403，
+	* 这正是「一键开隧道+出令牌」失效的根因）。
+	*
+	* 任一条件满足即结算：地址出现 → resolve(url)；进程退出/超时 → resolve(null)
+	* （不抛，调用方据 null 决定要不要让客户端走轮询补一步）。调用方传 AbortSignal 可提前走人。
+	*/
+	async waitForUrl(timeoutMs = 12e3, signal) {
+		if (this.url !== null) return this.url;
+		if (this.process === null || this.process.killed) return null;
+		return await new Promise((resolve) => {
+			let settled = false;
+			const finish = (value) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				this.offStatus(observer);
+				signal?.removeEventListener("abort", onAbort);
+				resolve(value);
+			};
+			const observer = () => {
+				if (this.url !== null) finish(this.url);
+				else if (this.process === null || this.process.killed) finish(null);
+			};
+			const onAbort = () => finish(null);
+			const timer = setTimeout(() => finish(null), timeoutMs);
+			timer.unref?.();
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.onStatus(observer);
+			observer();
+		});
+	}
 	/** 停止当前隧道。 */
 	stop() {
 		const child = this.process;
@@ -879,6 +1117,142 @@ var CloudflaredTunnelManager = class {
 	}
 };
 //#endregion
+//#region src/host/metrics.ts
+/**
+* 进程内**薄指标收集器**。
+*
+* ## 为什么需要它
+*
+* 本插件此前只有 9 处启动期日志（`index.ts`），运行期**一条都没有**，也没有任何耗时统计。
+* 于是「广播是不是串行卡住了」「内核 RPC 是不是超时了」「事件是不是被丢了」这三个问题
+* 在运行数据里**完全不可见** —— 只能靠读代码推断。这份模块就是让它们变得可观测的最小代价版本。
+*
+* ## 为什么是「进程内、无依赖、固定样本环」
+*
+* - **不引入 prometheus / otel**：这插件跑在用户的 DSH 进程里，加一个重依赖会拖慢启动、
+*   也会把「插件」变成「服务」；这里要的只是「出问题时能看一眼」。
+* - **固定样本环（256）**：P50/P95 需要排序，样本无界增长就是内存泄漏。256 个数字足以
+*   看出「大多数很快、尾部很慢」，而且分配是一次性的。
+* - **全部计数都是整数累加**：热路径（每个事件、每个 RPC）调用它只做 `+= 1` 与几次比较，
+*   不会自己变成瓶颈。
+*
+* ## 如何被读到
+*
+* `getMetricsSnapshot()` 是**纯读**。挂载点在 `GET /api/v1/debug/host-services` 的响应里
+* （由 router 负责，本模块不碰 HTTP）—— 那条端点本就是「只读诊断」，且已有同一套鉴权。
+*
+* 注意：这些数字**不参与任何业务判断**。它们只用于观测，坏了最坏是「数字不对」，
+* 不会让功能变化 —— 这是刻意划的边界。
+*/
+/** 保留多少个 RPC 耗时样本用于算分位数。 */
+const SAMPLE_CAPACITY = 256;
+const rpcBuckets = /* @__PURE__ */ new Map();
+/** WebSocket 与广播面的计数。 */
+const counters = {
+	wsConnections: 0,
+	wsRejected: 0,
+	wsTerminated: 0,
+	broadcastEvents: 0,
+	/** 所有连接队列里最长的那条有多长（背压信号）。 */
+	broadcastQueueDepth: 0,
+	/** 因队列满/背压被丢掉的事件数（任何连接）。 */
+	droppedEvents: 0,
+	/** FrameHub 因队列满丢掉的事件数（由 dsh-0.2-bridge 上报）。 */
+	frameHubDropped: 0
+};
+/**
+* 记录一次 RPC 耗时。
+*
+* @param name - 稳定的 RPC 名（如 `sessions.history`）。**不要**把参数拼进去，
+*   否则基数会炸（每个 sessionId 一个桶）。
+* @param ms - 毫秒耗时。
+* @param ok - 是否成功；失败单独计数，因为「慢」与「错」是两回事。
+*/
+function recordRpc(name, ms, ok = true) {
+	let bucket = rpcBuckets.get(name);
+	if (bucket === void 0) {
+		bucket = {
+			count: 0,
+			failures: 0,
+			totalMs: 0,
+			maxMs: 0,
+			samples: [],
+			index: 0,
+			filled: 0
+		};
+		rpcBuckets.set(name, bucket);
+	}
+	bucket.count += 1;
+	if (!ok) bucket.failures += 1;
+	if (!Number.isFinite(ms) || ms < 0) return;
+	bucket.totalMs += ms;
+	if (ms > bucket.maxMs) bucket.maxMs = ms;
+	bucket.samples[bucket.index] = ms;
+	bucket.index = (bucket.index + 1) % SAMPLE_CAPACITY;
+	if (bucket.filled < SAMPLE_CAPACITY) bucket.filled += 1;
+}
+function setWsConnections(value) {
+	counters.wsConnections = value < 0 ? 0 : value;
+}
+function recordWsRejected() {
+	counters.wsRejected += 1;
+}
+function recordWsTerminated() {
+	counters.wsTerminated += 1;
+}
+function recordBroadcastEvent() {
+	counters.broadcastEvents += 1;
+}
+/** 更新「最长连接队列」；传入当前所有连接队列长度的最大值。 */
+function setBroadcastQueueDepth(value) {
+	counters.broadcastQueueDepth = value < 0 ? 0 : value;
+}
+function recordDroppedEvent(count = 1) {
+	counters.droppedEvents += count;
+}
+/** 由 `FrameHub` 上报：它自己丢了几个事件（与 socket 队列无关的另一处丢弃点）。 */
+function recordFrameHubDropped(count = 1) {
+	counters.frameHubDropped += count;
+}
+/** 从环形样本里问分位数。空样本返回 0（而不是 NaN —— NaN 会让 JSON 变 `null`）。 */
+function quantile(bucket, f) {
+	if (bucket.filled === 0) return 0;
+	const live = bucket.samples.slice(0, bucket.filled).sort((left, right) => left - right);
+	return live[Math.min(live.length - 1, Math.max(0, Math.floor((live.length - 1) * f)))] ?? 0;
+}
+/**
+* 读一份快照。**纯读**：不重置任何计数（重置会让「谁先读谁清空」变成新的坑）。
+*
+* 返回的是**新对象**，调用方改它不会污染内部状态。
+*/
+function getMetricsSnapshot() {
+	const rpc = [];
+	for (const [name, bucket] of rpcBuckets) rpc.push({
+		name,
+		count: bucket.count,
+		failures: bucket.failures,
+		averageMs: bucket.count === 0 ? 0 : Math.round(bucket.totalMs / Math.max(1, bucket.count) * 100) / 100,
+		p50Ms: quantile(bucket, .5),
+		p95Ms: quantile(bucket, .95),
+		maxMs: bucket.maxMs
+	});
+	rpc.sort((left, right) => right.p95Ms - left.p95Ms);
+	return {
+		ws: {
+			connections: counters.wsConnections,
+			rejected: counters.wsRejected,
+			terminated: counters.wsTerminated
+		},
+		broadcast: {
+			events: counters.broadcastEvents,
+			queueDepth: counters.broadcastQueueDepth,
+			droppedEvents: counters.droppedEvents
+		},
+		frameHub: { dropped: counters.frameHubDropped },
+		rpc
+	};
+}
+//#endregion
 //#region src/host/path-policy.ts
 const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
 function validateRelativePath(value) {
@@ -1120,16 +1494,108 @@ function toRpcError(error) {
 	};
 }
 /** Run one host call and wrap its outcome or failure in the old envelope. */
-async function call(run) {
+/**
+* 一次内核 RPC 的**统一入口**：耗时统计 + 慢调用/失败日志。
+*
+* ## 为什么所有 RPC 都经过这一个函数
+*
+* 适配层有二十来条 RPC（sessions.list / history / prompt / models …），逐条埋点
+* 必然漂（有人加新方法时会忘）。这里是**唯一单点**：加一行就全覆盖。
+*
+* ## 为什么必须有一层超时
+*
+* 修复前 `call(run)` 不做任何超时，而 `run` 里的每次内核调用都用
+* `new AbortController().signal`（**永不 abort**）。于是内核侧一旦卡住：
+*
+* - 广播路径上那条 `sessions.list` 会把 `broadcastQueue` 永久堵住
+*   （整站事件停摆，`stop()` 也跟着挂）；
+* - 请求路径上那条会让 HTTP 连接一直挂着，客户端先超时、服务端资源不释放。
+*
+* 现在统一 10 秒上限。**注意语义**：超时被当作一次 RPC 失败（`code: 'rpc/timeout'`），
+* 由调用方决定怎么处理 —— 广播路径拿到 false 就「少推一条」，请求路径拿到 504。
+* 这比「无限等待」在任何情况下都更接近正确。
+*
+* @param name - 稳定的 RPC 名（如 `sessions.history`）。**不要**把 sessionId 拼进来，
+*   否则指标的基数会按会话数增长。
+* @param run - 真正的调用。它收到的 `signal` 已经带超时，应当传给宿主调用。
+* @param options.timeoutMs - 覆盖默认上限（流式/长任务可放宽，但**不能**设成无限）。
+*/
+async function call(name, run, options = {}) {
+	const startedAt = Date.now();
+	const timeoutMs = options.timeoutMs ?? RPC_TIMEOUT_MS;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`RPC ${name} timed out after ${timeoutMs}ms`)), timeoutMs);
+	timer.unref?.();
 	try {
-		return ok(await run());
+		const value = await run(controller.signal);
+		const elapsed = Date.now() - startedAt;
+		recordRpc(name, elapsed, true);
+		logSlowRpc(name, elapsed, true);
+		return ok(value);
 	} catch (error) {
+		const elapsed = Date.now() - startedAt;
+		recordRpc(name, elapsed, false);
+		logSlowRpc(name, elapsed, false);
+		if (controller.signal.aborted && isAbortLike(error)) return { result: {
+			ok: false,
+			error: {
+				code: "rpc/timeout",
+				message: `The host did not answer ${name} within ${timeoutMs}ms.`
+			}
+		} };
 		return { result: {
 			ok: false,
 			error: toRpcError(error)
 		} };
+	} finally {
+		clearTimeout(timer);
 	}
 }
+/** 默认 RPC 上限。10 秒：超过它基本可以断定内核卡了，而不是「慢」。 */
+const RPC_TIMEOUT_MS = 1e4;
+/**
+* 「查一下这个会话的工作目录 / 投影」这类**短查询**的上限。
+*
+* 比 [RPC_TIMEOUT_MS] 更紧，因为它们在 prompt 的同步前置里：用户按下发送之后
+* 要等它们回来（图才落盘、模型判定才完成）。让一个辅助查询拖 10 秒，
+* 用户已经认定「发不出去」了。
+*/
+const SESSION_DIR_LOOKUP_TIMEOUT_MS = 3e3;
+/**
+* 造一个**会自己到期**的 signal（并让它的定时器随 abort 一起清掉）。
+*
+* 为什么不在调用点写 `AbortSignal.timeout(ms)`：两者的过期行为一致，但这里需要
+* 「定时器不拖住进程退出」—— `AbortSignal.timeout` 内部没有 `unref`，
+* 在只剩它一个活跃句柄时会让进程多等三秒。这在本仓是已经踩过的纪律
+* （见 `server.ts` 的 `unref` 注释）。
+*/
+function timeoutSignal(ms) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`timed out after ${ms}ms`)), ms);
+	timer.unref?.();
+	controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+	return controller.signal;
+}
+/**
+* 慢调用 / 失败时打一条日志。
+*
+* 阈值 5 秒是刻意的：**正常**的内核调用都在毫秒级，5 秒说明真的出问题了；
+* 而每次都打日志会让热路径的日志量变成噪声（那反而更难看出问题）。
+*/
+function logSlowRpc(name, elapsedMs, okFlag) {
+	if (okFlag && elapsedMs < SLOW_RPC_LOG_MS) return;
+	const message = `dsh-0.2-bridge: rpc ${name} ${okFlag ? "slow" : "failed"}: ${elapsedMs}ms`;
+	console.warn(message);
+}
+const SLOW_RPC_LOG_MS = 5e3;
+/** 判断一个异常是不是「因为我们 abort 才抛」的（不同实现的 message 不一样）。 */
+function isAbortLike(error) {
+	if (error === null || typeof error !== "object") return false;
+	const candidate = error;
+	if (candidate.name === "AbortError") return true;
+	if (candidate.code === "ABORT_ERR") return true;
+	return typeof candidate.message === "string" && /abort/i.test(candidate.message);
+}
 /**
 * Replay-free fan-out of host facts into the `{ rpcId, payload }` frames the
 * old `apiProxy` streams produced. Subscribers only observe frames emitted
@@ -1150,8 +1616,23 @@ var FrameHub = class {
 		const queue = [];
 		let wake;
 		let closed = false;
+		/** 因队列满被丢掉的帧数（丢过就要告知消费方「事件流不连续」）。 */
+		let dropped = 0;
 		const onFrame = (frame) => {
 			if (closed) return;
+			if (queue.length >= FRAME_HUB_QUEUE_LIMIT) {
+				if (isRebuildableFrame(frame)) {
+					dropped += 1;
+					recordFrameHubDropped();
+					wake?.();
+					return;
+				}
+				const victim = queue.findIndex(isRebuildableFrame);
+				if (victim >= 0) queue.splice(victim, 1);
+				else queue.shift();
+				dropped += 1;
+				recordFrameHubDropped();
+			}
 			queue.push(frame);
 			wake?.();
 		};
@@ -1166,6 +1647,18 @@ var FrameHub = class {
 		return { async *[Symbol.asyncIterator]() {
 			try {
 				while (!closed && !signal.aborted) {
+					if (dropped > 0) {
+						const count = dropped;
+						dropped = 0;
+						yield {
+							rpcId: randomUUID(),
+							payload: {
+								type: "bridge/resync-required",
+								dropped: count,
+								reason: "backpressure"
+							}
+						};
+					}
 					if (queue.length === 0) {
 						await new Promise((resolve) => {
 							wake = resolve;
@@ -1182,6 +1675,24 @@ var FrameHub = class {
 	}
 };
 /**
+* `FrameHub` 每个消费者的队列上限。
+*
+* 与 `server.ts` 的 `DEFAULT_SOCKET_QUEUE_LIMIT` 同量级但**不必相等**：
+* 这一层是「内核帧 → 插件帧」的缓冲，消费方是本插件的 `startEvents` 循环；
+* 那一层是「插件事件 → WebSocket 帧」，消费方是网络。两层各有各的慢法。
+*/
+const FRAME_HUB_QUEUE_LIMIT = 1e3;
+/**
+* 这一帧丢了能不能重建。
+*
+* 只有流式文本增量可以（客户端重拉历史即得）。判据看**归一化后的 payload.type**：
+* `assistant/chunk` 会经 `normalizeDshEvent` 变成 `chat.message.delta`，
+* 而 `FrameHub` 处在归一化**之前**，所以两边都要认。
+*/
+function isRebuildableFrame(frame) {
+	return frame.payload["type"] === "assistant/chunk";
+}
+/**
 * Relays live session frames into the old `session/event` shape.
 *
 * 0.2.x has no process-wide session event stream: both durable events and the
@@ -1195,16 +1706,48 @@ var SessionEventRelay = class {
 	host;
 	mux;
 	limit;
+	warn;
+	/**
+	* 活跃订阅。**Map 的插入顺序就是 LRU 顺序**：命中/新建都先 delete 再 set，
+	* 于是最旧（最久没动过）的会话永远在队首 —— 淘汰时取第一个即可，不用另建链表。
+	*/
 	active = /* @__PURE__ */ new Map();
-	constructor(host, mux, limit = 8) {
+	constructor(host, mux, limit = 8, warn = () => void 0) {
 		this.host = host;
 		this.mux = mux;
 		this.limit = limit;
+		this.warn = warn;
 	}
-	/** Start following one session; idempotent per session. */
+	/**
+	* Start following one session; idempotent per session.
+	*
+	* ## 到上限时的行为（修复点）
+	*
+	* 此前是 `if (this.active.size >= this.limit) return` —— **静默**不订阅。
+	* 后果：第 9 个「正在跑」的会话**没有流式事件**，而两侧日志一句话都没有；
+	* 用户看到的现象是「这个会话不实时了」，与网络问题完全无法区分。
+	*
+	* 现在改为 **LRU 淘汰 + warn**：踢掉最久没被触碰的那条订阅，给新会话腾位置。
+	* 这比「拒绝新会话」更接近用户预期 —— 用户切到的那个会话正是他此刻在看的那条，
+	* 而被淘汰的那条通常已经不在屏幕上了（它的下一次 `attach` 会重新订阅，
+	* 代价只是「那段时间的增量要重拉历史」，而不是永久看不到）。
+	*
+	* 淘汰必须**有日志**：不然「我的旧会话为什么突然不流式了」永远查不出来。
+	*/
 	attach(sessionId) {
-		if (this.active.has(sessionId)) return;
-		if (this.active.size >= this.limit) return;
+		const existing = this.active.get(sessionId);
+		if (existing !== void 0) {
+			this.active.delete(sessionId);
+			this.active.set(sessionId, existing);
+			return;
+		}
+		if (this.active.size >= this.limit) {
+			const oldest = this.active.keys().next().value;
+			if (oldest !== void 0) {
+				this.warn(`dsh-0.2-bridge: session event relay is at its limit (${this.limit}); evicting the least recently used subscription (${oldest}) to follow ${sessionId}`);
+				this.detach(oldest);
+			}
+		}
 		const controller = new AbortController();
 		this.active.set(sessionId, controller);
 		this.pump(sessionId, controller.signal).catch(() => {
@@ -1313,13 +1856,26 @@ var ApprovalBridge = class {
 				const settle = (value) => {
 					if (done) return;
 					done = true;
+					clearTimeout(entry.timer);
 					resolve(value);
 				};
-				this.pending.set(rpcId, { settle });
+				const entry = {
+					settle,
+					timer: setTimeout(() => void 0, 0),
+					requestedAt: Date.now()
+				};
+				clearTimeout(entry.timer);
+				entry.timer = setTimeout(() => {
+					this.pending.delete(rpcId);
+					settle("delegate");
+				}, APPROVAL_PENDING_TIMEOUT_MS);
+				entry.timer.unref?.();
+				this.pending.set(rpcId, entry);
 				req.signal?.addEventListener("abort", () => {
 					this.pending.delete(rpcId);
 					if (done) return;
 					done = true;
+					clearTimeout(entry.timer);
 					resolve("delegate");
 				}, { once: true });
 				this.mux.push({
@@ -1365,6 +1921,39 @@ var ApprovalBridge = class {
 */
 const MAX_PENDING_QUESTIONS = 32;
 /**
+* 同时跟踪多少个「正在跑」的会话的事件流。
+*
+* 每一条都是一个 `follow()` 订阅，占一个文件描述符与一段内存；无上限的话，
+* 一个「同时跑 50 个会话」的机器会把 fd 耗光。8 是既有取值，本轮不调 ——
+* 本轮只把「到顶就静默丢弃」改成「LRU 淘汰 + 日志」。
+*/
+const SESSION_RELAY_LIMIT = 8;
+/**
+* 一条审批**最多挂起多久**（10 分钟）。
+*
+* 为什么必须有这个上限：`approval/request` 是一个等待承诺 —— 客户端通过
+* `respond()` 结算，宿主通过 `req.signal` 的 abort 结算。**两条都不发生时，
+* 这个 Promise 永不结算**，内核那一轮就永久阻塞，`pending` 条目也永远留着。
+*
+* 而「客户端永远不回答」在真实场景里并不罕见：手机被放进兜里、App 被杀、
+* 通知被划掉。修复前遇到这种情况，用户看到的是「agent 卡住不动了」，
+* 除了重启 dsh 没有别的出路。
+*
+* 为什么超时是 `delegate` 而**不是** `allowed-once`：把「没人回答」解释成
+* 「默认批准」等于让安全判据失效于一个定时器。`delegate` 让内核回到下游
+* （官方 WebUI）继续等，同时推一条 `approval/resolved` 让陈旧卡片消失 ——
+* 功能上「回到没有这个插件时的行为」，这才是正确的降级方向。
+*/
+const APPROVAL_PENDING_TIMEOUT_MS = 6e5;
+/**
+* 一条前台提问**最多挂起多久**（10 分钟，与审批同口径）。
+*
+* 提问不阻塞内核（Agent 已经继续跑），但它一样会吊着一个 Promise 与一条挂起表条目。
+* 超时按 `dismissed` 结算：推 `userQuestions/dismissed` 让手机端那张卡片消失，
+* 同时把 `delegate` 交给调用方 —— 与「用户点了电脑端」同一条收尾路径。
+*/
+const QUESTION_PENDING_TIMEOUT_MS = 6e5;
+/**
 * `user-questions/request` 的接管者 —— 形状照 [ApprovalBridge]。
 *
 * 为什么非接不可：`ask_user_question` 只有在**参数 schema 声明了 `timeout`** 时才走
@@ -1422,14 +2011,24 @@ var QuestionBridge = class {
 				const settle = (value) => {
 					if (done) return;
 					done = true;
+					clearTimeout(entry.timer);
 					resolve(value);
 				};
-				bridge.pending.set(rpcId, {
+				const entry = {
 					sessionId,
 					callId,
 					questions,
-					settle
-				});
+					settle,
+					timer: setTimeout(() => void 0, 0),
+					requestedAt: Date.now()
+				};
+				clearTimeout(entry.timer);
+				entry.timer = setTimeout(() => {
+					bridge.pending.delete(rpcId);
+					settle({ kind: "dismissed" });
+				}, QUESTION_PENDING_TIMEOUT_MS);
+				entry.timer.unref?.();
+				bridge.pending.set(rpcId, entry);
 				request?.signal?.addEventListener("abort", () => {
 					bridge.pending.delete(rpcId);
 					settle({ kind: "dismissed" });
@@ -1489,6 +2088,30 @@ var QuestionBridge = class {
 		};
 	}
 	/**
+	* 清扫**已经超期**的挂起项。
+	*
+	* 为什么还需要这个「批量清扫」，既然每条都有自己的定时器：
+	* 定时器是**正常**路径；清扫是**兜底**。两者都存在的理由与 `pending` 表的最小不变式
+	* 有关 —— 表里的每一条都必须「要么会被用户结算、要么会被超时结算、要么会被这里扫掉」。
+	* 少任何一条都会留下永久条目（那正是修复前的状态：只有用户结算这一条路）。
+	*
+	* 它按 `requestedAt` 判断而不是再挂一个计时器：调用方（适配层）可以在任意时机
+	* 顺手调一次，代价是 O(表中条目数)，而这个表被 `MAX_PENDING_QUESTIONS` 封在 32。
+	*
+	* @returns 被清掉多少条（供日志/测试断言）。
+	*/
+	sweepExpired(now = Date.now()) {
+		let swept = 0;
+		for (const [rpcId, entry] of this.pending) {
+			if (now - entry.requestedAt < QUESTION_PENDING_TIMEOUT_MS) continue;
+			this.pending.delete(rpcId);
+			clearTimeout(entry.timer);
+			entry.settle({ kind: "dismissed" });
+			swept += 1;
+		}
+		return swept;
+	}
+	/**
 	* 某会话当前挂起中的提问（供 `GET /questions` 合并）。
 	*
 	* `state` 刻意报 `'continued'`：客户端（dsh-companion 的 HarnessViewModel:1314）
@@ -1598,6 +2221,14 @@ function sessionIdOf(summary) {
 *   宁可落到私有目录也不能让「发消息」本身失败。
 */
 const DEFAULT_IMAGE_HANDOFF_DIR = join(homedir(), ".dsh", "image-handoff");
+/**
+* 交接图片读取的体积上限（32 MiB）。
+*
+* 与只读图片路由里的 `MAX_BYTES`（`image-handoff.ts`）**同值但不同职责**：
+* 那边是「浏览器要不要显示」，这边是「服务端要不要把字节读进内存」。
+* 这里必须**在读之前**判 —— 先读完再判等于闸门形同虚设。
+*/
+const MAX_HANDOFF_BYTES = 33554432;
 const IMAGE_EXTENSIONS = {
 	"image/png": "png",
 	"image/jpeg": "jpg",
@@ -1626,16 +2257,23 @@ function handoffExtension(mediaType, bytes) {
 * `relative` 是相对会话工作目录的短路径，给人看；`absolute` 给读图工具用。
 * 目录 0700、文件 0600：这些字节可能包含用户隐私。
 */
-function writeHandoffFile(dir, workspace, mediaType, data) {
+async function writeHandoffFile(dir, workspace, mediaType, data) {
 	const bytes = Buffer.from(data, "base64");
 	if (bytes.length === 0) throw new Error("EMPTY_IMAGE");
-	mkdirSync(dir, {
+	await mkdir(dir, {
 		recursive: true,
 		mode: 448
 	});
 	const fileName = `${createHash("sha256").update(bytes).digest("hex")}.${handoffExtension(mediaType, bytes)}`;
 	const absolute = join(dir, fileName);
-	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
+	try {
+		await writeFile(absolute, bytes, {
+			mode: 384,
+			flag: "wx"
+		});
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+	}
 	return {
 		absolute,
 		relative: workspace !== void 0 && absolute.startsWith(workspace + sep) ? absolute.slice(workspace.length + 1).split(sep).join("/") : fileName
@@ -1665,10 +2303,21 @@ async function readHandoffImageFile(host, roots, fallbackDir, subdir, sessionId,
 	const ext = (match[1] ?? "").toLowerCase();
 	const mediaType = HANDOFF_MEDIA_TYPES[ext] ?? "application/octet-stream";
 	const workspace = await sessionWorkspaceDir(host, roots, sessionId);
-	const target = [...workspace !== void 0 ? [join(workspace, subdir, fileName)] : [], join(fallbackDir, fileName)].find((candidate) => existsSync(candidate));
+	const candidates = [...workspace !== void 0 ? [join(workspace, subdir, fileName)] : [], join(fallbackDir, fileName)];
+	let target;
+	let size = 0;
+	for (const candidate of candidates) try {
+		const info = await stat(candidate);
+		if (!info.isFile()) continue;
+		target = candidate;
+		size = info.size;
+		break;
+	} catch {}
 	if (target === void 0) throw new Error("HANDOFF_IMAGE_NOT_FOUND");
+	if (size === 0) throw new Error("HANDOFF_IMAGE_EMPTY");
+	if (size > MAX_HANDOFF_BYTES) throw new Error("HANDOFF_IMAGE_TOO_LARGE");
 	return {
-		bytes: new Uint8Array(readFileSync(target)),
+		bytes: new Uint8Array(await readFile(target)),
 		mediaType
 	};
 }
@@ -1681,7 +2330,7 @@ async function readHandoffImageFile(host, roots, fallbackDir, subdir, sessionId,
 */
 async function sessionWorkspaceDir(host, roots, sessionId) {
 	if (roots.length === 0) return void 0;
-	const item = (await host.sessionController.list({}, new AbortController().signal)).items?.find((entry) => entry.sessionId === sessionId);
+	const item = (await host.sessionController.list({}, timeoutSignal(SESSION_DIR_LOOKUP_TIMEOUT_MS))).items?.find((entry) => entry.sessionId === sessionId);
 	const cwd = typeof item?.cwd === "string" ? item.cwd : void 0;
 	if (cwd === void 0) return void 0;
 	for (const root of roots) {
@@ -1812,7 +2461,7 @@ async function readSessionProjections(host, sessionId, signal) {
 }
 /** 会话当前生效的模型（pending > lastUsed > 目录默认），取不到返回 undefined。 */
 async function currentModelSelection(host, sessionId) {
-	const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
+	const selection = (await host.sessionController.projections({ sessionId }, timeoutSignal(SESSION_DIR_LOOKUP_TIMEOUT_MS)))?.values?.["modelSelection"];
 	const catalog = await host.sessionController.modelCatalog();
 	const current = selection?.next ?? selection?.lastUsed ?? catalog.default;
 	const provider = current?.provider;
@@ -1866,16 +2515,22 @@ async function handoffImagesForTextOnlyModel(host, roots, fallbackDir, subdir, l
 		const workspace = await sessionWorkspaceDir(host, roots, sessionId);
 		const dir = workspace !== void 0 ? join(workspace, subdir) : fallbackDir;
 		let index = 0;
-		return content.map((part) => {
-			if (part.type !== "image") return part;
+		const mapped = [];
+		for (const part of content) {
+			if (part.type !== "image") {
+				mapped.push(part);
+				continue;
+			}
 			index += 1;
-			const { absolute, relative } = writeHandoffFile(dir, workspace, part.mediaType, part.data);
+			const { absolute, relative } = await writeHandoffFile(dir, workspace, part.mediaType, part.data);
 			const name = typeof part.name === "string" && part.name.trim() !== "" ? part.name.trim() : locale === "en" ? `image ${index}` : `图片 ${index}`;
-			return {
+			const text = [handoffLine(index, name, relative, locale), `[Image: source: ${absolute}]`].join("\n");
+			mapped.push({
 				type: "text",
-				text: [handoffLine(index, name, relative, locale), `[Image: source: ${absolute}]`].join("\n")
-			};
-		});
+				text
+			});
+		}
+		return mapped;
 	} catch {
 		return content;
 	}
@@ -1921,7 +2576,9 @@ function createDsh02ApiProxy(host, options = {}) {
 	approvals.attach();
 	const questions = new QuestionBridge(host, mux);
 	questions.attach();
-	const relay = new SessionEventRelay(host, mux);
+	const relay = new SessionEventRelay(host, mux, SESSION_RELAY_LIMIT, (message) => {
+		console.warn(message);
+	});
 	host.on("api-session/added", (summary) => {
 		const sessionId = sessionIdOf(summary);
 		if (sessionId === void 0) return;
@@ -1983,18 +2640,20 @@ function createDsh02ApiProxy(host, options = {}) {
 	return {
 		respond: (message) => approvals.respond(message),
 		sessions: {
-			list: (request) => call(async () => {
-				const page = await host.sessionController.list(request.payload, new AbortController().signal);
+			list: (request) => call("sessions.list", async (signal) => {
+				const page = await host.sessionController.list(request.payload, signal);
 				const items = Array.isArray(page.items) ? page.items.filter((item) => item.origin !== "subagent") : page.items;
 				return {
 					...page,
 					items
 				};
 			}),
-			create: (request) => call(() => host.sessionController.create(request.payload)),
-			history: (request) => call(async () => {
+			create: (request) => call("sessions.create", (signal) => host.sessionController.create(request.payload)),
+			history: (request) => call("sessions.history", async (signal) => {
 				const { sessionId, maxMessages, beforeSeq } = request.payload;
 				const controller = new AbortController();
+				if (signal.aborted) controller.abort();
+				else signal.addEventListener("abort", () => controller.abort(), { once: true });
 				try {
 					const snapshot = (await host.sessionController.follow({
 						address: {
@@ -2033,7 +2692,7 @@ function createDsh02ApiProxy(host, options = {}) {
 					controller.abort();
 				}
 			}),
-			prompt: (request) => call(async () => {
+			prompt: (request) => call("sessions.prompt", async (signal) => {
 				const requestId = randomUUID();
 				const { locale, ...kernelPayload } = request.payload;
 				const receiptIds = request.payload.content.filter((part) => part.type === "file").map((part) => part.receiptId);
@@ -2046,22 +2705,22 @@ function createDsh02ApiProxy(host, options = {}) {
 					requestId,
 					...kernelPayload,
 					content
-				}, new AbortController().signal);
+				}, signal);
 				binding?.commit();
 				return { accepted: true };
 			}),
-			uploadAttachment: (request) => call(async () => {
+			uploadAttachment: (request) => call("sessions.uploadAttachment", async (signal) => {
 				const { sessionId, data, name } = request.payload;
 				if (fileUploadService == null) throw new Error("FILE_UPLOADS_UNAVAILABLE: this DSH build provides no ctx.fileUploads service, so file attachments cannot be sent");
 				return {
 					receiptId: (await fileUploadService.upload(await agentFor(sessionId), name === void 0 || name === "" ? { data } : {
 						data,
 						name
-					}, new AbortController().signal)).receiptId,
+					}, signal)).receiptId,
 					name: name ?? null
 				};
 			}),
-			readAttachment: (request) => call(async () => {
+			readAttachment: (request) => call("sessions.readAttachment", async (signal) => {
 				const { sessionId, attachmentId } = request.payload;
 				const value = await host.sessionController.attachment({
 					sessionId,
@@ -2072,20 +2731,20 @@ function createDsh02ApiProxy(host, options = {}) {
 					mediaType: value.attachment.mediaType
 				};
 			}),
-			readHandoffImage: (request) => call(async () => {
+			readHandoffImage: (request) => call("sessions.readHandoffImage", async (signal) => {
 				const { sessionId, name } = request.payload;
 				return readHandoffImageFile(host, handoffRootsOf(), imageHandoffDir, handoffSubdirOf(), sessionId, name);
 			}),
-			cancel: (request) => call(() => host.sessionController.cancel(request.payload)),
-			rename: (request) => call(() => host.sessionController.rename(request.payload)),
-			fork: (request) => call(() => host.sessionController.fork(request.payload)),
-			models: (request) => call(async () => {
+			cancel: (request) => call("sessions.cancel", (signal) => host.sessionController.cancel(request.payload)),
+			rename: (request) => call("sessions.rename", (signal) => host.sessionController.rename(request.payload)),
+			fork: (request) => call("sessions.fork", (signal) => host.sessionController.fork(request.payload)),
+			models: (request) => call("sessions.models", async (signal) => {
 				const { sessionId } = request.payload;
 				try {
 					await host.sessionController.resolveAgent(sessionId);
 				} catch {}
 				const catalog = await host.sessionController.modelCatalog();
-				const selection = (await host.sessionController.projections({ sessionId }, new AbortController().signal))?.values?.["modelSelection"];
+				const selection = (await host.sessionController.projections({ sessionId }, signal))?.values?.["modelSelection"];
 				return {
 					current: selection?.next ?? selection?.lastUsed ?? catalog.default,
 					routable: Array.isArray(catalog.routableProviders) && catalog.routableProviders.length > 0,
@@ -2096,10 +2755,10 @@ function createDsh02ApiProxy(host, options = {}) {
 					})) : []
 				};
 			}),
-			selectModel: (request) => call(() => host.sessionController.selectModel(request.payload))
+			selectModel: (request) => call("sessions.selectModel", (signal) => host.sessionController.selectModel(request.payload))
 		},
 		workspace: {
-			list: () => call(async () => {
+			list: () => call("workspace.list", async (signal) => {
 				return {
 					items: host.workspaceRegistry.list().map((row) => ({
 						workspaceId: row.id,
@@ -2112,16 +2771,16 @@ function createDsh02ApiProxy(host, options = {}) {
 					archivedSessionIds: readArchivedSessionIds(host.workspaceRegistry)
 				};
 			}),
-			create: (request) => call(() => host.workspaceController.create(request.payload)),
-			rename: (request) => call(() => host.workspaceController.rename(request.payload)),
-			delete: (request) => call(async () => {
+			create: (request) => call("workspace.create", (signal) => host.workspaceController.create(request.payload)),
+			rename: (request) => call("workspace.rename", (signal) => host.workspaceController.rename(request.payload)),
+			delete: (request) => call("workspace.delete", async (signal) => {
 				await host.workspaceController.delete(request.payload);
 				return { deleted: true };
 			}),
-			archiveSession: (request) => call(() => host.workspaceController.archiveSession(request.payload))
+			archiveSession: (request) => call("workspace.archiveSession", (signal) => host.workspaceController.archiveSession(request.payload))
 		},
 		agentPresets: {
-			list: () => call(async () => {
+			list: () => call("agentPresets.list", async (signal) => {
 				const withTrust = (rows) => rows.map((row) => ({
 					...row,
 					trust: row.trust ?? "system"
@@ -2141,19 +2800,19 @@ function createDsh02ApiProxy(host, options = {}) {
 					hasDocument: false
 				};
 			}),
-			select: (request) => call(async () => {
+			select: (request) => call("agentPresets.select", async (signal) => {
 				const agent = await agentFor(request.payload.sessionId);
 				return { agentPreset: await host.agentPresets.select(agent, request.payload.agentPreset) };
 			})
 		},
-		permissionPresets: { catalog: () => call(async () => {
+		permissionPresets: { catalog: () => call("permissionPresets.catalog", async (signal) => {
 			const service = optionalService(host, "permissionPresets");
 			if (service === null || typeof service.catalog !== "function") return FALLBACK_PERMISSION_CATALOG;
 			return normalizePermissionCatalog(await service.catalog());
 		}) },
 		userQuestions: {
 			pendingAll: () => questions.pendingAll(),
-			list: (request) => call(async () => {
+			list: (request) => call("userQuestions.list", async (signal) => {
 				const { sessionId } = request.payload;
 				const bridged = questions.pendingFor(sessionId);
 				const bridgedIds = new Set(bridged.map((item) => item.callId));
@@ -2165,7 +2824,7 @@ function createDsh02ApiProxy(host, options = {}) {
 				const continued = Array.isArray(rows) ? rows.map(toUserQuestionView).filter((item) => item !== void 0) : [];
 				return { items: [...bridged, ...continued.filter((item) => !bridgedIds.has(item.callId))] };
 			}),
-			answer: (request) => call(async () => {
+			answer: (request) => call("userQuestions.answer", async (signal) => {
 				const { sessionId, callId, answer } = request.payload;
 				const agent = await agentForQuestions(sessionId);
 				let kernelCouldNotAnswer = false;
@@ -2212,24 +2871,24 @@ function createDsh02ApiProxy(host, options = {}) {
 			})
 		},
 		settings: {
-			describe: () => call(() => host.settingsController.describe()),
-			mutate: (request) => call(() => host.settingsController.mutate(request.payload.ns, request.payload.ops, request.payload.expectedRevision))
+			describe: () => call("settings.describe", (signal) => host.settingsController.describe()),
+			mutate: (request) => call("settings.mutate", (signal) => host.settingsController.mutate(request.payload.ns, request.payload.ops, request.payload.expectedRevision))
 		},
 		credentials: {
-			describe: (request) => call(async () => {
+			describe: (request) => call("credentials.describe", async (signal) => {
 				return { credentials: await host.credentialsController.describe(request.payload.refs) };
 			}),
-			set: (request) => call(async () => {
+			set: (request) => call("credentials.set", async (signal) => {
 				await host.credentialsController.set(request.payload.ref, request.payload.value);
 				return {};
 			}),
-			unset: (request) => call(async () => {
+			unset: (request) => call("credentials.unset", async (signal) => {
 				await host.credentialsController.unset(request.payload.ref);
 				return {};
 			})
 		},
 		llm: {
-			providers: () => call(async () => {
+			providers: () => call("llm.providers", async (signal) => {
 				const directory = host.llm.listConfigurableProviders();
 				const live = new Set(host.llm.listProviders().map((entry) => entry.id));
 				return { providers: directory.map((entry) => ({
@@ -2247,14 +2906,14 @@ function createDsh02ApiProxy(host, options = {}) {
 					} }
 				})) };
 			}),
-			models: () => call(async () => {
+			models: () => call("llm.models", async (signal) => {
 				const view = await host.sessionController.modelCatalog();
 				return {
 					groups: Array.isArray(view.groups) ? view.groups : [],
 					failures: Array.isArray(view.failures) ? view.failures : []
 				};
 			}),
-			discoverModels: (request) => call(async () => {
+			discoverModels: (request) => call("llm.discoverModels", async (signal) => {
 				const { settingsNs, ...rest } = request.payload;
 				return { models: [...await host.llm.discoverModels(settingsNs, rest)] };
 			})
@@ -2267,7 +2926,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.5.1";
+const PLUGIN_VERSION = "2.5.2";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -2298,7 +2957,8 @@ const PLUGIN_VERSION = "2.5.1";
 *    `approvals-v1` / `questions-v1`（`dsh-companion` 的 `REQUIRED_CAPABILITIES`：
 *    缺了就明说「插件过旧、卡片不会出现」）与 `session-archive-list-v1`
 *    （决定会话面板是否显示「已归档」入口）。
-* 2. **对外声明** —— 其余 23 项。它们回答的是「这台服务端能做什么」，
+* 2. **对外声明** —— 其余所有能力位（数量以本文件数组为准，勿在注释里写数字，
+*    加一个位就要改注释的纪律只会让注释过期）。它们回答的是「这台服务端能做什么」，
 *    **服务的是任何客户端（包括第三方）**，而不是某一处分支。
 *
 * 所以：**「我方客户端没用到」不等于「没人用」**。删掉第 2 类会破坏对外承诺
@@ -2351,15 +3011,50 @@ const BRIDGE_CAPABILITIES = [
 	"job-kill-v1"
 ];
 /**
+* 运行时**不可用**的能力位：服务端此刻做不了这些事，就不该声明。
+*
+* ## 为什么必须过滤（这是本节最重要的一条）
+*
+* 能力位的全部意义是让客户端把「服务端不支持」与「本来就没有」分开
+* （见文件头的说明）。而 `jobController` 是**可选宿主服务**：0.2.0-rc.2 上没有它，
+* 三个 `/jobs` 端点在那套内核上根本不会被挂载（`index.ts` 直接不下发，路由返回 404）。
+* 若 `connection.ready` 仍然宣告 `job-list-v1`，客户端按位探测后就会去打一个必然
+* 404 的端点 —— 这恰好是这份清单本身想消灭的那种「静默少一个功能」。
+*
+* ## 为什么按「能力位 → 依赖的服务」映射，而不是在调用点手写过滤
+*
+* 声明与端点必须**同源**。把「哪个位依赖哪个可选服务」写在一处，将来再加一个
+* 可选服务只需要在这里补一行；散在调用点就会漂。
+*/
+const CAPABILITY_REQUIREMENTS = {
+	"job-list-v1": "jobs",
+	"job-output-v1": "jobs",
+	"job-kill-v1": "jobs"
+};
+/**
+* 这台进程此刻真的能提供的能力位。
+*
+* @param flags - 运行时可用性；**缺省当作「全都可用」**。
+*   缺省必须保守地全给：测试替身与老调用点（不传参）拿到的仍是完整清单，
+*   行为与加参数之前一字不差 —— 否则这个改动会悄悄改掉所有既有测试的期望。
+*/
+function availableCapabilities(flags = {}) {
+	return BRIDGE_CAPABILITIES.filter((capability) => {
+		const requirement = CAPABILITY_REQUIREMENTS[capability];
+		if (requirement === void 0) return true;
+		return flags[requirement] !== false;
+	});
+}
+/**
 * `connection.ready` 事件的载荷。
 *
 * 每次调用返回**新的副本**：调用方（或测试）改它不该影响常量，
 * 否则一处手滑就会让整个进程后续所有连接都收到被改过的能力清单。
 */
-function connectionReadyData() {
+function connectionReadyData(flags = {}) {
 	return {
 		bridgeVersion: PLUGIN_VERSION,
-		capabilities: [...BRIDGE_CAPABILITIES]
+		capabilities: availableCapabilities(flags)
 	};
 }
 //#endregion
@@ -2477,25 +3172,39 @@ function clampStrings(value, limit, seen) {
 */
 function clampHistoryEvents(events, byteBudget = HISTORY_BYTE_BUDGET, perEventBudget = HISTORY_EVENT_BYTE_BUDGET) {
 	let clampedStrings = 0;
-	const prepared = events.map((entry) => {
-		if (byteLength(entry) <= perEventBudget) return entry;
+	const sizes = new Array(events.length);
+	const prepared = new Array(events.length);
+	for (let index = 0; index < events.length; index += 1) {
+		const entry = events[index];
+		const size = byteLength(entry);
+		if (size <= perEventBudget) {
+			sizes[index] = size;
+			prepared[index] = entry;
+			continue;
+		}
 		const result = clampStrings(entry, perEventBudget, /* @__PURE__ */ new WeakSet());
-		if (result.clamped === 0) return entry;
+		if (result.clamped === 0) {
+			sizes[index] = size;
+			prepared[index] = entry;
+			continue;
+		}
 		clampedStrings += result.clamped;
 		const marker = { truncated: true };
 		const clampedValue = result.value;
-		return clampedValue !== null && typeof clampedValue === "object" && !Array.isArray(clampedValue) ? {
+		const marked = clampedValue !== null && typeof clampedValue === "object" && !Array.isArray(clampedValue) ? {
 			...clampedValue,
 			bridgeTruncated: marker
 		} : {
 			value: clampedValue,
 			bridgeTruncated: marker
 		};
-	});
+		prepared[index] = marked;
+		sizes[index] = byteLength(marked);
+	}
 	const kept = [];
 	let bytes = 0;
 	for (let index = prepared.length - 1; index >= 0; index -= 1) {
-		const size = byteLength(prepared[index]);
+		const size = sizes[index] ?? 0;
 		if (kept.length > 0 && bytes + size > byteBudget) break;
 		bytes += size;
 		kept.push(prepared[index]);
@@ -2531,10 +3240,49 @@ function applyHistoryBudget(raw, byteBudget = HISTORY_BYTE_BUDGET, perEventBudge
 }
 //#endregion
 //#region src/host/chat-adapter.ts
+/** 会话可见性缓存的 TTL（见 `DshChatAdapter.sessionVisibility` 的说明）。 */
+const SESSION_VISIBILITY_TTL_MS = 2e3;
+/** 可见性缓存条目上限；到顶就按 TTL 清一遍（见 `rememberVisibility`）。 */
+const SESSION_VISIBILITY_CACHE_LIMIT = 2048;
+/**
+* 把 principal 收敛成一个稳定的缓存键。
+*
+* 为什么不用 `JSON.stringify(principal)`：`rootIds` 是 `Set`（序列化出来是 `{}`，
+* 所有设备会撞成同一个键 —— 那就是越权）。这里只用**身份**部分，
+* 授权范围的变化由 TTL 与 `sessionRootId` 那条独立缓存兜住。
+*/
+function principalKey(principal) {
+	return principal.kind === "admin" ? "admin" : `device:${principal.id}`;
+}
 var DshChatAdapter = class {
 	api;
 	database;
 	commandServices;
+	/**
+	* 会话 → 可见性快照的短 TTL 缓存。
+	*
+	* ## 为什么需要（这是本文件最热的一处浪费）
+	*
+	* `requireSession()` 会在**几乎每个** API 调用里跑一遍 `listSessions()`，
+	* 而 `listSessions` 一次要打两次内核 RPC（`sessions.list` + `workspace.list`）
+	* 加一次 `database.listRoots()`。也就是说 history / commands / approvals /
+	* models / questions / prompt 每条请求都白花两次内核往返 —— 只为回答
+	* 「这个 session 能不能被这台设备看见」。
+	*
+	* ## 为什么 TTL 是 2 秒（短到近乎无感，长到足以省掉重复）
+	*
+	* 客户端在打开一个会话时会**连续**打四五个接口（历史、审批、提问、命令、模型），
+	* 2 秒足以把这一串并成一两次真实查询。再长就会让「刚建的会话看不到」
+	* 变成一个可感受到的延迟 —— 而那正是我们要避免的另一类 bug。
+	*
+	* ## 缓存的是什么（关键：缓存的是**授权结论**，不是会话内容）
+	*
+	* 只缓存「这个 sessionId 对当前设备可见吗」这一个布尔结论，且按 `principal.id`
+	* 分桶。**不缓存会话正文**：正文会被 `rename`/`archive`/新消息改掉，
+	* 缓存它等于制造陈旧数据；而可见性只随「根授权变没变」与「会话删没删」变，
+	* 两者都是低频且由用户操作驱动的。
+	*/
+	sessionVisibility = /* @__PURE__ */ new Map();
 	sessionRootIds = /* @__PURE__ */ new Map();
 	sessionRootLookups = /* @__PURE__ */ new Map();
 	pendingApprovals = /* @__PURE__ */ new Map();
@@ -3028,8 +3776,13 @@ var DshChatAdapter = class {
 		}
 	}
 	async isSessionAuthorized(principal, sessionId) {
+		const key = `${principalKey(principal)}\u0000${sessionId}`;
+		const cached = this.sessionVisibility.get(key);
+		if (cached !== void 0 && Date.now() - cached.visibleAt < SESSION_VISIBILITY_TTL_MS) return cached.visible;
 		const rootId = await this.sessionRootId(sessionId);
-		return rootId !== void 0 && (principal.rootIds === "all" || principal.rootIds.has(rootId));
+		const allowed = rootId !== void 0 && (principal.rootIds === "all" || principal.rootIds.has(rootId));
+		this.rememberVisibility(key, allowed);
+		return allowed;
 	}
 	startEvents(signal, emit) {
 		const run = async (kind) => {
@@ -3092,10 +3845,37 @@ var DshChatAdapter = class {
 		return services.agents.get(sessionId);
 	}
 	async requireSession(principal, sessionId) {
+		const key = `${principalKey(principal)}\u0000${sessionId}`;
+		const cached = this.sessionVisibility.get(key);
+		if (cached !== void 0 && Date.now() - cached.visibleAt < SESSION_VISIBILITY_TTL_MS) {
+			if (cached.visible) {
+				const session = (await this.listSessions(principal)).find((item) => item.id === sessionId);
+				if (session !== void 0) return session;
+				this.sessionVisibility.delete(key);
+			} else throw new ApiError(404, "SESSION_NOT_FOUND", "The session is not visible to this device.");
+		}
 		const session = (await this.listSessions(principal)).find((item) => item.id === sessionId);
+		this.rememberVisibility(key, session !== void 0);
 		if (session === void 0) throw new ApiError(404, "SESSION_NOT_FOUND", "The session is not visible to this device.");
 		return session;
 	}
+	/**
+	* 记一条可见性结论，并顺手把过期条目清掉。
+	*
+	* 为什么在这里做清扫而不是定时器：缓存条目数与「设备数 × 会话数」同阶，
+	* 对单机部署来说是千级 —— 每次写入顺手扫一遍完全够，而且**没有定时器泄漏**。
+	* （本仓的纪律：服务端不引入 `setInterval`，见 `server.ts` 的心跳是唯一的例外，
+	* 且它 `unref` 过。）
+	*/
+	rememberVisibility(key, visible) {
+		const now = Date.now();
+		this.sessionVisibility.set(key, {
+			visibleAt: now,
+			visible
+		});
+		if (this.sessionVisibility.size < SESSION_VISIBILITY_CACHE_LIMIT) return;
+		for (const [entryKey, entry] of this.sessionVisibility) if (now - entry.visibleAt >= SESSION_VISIBILITY_TTL_MS) this.sessionVisibility.delete(entryKey);
+	}
 	async requireWorkspace(principal, workspaceId) {
 		const workspace = (await this.listWorkspaces(principal)).find((item) => item.id === workspaceId);
 		if (workspace === void 0) throw new ApiError(404, "WORKSPACE_NOT_FOUND", "The DSH workspace is not visible to this device.");
@@ -3511,15 +4291,42 @@ var WorkspaceDatabase = class {
 	trashDir;
 	db;
 	closed = false;
-	constructor(dataDir) {
-		this.dataDir = path.resolve(dataDir);
-		this.trashDir = path.join(this.dataDir, "trash");
-		mkdirSync(this.trashDir, { recursive: true });
-		this.db = new DatabaseSync(path.join(this.dataDir, "workspace.sqlite"));
-		this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
+	/**
+	* 「设备集合或设备权限发生过写」的进程内单调计数。
+	*
+	* ## 为什么需要它
+	*
+	* WebSocket 广播的每一条事件都要确认「这条连接背后的设备还有效吗、scope/root 变了吗」
+	* —— 旧实现是**每条事件查一次库**（`getActiveDevice`）。多条连接 × 持续事件
+	* 就是成百次纯浪费的 SQLite 查询。
+	*
+	* 有了这个计数，`server.ts` 可以只在**它变了**的时候重新水化设备
+	* （特性探测：getter 不存在就退回逐事件查库，所以迟到或缺席都不会更差）。
+	*
+	* ## 语义（与 perf-reader 的 PERF-1 契约一致）
+	*
+	* 「任何改变**设备是否存在 / scope / rootIds** 的写」都要 +1。当前四处：
+	* `exchangePairing` / `updateDevice` / `revokeDevice` / `purgeRevokedDevices`。
+	*
+	* 根（roots）的增删**不** +1：设备记录本身没变；`/roots` 那条路径本来就是实时查库。
+	*
+	* 保守性：宁可多 +1（多一次缓存失效，代价是一次查询），不可漏 +1
+	* （漏了就是「撤销后仍能收事件」—— 那正是 `device-revocation` 要防的事）。
+	*/
+	devicesRevisionCounter = 0;
+	constructor(dataDir) {
+		this.dataDir = path.resolve(dataDir);
+		this.trashDir = path.join(this.dataDir, "trash");
+		mkdirSync(this.trashDir, { recursive: true });
+		this.db = new DatabaseSync(path.join(this.dataDir, "workspace.sqlite"));
+		this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
 		this.migrate();
 		openDatabases.add(new WeakRef(this));
 	}
+	/** 当前设备状态版本号。用途见字段注释（`server.ts` 的广播缓存失效）。 */
+	get devicesRevision() {
+		return this.devicesRevisionCounter;
+	}
 	/** 关闭数据库。**幂等** —— 重复调用不抛错。 */
 	close() {
 		if (this.closed) return;
@@ -3543,6 +4350,13 @@ var WorkspaceDatabase = class {
 	setSetting(key, value) {
 		this.db.prepare("INSERT INTO settings(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(key, value);
 	}
+	/**
+	* 登记一条授权根。
+	*
+	* @param options.requestId - 发起这次登记的那条 HTTP 请求的 id。
+	*   审计的用途不只是「记下发生了什么」，还要能回答「**哪一次请求**干的」；
+	*   不传（插件启动期登记内置根）时审计行的 `request_id` 为 null。
+	*/
 	async addRoot(inputPath, label, options) {
 		const realPath = await canonicalRoot(inputPath);
 		if (options?.allowDuplicate !== true) {
@@ -3553,7 +4367,7 @@ var WorkspaceDatabase = class {
 		const createdAt = Date.now();
 		const resolvedLabel = label?.trim() || path.basename(realPath) || realPath;
 		this.db.prepare("INSERT INTO roots(id,label,real_path,created_at,builtin) VALUES(?,?,?,?,0)").run(id, resolvedLabel, realPath, createdAt);
-		this.audit("admin", "loopback-admin", "root.add", id, void 0, { label: resolvedLabel });
+		this.audit("admin", "loopback-admin", "root.add", id, void 0, { label: resolvedLabel }, options?.requestId);
 		return {
 			id,
 			label: resolvedLabel,
@@ -3611,7 +4425,12 @@ var WorkspaceDatabase = class {
 		if (this.db.prepare("DELETE FROM roots WHERE id = ?").run(id).changes === 0) throw new ApiError(404, "ROOT_NOT_FOUND", "The authorized root does not exist.");
 		this.audit("admin", "loopback-admin", "root.remove", id);
 	}
-	createPairing(rootIds, scopes, ttlMs = 6e5) {
+	/**
+	* 生成一枚配对码。
+	*
+	* @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+	*/
+	createPairing(rootIds, scopes, ttlMs = 6e5, options = {}) {
 		assertScopes(scopes);
 		for (const rootId of rootIds) if (this.getRoot(rootId) === void 0) throw new ApiError(404, "ROOT_NOT_FOUND", `Unknown root ${rootId}.`);
 		const raw = randomBytes(5).toString("hex").toUpperCase();
@@ -3622,13 +4441,20 @@ var WorkspaceDatabase = class {
 			rootIds,
 			scopes,
 			expiresAt
-		});
+		}, options.requestId);
 		return {
 			code,
 			expiresAt
 		};
 	}
-	exchangePairing(code, deviceName) {
+	/**
+	* 用配对码换一枚设备令牌。
+	*
+	* 审计**在事务内**写（FUNC-5）：它是「这台设备被授权了」的唯一留痕，
+	* 与设备行同生共死。审计写不进去 → 整个兑换回滚 → 客户端重试，
+	* 而不是「拿到令牌但库里没有这笔授权的记录」。
+	*/
+	exchangePairing(code, deviceName, options = {}) {
 		const normalized = normalizePairingCode(code);
 		const now = Date.now();
 		this.db.exec("BEGIN IMMEDIATE");
@@ -3644,18 +4470,18 @@ var WorkspaceDatabase = class {
 			this.db.prepare("INSERT INTO devices(id,name,token_hash,scopes_json,created_at) VALUES(?,?,?,?,?)").run(id, name, hashSecret(token), JSON.stringify(scopes), now);
 			const grant = this.db.prepare("INSERT INTO device_roots(device_id,root_id) VALUES(?,?)");
 			for (const rootId of rootIds) grant.run(id, rootId);
+			this.audit("device", id, "pairing.exchange", void 0, void 0, { name }, options.requestId);
 			this.db.exec("COMMIT");
-			const device = {
-				id,
-				name,
-				scopes,
-				rootIds,
-				createdAt: now
-			};
-			this.audit("device", id, "pairing.exchange", void 0, void 0, { name });
+			this.devicesRevisionCounter += 1;
 			return {
 				token,
-				device
+				device: {
+					id,
+					name,
+					scopes,
+					rootIds,
+					createdAt: now
+				}
 			};
 		} catch (error) {
 			this.db.exec("ROLLBACK");
@@ -3701,7 +4527,16 @@ var WorkspaceDatabase = class {
 	isDeviceActive(id) {
 		return this.db.prepare("SELECT 1 AS active FROM devices WHERE id = ? AND revoked_at IS NULL").get(id) !== void 0;
 	}
-	updateDevice(id, scopes, rootIds) {
+	/**
+	* 改一台设备的 scope 与 root 授权。
+	*
+	* 审计**在事务内**写（FUNC-5）：它是「谁的权限被扩大了」的唯一留痕。
+	* 审计失败 → 整个更新回滚。宁可让用户重试，也不能出现「权限已经变宽、
+	* 但没有任何记录说是谁在什么时候改的」—— 那是不可审计的提权。
+	*
+	* @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+	*/
+	updateDevice(id, scopes, rootIds, options = {}) {
 		assertScopes(scopes);
 		for (const rootId of rootIds) if (this.getRoot(rootId) === void 0) throw new ApiError(404, "ROOT_NOT_FOUND", `Unknown root ${rootId}.`);
 		this.db.exec("BEGIN IMMEDIATE");
@@ -3710,16 +4545,17 @@ var WorkspaceDatabase = class {
 			this.db.prepare("DELETE FROM device_roots WHERE device_id = ?").run(id);
 			const grant = this.db.prepare("INSERT INTO device_roots(device_id,root_id) VALUES(?,?)");
 			for (const rootId of rootIds) grant.run(id, rootId);
+			this.audit("admin", "loopback-admin", "device.update", void 0, void 0, {
+				deviceId: id,
+				scopes,
+				rootIds
+			}, options.requestId);
 			this.db.exec("COMMIT");
 		} catch (error) {
 			this.db.exec("ROLLBACK");
 			throw error;
 		}
-		this.audit("admin", "loopback-admin", "device.update", void 0, void 0, {
-			deviceId: id,
-			scopes,
-			rootIds
-		});
+		this.devicesRevisionCounter += 1;
 		const device = this.listDevices().find((item) => item.id === id);
 		if (device === void 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The device does not exist.");
 		return device;
@@ -3737,14 +4573,31 @@ var WorkspaceDatabase = class {
 	* - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
 	*   它们依然登不进来 —— 两层保险不冲突。
 	*/
-	revokeDevice(id) {
+	/**
+	* 撤销一台设备 = 删除设备行。
+	*
+	* 审计与删除**在同一事务里**（FUNC-5），且顺序是「先留痕、再删除」：
+	* 审计的 `actor_id` 不带外键，删设备不会把记录带走。反过来若先删后写、
+	* 而写审计失败，就会留下「设备已经没了，但没有任何记录说谁撤的」。
+	*
+	* @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+	*/
+	revokeDevice(id, options = {}) {
 		const active = this.getActiveDevice(id);
 		if (active === void 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
-		this.audit("admin", "loopback-admin", "device.revoke", void 0, void 0, {
-			deviceId: id,
-			name: active.name
-		});
-		if (this.db.prepare("DELETE FROM devices WHERE id = ?").run(id).changes === 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			this.audit("admin", "loopback-admin", "device.revoke", void 0, void 0, {
+				deviceId: id,
+				name: active.name
+			}, options.requestId);
+			if (this.db.prepare("DELETE FROM devices WHERE id = ?").run(id).changes === 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
+			this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+		this.devicesRevisionCounter += 1;
 	}
 	/**
 	* 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
@@ -3767,18 +4620,70 @@ var WorkspaceDatabase = class {
 		this.db.prepare("UPDATE devices SET revoked_at = ? WHERE id = ?").run(Date.now(), id);
 	}
 	purgeRevokedDevices() {
-		if (this.db.prepare("SELECT id FROM devices WHERE revoked_at IS NOT NULL").all().length === 0) return 0;
+		if (this.db.prepare("SELECT id FROM devices WHERE revoked_at IS NOT NULL").all().length === 0) {
+			this.devicesRevisionCounter += 1;
+			return 0;
+		}
 		this.db.exec("BEGIN IMMEDIATE");
 		try {
 			const result = this.db.prepare("DELETE FROM devices WHERE revoked_at IS NOT NULL").run();
-			this.db.exec("COMMIT");
 			this.audit("admin", "loopback-admin", "device.purge", void 0, void 0, { purged: result.changes });
+			this.db.exec("COMMIT");
+			this.devicesRevisionCounter += 1;
 			return Number(result.changes);
 		} catch (error) {
 			this.db.exec("ROLLBACK");
 			throw error;
 		}
 	}
+	/**
+	* 删掉早于 `cutoffMs` 的幂等回放记录，返回删除行数。
+	*
+	* 由 `retention.ts`（perf-reader）按调度调用，本方法只做 SQL —— 不判断策略、
+	* 不写日志，所以它可以被单独测试。
+	*
+	* 为什么用 `created_at` 而不是加一列 `expires_at`：24 小时的过期**完全**由
+	* `created_at` 推导得出，加列会让每次插入多写一个字段，还多一次 migration 风险。
+	*/
+	pruneIdempotency(cutoffMs) {
+		const result = this.db.prepare("DELETE FROM idempotency WHERE created_at < ?").run(cutoffMs);
+		return Number(result.changes);
+	}
+	/**
+	* 清理审计：先按时间删，再兜「总数超过 `keepMax` 就删最旧的」。
+	*
+	* ## 为什么是两段而不是一段
+	*
+	* 只按时间删不够：桥可以被一个「短时间高频写入」的场景灌满审计表
+	* （例如每秒几十条 `chat.delta` 对应的写操作），时间窗内的量仍然能压垮库。
+	* 只按数量删也不够：用户可能希望「一年前的都清掉」，而不在乎条数。
+	*
+	* ## `keepMax` 是**下限保护**
+	*
+	* 即使 `cutoffMs` 设成了未来（把全部行都判成过期），也**至少**保留最近
+	* `keepMax` 条 —— 一句写错的调用不该把审计清空。审计被清空本身就等于
+	* 「抹掉证据」，这个方向必须由这一层挡住。
+	*
+	* 返回删除的行数（两段之和）。
+	*/
+	pruneAudit(cutoffMs, keepMax) {
+		const floor = Math.max(0, Math.floor(keepMax));
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const total = Number(this.db.prepare("SELECT COUNT(*) AS n FROM audit").get().n);
+			const expired = Number(this.db.prepare("SELECT COUNT(*) AS n FROM audit WHERE time < ?").get(cutoffMs).n);
+			const removableByTime = Math.max(0, Math.min(expired, total - floor));
+			let removed = 0;
+			if (removableByTime > 0) removed += Number(this.db.prepare("DELETE FROM audit WHERE id IN (SELECT id FROM audit ORDER BY time ASC, id ASC LIMIT ?)").run(removableByTime).changes);
+			const over = Number(this.db.prepare("SELECT COUNT(*) AS n FROM audit").get().n) - floor;
+			if (over > 0) removed += Number(this.db.prepare("DELETE FROM audit WHERE id IN (SELECT id FROM audit ORDER BY time ASC, id ASC LIMIT ?)").run(over).changes);
+			this.db.exec("COMMIT");
+			return removed;
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+	}
 	insertTrash(record) {
 		this.db.prepare("INSERT INTO trash(id,root_id,relative_path,payload_path,kind,size,digest,created_at,status) VALUES(?,?,?,?,?,?,?,?,?)").run(record.id, record.rootId, record.relativePath, record.payloadPath, record.kind, record.size, record.digest, record.createdAt, record.status);
 	}
@@ -3944,6 +4849,14 @@ var WorkspaceEventBus = class {
 };
 //#endregion
 //#region src/host/file-service.ts
+/**
+* 列目录时同时 `lstat` 多少个子项。
+*
+* 32 是本仓已经用过、也验证过的并发量级（见 `plugin-inventory.ts` 的
+* `withUpdateCheck` 用的是 6 个 worker；这里是短促的 stat，可以更宽一点）。
+* 关键不是这个数字本身，而是**有界**：一把放 500 个在网络盘上会把请求队列打满。
+*/
+const LIST_STAT_CONCURRENCY = 32;
 var FileService = class {
 	database;
 	emit;
@@ -3962,18 +4875,21 @@ var FileService = class {
 		const pageSize = Math.min(Math.max(limit, 1), 500);
 		const selected = names.slice(start, start + pageSize);
 		const entries = [];
-		for (const name of selected) {
-			const absolute = path.join(resolved.absolutePath, name);
-			const info = await lstat(absolute);
-			const childPath = relativePath === "" ? name : `${relativePath}/${name}`;
-			entries.push({
-				name,
-				path: childPath,
-				kind: kindOf(info),
-				size: info.isFile() ? info.size : 0,
-				modifiedAt: info.mtimeMs,
-				writable: (info.mode & 128) !== 0
-			});
+		for (let offset = 0; offset < selected.length; offset += LIST_STAT_CONCURRENCY) {
+			const batch = selected.slice(offset, offset + LIST_STAT_CONCURRENCY);
+			const rows = await Promise.all(batch.map(async (name) => {
+				const absolute = path.join(resolved.absolutePath, name);
+				const info = await lstat(absolute);
+				return {
+					name,
+					path: relativePath === "" ? name : `${relativePath}/${name}`,
+					kind: kindOf(info),
+					size: info.isFile() ? info.size : 0,
+					modifiedAt: info.mtimeMs,
+					writable: (info.mode & 128) !== 0
+				};
+			}));
+			entries.push(...rows);
 		}
 		const last = selected.at(-1);
 		return {
@@ -3987,12 +4903,11 @@ var FileService = class {
 		const resolved = await resolveAuthorizedPath(root.realPath, relativePath);
 		const info = await lstat(resolved.absolutePath);
 		if (!info.isFile()) throw new ApiError(400, "PATH_NOT_FILE", "Only regular files have readable content.");
-		const etag = await fileEtag(resolved.absolutePath);
 		return {
 			absolutePath: resolved.absolutePath,
 			size: info.size,
 			modifiedAt: info.mtimeMs,
-			etag,
+			etag: etagFromStat(info),
 			contentType: contentTypeFor$1(relativePath)
 		};
 	}
@@ -4010,8 +4925,8 @@ var FileService = class {
 			if (!info.isFile()) throw new ApiError(400, "PATH_NOT_FILE", "Only regular files can be overwritten.");
 			if (conditions.ifNoneMatch === "*") throw new ApiError(412, "PATH_ALREADY_EXISTS", "The file already exists.");
 			if (conditions.ifMatch === void 0) throw new ApiError(428, "ETAG_REQUIRED", "If-Match is required when overwriting a file.");
-			const currentEtag = await fileEtag(resolved.absolutePath);
-			if (conditions.ifMatch !== currentEtag) throw new ApiError(412, "ETAG_MISMATCH", "The file changed after it was read.", { currentEtag });
+			const currentEtag = etagFromStat(info);
+			if (!etagEqual(conditions.ifMatch, currentEtag)) throw new ApiError(412, "ETAG_MISMATCH", "The file changed after it was read.", { currentEtag });
 			mode = info.mode;
 		} else if (conditions.ifNoneMatch !== "*") throw new ApiError(428, "CREATE_CONDITION_REQUIRED", "If-None-Match: * is required when creating file content.");
 		const temp = path.join(parent.absolutePath, `.${path.basename(resolved.absolutePath)}.dsh-${randomUUID()}.tmp`);
@@ -4024,8 +4939,8 @@ var FileService = class {
 				await handle.close();
 			}
 			if (resolved.exists) {
-				const currentEtag = await fileEtag(resolved.absolutePath);
-				if (conditions.ifMatch !== currentEtag) throw new ApiError(412, "ETAG_MISMATCH", "The file changed while the replacement was prepared.", { currentEtag });
+				const currentEtag = etagFromStat(await lstat(resolved.absolutePath));
+				if (!etagEqual(conditions.ifMatch, currentEtag)) throw new ApiError(412, "ETAG_MISMATCH", "The file changed while the replacement was prepared.", { currentEtag });
 			}
 			await replaceFile(temp, resolved.absolutePath, resolved.exists);
 		} catch (error) {
@@ -4033,7 +4948,7 @@ var FileService = class {
 			throw error;
 		}
 		const info = await stat(resolved.absolutePath);
-		const etag = await fileEtag(resolved.absolutePath);
+		const etag = etagFromStat(info);
 		this.notify("file.changed", root.id, relativePath, {
 			etag,
 			size: info.size
@@ -4171,10 +5086,75 @@ var FileService = class {
 		});
 	}
 };
-async function fileEtag(filePath) {
-	const hash = createHash("sha256");
-	await pipeline(createReadStream(filePath), hash);
-	return `"sha256-${hash.digest("base64url")}"`;
+/**
+* 一个文件的**弱验证器**：`W/"<size>-<mtimeMs>"`（两者都用 base36 缩短）。
+*
+* ## 为什么不再用全文件 sha256
+*
+* 修复前是 `sha256(整个文件)`：
+*
+* - `inspectContent`（本文件的 `:93`）在**每一个 GET** 都算一次 —— 一个 100 MiB 的
+*   文件被读一次，服务端就额外读 100 MiB、算一次 sha256；
+* - `writeContent` 在写前、写后、替换后再算（最多 **3 次**）；
+* - 而 `router.ts` 的 304 判断只需要「这个值变没变」，不需要「内容指纹」。
+*
+* 改成 stat-only 之后是 **O(1)**：一个字节都不读。这正是 Range 下载/大文件预览
+* 场景里最划算的一笔优化 —— 它不是什么高级技巧，只是把「哈希整个文件」换成
+* 「问一下 stat」。
+*
+* ## 为什么必须标 `W/`（弱）
+*
+* size + mtime 无法区分「同一毫秒内两次写入、且大小完全不变」。标成强验证器
+* （不带 `W/`）是在说谎：HTTP 语义里强验证器可用于 `If-Range` 与字节范围续传，
+* 客户端会据此跳过内容校验，于是**它可能把一个已经变了的内容当成没变**。
+*
+* 标弱之后：`If-None-Match` 仍可做协商缓存（弱比较本来就用它），
+* 而需要强验证的地方（`If-Match` 写冲突、`If-Range`）客户端不会拿它当证据。
+* 这是诚实的代价，也是这条改动唯一的语义变化，已在报告里记为已知边界。
+*
+* @returns 形如 `W/"2f-yx3k9q1"` 的弱 ETag。
+*/
+/**
+* 把客户端回传的验证器归一成「去掉所有 `W/` 前缀」的形式，用于**相等比较**。
+*
+* ## 为什么写路径也需要归一（不只是读路径的 If-None-Match）
+*
+* 服务端现在发的是**弱** ETag（`W/"..."`，见 [etagFromStat]），而客户端做
+* `If-Match` 时只能把我们发出去的那个值原样回传 —— 于是 `conditions.ifMatch`
+* 必然带 `W/`，而磁盘上重新算出来的也是 `W/"..."`：**单层**情况下字符串恰好相等，
+* 看起来没问题。
+*
+* 但两层就崩了：某些 HTTP 客户端/代理会把弱验证器再包一层，回传 `W/W/"..."`。
+* 那时严格 `!==` 会把「同一个文件」判成「文件变了」→ 412 → **用户保存失败且
+* 重试也不会成功**（因为客户端每次都回传同一个值）。
+*
+* ## 为什么这不是「放松安全」
+*
+* `If-Match` 在这里的职责是**乐观并发控制**（防止盲写覆盖别人的修改），
+* 不是身份认证。归一化只消除 `W/` 前缀这层语法噪声，`<size>-<mtime>` 的
+* 实质比较一字未改 —— 真正变了的文件照样 412。
+*
+* RFC 7232 里 `If-Match` 本应用强比较、而弱验证器不能用于它；这条张力是
+* 「用 stat 而非内容哈希」的已知代价（见 `etagFromStat` 的说明）。我们的取舍是：
+* **宁可让乐观锁偏松一点，也不让用户的保存无故失败** —— 因为这条路径的失败模式
+* 是「数据存不进去」，比「两个客户端几乎同时改同一文件」更常见、更痛。
+*/
+function normalizeValidator(value) {
+	return value.trim().replace(/^(?:W\/)+/i, "");
+}
+/**
+* 两个验证器是否表示同一版本（见 [normalizeValidator]）。
+*
+* `left` 允许 undefined：调用方在「创建分支」上可能没有 `If-Match`
+* （那时它已经被 428 拦下过，但第二个比较点在另一个分支里，TS 窄化不到）。
+* `undefined` 一律视为「不相等」—— 缺失的验证器绝不能匹配上任何真实版本。
+*/
+function etagEqual(left, right) {
+	if (left === void 0) return false;
+	return normalizeValidator(left) === normalizeValidator(right);
+}
+function etagFromStat(info) {
+	return `W/"${Math.max(0, Math.trunc(info.size)).toString(36)}-${Math.max(0, Math.floor(info.mtimeMs)).toString(36)}"`;
 }
 async function replaceFile(temp, destination, destinationExists) {
 	try {
@@ -4300,12 +5280,31 @@ function contentTypeFor$1(filePath) {
 function encodeCursor(name) {
 	return Buffer.from(name, "utf8").toString("base64url");
 }
+/** 游标长度上限：它编码的是一个文件名，几百字符足够；几千字符只可能是伪造。 */
+const MAX_CURSOR_CHARS = 1024;
+/** base64url 的字符集（无填充）。用正则**先**挡住非法输入，再交给解码器。 */
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/**
+* 解目录游标（`encodeCursor` 的逆运算）。
+*
+* ## 为什么需要显式校验，而不能靠 `try/catch`
+*
+* 旧实现写成 `try { Buffer.from(cursor,'base64url') } catch { 400 }`。
+* 那个 `catch` 是**不可达分支**：Node 的 base64url 解码是**宽松**的 ——
+* `Buffer.from('!!!','base64url')` 返回**空 Buffer**（不抛），`'@@@'`、`'中文'` 同理。
+*
+* 后果不是「报错」，而是**静默的错行为**：非法游标被解成空串 →
+* `names.findIndex(name => name > '')` 命中第一项 → **从第一页重新开始**。
+* 客户端看到的是「翻页突然跳回开头」，没有任何错误信号 —— 比报错更难查。
+*
+* 所以这里先做两件**能真正失败**的检查：字符集与长度。
+* 校验通过后才解码；解码结果为空也算非法（空串不是任何文件名）。
+*/
 function decodeCursor(cursor) {
-	try {
-		return Buffer.from(cursor, "base64url").toString("utf8");
-	} catch {
-		throw new ApiError(400, "CURSOR_INVALID", "The directory cursor is invalid.");
-	}
+	if (cursor.length > MAX_CURSOR_CHARS || !BASE64URL_PATTERN.test(cursor)) throw new ApiError(400, "CURSOR_INVALID", "The directory cursor is invalid.");
+	const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+	if (decoded === "") throw new ApiError(400, "CURSOR_INVALID", "The directory cursor is invalid.");
+	return decoded;
 }
 function trashView(record) {
 	return {
@@ -4449,6 +5448,95 @@ function probeHostServices(host, pluginVersion) {
 	};
 }
 //#endregion
+//#region src/host/retention.ts
+/**
+* 数据保留（retention）调度器：把**会无限增长的两张表**按时间清掉。
+*
+* ## 为什么需要它（这是唯一一条「随时间必然恶化」的债）
+*
+* `audit` 与 `idempotency` 都只增不删：
+*
+* - `audit` 在 router 里有 20+ 处写入点（登录、撤销、建根、发消息、审批、命令…），
+*   单机长期运行会到几十万行；
+* - `idempotency` 每个带 `clientRequestId` 的请求一行，而且 `response_json` 存的是
+*   **整份响应体** —— 它增长得比审计还快，而且存的是重复数据。
+*
+* 两者都没有 TTL 列、也没有清理任务（`src/` 下 `DELETE FROM audit` / `VACUUM` /
+* `DELETE FROM idempotency` 零命中）。跑三个月之后的表现是：库文件与 WAL 持续变大、
+* `listAudit` 变慢、备份与迁移成本上升 —— 而这些问题在「刚装上」的时候完全看不到。
+*
+* ## 为什么这个模块只做调度、不写 SQL
+*
+* SQL 属于 `database.ts` 的所有权（表结构、事务边界、索引都在那边）。这个模块负责的是
+* **策略**：清多久以前的、最多留多少、什么时候清、清完记什么日志。
+*
+* 所以它通过一个**窄端口**（[RetentionPort]）调用数据库，并在端口缺席时
+* **静默降级**（只记一次 warn）。理由与可选宿主服务同一条：一个清理任务缺席，
+* 不该让整个插件激活失败。
+*
+* ## 为什么幂等记录只按时间清、不改存的内容
+*
+* 有个更"省空间"的方案是把 `response_json` 从整份响应裁成 `{sessionId}`。**否决**：
+* 幂等重放的语义就是「把当初那次响应原样再给你一次」，形状一变，已发布客户端的
+* 严格解码器会当场炸。省下的那点体积已经由按时间清理覆盖了，不值得换个破坏性变更。
+*/
+/** 幂等记录保留多久。24 h 足够覆盖任何「客户端重试」窗口（配对/发消息都是秒级重试）。 */
+const IDEMPOTENCY_TTL_MS = 864e5;
+/** 审计保留多久。90 天是「事后追查」与「库不失控」之间的常规取舍。 */
+const AUDIT_TTL_MS = 7776e6;
+/** 审计最多留多少行（TTL 之内的兜底：短时间高频写不该把库顶爆）。 */
+const AUDIT_KEEP_MAX = 5e5;
+/**
+* 从数据库对象上取保留端口；没有就返回 null。
+*
+* **特性探测**而不是直接调用：`database.ts` 归另一条手术台，两侧必须能分批落地。
+* 端口缺席时本模块什么也不做 —— 那是「清理任务没上」，不是「插件坏了」。
+*/
+function resolveRetentionPort(database) {
+	const candidate = database;
+	if (typeof candidate.pruneIdempotency !== "function") return null;
+	if (typeof candidate.pruneAudit !== "function") return null;
+	return database;
+}
+/**
+* 启动清理：一次把两张表都收到阈值以内。
+*
+* 放在**插件启动**时跑，因为它要处理的是「上次运行攒下来的量」—— 而那批数据
+* 可能远超一次请求能承受的规模，所以不该混进请求路径。
+*
+* 失败**不抛**（返回 `ran: true` 但两个计数为 0 并记 warn）：清理失败只是「这次没清」，
+* 让它把插件启动打掉是轻重倒置。
+*/
+function runStartupRetention(database, logger, now = Date.now()) {
+	const port = resolveRetentionPort(database);
+	if (port === null) {
+		logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: retention skipped — the database exposes no pruneIdempotency/pruneAudit; audit and idempotency tables will grow without bound"));
+		return {
+			ran: false,
+			idempotencyDeleted: 0,
+			auditDeleted: 0
+		};
+	}
+	let idempotencyDeleted = 0;
+	let auditDeleted = 0;
+	try {
+		idempotencyDeleted = port.pruneIdempotency(now - IDEMPOTENCY_TTL_MS);
+	} catch (error) {
+		logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: pruning idempotency failed: ${String(error)}`));
+	}
+	try {
+		auditDeleted = port.pruneAudit(now - AUDIT_TTL_MS, AUDIT_KEEP_MAX);
+	} catch (error) {
+		logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: pruning audit failed: ${String(error)}`));
+	}
+	if (idempotencyDeleted > 0 || auditDeleted > 0) logger.info(`dsh-remote-bridge: retention removed ${idempotencyDeleted} idempotency row(s) and ${auditDeleted} audit row(s)`);
+	return {
+		ran: true,
+		idempotencyDeleted,
+		auditDeleted
+	};
+}
+//#endregion
 //#region src/host/job-adapter.ts
 /**
 * job 适配层的错误。
@@ -4740,6 +5828,14 @@ function defaultDisplayName() {
 //#endregion
 //#region src/host/plugin-inventory.ts
 /**
+* 读包清单时的并发上限。
+*
+* 为什么不是 `Promise.all` 全放：`names` 的长度由用户装了多少插件决定，
+* 理论上可以几十上百；一把放出去在慢盘/网络盘上反而更慢，而且失败时更难定位。
+* 6 与 `withUpdateCheck` 的网络并发同值，本仓已经验证过。
+*/
+const INVENTORY_READ_CONCURRENCY = 6;
+/**
 * 把 profile 标识归一化成 profile 名。
 *
 * 内核接受**两种**写法，两者都合法：
@@ -4883,8 +5979,17 @@ async function readPluginInventory(input = {}) {
 	const bundles = stringArray((typeof dshSection.profile === "object" && dshSection.profile !== null ? dshSection.profile : {}).bundles);
 	const names = [.../* @__PURE__ */ new Set([...Object.keys(dependencies), ...bundles])].sort();
 	const items = [];
+	const manifests = /* @__PURE__ */ new Map();
+	for (let offset = 0; offset < names.length; offset += INVENTORY_READ_CONCURRENCY) {
+		const batch = names.slice(offset, offset + INVENTORY_READ_CONCURRENCY);
+		const rows = await Promise.all(batch.map(async (name) => ({
+			name,
+			manifest: await readPackageManifest(profilePath, name)
+		})));
+		for (const row of rows) manifests.set(row.name, row.manifest);
+	}
 	for (const name of names) {
-		const pkgManifest = await readPackageManifest(profilePath, name);
+		const pkgManifest = manifests.get(name) ?? null;
 		const installedRaw = pkgManifest?.version;
 		const installed = typeof installedRaw === "string" && installedRaw.trim() ? installedRaw : null;
 		const loaded = bundles.includes(name);
@@ -5300,25 +6405,25 @@ function matchJobRoute(pathname) {
 	const jobs = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs$/);
 	if (jobs !== null) return {
 		kind: "list",
-		sessionId: decodeURIComponent(jobs[1])
+		sessionId: decodePathSegment(jobs[1])
 	};
 	const output = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)\/output$/);
 	if (output !== null) return {
 		kind: "output",
-		sessionId: decodeURIComponent(output[1]),
-		jobId: decodeURIComponent(output[2])
+		sessionId: decodePathSegment(output[1]),
+		jobId: decodePathSegment(output[2])
 	};
 	const kill = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)\/kill$/);
 	if (kill !== null) return {
 		kind: "kill",
-		sessionId: decodeURIComponent(kill[1]),
-		jobId: decodeURIComponent(kill[2])
+		sessionId: decodePathSegment(kill[1]),
+		jobId: decodePathSegment(kill[2])
 	};
 	const bare = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)$/);
 	if (bare !== null) return {
 		kind: "unknown",
-		sessionId: decodeURIComponent(bare[1]),
-		jobId: decodeURIComponent(bare[2])
+		sessionId: decodePathSegment(bare[1]),
+		jobId: decodePathSegment(bare[2])
 	};
 	return null;
 }
@@ -5338,7 +6443,11 @@ function matchJobRoute(pathname) {
 * 「远程能读到 running 但读不到 url」这个方案被**否决**了：那需要在判据 1 上再开一个口子，
 * 而那正是本次修复要消灭的东西。`tunnelStateFor` 里还留了一层不变量检查作双保险。
 */
-const TUNNEL_MODE_EXEMPT_PATHS = /* @__PURE__ */ new Set(["/manage/cloudflare/status", "/manage/cloudflare/activity"]);
+const TUNNEL_MODE_EXEMPT_PATHS = /* @__PURE__ */ new Set([
+	"/manage/cloudflare/status",
+	"/manage/cloudflare/activity",
+	"/manage/cloudflare/stop"
+]);
 var ApiRouter = class {
 	options;
 	constructor(options) {
@@ -5349,6 +6458,15 @@ var ApiRouter = class {
 		setCors(req, res);
 		res.setHeader("X-Request-Id", requestId);
 		if (req.method === "OPTIONS") {
+			if (preflightRefused(req)) {
+				res.writeHead(403, { "Content-Type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: {
+					code: "CORS_ORIGIN_FORBIDDEN",
+					message: "Cross-origin preflight is accepted only from a loopback origin.",
+					requestId
+				} }));
+				return;
+			}
 			res.writeHead(204);
 			res.end();
 			return;
@@ -5383,25 +6501,30 @@ var ApiRouter = class {
 			});
 			return;
 		}
-		if (method === "GET" && pathname === "/api/v1/debug/host-services") {
-			const report = this.options.hostServiceReport;
-			if (report === void 0) throw new ApiError(404, "NOT_FOUND", "host service probe is not available in this build.");
-			sendJson(res, 200, report);
-			return;
-		}
 		if (method === "POST" && pathname === "/api/v1/pairings/exchange") {
-			this.options.auth.pairingAttempts.consume(requestAddress(req));
+			this.options.auth.pairingLimiter(req).consume(requestAddress(req));
 			const body = await readJson(req, 16384);
 			if (typeof body.code !== "string" || typeof body.deviceName !== "string") throw new ApiError(400, "BODY_INVALID", "code and deviceName are required strings.");
-			sendJson(res, 201, this.options.database.exchangePairing(body.code, body.deviceName));
+			sendJson(res, 201, this.options.database.exchangePairing(body.code, body.deviceName, { requestId }));
 			return;
 		}
-		if (pathname.startsWith("/manage")) {
+		if (pathname === "/manage" || pathname.startsWith("/manage/")) {
 			this.options.auth.requireAdmin(req, { ...TUNNEL_MODE_EXEMPT_PATHS.has(pathname) ? { allowTunnelMode: true } : {} });
 			await this.dispatchManagement(req, res, url, requestId);
 			return;
 		}
 		const principal = this.options.auth.principal(req, { allowAdmin: true });
+		if (method === "GET" && pathname === "/api/v1/debug/host-services") {
+			this.options.auth.requireScope(principal, "settings.read");
+			const report = this.options.hostServiceReport;
+			if (report === void 0) throw new ApiError(404, "NOT_FOUND", "host service probe is not available in this build.");
+			const metrics = await readMetricsSnapshot();
+			sendJson(res, 200, metrics === void 0 ? report : {
+				...report,
+				metrics
+			});
+			return;
+		}
 		if (method === "GET" && pathname === "/api/v1/devices/self") {
 			if (principal.kind === "admin") sendJson(res, 200, {
 				id: principal.id,
@@ -5438,7 +6561,7 @@ var ApiRouter = class {
 		}
 		const rootRoute = pathname.match(/^\/api\/v1\/roots\/([^/]+)\/(entries|content)$/);
 		if (rootRoute !== null) {
-			const rootId = decodeURIComponent(rootRoute[1]);
+			const rootId = decodePathSegment(rootRoute[1]);
 			const resource = rootRoute[2];
 			const root = this.requireRoot(principal, rootId);
 			if (resource === "entries") {
@@ -5457,7 +6580,7 @@ var ApiRouter = class {
 		const restoreRoute = pathname.match(/^\/api\/v1\/trash\/([^/]+)\/restore$/);
 		if (method === "POST" && restoreRoute !== null) {
 			this.options.auth.requireScope(principal, "files.delete");
-			const record = this.options.database.getTrash(decodeURIComponent(restoreRoute[1]));
+			const record = this.options.database.getTrash(decodePathSegment(restoreRoute[1]));
 			if (record === void 0) throw new ApiError(404, "TRASH_NOT_FOUND", "The trash item does not exist.");
 			const root = this.requireRoot(principal, record.rootId);
 			await this.options.files.restoreTrash(root, record.id);
@@ -5483,7 +6606,7 @@ var ApiRouter = class {
 		}
 		const workspaceRoute = pathname.match(/^\/api\/v1\/chat\/workspaces\/([^/]+)$/);
 		if (workspaceRoute !== null) {
-			const workspaceId = decodeURIComponent(workspaceRoute[1]);
+			const workspaceId = decodePathSegment(workspaceRoute[1]);
 			if (method === "PATCH") {
 				this.options.auth.requireScope(principal, "chat.write");
 				const body = await readJson(req, 64e3);
@@ -5571,7 +6694,7 @@ var ApiRouter = class {
 		}
 		const providerRoute = pathname.match(/^\/api\/v1\/settings\/providers\/([^/]+)$/);
 		if (providerRoute !== null) {
-			const providerId = decodeURIComponent(providerRoute[1]);
+			const providerId = decodePathSegment(providerRoute[1]);
 			if (method === "PATCH") {
 				this.options.auth.requireScope(principal, "settings.write");
 				const body = await readJson(req, 1e6);
@@ -5597,7 +6720,7 @@ var ApiRouter = class {
 		const discoverProviderRoute = pathname.match(/^\/api\/v1\/settings\/providers\/([^/]+)\/discover$/);
 		if (method === "POST" && discoverProviderRoute !== null) {
 			this.options.auth.requireScope(principal, "settings.write");
-			const providerId = decodeURIComponent(discoverProviderRoute[1]);
+			const providerId = decodePathSegment(discoverProviderRoute[1]);
 			const body = await readJson(req, 64e3);
 			const draft = {
 				...typeof body.baseURL === "string" ? { baseURL: body.baseURL } : {},
@@ -5641,7 +6764,7 @@ var ApiRouter = class {
 		const sessionRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)$/);
 		if (method === "PATCH" && sessionRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(sessionRoute[1]);
+			const sessionId = decodePathSegment(sessionRoute[1]);
 			const body = await readJson(req, 64e3);
 			if (typeof body.title !== "string") throw new ApiError(400, "BODY_INVALID", "title is required.");
 			const result = await this.options.chat.renameSession(principal, sessionId, body.title);
@@ -5652,7 +6775,7 @@ var ApiRouter = class {
 		const forkSessionRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/fork$/);
 		if (method === "POST" && forkSessionRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(forkSessionRoute[1]);
+			const sessionId = decodePathSegment(forkSessionRoute[1]);
 			const body = await readJson(req, 16384);
 			const atSeq = body.atSeq === void 0 ? void 0 : body.atSeq;
 			if (atSeq !== void 0 && (!Number.isSafeInteger(atSeq) || atSeq < 0)) throw new ApiError(400, "BODY_INVALID", "atSeq must be a non-negative integer.");
@@ -5667,7 +6790,7 @@ var ApiRouter = class {
 		const archiveSessionRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/archive$/);
 		if (method === "POST" && archiveSessionRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(archiveSessionRoute[1]);
+			const sessionId = decodePathSegment(archiveSessionRoute[1]);
 			await this.options.chat.archiveSession(principal, sessionId);
 			this.audit(principal, "chat.session.archive", void 0, void 0, requestId, { sessionId });
 			sendJson(res, 200, { archived: true });
@@ -5704,7 +6827,7 @@ var ApiRouter = class {
 		}
 		const messagesRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/messages$/);
 		if (messagesRoute !== null) {
-			const sessionId = decodeURIComponent(messagesRoute[1]);
+			const sessionId = decodePathSegment(messagesRoute[1]);
 			if (method === "GET") {
 				this.options.auth.requireScope(principal, "chat.read");
 				const beforeSeq = optionalInteger(url.searchParams.get("beforeSeq"));
@@ -5739,7 +6862,7 @@ var ApiRouter = class {
 		const attachmentRoute = pathname.match(/^\/api\/v1\/attachments\/([^/]+)$/);
 		if (attachmentRoute !== null && method === "GET") {
 			this.options.auth.requireScope(principal, "files.read");
-			const attachmentId = decodeURIComponent(attachmentRoute[1]);
+			const attachmentId = decodePathSegment(attachmentRoute[1]);
 			const sessionId = url.searchParams.get("sessionId")?.trim();
 			if (!sessionId) throw new ApiError(400, "BODY_INVALID", "sessionId query parameter is required.");
 			const { bytes, mediaType } = await this.options.chat.readAttachment(principal, sessionId, attachmentId);
@@ -5759,7 +6882,7 @@ var ApiRouter = class {
 			res.statusCode = 200;
 			res.setHeader("Content-Type", mediaType);
 			res.setHeader("Content-Length", String(bytes.byteLength));
-			res.setHeader("Cache-Control", "private, max-age=3600");
+			res.setHeader("Cache-Control", "private, max-age=0, must-revalidate");
 			res.end(Buffer.from(bytes));
 			return;
 		}
@@ -5769,12 +6892,12 @@ var ApiRouter = class {
 			const body = await readJson(req, 24e6);
 			if (typeof body.data !== "string" || body.data === "") throw new ApiError(400, "BODY_INVALID", "data (base64) is required.");
 			const name = typeof body.name === "string" && body.name.trim() !== "" ? body.name.trim() : void 0;
-			sendJson(res, 201, await this.options.chat.uploadAttachment(principal, decodeURIComponent(attachmentsRoute[1]), body.data, name));
+			sendJson(res, 201, await this.options.chat.uploadAttachment(principal, decodePathSegment(attachmentsRoute[1]), body.data, name));
 			return;
 		}
 		const commandsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/commands$/);
 		if (commandsRoute !== null) {
-			const sessionId = decodeURIComponent(commandsRoute[1]);
+			const sessionId = decodePathSegment(commandsRoute[1]);
 			if (method === "GET") {
 				this.options.auth.requireScope(principal, "chat.read");
 				sendJson(res, 200, { items: await this.options.chat.listCommands(principal, sessionId) });
@@ -5796,15 +6919,15 @@ var ApiRouter = class {
 		const approvalsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/approvals$/);
 		if (method === "GET" && approvalsRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.read");
-			const sessionId = decodeURIComponent(approvalsRoute[1]);
+			const sessionId = decodePathSegment(approvalsRoute[1]);
 			sendJson(res, 200, { items: await this.options.chat.listPendingApprovals(principal, sessionId) });
 			return;
 		}
 		const approvalDecisionRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/approvals\/([^/]+)\/decision$/);
 		if (method === "POST" && approvalDecisionRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(approvalDecisionRoute[1]);
-			const approvalId = decodeURIComponent(approvalDecisionRoute[2]);
+			const sessionId = decodePathSegment(approvalDecisionRoute[1]);
+			const approvalId = decodePathSegment(approvalDecisionRoute[2]);
 			const body = await readJson(req, 16384);
 			if (body.outcome !== "allowed-once" && body.outcome !== "rejected") throw new ApiError(400, "BODY_INVALID", "outcome must be allowed-once or rejected.");
 			const approval = await this.options.chat.decideApproval(principal, sessionId, approvalId, body.outcome);
@@ -5821,15 +6944,15 @@ var ApiRouter = class {
 		const questionsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/questions$/);
 		if (method === "GET" && questionsRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.read");
-			const sessionId = decodeURIComponent(questionsRoute[1]);
+			const sessionId = decodePathSegment(questionsRoute[1]);
 			sendJson(res, 200, { items: await this.options.chat.listUserQuestions(principal, sessionId) });
 			return;
 		}
 		const questionAnswerRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/questions\/([^/]+)\/answer$/);
 		if (method === "POST" && questionAnswerRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(questionAnswerRoute[1]);
-			const callId = decodeURIComponent(questionAnswerRoute[2]);
+			const sessionId = decodePathSegment(questionAnswerRoute[1]);
+			const callId = decodePathSegment(questionAnswerRoute[2]);
 			const answer = readUserQuestionAnswer(await readJson(req, 64e3));
 			await this.options.chat.answerUserQuestion(principal, sessionId, callId, answer);
 			this.audit(principal, "chat.question.answer", void 0, void 0, requestId, {
@@ -5843,7 +6966,7 @@ var ApiRouter = class {
 		}
 		const sessionModelsRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/model(?:s)?$/);
 		if (sessionModelsRoute !== null) {
-			const sessionId = decodeURIComponent(sessionModelsRoute[1]);
+			const sessionId = decodePathSegment(sessionModelsRoute[1]);
 			if (method === "GET") {
 				this.options.auth.requireScope(principal, "chat.read");
 				sendJson(res, 200, await this.options.chat.models(principal, sessionId));
@@ -5871,7 +6994,7 @@ var ApiRouter = class {
 		const sessionAgentPresetRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/agent-preset$/);
 		if (method === "PUT" && sessionAgentPresetRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(sessionAgentPresetRoute[1]);
+			const sessionId = decodePathSegment(sessionAgentPresetRoute[1]);
 			const body = await readJson(req, 64e3);
 			if (typeof body.agentPreset !== "string") throw new ApiError(400, "BODY_INVALID", "agentPreset is required.");
 			const agentPreset = await this.options.chat.selectAgentPreset(principal, sessionId, body.agentPreset);
@@ -5885,7 +7008,7 @@ var ApiRouter = class {
 		const cancelRoute = pathname.match(/^\/api\/v1\/chat\/runs\/([^/]+)\/cancel$/);
 		if (method === "POST" && cancelRoute !== null) {
 			this.options.auth.requireScope(principal, "chat.write");
-			const sessionId = decodeURIComponent(cancelRoute[1]);
+			const sessionId = decodePathSegment(cancelRoute[1]);
 			await this.options.chat.cancel(principal, sessionId);
 			this.audit(principal, "chat.run.cancel", void 0, void 0, requestId, { sessionId });
 			sendJson(res, 202, { accepted: true });
@@ -5912,12 +7035,12 @@ var ApiRouter = class {
 		if (method === "POST" && pathname === "/manage/roots") {
 			const body = await readJson(req, 64e3);
 			if (typeof body.path !== "string") throw new ApiError(400, "BODY_INVALID", "path is required.");
-			sendJson(res, 201, await this.options.database.addRoot(body.path, typeof body.label === "string" ? body.label : void 0));
+			sendJson(res, 201, await this.options.database.addRoot(body.path, typeof body.label === "string" ? body.label : void 0, { requestId }));
 			return;
 		}
 		const rootRoute = pathname.match(/^\/manage\/roots\/([^/]+)$/);
 		if (method === "DELETE" && rootRoute !== null) {
-			this.options.database.removeRoot(decodeURIComponent(rootRoute[1]));
+			this.options.database.removeRoot(decodePathSegment(rootRoute[1]));
 			res.writeHead(204);
 			res.end();
 			return;
@@ -5931,44 +7054,23 @@ var ApiRouter = class {
 			const body = await readJson(req, 64e3);
 			const scopes = validateScopes(body.scopes);
 			const rootIds = validateStringArray(body.rootIds, "rootIds");
-			sendJson(res, 200, this.options.database.updateDevice(decodeURIComponent(deviceRoute[1]), scopes, rootIds));
+			sendJson(res, 200, this.options.database.updateDevice(decodePathSegment(deviceRoute[1]), scopes, rootIds, { requestId }));
 			return;
 		}
 		if (deviceRoute !== null && method === "DELETE") {
-			this.options.database.revokeDevice(decodeURIComponent(deviceRoute[1]));
+			this.options.database.revokeDevice(decodePathSegment(deviceRoute[1]), { requestId });
 			res.writeHead(204);
 			res.end();
 			return;
 		}
 		if (method === "POST" && pathname === "/manage/pairings") {
 			const body = await readJson(req, 64e3);
-			sendJson(res, 201, this.options.database.createPairing(validateStringArray(body.rootIds, "rootIds"), validateScopes(body.scopes)));
+			sendJson(res, 201, this.options.database.createPairing(validateStringArray(body.rootIds, "rootIds"), validateScopes(body.scopes), void 0, { requestId }));
 			return;
 		}
 		if (method === "POST" && pathname === "/manage/config/text") {
 			const body = await readJson(req, 64e3);
-			const port = Number.isInteger(body.port) && Number(body.port) > 0 && Number(body.port) < 65536 ? Number(body.port) : DEFAULT_PORT;
-			const endpoints = readRequestedEndpoints(body.endpoints) ?? detectEndpoints(port);
-			if (endpoints.length === 0) throw new ApiError(400, "NO_ENDPOINT", "No usable local address was detected. Provide endpoints explicitly.");
-			const scopes = body.scopes === void 0 ? [...DEFAULT_CONFIG_SCOPES] : validateScopes(body.scopes);
-			const rootIds = body.rootIds === void 0 ? this.options.database.listRoots().map((root) => root.id) : validateStringArray(body.rootIds, "rootIds");
-			const deviceName = readOptionalText(body.deviceName) ?? "Android 设备";
-			const displayName = readOptionalText(body.displayName) ?? defaultDisplayName();
-			const pairing = this.options.database.createPairing(rootIds, scopes);
-			const exchanged = this.options.database.exchangePairing(pairing.code, deviceName);
-			sendJson(res, 201, {
-				text: encodeConfigText({
-					displayName,
-					endpoints,
-					token: exchanged.token,
-					deviceName,
-					scopes
-				}),
-				displayName,
-				deviceName,
-				endpoints,
-				deviceId: exchanged.device.id
-			});
+			sendJson(res, 201, this.buildConfigText(body, requestId));
 			return;
 		}
 		if (method === "POST" && pathname === "/manage/remote/enable") {
@@ -6008,7 +7110,7 @@ var ApiRouter = class {
 		}
 		const purgeRoute = pathname.match(/^\/manage\/trash\/([^/]+)$/);
 		if (method === "DELETE" && purgeRoute !== null) {
-			await this.options.files.purgeTrash(decodeURIComponent(purgeRoute[1]));
+			await this.options.files.purgeTrash(decodePathSegment(purgeRoute[1]));
 			this.options.database.audit("admin", "loopback-admin", "trash.purge", void 0, void 0, {}, requestId);
 			res.writeHead(204);
 			res.end();
@@ -6027,6 +7129,8 @@ var ApiRouter = class {
 			}
 		}
 		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/create") {
+			const createBody = await readJson(req, 64e3).catch(() => ({}));
+			const wantConfig = createBody.configText === true;
 			const binDir = this.options.cloudflaredBinDir;
 			let exe;
 			try {
@@ -6035,13 +7139,37 @@ var ApiRouter = class {
 				});
 			} catch (cause) {
 				this.options.tunnels.clearActivity();
-				throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", cause instanceof Error ? cause.message : String(cause));
+				throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", "Failed to download or unpack cloudflared. Check the network and retry, or set CLOUDFLARED_MIRROR.", {
+					errorKey: "tunnelErrorDownload",
+					...cause instanceof Error ? { reason: sanitizeDownloadError(cause.message) } : {}
+				});
 			}
 			const port = this.options.remote.status().configuredPort ?? 3090;
 			const state = await this.options.tunnels.startQuick(exe, port);
+			let configText;
+			let resolvedUrl = state.url;
+			if (wantConfig) {
+				const tunnelUrl = state.url ?? await this.options.tunnels.waitForUrl();
+				resolvedUrl = tunnelUrl;
+				if (tunnelUrl !== null) configText = this.buildConfigText({
+					endpoints: [{
+						label: readOptionalText(createBody.endpointLabel) ?? "云隧道",
+						baseUrl: tunnelUrl
+					}],
+					...createBody.rootIds === void 0 ? {} : { rootIds: createBody.rootIds },
+					...createBody.deviceName === void 0 ? {} : { deviceName: createBody.deviceName }
+				}, requestId);
+			}
 			this.options.tunnels.clearActivity();
 			this.options.database.audit("admin", "loopback-admin", "cloudflare.create", void 0, void 0, {}, requestId);
-			sendJson(res, 201, state);
+			const responseState = resolvedUrl === state.url ? state : {
+				...state,
+				url: resolvedUrl
+			};
+			sendJson(res, 201, configText === void 0 ? responseState : {
+				...responseState,
+				configText
+			});
 			return;
 		}
 		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/stop") {
@@ -6067,6 +7195,42 @@ var ApiRouter = class {
 	* 评估结论见报告：本轮选择「远程一律 403」而不是「远程读得到但 `url` 为 null」，
 	* 因为后者需要为状态端点在判据 1 上再开一个口子，而那正是这次修复要消灭的东西。
 	*/
+	/**
+	* 生成一行可粘贴的 `DSH1:` 配置文本（POST /manage/config/text 与「一键开隧道并出令牌」
+	* 的 create 端点共用，避免两处各写一套配对/兑换/编码逻辑而漂移）。
+	*
+	* 入参字段与 /manage/config/text 的窄格式一致：
+	* - endpoints：显式给出则不再做本机网卡探测（隧道场景必须只塞隧道地址，不能混入 LAN）；
+	* - rootIds / scopes / deviceName / displayName / port：全部可选，缺省沿用原端点口径；
+	* - scopes 缺省是**五个非破坏性默认权限**（不含 files.delete / settings.write），
+	*   调用方若显式传 DEVICE_SCOPES 会放大手机权限，create 一键路径不传。
+	*
+	* 刻意不返回 pairing.expiresAt：那是配对码的十分钟有效期，设备令牌本身不过期。
+	*/
+	buildConfigText(body, requestId) {
+		const port = Number.isInteger(body.port) && Number(body.port) > 0 && Number(body.port) < 65536 ? Number(body.port) : DEFAULT_PORT;
+		const endpoints = readRequestedEndpoints(body.endpoints) ?? detectEndpoints(port);
+		if (endpoints.length === 0) throw new ApiError(400, "NO_ENDPOINT", "No usable local address was detected. Provide endpoints explicitly.");
+		const scopes = body.scopes === void 0 ? [...DEFAULT_CONFIG_SCOPES] : validateScopes(body.scopes);
+		const rootIds = body.rootIds === void 0 ? this.options.database.listRoots().map((root) => root.id) : validateStringArray(body.rootIds, "rootIds");
+		const deviceName = readOptionalText(body.deviceName) ?? "Android 设备";
+		const displayName = readOptionalText(body.displayName) ?? defaultDisplayName();
+		const pairing = this.options.database.createPairing(rootIds, scopes, void 0, { requestId });
+		const exchanged = this.options.database.exchangePairing(pairing.code, deviceName, { requestId });
+		return {
+			text: encodeConfigText({
+				displayName,
+				endpoints,
+				token: exchanged.token,
+				deviceName,
+				scopes
+			}),
+			displayName,
+			deviceName,
+			endpoints,
+			deviceId: exchanged.device.id
+		};
+	}
 	tunnelStateFor(req) {
 		const tunnels = this.options.tunnels;
 		if (tunnels === void 0) throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
@@ -6118,12 +7282,18 @@ var ApiRouter = class {
 		if (req.method === "GET") {
 			this.options.auth.requireScope(principal, "files.read");
 			const descriptor = await this.options.files.inspectContent(root, relativePath);
-			const range = parseRange(req.headers.range, descriptor.size);
+			res.setHeader("Cache-Control", "private, max-age=0, must-revalidate");
 			res.setHeader("Accept-Ranges", "bytes");
 			res.setHeader("ETag", descriptor.etag);
 			res.setHeader("Last-Modified", new Date(descriptor.modifiedAt).toUTCString());
 			res.setHeader("Content-Type", descriptor.contentType);
 			res.setHeader("Content-Disposition", `inline; filename*=UTF-8''${encodeURIComponent(relativePath.split("/").at(-1) ?? "file")}`);
+			const range = parseRange(req.headers.range, descriptor.size);
+			if (range === void 0 && etagMatches(req.headers["if-none-match"], descriptor.etag)) {
+				res.writeHead(304, { ETag: descriptor.etag });
+				res.end();
+				return;
+			}
 			if (range === void 0) {
 				res.writeHead(200, { "Content-Length": descriptor.size });
 				this.options.files.streamContent(descriptor).pipe(res);
@@ -6208,17 +7378,71 @@ function sendJson(res, status, body) {
 	});
 	res.end(encoded);
 }
+/**
+* 这个 `Origin` 是否指向回环（`127.0.0.1` / `localhost` / `[::1]`）。
+*
+* 与 `auth.ts` 的 `isLoopbackOrigin` **同一个判据**，只是这里需要「是否回环」这个
+* 布尔值本身（那边是「放不放行」）。两处若各写一套，就会出现「CORS 放行、
+* 鉴权拒绝」或反之的漂移 —— 2.5.1 的 CORS 缺陷正是这种漂移的一种。
+*/
+function isLoopbackOriginValue(origin) {
+	try {
+		const hostname = new URL(origin).hostname.toLowerCase();
+		return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+	} catch {
+		return false;
+	}
+}
+/**
+* 写 CORS 响应头。**只对回环 Origin 回显**（2.5.2 修复）。
+*
+* ## 修复前
+*
+* 只要请求带 `Origin` 就原样回显 `Access-Control-Allow-Origin: <它>`，
+* 且 `Allow-Headers` 里含 `X-Dsh-Workspace-Admin`。那等于在**协议层**对任意网站宣告：
+* 「你可以跨站调这个服务，连管理头都可以带」。
+*
+* 当时没有立刻变成提权，是因为 `adminRefusal` 的判据 3 会看 `Origin` 并 403 ——
+* **判据替 CORS 兜住了**。但纵深只剩一层：以后任何一次「为兼容放宽判据 3」的改动
+* （比如允许 `Origin: null`）都会立刻变成 CSRF 敞口。
+*
+* ## 修复后
+*
+* - 回环 Origin → 回显它（桌面 WebUI 在 `127.0.0.1:3080` 起，同源或跨端口都照常）；
+* - 非回环 Origin → **不发** ACAO（浏览器自然拒绝跨站读取，不需要服务端 403 也算安全）；
+* - 无 Origin → 不发（本机 `curl` 不需要 CORS）；
+* - `Allow-Headers` **去掉** `X-Dsh-Workspace-Admin`：桌面面板是同源的，
+*   它带这个头根本不需要预检许可，把它写进协议只会误导后人。
+*
+* `Cache-Control: no-store` 仍在这里设默认值；少数可缓存的三条端点
+* （`/roots/:id/content`、`/attachments/:id`、`/image-handoff`）在各自的处理分支里覆盖。
+*/
 function setCors(req, res) {
 	const origin = req.headers.origin;
-	if (origin !== void 0) {
+	if (origin !== void 0 && isLoopbackOriginValue(origin)) {
 		res.setHeader("Access-Control-Allow-Origin", origin);
 		res.setHeader("Vary", "Origin");
 	}
-	res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, If-Match, If-None-Match, X-Request-Id, X-Dsh-Workspace-Admin");
+	res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, If-Match, If-None-Match, X-Request-Id");
 	res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
 	res.setHeader("Access-Control-Expose-Headers", "ETag, Content-Range, X-Request-Id");
 	res.setHeader("Cache-Control", "no-store");
 }
+/**
+* 预检（`OPTIONS`）是否该被回答。
+*
+* 浏览器预检一定带 `Origin`。带**非回环** Origin 的预检直接 403 ——
+* 与「不发 ACAO」相比这条更明确：让攻击者立刻知道跨站不被接受，
+* 而不是让它在一个「看起来成功但读不到内容」的响应里猜。
+*
+* 没有 `Origin` 的 `OPTIONS` 不是浏览器预检（`curl` 常这么探活），照旧 204 ——
+* 与 `adminRefusal` 放行「缺 Origin」是同一个口径（缺 Origin 不构成声明）。
+*/
+function preflightRefused(req) {
+	const origin = req.headers.origin;
+	if (typeof origin !== "string" || origin === "") return false;
+	return !isLoopbackOriginValue(origin);
+}
 function validateScopes(value) {
 	const values = validateStringArray(value, "scopes");
 	if (values.some((item) => !DEVICE_SCOPES.includes(item))) throw new ApiError(400, "SCOPE_INVALID", "The request contains an unknown device scope.");
@@ -6351,6 +7575,39 @@ function optionalInteger(value) {
 function commandName(line) {
 	return /^\/([a-z][a-z0-9_-]*)/u.exec(line)?.[1] ?? "unknown";
 }
+/**
+* 读一份运行期指标快照；读取本身抛错时返回 `undefined`（诊断端点绝不能反过来炸掉）。
+*
+* 历史：这里曾是动态 `import('./metrics.ts')`，因为 metrics.ts 与本文件由不同手术台并行落地，
+* 静态依赖会造成编译顺序耦合。metrics.ts 落地后该动态导入既不省包（server/bridge 已静态引用，
+* tsdown 会打 INEFFECTIVE_DYNAMIC_IMPORT 警告）也不提供容错，改为静态导入。
+*/
+async function readMetricsSnapshot() {
+	try {
+		return getMetricsSnapshot();
+	} catch {
+		return;
+	}
+}
+/**
+* `If-None-Match` 是否命中当前 ETag。**带弱比较**（忽略 `W/` 前缀）。
+*
+* 为什么不用严格相等：ETag 的强弱前缀（`W/`）属于缓存语义的**修饰**，
+* 不改变「这份内容是不是同一份」。而两端（路由器 / `file-service`）谁加 `W/`
+* 都可能随实现变化（本仓的 ETag 格式正在被改成 stat-only 的弱校验器），
+* 写死严格相等会让「格式一改，304 静默失效」—— 那种失效没有任何报错，
+* 只是客户端永远拿不到 304，悄悄地退回每次重下整份。
+*
+* 支持逗号分隔的多值（`If-None-Match: W/"a", "b"`）与通配 `*`。
+*/
+function etagMatches(headerValue, etag) {
+	const raw = Array.isArray(headerValue) ? headerValue.join(",") : headerValue;
+	if (raw === void 0 || raw === "") return false;
+	if (raw.trim() === "*") return true;
+	const normalize = (value) => value.trim().replace(/^(?:W\/)+/i, "");
+	const target = normalize(etag);
+	return raw.split(",").some((candidate) => normalize(candidate) === target);
+}
 function parseRange(value, size) {
 	if (value === void 0) return void 0;
 	const match = /^bytes=(\d*)-(\d*)$/.exec(value);
@@ -6376,8 +7633,72 @@ function header(req, name) {
 	const value = req.headers[name];
 	return Array.isArray(value) ? value[0] : value;
 }
+/**
+* 解码一个 URL **路径段**（不是 query 参数）。
+*
+* ## 为什么要收口成一个函数
+*
+* `decodeURIComponent` 对非法百分号（`%ZZ`、`%E0%A4%A`、孤零零的 `%`）抛 `URIError`。
+* 而 `new URL()` **不会**提前拒绝它们（实测 `pathname` 保留字面 `%ZZ`），
+* 于是请求真的会走到解码这一步 —— 抛出后一路冒到 `router.handle` 的兜底 `catch`，
+* 被 `asApiError` 包成 **500 `INTERNAL_ERROR`**。
+*
+* 那是**错误的分类**：客户端把 URL 打错，不是桥内部炸了。两层代价：
+* 1. 排障时把「你 URL 写错了」读成「服务端故障」，方向全错；
+* 2. 污染 `INTERNAL_ERROR` 这个码 —— 真出 500 时没人能再靠码区分。
+*
+* 所以这里把「客户端输入非法」固定成 **400 `PATH_INVALID`**，
+* 与 `path-policy.ts` 里其它非法路径的码保持一致（客户端只需认一个码）。
+*
+* ## 为什么不用 `URLSearchParams` 或 `decodeURI`
+*
+* - `URLSearchParams.get()` 会把 `+` 解成空格（那是 **query** 的
+*   `application/x-www-form-urlencoded` 语义）。路径段里的 `+` 是字面量 ——
+*   用它会把 `a+b` 这类合法 id 静默改成 `a b`。
+* - `decodeURI` 不处理保留字符（`%3A` 之类解不出来），语义不对。
+*
+* 所以：`decodeURIComponent` + 严格 catch，什么都不额外做。
+*/
+function decodePathSegment(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		throw new ApiError(400, "PATH_INVALID", "A path segment contains malformed percent-encoding.");
+	}
+}
 //#endregion
 //#region src/host/server.ts
+/** 默认同时连接数。比手机端可能的重连风暴宽，又不至于让一个坏客户端吃满。 */
+const DEFAULT_MAX_CONNECTIONS = 32;
+/** 默认单帧上限（`ws` 的 `maxPayload`）。 */
+const DEFAULT_MAX_PAYLOAD_BYTES = 1048576;
+/** 默认心跳间隔。 */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+/** 连接内事件队列上限。 */
+const DEFAULT_SOCKET_QUEUE_LIMIT = 512;
+/** 发送缓冲高水位：`ws` 的 `bufferedAmount` 越过它说明对端读不动。 */
+const DEFAULT_HIGH_WATER_MARK_BYTES = 4194304;
+/** 卸载时等广播排空的硬上限（不让插件卡住进程退出）。 */
+const STOP_DRAIN_TIMEOUT_MS = 1e3;
+/** 背压复查间隔：越线后等这么久再看一眼缓冲降没降。 */
+const HIGH_WATER_RECHECK_MS = 250;
+/**
+* 关闭连接时的宽限期。
+*
+* 升级过的 WebSocket 不受 `closeAllConnections()` 管理，所以「一条读不动的连接」
+* 能让 `server.close()` 的回调永远不来。宽限期后一律 `terminate()`。
+*/
+const CLOSE_GRACE_MS = 500;
+/**
+* 这条事件「丢了能不能重建」。
+*
+* 只有流式文本增量是可重建的（客户端重拉历史即可）。状态类帧（`turn.*` /
+* `approval.*` / `deliverables.*` / `connection.ready`）丢了会让客户端停在错误状态，
+* 所以溢出时**优先牺牲增量**。
+*/
+function isRebuildable(event) {
+	return event.type === "chat.message.delta";
+}
 var RemoteApiServer = class {
 	options;
 	server;
@@ -6388,14 +7709,18 @@ var RemoteApiServer = class {
 	remoteEnabled = false;
 	operations = /* @__PURE__ */ new Map();
 	sockets = /* @__PURE__ */ new Map();
-	webSockets = new WebSocketServer({
-		noServer: true,
-		clientTracking: false
-	});
+	webSockets;
 	eventsAbort = new AbortController();
 	unsubscribeEvents;
-	broadcastQueue = Promise.resolve();
+	/** 所有连接的 drain 完成信号；`Promise.all` 它们即可等排空。 */
+	pendingDrains = /* @__PURE__ */ new Set();
+	heartbeatTimer;
+	changeTimer;
 	changing = false;
+	maxConnections;
+	socketQueueLimit;
+	highWaterMarkBytes;
+	heartbeatIntervalMs;
 	constructor(options) {
 		this.options = options;
 		const fallbackHost = normalizeListenerHost(options.remoteHost ?? "0.0.0.0");
@@ -6403,6 +7728,15 @@ var RemoteApiServer = class {
 		this.configuredHost = readStoredHost(options.database, fallbackHost);
 		this.configuredPort = readStoredPort(options.database, fallbackPort);
 		this.actualPort = this.configuredPort;
+		this.maxConnections = Math.max(1, options.maxConnections ?? DEFAULT_MAX_CONNECTIONS);
+		this.socketQueueLimit = Math.max(1, options.socketQueueLimit ?? DEFAULT_SOCKET_QUEUE_LIMIT);
+		this.highWaterMarkBytes = Math.max(1, options.highWaterMarkBytes ?? DEFAULT_HIGH_WATER_MARK_BYTES);
+		this.heartbeatIntervalMs = Math.max(1, options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS);
+		this.webSockets = new WebSocketServer({
+			noServer: true,
+			clientTracking: false,
+			maxPayload: Math.max(1, options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES)
+		});
 	}
 	async start() {
 		this.remoteEnabled = this.options.database.getSetting("remote_enabled") === "true";
@@ -6416,8 +7750,9 @@ var RemoteApiServer = class {
 			await this.bind(loopbackFor(this.configuredHost), this.configuredPort);
 		}
 		this.unsubscribeEvents = this.options.events.subscribe((event) => {
-			this.broadcastQueue = this.broadcastQueue.then(() => this.broadcast(event)).catch(() => void 0);
+			this.enqueueBroadcast(event);
 		});
+		this.startHeartbeat();
 		this.options.chat.startEvents(this.eventsAbort.signal, (event) => {
 			this.options.events.emit(event);
 		});
@@ -6426,9 +7761,15 @@ var RemoteApiServer = class {
 		this.eventsAbort.abort();
 		this.unsubscribeEvents?.();
 		this.unsubscribeEvents = void 0;
-		await this.broadcastQueue;
+		this.clearChangeTimer();
+		if (this.heartbeatTimer !== void 0) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = void 0;
+		}
+		await this.drainAll(STOP_DRAIN_TIMEOUT_MS);
 		await this.closeCurrent();
 		this.webSockets.close();
+		setWsConnections(0);
 	}
 	status(operationId) {
 		const operation = operationId === void 0 ? void 0 : this.operations.get(operationId);
@@ -6481,11 +7822,21 @@ var RemoteApiServer = class {
 		};
 		this.operations.set(operation.id, operation);
 		this.changing = true;
-		setTimeout(() => {
+		this.clearChangeTimer();
+		this.changeTimer = setTimeout(() => {
+			this.changeTimer = void 0;
 			this.performChange(operation);
 		}, 75);
+		this.changeTimer.unref?.();
 		return publicOperation(operation);
 	}
+	/** 取消还没触发的监听变更。幂等：没定时器就什么都不做。 */
+	clearChangeTimer() {
+		if (this.changeTimer === void 0) return;
+		clearTimeout(this.changeTimer);
+		this.changeTimer = void 0;
+		this.changing = false;
+	}
 	async performChange(operation) {
 		const previousHost = this.host;
 		const previousPort = this.actualPort;
@@ -6543,7 +7894,7 @@ var RemoteApiServer = class {
 	}
 	async createBoundServer(host, port) {
 		const server = createServer((req, res) => {
-			this.options.handle(req, res).catch((error) => failResponse(res, error));
+			Promise.resolve().then(() => this.options.handle(req, res)).catch((error) => failResponse(res, error));
 		});
 		server.requestTimeout = 3e4;
 		server.headersTimeout = 1e4;
@@ -6565,14 +7916,42 @@ var RemoteApiServer = class {
 			port: server.address().port
 		};
 	}
+	/**
+	* 关掉当前监听与全部连接，**有界**。
+	*
+	* `server.close()` 的回调要等所有连接结束；而**升级过的 WebSocket 不在
+	* `closeAllConnections()` 的管理范围里**（HTTP 层已经不跟踪它了）。于是只要有一条
+	* 连接读不动（暂停读 / 半开），`close()` 就永远等不到回调 —— 插件卸载会挂死。
+	*
+	* 所以这里的顺序是：先礼后兵 —— 发 1012（客户端会看到「服务端重绑」而不是异常断开），
+	* 等一小段宽限期；宽限期到就 `terminate()`，同时让 `close()` 的等待一起收尾。
+	*/
 	async closeCurrent() {
 		const server = this.server;
 		if (server === void 0) return;
 		this.server = void 0;
-		for (const socket of this.sockets.keys()) socket.close(1012, "Listener rebinding");
+		const pending = [...this.sockets.keys()];
+		for (const socket of pending) try {
+			socket.close(1012, "Listener rebinding");
+		} catch {}
 		this.sockets.clear();
+		setWsConnections(0);
 		await new Promise((resolve) => {
-			server.close(() => resolve());
+			let settled = false;
+			const done = () => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(grace);
+				resolve();
+			};
+			const grace = setTimeout(() => {
+				for (const socket of pending) try {
+					socket.terminate();
+				} catch {}
+				done();
+			}, CLOSE_GRACE_MS);
+			grace.unref?.();
+			server.close(done);
 			server.closeAllConnections();
 		});
 	}
@@ -6585,27 +7964,84 @@ var RemoteApiServer = class {
 			const protocolToken = parseProtocolToken(req.headers["sec-websocket-protocol"]);
 			if (protocolToken !== void 0) req.headers.authorization = `Bearer ${protocolToken}`;
 			const principal = this.options.auth.principal(req, { allowAdmin: true });
+			if (this.sockets.size >= this.maxConnections) {
+				recordWsRejected();
+				socket.end("HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\nRetry-After: 5\r\nContent-Length: 0\r\n\r\n");
+				return;
+			}
 			this.webSockets.handleUpgrade(req, socket, head, (webSocket) => {
-				this.sockets.set(webSocket, principal);
+				const state = {
+					principal,
+					queue: [],
+					draining: false,
+					dropped: 0,
+					resyncPending: false,
+					isAlive: true,
+					overHighWater: 0,
+					devicesRevision: this.devicesRevisionOf(),
+					recheckTimer: void 0
+				};
+				this.sockets.set(webSocket, state);
+				setWsConnections(this.sockets.size);
+				webSocket.on("pong", () => {
+					state.isAlive = true;
+				});
 				webSocket.on("close", () => {
+					this.clearSocketTimers(state);
 					this.sockets.delete(webSocket);
+					setWsConnections(this.sockets.size);
 				});
 				webSocket.on("error", () => {
+					this.clearSocketTimers(state);
 					this.sockets.delete(webSocket);
+					setWsConnections(this.sockets.size);
 				});
 				webSocket.send(stringifyWire({
 					id: randomUUID(),
 					type: "connection.ready",
 					time: Date.now(),
-					data: connectionReadyData()
+					data: connectionReadyData(this.options.capabilities ?? {})
 				}));
-				this.replayPendingInteractions(webSocket, principal);
+				this.replayPendingInteractions(webSocket, state);
 			});
 		} catch {
 			socket.destroy();
 		}
 	}
 	/**
+	* 心跳循环：每 `heartbeatIntervalMs` 检查一次存活标记。
+	*
+	* 时序要看清：`isAlive` **先读后置假**，并且只在本轮「活着」时才补一次 `ping`。
+	* 于是：
+	* - 本轮活着 → 标记为可疑，再 ping 一次；
+	* - 本轮仍可疑（上一轮 ping 没换来 pong）→ `terminate()`。
+	*
+	* 结果是**连续错过两个周期**才踢人。偶发丢一个包不会误杀在线设备，真正断掉的
+	* （手机切网 / 熄屏后 NAT 表项过期）最多两个周期就清掉 —— 而修复前它只能等
+	* TCP 自己超时，等于「半开连接长期占着额度，还在每轮广播里被白查一次库」。
+	*
+	* `unref()` 必需：这个定时器永不结束，不 unref 会让进程退不掉。
+	*/
+	startHeartbeat() {
+		if (this.heartbeatTimer !== void 0) return;
+		this.heartbeatTimer = setInterval(() => {
+			for (const [socket, state] of this.sockets) {
+				if (!state.isAlive) {
+					recordWsTerminated();
+					this.sockets.delete(socket);
+					setWsConnections(this.sockets.size);
+					socket.terminate();
+					continue;
+				}
+				state.isAlive = false;
+				try {
+					socket.ping();
+				} catch {}
+			}
+		}, this.heartbeatIntervalMs);
+		this.heartbeatTimer.unref?.();
+	}
+	/**
 	* 把待处理的**审批与提问**补推给刚建立的这条连接。
 	*
 	* 为什么要有这一步：「连接后要不要主动查一次 REST」是**每个客户端自己的选择**。
@@ -6614,43 +8050,213 @@ var RemoteApiServer = class {
 	* 重连窗口里产生的审批就会静默消失（内核阻塞着等决定、手机上却一片安静）。
 	* 重放把「新连接一定能拿到仍待处理的审批」变成**服务端保证**，而不是客户端的义务。
 	*
-	* 三个刻意的取舍：
+	* 四个刻意的取舍：
 	* - **不 await**：重放要按会话做授权过滤（异步），握手不能为它排队；
 	* - **只发这一条连接**：不走 `broadcast`，避免每次有人重连就骚扰所有在线设备；
 	* - **失败静默**：重放是补救措施，它出错不该影响这条连接正常收事件。
-	*   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖。
+	*   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖；
+	* - **走连接自己的队列**：重放帧与随后的广播帧必须保序。直接 `socket.send`
+	*   会让「重放的第 2 帧」插到「广播的第 1 帧」前面去。
 	*/
-	async replayPendingInteractions(socket, principal) {
+	async replayPendingInteractions(socket, state) {
 		try {
-			const events = [...await this.options.chat.replayPendingApprovals(principal), ...await this.options.chat.replayPendingQuestions(principal)];
-			for (const event of events) {
-				if (socket.readyState !== WebSocket.OPEN) return;
-				socket.send(stringifyWire(event));
-			}
+			const events = [...await this.options.chat.replayPendingApprovals(state.principal), ...await this.options.chat.replayPendingQuestions(state.principal)];
+			for (const event of events) this.enqueue(socket, state, event);
 		} catch {}
 	}
-	async broadcast(event) {
-		for (const [socket, principal] of this.sockets) {
+	/** 当前设备授权版本；`database` 还没提供就返回 undefined（退回逐事件查库的旧路径）。 */
+	devicesRevisionOf() {
+		const value = this.options.database.devicesRevision;
+		return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+	}
+	/**
+	* 广播入口：**只做快照 + 入队**，全程同步。
+	*
+	* 这里是宿主事件循环上的热路径 —— 订阅回调里的任何 `await`（查库、查内核、
+	* 发网络）都会反过来把宿主的 `push` 拖住。修复前正是这样：一条全局 promise 链
+	* 串起「事件 × 连接」，一个慢判定让所有事件、所有客户端一起排队，`stop()`
+	* 还得 `await` 那条链。
+	*/
+	enqueueBroadcast(event) {
+		recordBroadcastEvent();
+		let deepest = 0;
+		for (const [socket, state] of this.sockets) {
 			if (socket.readyState !== WebSocket.OPEN) continue;
-			let currentPrincipal = principal;
-			if (principal.kind === "device") {
-				const device = this.options.database.getActiveDevice(principal.id);
-				if (device === void 0) {
-					socket.close(4001, "Device revoked");
-					continue;
-				}
-				currentPrincipal = {
-					kind: "device",
-					id: device.id,
-					name: device.name,
-					scopes: new Set(device.scopes),
-					rootIds: new Set(device.rootIds)
-				};
-				this.sockets.set(socket, currentPrincipal);
+			this.enqueue(socket, state, event);
+			if (state.queue.length > deepest) deepest = state.queue.length;
+		}
+		setBroadcastQueueDepth(deepest);
+	}
+	/**
+	* 单连接入队：溢出时按「先丢可重建帧」处理，并给客户端一个 resync 信号。
+	*
+	* 为什么溢出不断连：手机端解码慢一次不该被踢下线（那会触发一条重连风暴，
+	* 而重连风暴又会把刚建好的连接再挤掉）。但「静默丢帧」更糟 —— 客户端会以为
+	* 事件流还连续，于是它手里的状态永远停在丢帧之前。所以丢的时候记一笔，
+	* 随后补发 `connection.resyncRequired`，把「静默」变成「告知」。
+	*/
+	enqueue(socket, state, event) {
+		if (state.queue.length >= this.socketQueueLimit) {
+			if (isRebuildable(event)) {
+				state.dropped += 1;
+				recordDroppedEvent();
+				state.resyncPending = true;
+				return;
+			}
+			const victimIndex = state.queue.findIndex(isRebuildable);
+			if (victimIndex >= 0) {
+				state.queue.splice(victimIndex, 1);
+				state.dropped += 1;
+				recordDroppedEvent();
+			} else {
+				state.queue.shift();
+				state.dropped += 1;
+				recordDroppedEvent();
 			}
-			if (!await this.eventAllowed(currentPrincipal, event)) continue;
-			socket.send(stringifyWire(event));
+			state.resyncPending = true;
+		}
+		state.queue.push(event);
+		this.startDrain(socket, state);
+	}
+	/** 保证一条连接只有一个 drain 循环（否则同一连接内的顺序会被打乱）。 */
+	startDrain(socket, state) {
+		if (state.draining) return;
+		state.draining = true;
+		const task = this.drain(socket, state).catch(() => void 0).finally(() => {
+			state.draining = false;
+			this.pendingDrains.delete(task);
+			if (state.recheckTimer !== void 0) return;
+			if (state.queue.length > 0 && this.sockets.get(socket) === state) this.startDrain(socket, state);
+		});
+		this.pendingDrains.add(task);
+	}
+	/**
+	* 一条连接的发送循环。
+	*
+	* `await` 只发生在「这条连接自己的准备工作」上（刷新设备身份、判断会话授权）。
+	* 于是慢连接只慢它自己 —— 这正是与修复前的根本区别。
+	*/
+	async drain(socket, state) {
+		while (state.queue.length > 0) {
+			if (socket.readyState !== WebSocket.OPEN) {
+				state.queue.length = 0;
+				return;
+			}
+			if (socket.bufferedAmount > this.highWaterMarkBytes) {
+				if (this.noteHighWater(socket, state)) return;
+				return;
+			}
+			state.overHighWater = 0;
+			if (state.resyncPending) {
+				state.resyncPending = false;
+				this.sendFrame(socket, {
+					id: randomUUID(),
+					type: "connection.resyncRequired",
+					time: Date.now(),
+					data: {
+						dropped: state.dropped,
+						reason: "backpressure"
+					}
+				});
+				state.dropped = 0;
+				continue;
+			}
+			const event = state.queue.shift();
+			const principal = await this.refreshPrincipal(socket, state);
+			if (principal === void 0) {
+				state.queue.length = 0;
+				socket.close(4001, "Device revoked");
+				return;
+			}
+			if (!await this.eventAllowed(principal, event)) continue;
+			if (socket.readyState !== WebSocket.OPEN) {
+				state.queue.length = 0;
+				return;
+			}
+			this.sendFrame(socket, event);
 		}
+		if (socket.readyState === WebSocket.OPEN && socket.bufferedAmount > this.highWaterMarkBytes) this.noteHighWater(socket, state);
+	}
+	/**
+	* 记录一次「越过发送高水位」，并安排复查。
+	*
+	* @returns 这条连接是否已经被关掉（调用方据此决定还要不要继续 drain）。
+	*
+	* 两拍才关是刻意的：一次越线可能只是客户端的短暂抖动（切网、GC），
+	* 立刻踢下线会制造重连风暴。但**必须有复查** —— 否则「第二拍」永远不会发生，
+	* 连接就卡在「不发也不关」的僵尸态，比直接断掉更难排查。
+	*/
+	noteHighWater(socket, state) {
+		state.overHighWater += 1;
+		if (state.overHighWater >= 2) {
+			this.closeBackpressured(socket, state);
+			return true;
+		}
+		if (state.recheckTimer !== void 0) return false;
+		state.recheckTimer = setTimeout(() => {
+			state.recheckTimer = void 0;
+			if (this.sockets.get(socket) !== state) return;
+			if (socket.readyState === WebSocket.OPEN) this.startDrain(socket, state);
+		}, HIGH_WATER_RECHECK_MS);
+		return false;
+	}
+	sendFrame(socket, payload) {
+		try {
+			socket.send(stringifyWire(payload));
+		} catch {}
+	}
+	/** 清掉这条连接自己的定时器。**必须**在连接被摘掉时调用，否则定时器会拖住进程。 */
+	clearSocketTimers(state) {
+		if (state.recheckTimer === void 0) return;
+		clearTimeout(state.recheckTimer);
+		state.recheckTimer = void 0;
+	}
+	closeBackpressured(socket, state) {
+		this.clearSocketTimers(state);
+		const dropped = state.dropped;
+		state.queue.length = 0;
+		state.dropped = 0;
+		state.resyncPending = false;
+		recordWsTerminated();
+		this.sockets.delete(socket);
+		setWsConnections(this.sockets.size);
+		this.sendFrame(socket, {
+			id: randomUUID(),
+			type: "connection.resyncRequired",
+			time: Date.now(),
+			data: {
+				dropped,
+				reason: "backpressure"
+			}
+		});
+		socket.close(1013, "Backpressure");
+	}
+	/**
+	* 按需刷新这条连接的身份快照。
+	*
+	* 有 `devicesRevision` 时：只有版本变了才查库 —— 正常情况**一件事都不做**，
+	* 而修复前是「每个事件、每条连接都查一次 `getActiveDevice`」。
+	* 没有该 getter 时退回旧行为（逐事件查库）：老数据库上功能不变，只是慢一点。
+	* 这比「广播路径依赖一个可能不存在的 API」安全得多，也让两侧改动可以分批落地。
+	*
+	* @returns 最新身份；设备已被撤销时返回 undefined。
+	*/
+	async refreshPrincipal(socket, state) {
+		if (state.principal.kind !== "device") return state.principal;
+		const revision = this.devicesRevisionOf();
+		if (revision !== void 0 && revision === state.devicesRevision) return state.principal;
+		const device = this.options.database.getActiveDevice(state.principal.id);
+		if (device === void 0) return void 0;
+		const next = {
+			kind: "device",
+			id: device.id,
+			name: device.name,
+			scopes: new Set(device.scopes),
+			rootIds: new Set(device.rootIds)
+		};
+		state.principal = next;
+		state.devicesRevision = revision;
+		return next;
 	}
 	async eventAllowed(principal, event) {
 		if (event.type.startsWith("file.") && !principal.scopes.has("files.read")) return false;
@@ -6661,6 +8267,20 @@ var RemoteApiServer = class {
 		if (sessionId !== void 0) return this.options.chat.isSessionAuthorized(principal, sessionId);
 		return rootId !== void 0 || principal.kind === "admin";
 	}
+	/**
+	* 等所有连接排空，**有上限**。
+	*
+	* `stop()` 不能无限等：一条读不动的 socket 会让插件卸载挂死，进而拖住进程退出。
+	* 超时后照样会断开它们（`closeCurrent` 负责），只是不再尝试把队列里的东西送出去 ——
+	* 卸载路径上「送达」本来就不是目标。
+	*/
+	async drainAll(timeoutMs) {
+		if (this.pendingDrains.size === 0) return;
+		const all = Promise.all([...this.pendingDrains]).then(() => void 0);
+		await Promise.race([all, new Promise((resolve) => {
+			setTimeout(resolve, timeoutMs).unref?.();
+		})]);
+	}
 	trimOperations() {
 		while (this.operations.size > 20) {
 			const first = this.operations.keys().next().value;
@@ -6670,6 +8290,7 @@ var RemoteApiServer = class {
 	}
 };
 function attachEmbeddedRoutes(webServer, router, remote, extraRoutes = []) {
+	assertExtraRoutePrefixes(extraRoutes);
 	const disposers = [webServer.register({
 		kind: "prefix",
 		path: "/dsh-workspace-api",
@@ -6679,6 +8300,29 @@ function attachEmbeddedRoutes(webServer, router, remote, extraRoutes = []) {
 		for (const dispose of disposers.reverse()) dispose();
 	};
 }
+/**
+* `extraRoutes` 只许挂在 `/plugin/` 下 —— **启动即断言**，违例直接抛。
+*
+* ## 为什么这是一条启动断言，而不是一句注释
+*
+* `extraRoutes` 的全部理由是「浏览器 `<img src>` 带不了 `Authorization` 头」，
+* 所以那条路由不校验设备 token，改用「回环 + 同源 + 裸文件名白名单 + 字节自证」。
+* 那是一套**为只读图片量身定的**信任模型。
+*
+* 只要有人往这个座位里塞一条别的东西（比如一个能读文件的接口），那套模型就
+* 立刻成了漏洞：免令牌 + 只有回环判据，等于任何能从本机发起请求的页面都能用它。
+* 而这种事**不会在 dev 环境暴露** —— 本机回环一切正常，装到用户机器上才变成
+* 「谁都能读」。
+*
+* 所以把「只许 `/plugin/`」写成断言而不是注释：注释管不住下一个人，
+* 断言会在插件**启动时**立刻红，且在 CI 里红在测试而不是用户机器上。
+*
+* `/dsh-workspace-api` 这个**既有**前缀不受影响：它是上面那条固定路由，
+* 不经过 `extraRoutes`。
+*/
+function assertExtraRoutePrefixes(extraRoutes) {
+	for (const route of extraRoutes) if (!route.path.startsWith("/plugin/")) throw new Error(`dsh-remote-bridge: extraRoutes may only be registered under /plugin/ (got "${route.path}"). Routes on this seat bypass the device-token check, so they are restricted to the read-only plugin surface.`);
+}
 function publicOperation(operation) {
 	return {
 		id: operation.id,
@@ -6723,15 +8367,26 @@ function parseProtocolToken(value) {
 	if (joined === void 0) return void 0;
 	return joined.split(",").map((item) => item.trim()).find((item) => item.startsWith("bearer."))?.slice(7);
 }
+/**
+* 500 兜底。
+*
+* `requestId` **必须**复用 router 已经写进 `X-Request-Id` 响应头的那个值：
+* 用户报障时给的是 body 里的 id，而运维翻日志靠的是头里的 id —— 两个不同的
+* UUID 等于「这条线索永远搜不到」。修复前这里**另生成一个** `randomUUID()`。
+*
+* 头不存在时（理论上只有 router 之外的调用方）才新生成，保证字段不为空。
+*/
 function failResponse(res, error) {
 	if (res.headersSent) {
 		res.destroy(error instanceof Error ? error : void 0);
 		return;
 	}
+	const headerValue = res.getHeader("x-request-id");
+	const requestId = typeof headerValue === "string" && headerValue !== "" ? headerValue : randomUUID();
 	const body = Buffer.from(JSON.stringify({ error: {
 		code: "INTERNAL_ERROR",
 		message: "An internal server error occurred.",
-		requestId: randomUUID()
+		requestId
 	} }));
 	res.writeHead(500, {
 		"Content-Type": "application/json",
@@ -6741,6 +8396,15 @@ function failResponse(res, error) {
 }
 //#endregion
 //#region src/host/settings-adapter.ts
+/**
+* provider 上下文的复用窗口。
+*
+* 1 秒足以覆盖「同一个 PATCH 请求里的连续两次 context 查询」，又短到不会让
+* 用户可感知地读到旧值（真正的并发控制由 `expectedRevision` 负责）。
+*/
+const PROVIDER_CONTEXT_TTL_MS = 1e3;
+/** 缓存条目上限；到顶就整表清空（条目数与 provider 数量同阶，很小）。 */
+const PROVIDER_CONTEXT_CACHE_LIMIT = 128;
 var DshSettingsAdapter = class {
 	api;
 	constructor(api) {
@@ -6891,6 +8555,7 @@ var DshSettingsAdapter = class {
 				}
 			}));
 		}
+		this.invalidateProviderContext(providerId);
 	}
 	async createProvider(input) {
 		const id = input.id.trim();
@@ -6941,6 +8606,7 @@ var DshSettingsAdapter = class {
 				value: key
 			}
 		}));
+		this.invalidateProviderContext(id);
 	}
 	async removeProvider(providerId, expectedRevision) {
 		const context = await this.providerContext(providerId);
@@ -6957,6 +8623,7 @@ var DshSettingsAdapter = class {
 				...expectedRevision === void 0 ? {} : { expectedRevision }
 			}
 		}));
+		this.invalidateProviderContext(providerId);
 	}
 	async discover(providerId, draft) {
 		const payload = {
@@ -6971,7 +8638,47 @@ var DshSettingsAdapter = class {
 			payload
 		})).models;
 	}
+	/**
+	* 取一个 provider 的上下文（目录条目 + 设置命名空间 + 当前 profile）。
+	*
+	* ## 为什么加一层「单请求内复用」
+	*
+	* 修复前 `updateProvider()` 会**连续**调它两次（一次在开头做校验、一次在
+	* `createProvider`/`removeProvider` 里），而每次 `providerContext` 都要打
+	* **两次**内核 RPC（`llm.providers` + `settings.describe`）。于是一次 PATCH
+	* 实际可能产生 4~5 次内核往返 —— 而它们问的是**同一份数据**。
+	*
+	* 这里用一个极短的 TTL（默认 1 秒，覆盖「同一请求内」的连续调用）缓存结果。
+	* 为什么不用「请求作用域」的显式传参：那要改每个方法的签名，而调用点散在
+	* router 与 adapter 两处 —— 收益远不抵这次改动。1 秒 TTL 的副作用是：
+	* 同一秒内两次改同一个 provider 时，第二次读到的是第一次之前的快照 ——
+	* 而 `settings.mutate` 有 `expectedRevision` 做真正的并发控制，所以不会写坏。
+	*/
+	providerContextCache = /* @__PURE__ */ new Map();
 	async providerContext(providerId) {
+		const cached = this.providerContextCache.get(providerId);
+		const now = Date.now();
+		if (cached !== void 0 && now - cached.at < PROVIDER_CONTEXT_TTL_MS) return cached.value;
+		const value = await this.loadProviderContext(providerId);
+		if (this.providerContextCache.size >= PROVIDER_CONTEXT_CACHE_LIMIT) this.providerContextCache.clear();
+		this.providerContextCache.set(providerId, {
+			at: now,
+			value
+		});
+		return value;
+	}
+	/**
+	* 写操作之后**必须**让缓存失效。
+	*
+	* 为什么不能只靠 TTL：`updateProvider` 改完 baseURL 之后，同一个请求尾部的
+	* `listProviders()` 要给出新值。靠 TTL 等 1 秒等于把一个「刚刚改成功」的
+	* 界面回滚成旧值 —— 那会被用户当成「改了没生效」。
+	*/
+	invalidateProviderContext(providerId) {
+		if (providerId === void 0) this.providerContextCache.clear();
+		else this.providerContextCache.delete(providerId);
+	}
+	async loadProviderContext(providerId) {
 		const [directoryResponse, settingsResponse] = await Promise.all([this.api.llm.providers({
 			rpcId: randomUUID(),
 			payload: {}
@@ -7130,6 +8837,7 @@ async function apply(ctx, config = {}) {
 	} catch (error) {
 		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: could not purge revoked devices: ${String(error)}`));
 	}
+	runStartupRetention(database, ctx.logger);
 	await registerBuiltinWorkspaceRoot(ctx, database);
 	const events = new WorkspaceEventBus();
 	const tunnels = new CloudflaredTunnelManager();
@@ -7171,7 +8879,8 @@ async function apply(ctx, config = {}) {
 		auth,
 		chat,
 		events,
-		handle: (req, res) => router.handle(req, res)
+		handle: (req, res) => router.handle(req, res),
+		capabilities: { jobs: jobControllerAvailable }
 	});
 	router = new ApiRouter({
 		database,