dsh-remote-bridge 2.5.1 → 2.6.0

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.6.0";
 //#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.");
@@ -3198,7 +3978,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			}
 		};
 	}
-	if (payloadType === "session/event" && typeof payload.sessionId === "string" && isRecord$1(payload.event)) {
+	if (payloadType === "session/event" && typeof payload.sessionId === "string" && isRecord$2(payload.event)) {
 		const event = payload.event;
 		const eventType = typeof event.type === "string" ? event.type : "unknown";
 		const seq = typeof event.seq === "number" ? event.seq : void 0;
@@ -3208,9 +3988,9 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			...seq === void 0 ? {} : { seq }
 		};
 		const assistantData = event.data;
-		if (eventType === "assistant/chunk" && isRecord$1(assistantData)) {
+		if (eventType === "assistant/chunk" && isRecord$2(assistantData)) {
 			const rawChunk = assistantData.chunk;
-			if (isRecord$1(rawChunk)) {
+			if (isRecord$2(rawChunk)) {
 				const kind = rawChunk.type === "text-delta" ? "text" : rawChunk.type === "reasoning-delta" ? "reasoning" : void 0;
 				if (kind !== void 0 && typeof rawChunk.text === "string" && typeof rawChunk.index === "number") return {
 					id: frame.rpcId,
@@ -3228,7 +4008,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			}
 		}
 		if (eventType === "user/message" || eventType === "assistant/message") {
-			const eventData = isRecord$1(event.data) ? event.data : {};
+			const eventData = isRecord$2(event.data) ? event.data : {};
 			return {
 				id: frame.rpcId,
 				type: "chat.message.committed",
@@ -3242,8 +4022,8 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			};
 		}
 		if (eventType === "deliverables/presented") {
-			const data = isRecord$1(payload.event) ? payload.event.data : void 0;
-			const files = isRecord$1(data) && Array.isArray(data.files) ? data.files : [];
+			const data = isRecord$2(payload.event) ? payload.event.data : void 0;
+			const files = isRecord$2(data) && Array.isArray(data.files) ? data.files : [];
 			return {
 				id: `${payload.sessionId}:deliverables:${seq ?? files.length}`,
 				type: "chat.deliverables.presented",
@@ -3271,7 +4051,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 					};
 				}
 			}
-			const turnReason = eventType === "turn/end" && isRecord$1(event.data) ? event.data.reason : void 0;
+			const turnReason = eventType === "turn/end" && isRecord$2(event.data) ? event.data.reason : void 0;
 			return {
 				id: frame.rpcId,
 				type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
@@ -3331,12 +4111,12 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 * 用本地化文案「API 密钥无效」顶上。这里保持原样转发，不替客户端猜。
 */
 function turnFailureOf(event) {
-	const reason = isRecord$1(event.data) ? event.data.reason : void 0;
-	if (!isRecord$1(reason)) return void 0;
+	const reason = isRecord$2(event.data) ? event.data.reason : void 0;
+	if (!isRecord$2(reason)) return void 0;
 	const kind = reason.kind;
 	if (kind === "error") {
 		const error = reason.error;
-		if (!isRecord$1(error)) return { message: String(error ?? "本轮运行失败") };
+		if (!isRecord$2(error)) return { message: String(error ?? "本轮运行失败") };
 		const code = typeof error.code === "string" ? error.code : void 0;
 		const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
 		return code === void 0 ? { message } : {
@@ -3344,13 +4124,13 @@ function turnFailureOf(event) {
 			code
 		};
 	}
-	if (kind === "aborted" && isRecord$1(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
+	if (kind === "aborted" && isRecord$2(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
 		message: "Stopped because you signed out of DeepSeek.",
 		code: "ACCOUNT_SIGNED_OUT",
 		stopped: true
 	};
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function matchRoot(roots, cwd) {
@@ -3436,13 +4216,13 @@ function findToolCallDetail(events, callId) {
 	if (callId === void 0) return void 0;
 	for (let index = events.length - 1; index >= 0; index -= 1) {
 		const candidate = events[index];
-		if (!isRecord$1(candidate)) continue;
-		const event = isRecord$1(candidate.event) ? candidate.event : candidate;
-		if (event.type !== "tool/call" || !isRecord$1(event.data)) continue;
+		if (!isRecord$2(candidate)) continue;
+		const event = isRecord$2(candidate.event) ? candidate.event : candidate;
+		if (event.type !== "tool/call" || !isRecord$2(event.data)) continue;
 		const data = event.data;
 		if ((typeof data.callId === "string" ? data.callId : typeof data.id === "string" ? data.id : void 0) !== callId) continue;
 		const args = decodeToolArguments(data.arguments);
-		if (isRecord$1(args) && typeof args.command === "string") return args.command;
+		if (isRecord$2(args) && typeof args.command === "string") return args.command;
 		if (typeof args === "string") return args;
 		if (args !== void 0) return JSON.stringify(args, null, 2);
 	}
@@ -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"));
+	/**
+	* 「设备集合或设备权限发生过写」的进程内单调计数。
+	*
+	* ## 为什么需要它
+	*
+	* 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` 的行）。
@@ -3763,22 +4616,127 @@ var WorkspaceDatabase = class {
 	* 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
 	* 并起一个自见其明的名字，免得有人把它当成正常 API。
 	*/
+	/**
+	* 仅供测试：把某台设备的「最后使用时间/创建时间」拨到过去。
+	*
+	* 生产路径没法造出「30 天没动过」的设备（认证一次就刷新 `last_seen_at`），而
+	* `pruneInactiveDevices` 的核心语义恰恰只在这种时间跨度上才看得见。与
+	* `markRevokedForTest` 同样的理由：显式开一个自见其明的测试入口，别让人误当 API。
+	*/
+	backdateDeviceForTest(id, options) {
+		if (options.lastSeenAt !== void 0) this.db.prepare("UPDATE devices SET last_seen_at = ? WHERE id = ?").run(options.lastSeenAt, id);
+		if (options.createdAt !== void 0) this.db.prepare("UPDATE devices SET created_at = ? WHERE id = ?").run(options.createdAt, id);
+	}
 	markRevokedForTest(id) {
 		this.db.prepare("UPDATE devices SET revoked_at = ? WHERE id = ?").run(Date.now(), id);
 	}
+	/**
+	* 按「最后使用时间」批量清掉长期没动过的设备。
+	*
+	* 「最后使用」取 `last_seen_at`（每次令牌认证成功都会刷新），从没认证过的设备退回
+	* `created_at` —— 否则一条配好就再没开过的设备会永远躲过清理，而那恰恰是用户最想
+	* 一键清掉的那类（换手机、临时配对、旧测试探针）。
+	*
+	* 与 `purgeRevokedDevices` 的区别：后者清的是历史遗留的「标记式撤销」脏行，这里清的是
+	* **仍然有效、但已经不用了**的设备 —— 用户的原话是「一键清理多少天未使用设备」。
+	*
+	* 语义边界（故意这么定）：
+	* - 只删设备行 + 级联的 `device_roots`，不碰审计（审计的 `actor_id` 不是外键）；
+	* - **不删本机正在用的那台**（`keepDeviceId`）：调用方就是它，删掉自己会让当前
+	*   客户端立刻 401，看起来像「点一下清理把手机踢下线了」；
+	* - 天数被夹在 1..3650，避免 `0` 或负数变成「清空所有设备」；
+	* - 返回真正删掉的条数，0 也是一次合法结果。
+	*/
+	pruneInactiveDevices(olderThanDays, options = {}) {
+		const days = Math.min(3650, Math.max(1, Math.trunc(olderThanDays)));
+		const cutoff = Date.now() - days * 24 * 60 * 60 * 1e3;
+		const rows = this.db.prepare("SELECT id, name FROM devices WHERE COALESCE(last_seen_at, created_at) < ? AND id IS NOT ?").all(cutoff, options.keepDeviceId ?? null);
+		if (rows.length === 0) {
+			this.devicesRevisionCounter += 1;
+			return 0;
+		}
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const statement = this.db.prepare("DELETE FROM devices WHERE id = ?");
+			for (const row of rows) statement.run(row.id);
+			this.audit("admin", "loopback-admin", "device.prune", void 0, void 0, {
+				olderThanDays: days,
+				pruned: rows.length,
+				names: rows.map((row) => row.name)
+			}, options.requestId);
+			this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+		this.devicesRevisionCounter += 1;
+		return rows.length;
+	}
 	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 +4902,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 +4928,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 +4956,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 +4978,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 +4992,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 +5001,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 +5139,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 +5333,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 +5501,265 @@ function probeHostServices(host, pluginVersion) {
 	};
 }
 //#endregion
+//#region src/host/im-command.ts
+/**
+* `/tunnel` —— 从即时通讯（微信 / 飞书 / 钉钉 / 企业微信 …）里远程开隧道并取回配置文本。
+*
+* ## 为什么需要它
+*
+* 用户常见的困境是「人已经出门，才发现电脑上的 Cloudflare 隧道没开，配置文本也没发给自己」。
+* 此时公网入口不存在，WebUI 与 App 都够不着这台机器 —— 唯一的反向通道是 IM 机器人的
+* **长连接**（手机/IM 云 → 本机主动连出去，不需要任何入站端口）。
+*
+* 本模块只做一件事：注册一条 `/tunnel` 命令，把「开隧道 + 生成 DSH1 配置文本」的结果
+* 直接作为聊天消息回给发送者。**不做停止、不做改配置、不读任何文件** —— 攻击面刻意压到
+* 「最多被人开一次隧道」，而隧道本身不授予任何数据面权限（数据面仍要设备令牌）。
+*
+* ## 门禁在哪里（重要）
+*
+* 本命令**自己不做身份校验**，它依赖 IM 插件在派发命令之前执行的访问策略：
+* `@xmanrui/dsh-im` 的每个机器人都有 `canExecuteCommands` / `defaultCanExecuteCommands`，
+* 非白名单发送者的 `/xxx` 根本到不了这里（`lib/index.js` 的 access policy 判定）。因此
+* 部署侧的必要条件是：**机器人保持 allowlist 模式，且只把自己加进白名单**。
+* 这条约束写在 README「远程开隧道」一节与 SECURITY.md 里，别只在代码注释里说。
+*
+* ## 为什么直接调宿主 API 而不是走 HTTP 自调用
+*
+* 「已开隧道」这一状态下，`/manage` 管理面被判据 0 整体关门（`auth.ts` 的
+* `TUNNEL_MODE_ADMIN_DISABLED`），`/manage/config/text` 必然 403 —— 走 HTTP 就取不到
+* 配置文本。命令在插件进程内执行，与路由共用同一个隧道管理器与同一套建配置逻辑，
+* 天然绕开这个自锁，且不需要为它额外豁免任何端点。
+*
+* @module dsh-remote-bridge/im-command
+*/
+/** 命令名（不带斜杠）。 */
+const TUNNEL_COMMAND_NAME = "tunnel";
+/** 命令描述：会出现在 IM 的 `/help` 里。 */
+const TUNNEL_COMMAND_DESCRIPTION = "开启 Cloudflare 隧道并返回一行配置文本（DSH1:…）";
+/** 把结果拼成聊天消息。 */
+function formatTunnelReply(result) {
+	return [
+		"云隧道已开启。",
+		`地址：${result.url}`,
+		`设备名：${result.deviceName}`,
+		"配置文本（一行，复制后粘贴到 App 的「导入配置」）：",
+		result.text
+	].join("\n");
+}
+/**
+* 创建 `/tunnel` 的命令定义（不注册，纯数据，便于单测）。
+*
+* 参数只接受空串：本命令刻意**不接受**任何开关，避免出现「`/tunnel stop`」这种需要
+* 额外鉴权语义的入口。带参数一律回用法说明。
+*/
+function createTunnelCommand(deps) {
+	/** 同一时刻只允许一次开隧道（IM 侧重发、双端同时发都可能撞上）。 */
+	let inFlight = false;
+	return {
+		name: TUNNEL_COMMAND_NAME,
+		description: TUNNEL_COMMAND_DESCRIPTION,
+		input: { hint: "（无需参数）" },
+		async handler(invocation) {
+			if (invocation.rawInput.trim().length > 0) return {
+				kind: "error",
+				text: "用法：/tunnel（不需要参数）"
+			};
+			if (inFlight) return {
+				kind: "error",
+				text: "上一次开隧道还没结束，请稍等几秒再发一次。"
+			};
+			inFlight = true;
+			try {
+				const result = await deps.openTunnel();
+				deps.logger?.info(`[dsh-remote-bridge] /tunnel 已开启隧道 ${result.url}`);
+				return {
+					kind: "success",
+					text: formatTunnelReply(result)
+				};
+			} catch (cause) {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				deps.logger?.warn(cause instanceof Error ? cause : new Error(message));
+				return {
+					kind: "error",
+					text: `开隧道失败：${message}`
+				};
+			} finally {
+				inFlight = false;
+			}
+		}
+	};
+}
+/**
+* 注册 `/tunnel` 并返回注销函数。
+*
+* 注册是**全局层**（不是 agent 子层），所以任何 IM 会话、任何工作区里都能用 ——
+* 这正是本命令的用途：开机时人不在电脑边。是否允许某个人执行，由 IM 插件的
+* 访问策略决定（见模块头注释）。
+*/
+function registerTunnelCommand(registry, deps) {
+	return registry.register(createTunnelCommand(deps));
+}
+/**
+* ## 为什么除命令之外还要一个工具
+*
+* `@xmanrui/dsh-im` 5.4.0 的斜杠命令表是**封闭的**：内置 31 条，另外只把
+* `/compact` `/clear` `/permission` 三条委派给宿主（`lib/index.js` 里
+* `executeCommand("/compact")` 等固定字面量），**没有**「未知命令转交宿主命令表」的通用派发，
+* 也从不调用 `commands.list`。所以在 IM 里发 `/tunnel` 到不了上面那个命令处理函数 ——
+* 它会当成一句普通消息交给智能体。
+*
+* 于是 IM 侧真正可用的入口是**工具**：用户用自然语言说一句（「帮我开隧道，把配置发我」），
+* 智能体调用本工具，结果直接回到聊天里。命令与工具共用同一个 `openTunnel()`，
+* 语义完全一致；两者的差别只是「谁来触发」。
+*/
+/** 工具名（模型可见）。 */
+const TUNNEL_TOOL_NAME = "open_tunnel_config";
+/**
+* 模型可见描述。
+*
+* 写英文是惯例（工具描述面向模型，与仓内其他描述同语言），并显式写清
+* 「用户说开隧道/取配置文本时调用」，否则模型倾向于自己用 bash 拼一条 curl。
+*/
+const TUNNEL_TOOL_DESCRIPTION = "Open the Cloudflare quick tunnel for this DSH host and return a one-line DSH1: config text that a phone app can paste to connect. Use it whenever the user asks to start the tunnel, to get the config text, or says they are away from the computer and need remote access. It never stops the tunnel and never touches files.";
+/** 创建工具定义（不注册，便于单测）。 */
+function createTunnelTool(deps) {
+	return {
+		name: TUNNEL_TOOL_NAME,
+		description: TUNNEL_TOOL_DESCRIPTION,
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					url: {
+						type: "string",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					deviceName: {
+						type: "string",
+						required: true
+					}
+				},
+				required: true
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Tunnel is up at ${value.url}`
+			}, {
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute() {
+			const result = await deps.openTunnel();
+			deps.logger?.info(`[dsh-remote-bridge] ${TUNNEL_TOOL_NAME} 已开启隧道 ${result.url}`);
+			return {
+				url: result.url,
+				text: result.text,
+				deviceName: result.deviceName
+			};
+		}
+	};
+}
+/** 注册工具并返回注销函数。注册是全局层：任何会话（含 IM 会话）都能调用。 */
+function registerTunnelTool(registry, deps) {
+	return registry.register(createTunnelTool(deps));
+}
+//#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 +6051,14 @@ function defaultDisplayName() {
 //#endregion
 //#region src/host/plugin-inventory.ts
 /**
+* 读包清单时的并发上限。
+*
+* 为什么不是 `Promise.all` 全放：`names` 的长度由用户装了多少插件决定，
+* 理论上可以几十上百；一把放出去在慢盘/网络盘上反而更慢，而且失败时更难定位。
+* 6 与 `withUpdateCheck` 的网络并发同值，本仓已经验证过。
+*/
+const INVENTORY_READ_CONCURRENCY = 6;
+/**
 * 把 profile 标识归一化成 profile 名。
 *
 * 内核接受**两种**写法，两者都合法：
@@ -4883,8 +6202,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);
@@ -5203,37 +6531,160 @@ async function inspectResolvedPath(root, wirePath) {
 	};
 }
 //#endregion
-//#region src/host/wire-json.ts
+//#region src/host/settings-namespace.ts
 /**
-* 出网 JSON 的安全序列化：把**孤立 UTF-16 代理项**换成 U+FFFD。
+* 通用设置命名空间的纯逻辑：写允许策略、密钥脱敏、ops 校验与响应投影。
 *
-* ## 为什么需要这一层（实发场景）
-*
-* DSH 内核在生成事件摘要时会按**字符数**截断字符串。若截断点正好落在
-* 一个代理对（emoji、部分 CJK 扩展字、某些工具输出的花括号表情）中间，
-* 字符串里就只剩**半个**代理项。`JSON.stringify` 会把它老实转义成 `\udXXX`，
-* 于是线上出现一份「语法合法、语义非法」的 JSON：
-* JavaScript 侧照常解析，而 **Swift/Foundation 的 JSONDecoder 会直接拒绝整帧**。
-* 症状极具误导性 —— 一条工具输出的半个 emoji，把整条 WebSocket 连接打死，
-* 客户端表现为「突然不再更新」，日志里只有一句解码失败。
+* 为什么单独成文件（2.6.0）：这一层不碰任何内核 RPC，全部可以纯单测；
+* 而 `settings-adapter.ts` 已贴着 `AGENTS.md` §3.2 的 600 行单文件预算。
+* 拆出来之后两边都不再挤，adapter 只保留「调内核 + 映射错误」的那几行。
 *
-* ## 为什么在传输层做，而不是在产生摘要的地方做
+* 契约见 `docs/api/openapi.yaml` 的 SettingsNamespace* 与 `docs/project/API.md`
+* 的「通用设置命名空间」一节；安全判据的理由见 `docs/project/SECURITY.md`。
+*/
+const MAX_OPS = 32;
+/**
+* 键名兜底脱敏正则。
 *
-* 摘要不只一处（chat-adapter 的工具输出、内核自己拼的标题、历史重放…），
-* 逐个补是打地鼠；而**出网**只有两个口（HTTP JSON 响应与 WebSocket 帧），
-* 在这里做一次就等于全覆盖，且未来新增事件类型自动受益。
+* **不是主要机制**：内核 `settings.describe()` 已经用 `redactSecrets: true` 读过一遍，
+* role('secret') 的字段不会随响应出网（见 dsh-api-settings-controller 的
+* `namespaceView`/`describe`）。这里是第二道保险 —— 万一某个自定义 schema 漏标了
+* role('secret')，或者凭据被写进了普通字段，桥也不会把它端给手机。
 *
-* ## 为什么不用正则
+* `apiKeyEnv` 是环境变量**名**不是密钥值，一并遮蔽是刻意的：名字本身能暴露
+* 「这台机器用哪家 key」，而 App 读设置根本不需要这个名字。
+*/
+const SECRET_KEY = /^(apiKey|secret|token|password|credential|apiKeyEnv)$/i;
+/**
+* 写允许策略：`ui-*`（界面类插件设置）与 `*locale`（语言/区域）默认可写。
 *
-* 「孤立代理项」的判定需要看**相邻字符**。带后向断言的正则在超长字符串上
-* 有性能与兼容两个问题（KMP/Server 端行为不一致），而这是一条会被每个事件
-* 走到的热路径。这里用单遍字符扫描：O(n)、无递归、无回溯，且对合法代理对
-* 原样放行（emoji 不会被吃掉）。
+* 其余一律默认只读，尤其是能改「模型、权限、子代理」的命名空间 —— 手机一旦
+* 丢了或被恶意 App 拿到令牌，改模型等于把请求引到攻击者的端点，改权限等于
+* 把审批闸门拆掉。需要放行时由部署者显式配 `settingsWriteNamespaces`。
+*/
+function isSettingsNamespaceWriteAllowed(ns, extra = []) {
+	if (ns.startsWith("ui-") || ns.endsWith("locale")) return true;
+	return extra.some((pattern) => pattern.endsWith("*") ? ns.startsWith(pattern.slice(0, -1)) : ns === pattern);
+}
+/**
+* 单个命名空间不可写的原因。
 *
-* 对标：第三方移动网关 `dsh-plugin-mobile-gateway` 的 `lib/wire-json.mjs` 做了同一件事
-* （它只用了 7 行 —— 我们这边多出来的部分全是给「为什么不那样做」留的注释）。
+* 宿主设置文档整体只读优先报 `HOST_READONLY`：那与 ns 策略无关，修策略也没用。
 */
-/** 孤儿代理项的统一替身：Unicode 的「替换字符」。 */
+function settingsNamespaceReason(hostWritable, ns, extra = []) {
+	if (!hostWritable) return "HOST_READONLY";
+	if (!isSettingsNamespaceWriteAllowed(ns, extra)) return "HIGH_RISK_NAMESPACE";
+}
+/**
+* 递归遮蔽密钥：键名命中 {@link SECRET_KEY}，或路径整体命中内核给出的
+* `secrets[].path`（前者是兜底，后者才是权威）。
+*
+* 路径按 `\u0000` 拼接比较，避免 `['a.b']` 与 `['a','b']` 混淆；
+* 数组下标也进路径，密钥恰好是数组元素时同样能命中。
+*/
+function redactSettingsSecrets(value, secretPaths = []) {
+	const exact = new Set(secretPaths.map((path) => path.join("\0")));
+	return walk(value, []);
+	function walk(current, path) {
+		if (path.length > 0 && exact.has(path.join("\0"))) return "***";
+		if (typeof current === "string") {
+			const key = path.at(-1);
+			return key !== void 0 && SECRET_KEY.test(key) ? "***" : current;
+		}
+		if (Array.isArray(current)) return current.map((item, index) => walk(item, [...path, String(index)]));
+		if (isRecord$1(current)) return Object.fromEntries(Object.entries(current).map(([key, item]) => [key, walk(item, [...path, key])]));
+		return current;
+	}
+}
+/** 校验并规范化请求里的 `ops`；结构不合法一律 400 `SETTINGS_OPS_INVALID`。 */
+function parseSettingsNamespaceOps(input) {
+	if (!Array.isArray(input) || input.length === 0 || input.length > MAX_OPS) throw new ApiError(400, "SETTINGS_OPS_INVALID", `ops must be an array of 1 to ${MAX_OPS} operations.`);
+	return input.map((raw, index) => {
+		const where = `ops[${index}]`;
+		if (!isRecord$1(raw)) throw invalid(`${where} must be an object.`);
+		if (raw.op !== "set" && raw.op !== "unset") throw invalid(`${where}.op must be "set" or "unset".`);
+		if (!Array.isArray(raw.path) || raw.path.some((segment) => typeof segment !== "string")) throw invalid(`${where}.path must be an array of strings.`);
+		const path = [...raw.path];
+		if (raw.op === "unset") return {
+			op: "unset",
+			path
+		};
+		if (!Object.hasOwn(raw, "value")) throw invalid(`${where}.value is required for "set".`);
+		return {
+			op: "set",
+			path,
+			value: raw.value
+		};
+	});
+}
+/** 审计用字段清单：只记路径，**绝不记值**。根路径（空数组）不产生字段名。 */
+function settingsNamespaceOpFields(ops) {
+	return [...new Set(ops.map((op) => op.path.join(".")).filter((field) => field !== ""))];
+}
+/** 本次写入是否碰到了密钥位（审计 `credentialChanged`）；只看路径，不看值。 */
+function settingsNamespaceCredentialChanged(ops, secrets) {
+	if (secrets === void 0 || secrets.length === 0) return false;
+	const exact = new Set(secrets.map((secret) => secret.path.join("\0")));
+	return ops.some((op) => exact.has(op.path.join("\0")));
+}
+/** 内核视图 → 对外视图：叠加写策略并脱敏。 */
+function projectSettingsNamespace(view, hostWritable, extra = []) {
+	const writable = hostWritable && isSettingsNamespaceWriteAllowed(view.ns, extra);
+	const secretPaths = (view.secrets ?? []).map((secret) => secret.path);
+	const project = (value) => redactSettingsSecrets(value, secretPaths);
+	const reason = settingsNamespaceReason(hostWritable, view.ns, extra);
+	return {
+		ns: view.ns,
+		revision: view.revision,
+		...view.schema === void 0 ? {} : { schema: view.schema },
+		value: project(view.value),
+		...view.base === void 0 ? {} : { base: project(view.base) },
+		...view.user === void 0 ? {} : { user: project(view.user) },
+		...view.autoGenerate === void 0 ? {} : { autoGenerate: view.autoGenerate },
+		...view.applies === void 0 ? {} : { applies: view.applies },
+		...view.secrets === void 0 ? {} : { secrets: view.secrets },
+		writable,
+		...reason === void 0 ? {} : { reason }
+	};
+}
+function invalid(message) {
+	return new ApiError(400, "SETTINGS_OPS_INVALID", message);
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/host/wire-json.ts
+/**
+* 出网 JSON 的安全序列化：把**孤立 UTF-16 代理项**换成 U+FFFD。
+*
+* ## 为什么需要这一层（实发场景）
+*
+* DSH 内核在生成事件摘要时会按**字符数**截断字符串。若截断点正好落在
+* 一个代理对（emoji、部分 CJK 扩展字、某些工具输出的花括号表情）中间，
+* 字符串里就只剩**半个**代理项。`JSON.stringify` 会把它老实转义成 `\udXXX`，
+* 于是线上出现一份「语法合法、语义非法」的 JSON：
+* JavaScript 侧照常解析，而 **Swift/Foundation 的 JSONDecoder 会直接拒绝整帧**。
+* 症状极具误导性 —— 一条工具输出的半个 emoji，把整条 WebSocket 连接打死，
+* 客户端表现为「突然不再更新」，日志里只有一句解码失败。
+*
+* ## 为什么在传输层做，而不是在产生摘要的地方做
+*
+* 摘要不只一处（chat-adapter 的工具输出、内核自己拼的标题、历史重放…），
+* 逐个补是打地鼠；而**出网**只有两个口（HTTP JSON 响应与 WebSocket 帧），
+* 在这里做一次就等于全覆盖，且未来新增事件类型自动受益。
+*
+* ## 为什么不用正则
+*
+* 「孤立代理项」的判定需要看**相邻字符**。带后向断言的正则在超长字符串上
+* 有性能与兼容两个问题（KMP/Server 端行为不一致），而这是一条会被每个事件
+* 走到的热路径。这里用单遍字符扫描：O(n)、无递归、无回溯，且对合法代理对
+* 原样放行（emoji 不会被吃掉）。
+*
+* 对标：第三方移动网关 `dsh-plugin-mobile-gateway` 的 `lib/wire-json.mjs` 做了同一件事
+* （它只用了 7 行 —— 我们这边多出来的部分全是给「为什么不那样做」留的注释）。
+*/
+/** 孤儿代理项的统一替身：Unicode 的「替换字符」。 */
 const REPLACEMENT = "�";
 const HIGH_SURROGATE_START = 55296;
 const HIGH_SURROGATE_END = 56319;
@@ -5300,25 +6751,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 +6789,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 +6804,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 +6847,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 +6907,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 +6926,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 +6952,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);
@@ -5544,6 +7013,27 @@ var ApiRouter = class {
 			sendJson(res, 200, await this.options.settings.catalog());
 			return;
 		}
+		if (method === "GET" && pathname === "/api/v1/settings/namespaces") {
+			this.options.auth.requireScope(principal, "settings.read");
+			sendJson(res, 200, await this.options.settings.describeNamespaces());
+			return;
+		}
+		const settingsNamespaceRoute = pathname.match(/^\/api\/v1\/settings\/namespaces\/([^/]+)$/);
+		if (settingsNamespaceRoute !== null && method === "PATCH") {
+			this.options.auth.requireScope(principal, "settings.write");
+			const ns = decodePathSegment(settingsNamespaceRoute[1]);
+			const body = await readJson(req, 256e3);
+			const record = typeof body === "object" && body !== null ? body : {};
+			const ops = parseSettingsNamespaceOps(record.ops);
+			const entry = await this.options.settings.mutateNamespace(ns, ops, settingsExpectedRevision(record.expectedRevision));
+			this.audit(principal, "settings.namespace.mutate", void 0, void 0, requestId, {
+				ns,
+				fields: settingsNamespaceOpFields(ops),
+				credentialChanged: settingsNamespaceCredentialChanged(ops, entry.secrets)
+			});
+			sendJson(res, 200, entry);
+			return;
+		}
 		if (method === "GET" && pathname === "/api/v1/settings/plugins") {
 			this.options.auth.requireScope(principal, "settings.read");
 			const inventory = await readPluginInventory();
@@ -5571,7 +7061,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 +7087,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 +7131,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 +7142,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 +7157,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 +7194,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 +7229,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 +7249,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 +7259,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 +7286,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 +7311,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 +7333,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 +7361,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 +7375,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 +7402,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;
@@ -5926,49 +7416,34 @@ var ApiRouter = class {
 			sendJson(res, 200, { items: this.options.database.listDevices() });
 			return;
 		}
+		if (method === "POST" && pathname === "/manage/devices/prune") {
+			const raw = (await readJson(req, 64e3)).olderThanDays;
+			if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1 || raw > 3650) throw new ApiError(400, "INVALID_OLDER_THAN_DAYS", "olderThanDays must be an integer between 1 and 3650.");
+			sendJson(res, 200, { pruned: this.options.database.pruneInactiveDevices(raw, { requestId }) });
+			return;
+		}
 		const deviceRoute = pathname.match(/^\/manage\/devices\/([^/]+)$/);
 		if (deviceRoute !== null && method === "PATCH") {
 			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 +7483,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,21 +7502,12 @@ var ApiRouter = class {
 			}
 		}
 		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/create") {
-			const binDir = this.options.cloudflaredBinDir;
-			let exe;
-			try {
-				exe = await ensureCloudflared(binDir ?? this.options.database.dataDir, (a) => {
-					this.options.tunnels.reportActivity(a);
-				});
-			} catch (cause) {
-				this.options.tunnels.clearActivity();
-				throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", cause instanceof Error ? cause.message : String(cause));
-			}
-			const port = this.options.remote.status().configuredPort ?? 3090;
-			const state = await this.options.tunnels.startQuick(exe, port);
-			this.options.tunnels.clearActivity();
-			this.options.database.audit("admin", "loopback-admin", "cloudflare.create", void 0, void 0, {}, requestId);
-			sendJson(res, 201, state);
+			const createBody = await readJson(req, 64e3).catch(() => ({}));
+			const { state, configText } = await this.createTunnel(createBody, requestId, "loopback-admin");
+			sendJson(res, 201, configText === void 0 ? state : {
+				...state,
+				configText
+			});
 			return;
 		}
 		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/stop") {
@@ -6053,6 +7519,99 @@ var ApiRouter = class {
 		throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
 	}
 	/**
+	* 打开隧道并（可选）顺带产出配置文本 —— HTTP `POST /manage/cloudflare/create` 与
+	* IM `/tunnel` 命令**共用**这一条实现。
+	*
+	* 抽出来的原因：两条入口的前半段完全一致（确保 cloudflared → startQuick → 等随机域名 →
+	* 建配置文本），差别只在「谁在调用」——HTTP 侧要先把请求体读干净（流会随时间关闭），
+	* 命令侧没有请求体。复制一份会让「一键出令牌」在两条路径上慢慢漂移。
+	*
+	* @param createBody - 已解析的请求体（HTTP 侧）或 `{ configText: true }`（命令侧）。
+	* @param requestId - 审计与配对记录共用的请求 ID。
+	* @param actorLabel - 审计里的操作者标签：`loopback-admin`（本机管理面）或 `im-command`。
+	* @returns 合并了「等到地址」的 state，以及（wantConfig 且拿到地址时）配置文本。
+	*/
+	async createTunnel(createBody, requestId, actorLabel) {
+		const wantConfig = createBody.configText === true;
+		const binDir = this.options.cloudflaredBinDir;
+		let exe;
+		try {
+			exe = await ensureCloudflared(binDir ?? this.options.database.dataDir, (a) => {
+				this.options.tunnels.reportActivity(a);
+			});
+		} catch (cause) {
+			this.options.tunnels.clearActivity();
+			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", actorLabel, "cloudflare.create", void 0, void 0, {}, requestId);
+		return {
+			state: resolvedUrl === state.url ? state : {
+				...state,
+				url: resolvedUrl
+			},
+			...configText === void 0 ? {} : { configText }
+		};
+	}
+	/**
+	* IM `/tunnel` 命令的宿主侧入口：开隧道并返回一行可粘贴的配置文本。
+	*
+	* 与 HTTP 路径的两点差别：
+	*
+	* 1. **隧道已在运行时直接复用当前地址**，不重复 spawn（第二次 `startQuick` 会撞
+	*    `TUNNEL_ALREADY_RUNNING`，而用户在 IM 里连发两条是很常见的）。
+	* 2. 配置文本的 endpoint 只用隧道地址，设备名缺省由 `buildConfigText` 决定 —— 命令
+	*    不接受参数，所以没有 `endpointLabel` / `rootIds` 的透传面。
+	*
+	* @throws 当 12 秒内没拿到公网地址，或 cloudflared 下载失败时。
+	*/
+	async openTunnelForCommand() {
+		const tunnels = this.options.tunnels;
+		if (tunnels === void 0) throw new Error("隧道功能未启用。");
+		const requestId = randomUUID();
+		const current = tunnels.publicState;
+		if (current.running === true && current.url !== null) {
+			const reused = this.buildConfigText({ endpoints: [{
+				label: "云隧道",
+				baseUrl: current.url
+			}] }, requestId);
+			this.options.database.audit("admin", "im-command", "cloudflare.create", void 0, void 0, { reused: true }, requestId);
+			return {
+				url: current.url,
+				text: reused.text,
+				deviceName: reused.deviceName
+			};
+		}
+		const { state, configText } = await this.createTunnel({ configText: true }, requestId, "im-command");
+		if (configText === void 0 || state.url === null) throw new Error("隧道已启动，但 12 秒内没拿到公网地址。稍等片刻再发一次 /tunnel 可复用当前地址。");
+		const text = typeof configText.text === "string" ? configText.text : "";
+		const deviceName = typeof configText.deviceName === "string" ? configText.deviceName : "Android 设备";
+		return {
+			url: state.url,
+			text,
+			deviceName
+		};
+	}
+	/**
 	* 隧道状态视图。
 	*
 	* **这里不做脱敏，因为用不上**：判据 1 已经把 Cloudflare 边缘头（`Cf-Connecting-IP` /
@@ -6067,6 +7626,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 +7713,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 +7809,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.");
@@ -6348,9 +8003,53 @@ function optionalInteger(value) {
 	if (!Number.isSafeInteger(parsed) || parsed < 0) throw new ApiError(400, "NUMBER_INVALID", "A query parameter must be a non-negative integer.");
 	return parsed;
 }
+/**
+* 请求体里的 `expectedRevision`。
+*
+* 不复用 `optionalInteger()`：它读的是查询串（字符串）且错误码是 `NUMBER_INVALID`；
+* 这里是 JSON 数字，非法时属于「ops 请求体不合法」，契约要求 `SETTINGS_OPS_INVALID`。
+*/
+function settingsExpectedRevision(value) {
+	if (value === void 0) return void 0;
+	if (!Number.isSafeInteger(value) || value < 0) throw new ApiError(400, "SETTINGS_OPS_INVALID", "expectedRevision must be a non-negative integer.");
+	return 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 +8075,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 +8151,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 +8170,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 +8192,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 +8203,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 +8264,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 +8336,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 +8358,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 +8406,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 +8492,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();
+			}
+			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;
 			}
-			if (!await this.eventAllowed(currentPrincipal, event)) continue;
-			socket.send(stringifyWire(event));
+			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 +8709,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 +8732,7 @@ var RemoteApiServer = class {
 	}
 };
 function attachEmbeddedRoutes(webServer, router, remote, extraRoutes = []) {
+	assertExtraRoutePrefixes(extraRoutes);
 	const disposers = [webServer.register({
 		kind: "prefix",
 		path: "/dsh-workspace-api",
@@ -6679,6 +8742,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 +8809,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,10 +8838,82 @@ 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) {
+	options;
+	/**
+	* @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
+	*   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+	*/
+	constructor(api, options = {}) {
 		this.api = api;
+		this.options = options;
+	}
+	/**
+	* 列出全部设置命名空间（通用设置面的读侧）。
+	*
+	* 与 `listProviders()` 的区别：它不理解任何 provider 语义，原样透出内核按插件
+	* 划分的命名空间，由手机端按 `schema` 自己长表单 —— 新装插件不必等 App 发版。
+	*/
+	async describeNamespaces() {
+		const described = unwrapDsh(await this.settingsService().describe({
+			rpcId: randomUUID(),
+			payload: {}
+		}));
+		return {
+			writable: described.writable,
+			namespaces: described.namespaces.map((view) => projectSettingsNamespace(view, described.writable, this.writeNamespaces))
+		};
+	}
+	/**
+	* 按路径改一个命名空间（通用设置面的写侧）。
+	*
+	* 校验顺序是刻意的：ns 策略 → ops 结构 → 内核 describe（host 可写性）→ mutate。
+	* 先验策略既省一次内核往返，也保证「高危命名空间」无论 ops 怎么错都先得到 403。
+	*/
+	async mutateNamespace(ns, ops, expectedRevision) {
+		if (!isSettingsNamespaceWriteAllowed(ns, this.writeNamespaces)) throw new ApiError(403, "SETTINGS_NAMESPACE_READONLY", `The settings namespace "${ns}" is not writable from this bridge.`, {
+			ns,
+			reason: "HIGH_RISK_NAMESPACE"
+		});
+		const normalized = parseSettingsNamespaceOps(ops);
+		const described = unwrapDsh(await this.settingsService().describe({
+			rpcId: randomUUID(),
+			payload: {}
+		}));
+		if (!described.writable) throw new ApiError(409, "SETTINGS_READ_ONLY", "DSH settings are read-only.");
+		let mutated;
+		try {
+			mutated = unwrapDsh(await this.settingsService().mutate({
+				rpcId: randomUUID(),
+				payload: {
+					ns,
+					ops: normalized,
+					...expectedRevision === void 0 ? {} : { expectedRevision }
+				}
+			}));
+		} catch (error) {
+			throw mapSettingsMutationError(error);
+		}
+		return projectSettingsNamespace(mutated, described.writable, this.writeNamespaces);
+	}
+	get writeNamespaces() {
+		return this.options.writeNamespaces ?? [];
+	}
+	/** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
+	settingsService() {
+		const settings = this.api.settings;
+		if (settings === void 0) throw new ApiError(503, "SETTINGS_UNAVAILABLE", "The DSH settings service is not available.");
+		return settings;
 	}
 	async listProviders() {
 		const [directoryResponse, settingsResponse, catalogResponse] = await Promise.all([
@@ -6891,6 +9060,7 @@ var DshSettingsAdapter = class {
 				}
 			}));
 		}
+		this.invalidateProviderContext(providerId);
 	}
 	async createProvider(input) {
 		const id = input.id.trim();
@@ -6941,6 +9111,7 @@ var DshSettingsAdapter = class {
 				value: key
 			}
 		}));
+		this.invalidateProviderContext(id);
 	}
 	async removeProvider(providerId, expectedRevision) {
 		const context = await this.providerContext(providerId);
@@ -6957,6 +9128,7 @@ var DshSettingsAdapter = class {
 				...expectedRevision === void 0 ? {} : { expectedRevision }
 			}
 		}));
+		this.invalidateProviderContext(providerId);
 	}
 	async discover(providerId, draft) {
 		const payload = {
@@ -6971,7 +9143,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: {}
@@ -6992,6 +9204,20 @@ var DshSettingsAdapter = class {
 		};
 	}
 };
+/**
+* 把内核 `settings.mutate` 的错误翻成契约错误码。
+*
+* `unwrapDsh()` 的通用映射只认 `busy` / `locked` 为 409，所以内核的
+* `settings/conflict` 会落到 400 `DSH_SETTINGS_CONFLICT` —— 这里按契约改回
+* 409 `SETTINGS_CONFLICT`（客户端据此提示「刷新后重试」而不是「参数不对」）。
+* `settings/rejected` 是 ops 在 schema 上不合法，落回 400 `SETTINGS_OPS_INVALID`。
+*/
+function mapSettingsMutationError(error) {
+	if (!(error instanceof ApiError)) return error;
+	if (error.code.includes("SETTINGS") && error.code.includes("CONFLICT")) return new ApiError(409, "SETTINGS_CONFLICT", "Settings changed since they were read; refresh and retry.", error.details);
+	if (error.code.includes("SETTINGS") && error.code.includes("REJECTED")) return new ApiError(400, "SETTINGS_OPS_INVALID", error.message, error.details);
+	return error;
+}
 function projectConfig(profile, inheritedModels) {
 	const baseURL = text(profile?.baseURL);
 	const api = text(profile?.api);
@@ -7130,6 +9356,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();
@@ -7149,7 +9376,7 @@ async function apply(ctx, config = {}) {
 		agents: ctx.agents,
 		commands: ctx.commands
 	});
-	const settings = new DshSettingsAdapter(apiProxy);
+	const settings = new DshSettingsAdapter(apiProxy, { writeNamespaces: config.settingsWriteNamespaces ?? [] });
 	let hostServiceReport;
 	try {
 		hostServiceReport = probeHostServices(ctx, PLUGIN_VERSION);
@@ -7171,7 +9398,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,
@@ -7199,6 +9427,34 @@ async function apply(ctx, config = {}) {
 		path: IMAGE_ROUTE,
 		handler: imageRoute
 	}]);
+	try {
+		ctx.effect(() => registerTunnelCommand(ctx.commands, {
+			openTunnel: () => router.openTunnelForCommand(),
+			logger: {
+				info: (message) => ctx.logger.info(message),
+				warn: (error) => ctx.logger.warn(error)
+			}
+		}), "dsh-remote-bridge /tunnel command");
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: /tunnel command registration failed (ignored): ${String(error)}`));
+	}
+	let toolsService;
+	try {
+		toolsService = reflect?.get?.("tools", false);
+	} catch {
+		toolsService = void 0;
+	}
+	if (toolsService !== void 0) try {
+		ctx.effect(() => registerTunnelTool(toolsService, {
+			openTunnel: () => router.openTunnelForCommand(),
+			logger: {
+				info: (message) => ctx.logger.info(message),
+				warn: (error) => ctx.logger.warn(error)
+			}
+		}), "dsh-remote-bridge open_tunnel_config tool");
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: open_tunnel_config registration failed (ignored): ${String(error)}`));
+	}
 	ctx.effect(() => async () => {
 		disposeEmbedded();
 		await remote.stop();