dsh-deeppilot 0.9.8 → 0.9.11

package/lib/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { X509Certificate, createHash, createPrivateKey, createPublicKey, randomBytes, randomUUID, sign, timingSafeEqual, verify } from "node:crypto";
-import { access, chmod, mkdir, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { access, appendFile, chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { WebSocketServer } from "ws";
 import { homedir, networkInterfaces } from "node:os";
@@ -394,6 +394,333 @@ var AuthRateLimiter = class {
 	}
 };
 //#endregion
+//#region src/diagnostics.ts
+/**
+* 连接诊断事件模型（Diagnostics）——插件唯一的「失败可观测」面。
+*
+* 为什么需要独立模块：本插件的日志出口原先是 `apply()` 里的一个闭包
+* （`console.log('[deeppilot] ' + message)`），无时间戳、无级别、无来源；
+* 连接被拒、认证失败、TLS 握手失败都各自静默结束，用户在设置页只看到
+* 「连不上」三个字。把事件模型、节流、环形缓冲与落盘收在这里，目的有三：
+*
+* 1. 一次失败 = 一条结构化事件（时间戳 + kind + reason + 来源哈希 +
+*    可选 attemptId / 关闭码 / 耗时），微信、tailscale、扫描器刷屏时仍
+*    只留可读的十几行；
+* 2. index.ts / connection-gate.ts / phone-server.ts / connection.ts 四个
+*    入口共用同一个 `record(kind, reason, extra)`，失败路径不再各自发明
+*    日志文案；
+* 3. 环形 256 条 + 按天落盘（保留 7 天、目录上限 5MB）让「刚刚那次连不上」
+*    在重启前后都能查；`recent()` / `lastFailure()` 同时供 `/phone/health`
+*    与设置页诊断区块读取。
+*
+* 硬约束（与 AGENTS.md 一致）：
+* - 事件里只出现 auditLabel 产生的来源哈希，绝不出现原始 IP；
+* - attemptId 只记录、不校验、不参与任何准入判断；长度 ≤16，字符集
+*   `[A-Za-z0-9_-]`，来源不可信（WS query `at` / HTTP header
+*   `X-DeepPilot-Attempt`）；
+* - 不打印配对码、公钥原文、APNs token、relay 凭据与消息正文。detail
+*   字段只接受代码生成的短文本（如 socket 错误码），最长 160 字符。
+*
+* 与 `diagnostics.debug` 的关系：本模块的事件**无条件记录**。那个开关只
+* 控制现有的 per-frame / 推送日志，失败事件若也绑到它上面，用户不开调试
+* 开关就永远看不到为什么连不上——这正是本轮要修的 P0。
+*/
+/**
+* 统一日志行格式：`[deeppilot] <ISO 时间戳> <LEVEL> <message>`。
+*
+* 时间戳是 P0 的可观测性基线：没有它，用户贴回来的日志无法与手机端时间
+* 对齐，也无法判断「刚才那次」是哪一次。ISO-8601（UTC）避免时区误读。
+*/
+function formatLogLine(level, message, at = Date.now()) {
+	return `[deeppilot] ${new Date(at).toISOString()} ${level.toUpperCase()} ${message}`;
+}
+/**
+* 插件日志函数。单参调用即 info；失败路径显式传 'warn'。
+* 返回值的双参签名可以安全地传给只接受 `(message: string) => void` 的
+* 既有依赖（PushGateway / HostBridge / 两个 transport 行）。
+*/
+function createLogger() {
+	return (message, level = "info") => {
+		console.log(formatLogLine(level, message));
+	};
+}
+const MAX_DETAIL_CHARS = 160;
+const MAX_REASON_CHARS = 64;
+const DEFAULT_CAPACITY$1 = 256;
+/** 同 kind + reason + source 在 60 秒内只输出一行。 */
+const DEFAULT_THROTTLE_MS = 6e4;
+const INFO_KINDS = /* @__PURE__ */ new Set(["connection-opened"]);
+function defaultLevel(kind) {
+	return INFO_KINDS.has(kind) ? "info" : "warn";
+}
+/** 事件文本一律单行：换成空格并去掉控制字符，避免日志被注入换行。 */
+function sanitizeText(value, maxChars) {
+	return value.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").replace(/\s+/g, " ").trim().slice(0, maxChars);
+}
+function normalizeReason(reason) {
+	return sanitizeText(reason, MAX_REASON_CHARS).replace(/\s+/g, "-");
+}
+/**
+* 来源只允许短标识（auditLabel 的 12 位十六进制）。原始 IP 含 `.` / `:`，
+* 会在这一步被丢弃——即便某个调用方忘了哈希，也不会有 IP 落进日志。
+*/
+function normalizeSource(value) {
+	if (typeof value !== "string") return void 0;
+	return /^[A-Za-z0-9_-]{1,64}$/.test(value) ? value : void 0;
+}
+const ATTEMPT_ID_HEADER = "x-deeppilot-attempt";
+/** 只允许 URL 安全字符，最长 16：记录用，永不回显或参与判定。 */
+const ATTEMPT_ID_PATTERN = /^[A-Za-z0-9_-]{1,16}$/;
+/** 归一化一个客户端提供的 attemptId；不合法即丢弃（不报错、不拒绝请求）。 */
+function normalizeAttemptId(value) {
+	if (typeof value !== "string") return void 0;
+	return ATTEMPT_ID_PATTERN.test(value) ? value : void 0;
+}
+/**
+* 从一条 HTTP / WS 升级请求里取 attemptId。
+*
+* 优先 HTTP header（真实 HTTP 客户端可自由设置），其次 WS 升级 URL 的
+* `?at=`（浏览器 / URLSession 的 WS 握手无法自定义 header）。两个来源都
+* 经过同一份长度与字符集校验；任何异常（畸形 URL、数组头）都按「没有
+* attemptId」处理——这是纯观测字段，绝不能因为它让握手失败。
+*/
+function attemptIdFromRequest(request) {
+	const header = request.headers?.[ATTEMPT_ID_HEADER];
+	const fromHeader = normalizeAttemptId(Array.isArray(header) ? header[0] : header);
+	if (fromHeader !== void 0) return fromHeader;
+	if (typeof request.url !== "string" || request.url.length === 0) return void 0;
+	try {
+		return normalizeAttemptId(new URL(request.url, "http://phone.local").searchParams.get("at"));
+	} catch {
+		return;
+	}
+}
+/**
+* 内存环形 + 节流日志 + 按天落盘。
+*
+* 职责边界：它不做任何策略判断（不决定是否拒绝连接），只负责把调用方
+* 已经判定的失败事实记下来。因此它可以在四个入口之间安全共用。
+*/
+var DiagnosticsStore = class {
+	events = [];
+	throttles = /* @__PURE__ */ new Map();
+	capacity;
+	throttleMs;
+	now;
+	write;
+	dir;
+	tail = Promise.resolve();
+	/** 已统计过的文件大小，避免每次 append 前都 stat。 */
+	fileSizes = /* @__PURE__ */ new Map();
+	directoryBytes = 0;
+	/** 最近一次执行过保留期清理的 UTC 日期（YYYY-MM-DD）。 */
+	prunedDay;
+	/** 落盘自身失败只报一次：否则磁盘满会把日志刷成新的刷屏源。 */
+	writeFailureReported = false;
+	constructor(options = {}) {
+		this.capacity = options.capacity ?? DEFAULT_CAPACITY$1;
+		this.throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+		this.now = options.now ?? Date.now;
+		this.write = options.write ?? ((line) => {
+			console.log(line);
+		});
+		this.dir = options.dir;
+	}
+	/**
+	* 记录一条事件。事件总是进入内存环形；终端日志与落盘按
+	* kind + reason + source 节流（60s 一行，恢复时标注 suppressed 次数）。
+	* 返回完整事件，方便调用方测试与断言。
+	*/
+	record(kind, reason, extra = {}) {
+		const ts = this.now();
+		const attemptId = normalizeAttemptId(extra.attemptId);
+		const source = normalizeSource(extra.source);
+		const event = {
+			ts,
+			kind,
+			reason: normalizeReason(reason),
+			level: extra.level ?? defaultLevel(kind),
+			...attemptId !== void 0 ? { attemptId } : {},
+			...source !== void 0 ? { source } : {},
+			...extra.closeCode !== void 0 ? { closeCode: extra.closeCode } : {},
+			...extra.durationMs !== void 0 ? { durationMs: Math.max(0, Math.round(extra.durationMs)) } : {},
+			...extra.authenticated !== void 0 ? { authenticated: extra.authenticated } : {},
+			...extra.detail !== void 0 ? { detail: sanitizeText(extra.detail, MAX_DETAIL_CHARS) } : {}
+		};
+		this.events.push(event);
+		while (this.events.length > this.capacity) this.events.shift();
+		const throttleKey = `${kind}\u0000${event.reason}\u0000${event.source ?? "-"}`;
+		const previous = this.throttles.get(throttleKey);
+		let suppressed = 0;
+		if (previous !== void 0 && ts - previous.lastTs < this.throttleMs) {
+			previous.suppressed += 1;
+			return event;
+		}
+		if (previous !== void 0) suppressed = previous.suppressed;
+		this.throttles.set(throttleKey, {
+			lastTs: ts,
+			suppressed: 0
+		});
+		this.write(formatEventLine(event, suppressed));
+		this.persist(event, suppressed);
+		return event;
+	}
+	/** 最近 `limit` 条事件（时间升序），供 health / report / 测试读取。 */
+	recent(limit = 20) {
+		const size = Math.max(0, Math.trunc(limit));
+		return this.events.slice(-size);
+	}
+	/** 最近 `limit` 条失败事件（warn 级），新→旧排序前的升序切片。 */
+	recentFailures(limit = 10) {
+		const failures = this.events.filter((event) => event.level === "warn");
+		const size = Math.max(0, Math.trunc(limit));
+		return failures.slice(-size);
+	}
+	/** 最近一条失败事件；没有失败时 undefined。 */
+	lastFailure() {
+		for (let index = this.events.length - 1; index >= 0; index -= 1) {
+			const event = this.events[index];
+			if (event !== void 0 && event.level === "warn") return event;
+		}
+	}
+	/** 等价于「诊断面板复制」/health 需要的最近失败摘要。 */
+	lastFailureSummary() {
+		const failure = this.lastFailure();
+		return failure === void 0 ? void 0 : {
+			kind: failure.kind,
+			reason: failure.reason,
+			ts: failure.ts
+		};
+	}
+	/** 等待所有排队中的落盘完成（测试与进程收尾用）。 */
+	async flush() {
+		await this.tail;
+	}
+	/** 进程收尾：不再有新的写入队列，等待既有写入落盘。 */
+	async dispose() {
+		await this.flush();
+	}
+	/**
+	* 追加一行 JSONL。写入串行、失败静默（只报一次），绝不阻塞调用方——
+	* 诊断日志不能反过来拖慢或搞崩握手路径。
+	*/
+	persist(event, suppressed) {
+		const dir = this.dir;
+		if (dir === void 0) return;
+		const day = utcDay(event.ts);
+		const path = join(dir, `diagnostics-${day}.jsonl`);
+		const payload = suppressed > 0 ? {
+			...event,
+			suppressed
+		} : event;
+		const line = JSON.stringify(payload) + "\n";
+		const bytes = Buffer.byteLength(line);
+		this.tail = this.tail.then(async () => {
+			try {
+				await this.prepareDirectory(dir, day);
+				const currentSize = this.fileSizes.get(path) ?? await stat(path).then((info) => info.size).catch(() => 0);
+				this.fileSizes.set(path, currentSize);
+				if (this.directoryBytes + bytes > 5242880) return;
+				await mkdir(dir, {
+					recursive: true,
+					mode: 448
+				});
+				await appendFile(path, line, { mode: 384 });
+				this.fileSizes.set(path, currentSize + bytes);
+				this.directoryBytes += bytes;
+			} catch (error) {
+				this.reportWriteFailure(error);
+			}
+		});
+		this.tail = this.tail.catch(() => {});
+	}
+	/**
+	* 每天第一次落盘时清理保留期之外的文件并统计目录大小；同时限制目录
+	* 总量（5MB）。清理失败不影响当次写入。
+	*/
+	async prepareDirectory(dir, day) {
+		if (this.prunedDay === day) return;
+		const names = await readdir(dir).catch(() => []);
+		const cutoffDay = utcDayMinus(day, 6);
+		let total = 0;
+		for (const name of names) {
+			const match = /^diagnostics-(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(name);
+			if (match === null) continue;
+			const full = join(dir, name);
+			if (match[1] !== void 0 && match[1] < cutoffDay) {
+				await unlink(full).catch(() => {});
+				this.fileSizes.delete(full);
+				continue;
+			}
+			const size = await stat(full).then((info) => info.size).catch(() => 0);
+			this.fileSizes.set(full, size);
+			total += size;
+		}
+		this.directoryBytes = total;
+		this.prunedDay = day;
+	}
+	reportWriteFailure(error) {
+		if (this.writeFailureReported) return;
+		this.writeFailureReported = true;
+		this.write(formatLogLine("warn", "diagnostics write failed: " + sanitizeText(String(error), MAX_DETAIL_CHARS)));
+	}
+};
+/** 一条事件的终端日志文本（不含前缀时间戳，由 formatLogLine 统一加）。 */
+function formatEventLine(event, suppressed) {
+	const parts = [event.kind, event.reason];
+	if (event.source !== void 0) parts.push("src=" + event.source);
+	if (event.attemptId !== void 0) parts.push("attempt=" + event.attemptId);
+	if (event.closeCode !== void 0) parts.push("code=" + String(event.closeCode));
+	if (event.durationMs !== void 0) parts.push("durationMs=" + String(event.durationMs));
+	if (event.authenticated !== void 0) parts.push("auth=" + (event.authenticated ? "yes" : "no"));
+	if (suppressed > 0) parts.push("suppressed=" + String(suppressed));
+	if (event.detail !== void 0) parts.push("detail=" + event.detail);
+	return formatLogLine(event.level, parts.join(" "), event.ts);
+}
+function utcDay(ts) {
+	return new Date(ts).toISOString().slice(0, 10);
+}
+/** 日期字符串（YYYY-MM-DD）往前推 `days` 天；保留期计算用。 */
+function utcDayMinus(day, days) {
+	const date = /* @__PURE__ */ new Date(day + "T00:00:00.000Z");
+	date.setUTCDate(date.getUTCDate() - days);
+	return date.toISOString().slice(0, 10);
+}
+/**
+* `/phone/health` 的响应体：**只加不删**。
+*
+* 原有 `ok/enabled/protocolVersion/serverVersion/dataPlane` 保持原义；
+* 新增字段只描述「这台电脑此刻能不能被连上」，不含 debug 开关状态，
+* 也不返回局域网地址候选（那是配对页的职责，health 不该成为扫描器
+* 的地址字典）：
+* - `local`：LAN 传输此刻的相位与端口；
+* - `dataPlanePhase`：数据面 active / inactive；
+* - `tlsRebuilt`：本次运行是否重建过 TLS 身份（手机据此判断是否需要重新配对）；
+* - `startedAt`：插件启动时刻；
+* - `lastFailure`：最近一次失败的类型、分因与时间。
+*/
+function buildHealthPayload(input) {
+	return {
+		ok: true,
+		enabled: input.enabled,
+		protocolVersion: input.protocolVersion,
+		serverVersion: input.serverVersion,
+		dataPlane: input.dataPlaneActive,
+		dataPlanePhase: input.dataPlaneActive ? "active" : "inactive",
+		local: {
+			phase: input.localPhase,
+			port: input.localPort
+		},
+		tlsRebuilt: input.tlsIdentityRegenerated,
+		startedAt: input.startedAt,
+		lastFailure: input.lastFailure === void 0 ? null : {
+			kind: input.lastFailure.kind,
+			reason: input.lastFailure.reason,
+			ts: input.lastFailure.ts
+		}
+	};
+}
+//#endregion
 //#region src/device-auth.ts
 function getPairingCodeTtlMs() {
 	return Number(process.env.DEEPPILOT_PAIRING_TTL_MS) || 3e5;
@@ -419,6 +746,7 @@ async function loadOrCreateHostAudience(path) {
 	const audience = "deeppilot:" + randomBytes(16).toString("base64url");
 	await mkdir(dirname(path), { recursive: true });
 	await writeFile(path, audience + "\n", { mode: 384 });
+	console.log(formatLogLine("info", "host identity created: " + path + " (previously paired devices must pair again)"));
 	return audience;
 }
 function b64urlText(value) {
@@ -683,6 +1011,11 @@ var DeviceStore = class DeviceStore {
 	filePath;
 	devices = /* @__PURE__ */ new Map();
 	flushTail = Promise.resolve();
+	/**
+	* 注册表写失败的日志节流：磁盘只读 / 空间不足时每次 flush 都会失败，
+	* 不节流会把「写不进去」变成新的刷屏源。同一条错误 60s 只报一次。
+	*/
+	lastWriteFailureLogAt = 0;
 	constructor(filePath) {
 		this.filePath = filePath;
 	}
@@ -692,7 +1025,7 @@ var DeviceStore = class DeviceStore {
 			const raw = JSON.parse(await readFile(expandHome(filePath), "utf8"));
 			for (const rec of raw.devices ?? []) if (typeof rec.deviceId === "string") store.devices.set(rec.deviceId, rec);
 		} catch (error) {
-			if (error?.code === "ENOENT") {} else console.log("[deeppilot] device registry unreadable, starting empty: " + String(error));
+			if (error?.code === "ENOENT") {} else console.log(formatLogLine("warn", "device registry unreadable, starting empty: " + String(error)));
 		}
 		return store;
 	}
@@ -725,6 +1058,18 @@ var DeviceStore = class DeviceStore {
 		if (!record?.publicKey || record.revokedAt !== void 0) return void 0;
 		return record;
 	}
+	/**
+	* 认证分因用：把「为什么 authorized() 返回 undefined」拆成三种情形。
+	* 只给日志使用，准入判定仍然只走 authorized()——wire 响应不会因为
+	* 这个方法泄露设备是否注册过（4401 仍只有一个码）。
+	*/
+	statusOf(deviceId) {
+		const record = this.devices.get(deviceId);
+		if (record === void 0) return "unknown";
+		if (record.revokedAt !== void 0) return "revoked";
+		if (record.publicKey === void 0) return "unknown";
+		return "active";
+	}
 	markAuthenticated(deviceId, deviceName, appVersion, now) {
 		const record = this.authorized(deviceId);
 		if (!record) return;
@@ -889,7 +1234,18 @@ var DeviceStore = class DeviceStore {
 			const temp = `${full}.${randomBytes(6).toString("hex")}.tmp`;
 			await writeFile(temp, body + "\n", { mode: 384 });
 			await rename(temp, full);
-		} catch {}
+		} catch (error) {
+			this.logWriteFailure(error);
+		}
+	}
+	/** 写失败日志按 60s 节流：磁盘满时 flush 会被反复触发，不能让它刷屏。 */
+	logWriteFailure(error) {
+		const now = Date.now();
+		if (now - this.lastWriteFailureLogAt < 6e4) return;
+		this.lastWriteFailureLogAt = now;
+		const code = error?.code;
+		const message = error instanceof Error ? error.message : String(error);
+		console.log(formatLogLine("warn", "device registry write failed" + (typeof code === "string" ? " code=" + code : "") + ": " + message.slice(0, 160)));
 	}
 };
 //#endregion
@@ -2504,6 +2860,27 @@ function registryRowFor(type) {
 *   （成功/证明无效/超时/关闭）都经 settleAuthentication 的 exactly-once
 *   守卫释放一次。
 */
+/**
+* 把一次认证失败归一到一个原因。判定顺序就是语义优先级：
+*
+* 1. 注册表状态先行——设备不存在 / 已撤销时，后面任何字段都不可信；
+* 2. nonce / audience 不匹配：挑战对象不是这一次（重放或串线）；
+* 3. 服务器时钟已过挑战有效期：挑战过期；
+* 4. 客户端回显的 issuedAt / expiresAt 与挑战不同：客户端时钟或状态偏差；
+* 5. 其余（签名缺失 / 验签失败）：bad-signature。
+*
+* 纯函数，连接门与单测共用同一份判定。
+*/
+function classifyAuthFailure(input) {
+	if (input.device === "revoked") return "revoked";
+	if (input.device === "unknown") return "unknown-device";
+	const { proof, challenge, now } = input;
+	if (proof.nonce !== challenge.nonce) return "nonce-mismatch";
+	if (proof.audience !== challenge.audience) return "audience-mismatch";
+	if (now > challenge.expiresAt) return "challenge-expired";
+	if (proof.issuedAt !== challenge.issuedAt || proof.expiresAt !== challenge.expiresAt) return "clock-skew";
+	return "bad-signature";
+}
 /** upgrade 正常是毫秒级；5 秒已极宽，只为「回调根本不执行」兜底。 */
 const DEFAULT_ATTACH_TIMEOUT_MS = 5e3;
 var ConnectionGate = class {
@@ -2564,6 +2941,7 @@ var ConnectionGate = class {
 			this.helloTimer = void 0;
 			if (this.authenticated) return;
 			this.settle(false, "timeout");
+			this.reportAuthFailure("timeout", 4402);
 			this.host?.close(4402, "auth timeout");
 		}, AUTH_TIMEOUT_MS);
 		this.helloTimer.unref();
@@ -2653,18 +3031,21 @@ var ConnectionGate = class {
 		const p = env.payload ?? {};
 		if (!p.deviceId) {
 			host.fail(env.id, "E_PROTOCOL", "deviceId required");
+			this.reportAuthFailure("device-id-missing", 4403);
 			host.close(4403, "deviceId required");
 			return;
 		}
 		const deviceId = sanitizeDeviceField(p.deviceId, 128);
 		if (!deviceId) {
 			host.fail(env.id, "E_PROTOCOL", "deviceId required");
+			this.reportAuthFailure("device-id-missing", 4403);
 			host.close(4403, "deviceId required");
 			return;
 		}
 		const deviceName = sanitizeDeviceField(p.deviceName, 64) || "unknown";
 		const appVersion = sanitizeDeviceField(p.appVersion, 32) || "unknown";
-		const record = this.options.devices.authorized(deviceId);
+		const deviceState = this.options.devices.statusOf(deviceId);
+		const record = deviceState === "active" ? this.options.devices.authorized(deviceId) : void 0;
 		const resumeCursor = typeof p.resumeCursor === "number" && Number.isInteger(p.resumeCursor) && p.resumeCursor >= 0 ? p.resumeCursor : void 0;
 		const challengeMatches = p.nonce === this.challenge.nonce && p.audience === this.challenge.audience && p.issuedAt === this.challenge.issuedAt && p.expiresAt === this.challenge.expiresAt && Date.now() <= this.challenge.expiresAt;
 		if (!(record?.publicKey !== void 0 && typeof p.signature === "string" && challengeMatches && verifyAuthProof(record.publicKey, {
@@ -2674,7 +3055,14 @@ var ConnectionGate = class {
 			resumeCursor,
 			...this.challenge
 		}, p.signature)) || record === void 0) {
+			const reason = classifyAuthFailure({
+				device: deviceState,
+				proof: p,
+				challenge: this.challenge,
+				now: Date.now()
+			});
 			host.fail(env.id, "E_AUTH", "device proof missing or invalid");
+			this.reportAuthFailure(reason, 4401);
 			this.settle(false, "invalid-proof");
 			host.close(4401, "invalid device proof");
 			return;
@@ -2696,6 +3084,19 @@ var ConnectionGate = class {
 			appVersion
 		});
 	}
+	/**
+	* 认证失败事件。来源只写 auditLabel 哈希（没有哈希函数时宁可不写，
+	* 也不把原始 IP 落盘）；attemptId 原样带出，便于把同一次握手的
+	* upgrade / auth 两条日志串起来。
+	*/
+	reportAuthFailure(reason, closeCode) {
+		const source = this.options.auditLabel?.(this.options.source);
+		this.options.diagnostics?.record("auth-failed", reason, {
+			...source !== void 0 ? { source } : {},
+			...this.options.attemptId !== void 0 ? { attemptId: this.options.attemptId } : {},
+			closeCode
+		});
+	}
 	/** 限流记账与名额释放只此一处；exactly-once 由 settled 守卫保证。 */
 	settle(ok, reason) {
 		if (this.settled) return;
@@ -2782,6 +3183,10 @@ var BridgeConnection = class {
 	pendingLiveActivityId;
 	lastActivity = Date.now();
 	streamAbort = new AbortController();
+	/** 建连时刻：关闭事件用它算存活时长。 */
+	openedAt = Date.now();
+	/** 来源的审计哈希；没有 auditLabel 时留空，绝不记录原始 IP。 */
+	sourceLabel;
 	/** True when no inbound frame arrived within maxIdleMs. */
 	isStale(now, maxIdleMs) {
 		return now - this.lastActivity > maxIdleMs;
@@ -2796,11 +3201,15 @@ var BridgeConnection = class {
 		audience: deps.audience,
 		limiter: deps.rateLimiter ?? new AuthRateLimiter(),
 		log: (message) => deps.log(message),
-		...deps.auditLabel ? { auditLabel: deps.auditLabel } : {}
+		...deps.auditLabel ? { auditLabel: deps.auditLabel } : {},
+		...deps.diagnostics ? { diagnostics: deps.diagnostics } : {},
+		...deps.attemptId !== void 0 ? { attemptId: deps.attemptId } : {}
 	})) {
 		this.ws = ws;
 		this.deps = deps;
 		const connection = this;
+		const sourceLabel = deps.auditLabel?.(deps.source ?? "local");
+		this.sourceLabel = sourceLabel;
 		const host = {
 			signal: this.streamAbort.signal,
 			waitForWritable: async () => {
@@ -2862,12 +3271,23 @@ var BridgeConnection = class {
 				this.terminate();
 			});
 		});
-		ws.on("close", () => {
-			this.onClose();
+		ws.on("close", (code) => {
+			this.onClose(code);
 			deps.onClosed?.(this);
 		});
-		ws.on("error", () => {});
+		ws.on("error", (error) => {
+			this.deps.diagnostics?.record("connection-error", "socket-error", {
+				...this.sourceLabel !== void 0 ? { source: this.sourceLabel } : {},
+				...this.deps.attemptId !== void 0 ? { attemptId: this.deps.attemptId } : {},
+				authenticated: this.identity !== void 0,
+				detail: error instanceof Error ? error.message : String(error ?? "unknown")
+			});
+		});
 		gate.attach(host);
+		this.deps.diagnostics?.record("connection-opened", "socket-open", {
+			...sourceLabel !== void 0 ? { source: sourceLabel } : {},
+			...deps.attemptId !== void 0 ? { attemptId: deps.attemptId } : {}
+		});
 	}
 	/** Hard-drop the socket (server-side stale sweep). */
 	terminate() {
@@ -2952,9 +3372,17 @@ var BridgeConnection = class {
 			else this.resync();
 		}
 	}
-	onClose() {
+	onClose(code) {
 		if (this.closed) return;
 		this.closed = true;
+		const closeCode = code ?? 1005;
+		if (closeCode !== 1e3 && closeCode !== 1001) this.deps.diagnostics?.record("connection-closed", "abnormal-close", {
+			...this.sourceLabel !== void 0 ? { source: this.sourceLabel } : {},
+			...this.deps.attemptId !== void 0 ? { attemptId: this.deps.attemptId } : {},
+			closeCode,
+			durationMs: Date.now() - this.openedAt,
+			authenticated: this.identity !== void 0
+		});
 		this.streamAbort.abort();
 		this.gate.onClose();
 		for (const id of this.openSessions) this.deps.bridge.markSinkClosed(this, id);
@@ -3609,7 +4037,7 @@ function apnsPayload(notification) {
 	return alertPayload(notification);
 }
 function alertPayload(notification) {
-	const timeSensitive = notification.category === "approval.required" || notification.category === "question.asked";
+	const timeSensitive = notification.category === "approval.required" || notification.category === "question.asked" || notification.category === "session.error";
 	return {
 		aps: {
 			alert: {
@@ -3618,13 +4046,18 @@ function alertPayload(notification) {
 			},
 			sound: "default",
 			category: notification.category,
+			"mutable-content": 1,
 			"thread-id": notification.hostAudience ? createHash("sha256").update(`${notification.hostAudience}:${notification.sessionId}`).digest("hex") : notification.sessionId.slice(0, 64),
 			...timeSensitive ? { "interruption-level": "time-sensitive" } : {}
 		},
 		...notification.hostAudience ? { hostAudience: notification.hostAudience } : {},
 		sessionId: notification.sessionId,
 		notificationId: notification.notificationId,
-		kind: notification.category
+		kind: notification.category,
+		...notification.category === "approval.required" && notification.toolName ? {
+			toolName: notification.toolName.slice(0, 80),
+			...notification.detail ? { detail: notification.detail.slice(0, 600) } : {}
+		} : {}
 	};
 }
 function pushHeaders(bundleId, notification) {
@@ -3945,7 +4378,7 @@ function liveActivityState(session) {
 		task: Array.from(session?.activity?.trim() || task?.content || "").slice(0, 160).join(""),
 		done,
 		total,
-		phase: !session || total === 0 ? "unavailable" : session.pendingApproval ? "approval" : session.pendingQuestion ? "question" : session.status === "running" ? "running" : session.status === "idle" ? "ended" : "unavailable"
+		phase: !session || total === 0 ? "unavailable" : session.pendingApproval ? "approval" : session.pendingQuestion ? "question" : session.status === "running" ? "running" : session.status === "idle" ? "ended" : session.status === "error" ? "failed" : "unavailable"
 	};
 }
 /** Persist terminal state before coalescing so a rapid next round cannot revive an activity. */
@@ -3966,7 +4399,7 @@ var LiveActivityPushManager = class {
 			const r = device.liveActivity;
 			if (!r) continue;
 			const state = liveActivityState(this.latest.get(r.sessionId));
-			if (state.phase === "ended" || state.phase === "unavailable") this.devices()?.endLiveActivity(device.deviceId, r.token, state);
+			if (state.phase === "ended" || state.phase === "failed" || state.phase === "unavailable") this.devices()?.endLiveActivity(device.deviceId, r.token, state);
 		}
 		this.scheduler.changed();
 	}
@@ -4030,6 +4463,8 @@ function shouldReEnrollRelayToken(transport, outcome, reason, opts) {
 /** Apply before either transport receives the payload, including the Relay. */
 function pushContent(notification, mode) {
 	if (mode !== "generic") return notification;
+	const { toolName: _toolName, detail: _detail, ...rest } = notification;
+	notification = rest;
 	const bodies = {
 		"turn.completed": "A task has completed.",
 		"approval.required": "An approval needs your attention.",
@@ -4671,7 +5106,7 @@ var PushGateway = class {
 * it the listener is plain HTTP, which is reserved for the loopback Funnel
 * origin where tailscaled terminates TLS.
 */
-function createPhoneServer(handlers, tls) {
+function createPhoneServer(handlers, tls, options) {
 	const onRequest = (req, res) => {
 		const path = requestPath(req);
 		if (path === "/phone/health") handlers.health(req, res);
@@ -4693,6 +5128,25 @@ function createPhoneServer(handlers, tls) {
 		}
 		handlers.upgrade(req, socket, head);
 	});
+	const onTransportError = options?.onTransportError;
+	if (onTransportError !== void 0) {
+		if (tls !== void 0) server.on("tlsClientError", (error, socket) => {
+			onTransportError({
+				kind: "tls-client-error",
+				error,
+				remoteAddress: socket.remoteAddress
+			});
+			socket.destroy();
+		});
+		server.on("clientError", (error, socket) => {
+			onTransportError({
+				kind: "client-error",
+				error,
+				remoteAddress: socket.remoteAddress
+			});
+			socket.destroy();
+		});
+	}
 	return server;
 }
 function requestPath(req) {
@@ -4793,7 +5247,7 @@ var TransportReconciler = class {
 			this.instance = void 0;
 			if (partial !== void 0) await this.spec.stop(partial).catch(() => {});
 			this.currentStatus = this.spec.errorStatus(error, target);
-			this.log(this.spec.failureMessage?.(error) ?? "transport failed: " + String(error));
+			this.log(this.spec.failureMessage?.(error, target) ?? "transport failed: " + String(error));
 		}
 	}
 	/** 进程收尾：标记销毁、拆掉实例、等在途的那一次完成。 */
@@ -4834,7 +5288,7 @@ function createLocalTransport(deps) {
 			const server = createPhoneServer(deps.handlers, {
 				key: tls.key,
 				cert: tls.cert
-			});
+			}, deps.onTransportError !== void 0 ? { onTransportError: deps.onTransportError } : void 0);
 			instance.server = server;
 			instance.tlsFingerprint = tls.fingerprint;
 			await listen(server, port, "0.0.0.0");
@@ -4872,7 +5326,7 @@ function createLocalTransport(deps) {
 			updatedAt: Date.now()
 		}),
 		disabledMessage: "local transport disabled",
-		failureMessage: (error) => "local transport failed: " + localListenError(error, 0),
+		failureMessage: (error, target) => "local transport failed: " + localListenError(error, normalizeLocalPort(target.port)),
 		statusOf: (instance) => {
 			if (instance === void 0 || instance.server === void 0) return void 0;
 			return {
@@ -5384,6 +5838,50 @@ function scheduleMutationCodec(persistValues) {
 	};
 }
 //#endregion
+//#region src/notification-text.ts
+/**
+* 通知正文的纯文本投影。
+*
+* 为什么需要：s2c.notify 与 APNs 的 body 是"可直接展示"的文本（PROTOCOL §6），
+* 客户端不得改写；而来源（助手回复、审批原因、提问）都是 Host 给的 Markdown。
+* 直接截原文会把链接地址、URL 编码的中文路径、代码块符号带进锁屏横幅，
+* 所以 Bridge 出站前在这里统一转成纯文本。
+*
+* 只做"去标记、留可读文字"，不追求完整 Markdown 语义；任何无法识别的写法原样保留。
+*/
+/** 把 Markdown 拆成段落并逐段转为单行纯文本；清洗后为空的段落被丢弃。 */
+function notificationParagraphs(markdown) {
+	return stripCodeFences(markdown.replace(/\r\n?/g, "\n")).split(/\n[ \t]*\n/).map(plainParagraph).filter((paragraph) => paragraph.length > 0);
+}
+/**
+* 通知正文：`last` 取最后一个非空段落（任务完成 / 异常结束——回复结尾通常是结论），
+* `all` 把全部段落合成一行（审批原因、提问原文）。长度上限由调用方负责。
+*/
+function notificationPlainText(markdown, pick) {
+	const paragraphs = notificationParagraphs(markdown);
+	return pick === "last" ? paragraphs.at(-1) ?? "" : paragraphs.join(" ");
+}
+/** 围栏代码块整体丢弃：横幅里放不下代码，留一半反而更难读。未闭合的围栏丢到文末。 */
+function stripCodeFences(text) {
+	return text.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^[ \t]*\1[ \t]*$|(?![\s\S]))/gm, "\n");
+}
+function plainParagraph(paragraph) {
+	return decodePercentRuns(stripInline(paragraph.split("\n").filter((line) => !(line.includes("|") && line.includes("-") && /^[\s|:-]+$/.test(line))).filter((line) => !/^\s*([*_-])(\s*\1){2,}\s*$/.test(line)).map((line) => line.replace(/^\s*(>\s?)+/, "").replace(/^\s*#{1,6}\s+/, "").replace(/^\s*([-*+]|\d+[.)])\s+(\[[ xX]\]\s+)?/, "").replace(/^\s*\|(.*?)\|?\s*$/, (_row, cells) => cells.replace(/\s*\|\s*/g, "  "))).join(" "))).replace(/\s+/g, " ").trim();
+}
+function stripInline(text) {
+	return text.replace(/!\[[^\]]*\]\((?:[^()]|\([^()]*\))*\)/g, "").replace(/\[([^\]]+)\]\((?:[^()]|\([^()]*\))*\)/g, "$1").replace(/\[([^\]]+)\]\[[^\]]*\]/g, "$1").replace(/<((?:https?|mailto):[^>\s]+)>/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/(`+)([^`]+?)\1/g, "$2").replace(/(\*\*|__|~~)(?=\S)([\s\S]*?\S)\1/g, "$2").replace(/(^|[^\w*])\*(?=\S)([^*\n]*?\S)\*(?![\w*])/g, "$1$2").replace(/(^|[^\w])_(?=\S)([^_\n]*?\S)_(?!\w)/g, "$1$2");
+}
+/** 正文里残留的 %E6%8F%90 这类编码串解码成原字符；解不开（非法 UTF-8）就保持原样。 */
+function decodePercentRuns(text) {
+	return text.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+		try {
+			return decodeURIComponent(run);
+		} catch {
+			return run;
+		}
+	});
+}
+//#endregion
 //#region src/host-api.ts
 /**
 * Subagent sessions are host-internal workers of a parent conversation.
@@ -5524,7 +6022,7 @@ var HostBridge = class {
 		return capabilityBits(this.apiProxy, this.pushOutlet);
 	}
 	diagnostic(message) {
-		console.log("[deeppilot] " + message);
+		console.log(formatLogLine("info", message));
 	}
 	currentCursor() {
 		return this.cursor;
@@ -5566,14 +6064,21 @@ var HostBridge = class {
 	*  PROTOCOL §6 + §7), then fan the same payload out to offline devices
 	*  holding an APNs token. */
 	emitNotify(args) {
-		if ((args.category === "turn.completed" || args.category === "session.error") && this.subagentSessionIds.has(args.sessionId)) return;
-		const body = args.body.length > 120 ? args.body.slice(0, 119) + "…" : args.body;
+		const turnEnd = args.category === "turn.completed" || args.category === "session.error";
+		if (turnEnd && this.subagentSessionIds.has(args.sessionId)) return;
+		const plain = notificationPlainText(args.body, turnEnd ? "last" : "all") || (args.fallbackBody ?? "");
+		const body = plain.length > 120 ? plain.slice(0, 119) + "…" : plain;
+		const approvalExtras = args.category === "approval.required" && args.toolName ? {
+			toolName: args.toolName.slice(0, 80),
+			...args.detail ? { detail: args.detail.slice(0, 600) } : {}
+		} : {};
 		this.record("s2c.notify", {
 			notificationId: args.notificationId,
 			category: args.category,
 			sessionId: args.sessionId,
 			title: args.title,
 			body,
+			...approvalExtras,
 			ts: Date.now()
 		}, (sink) => this.isViewedBy(sink, args.sessionId));
 		this.fanOutPush({
@@ -5581,7 +6086,8 @@ var HostBridge = class {
 			category: args.category,
 			sessionId: args.sessionId,
 			title: args.title,
-			body
+			body,
+			...approvalExtras
 		});
 	}
 	/** F-9: when a turn completes, notify every device not viewing the session. */
@@ -5589,12 +6095,12 @@ var HostBridge = class {
 		if (this.subagentSessionIds.has(sessionId)) return;
 		const row = this.summaries.get(sessionId);
 		const title = ok ? "任务完成" : "任务异常结束";
-		const body = this.lastAssistantText.get(sessionId) ?? row?.title ?? "";
 		this.emitNotify({
 			sessionId,
 			category: ok ? "turn.completed" : "session.error",
 			title,
-			body,
+			body: this.lastAssistantText.get(sessionId) ?? "",
+			fallbackBody: row?.title ?? "",
 			notificationId: "n-" + (this.cursor + 1)
 		});
 	}
@@ -5607,11 +6113,15 @@ var HostBridge = class {
 			this.pushOutlet?.fanOut(notification);
 		} catch {}
 	}
-	/** Remember the latest assistant text so notifications can quote it. */
+	/**
+	* Remember the latest assistant text so notifications can quote it. 存完整原文：
+	* 按字符数截尾会从链接地址中间切开（横幅只剩 URL 编码的路径），段落选择与
+	* Markdown 清洗统一留到 emitNotify。条目随 sessions.list / 归档清理。
+	*/
 	captureAssistantText(sessionId, event) {
 		if (event.type !== "assistant/message") return;
 		const text = messageText(event.data).trim();
-		if (text.length > 0) this.lastAssistantText.set(sessionId, text.slice(-160));
+		if (text.length > 0) this.lastAssistantText.set(sessionId, text);
 	}
 	/**
 	* Replay buffered pushes after the given cursor; false when the gap is
@@ -5811,7 +6321,9 @@ var HostBridge = class {
 					category: "approval.required",
 					title: "需要批准",
 					body: toolName + ": " + summary,
-					notificationId: "apr-" + p.approvalId
+					notificationId: "apr-" + p.approvalId,
+					toolName,
+					detail: summary
 				});
 				this.bumpPendingFlags(sessionId);
 				break;
@@ -8266,6 +8778,40 @@ function parsePushTestResult(value) {
 		results
 	};
 }
+function parseDiagnosticFailure(value) {
+	const s = rec(value, "diagnostics.recentFailures[]");
+	const kind = str(s, "kind", "diagnostics.kind");
+	if (!/^[a-z][a-z0-9-]{0,47}$/.test(kind)) reject("diagnostics.kind");
+	const reason = str(s, "reason", "diagnostics.reason");
+	if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(reason)) reject("diagnostics.reason");
+	const attemptId = s.attemptId;
+	if (attemptId !== void 0 && (typeof attemptId !== "string" || !/^[A-Za-z0-9_-]{1,16}$/.test(attemptId))) reject("diagnostics.attemptId");
+	const source = s.source;
+	if (source !== void 0 && (typeof source !== "string" || !/^[0-9a-f]{8,64}$/.test(source))) reject("diagnostics.source");
+	const closeCode = s.closeCode;
+	if (closeCode !== void 0 && (typeof closeCode !== "number" || !Number.isInteger(closeCode))) reject("diagnostics.closeCode");
+	const durationMs = s.durationMs;
+	if (durationMs !== void 0 && (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0)) reject("diagnostics.durationMs");
+	return {
+		ts: int(s, "ts", "diagnostics.ts"),
+		kind,
+		reason,
+		...typeof attemptId === "string" ? { attemptId } : {},
+		...typeof source === "string" ? { source } : {},
+		...typeof closeCode === "number" ? { closeCode } : {},
+		...typeof durationMs === "number" ? { durationMs: Math.round(durationMs) } : {}
+	};
+}
+function parseDiagnostics(value) {
+	const s = rec(value, "diagnostics");
+	const failures = s.recentFailures;
+	if (!Array.isArray(failures)) reject("diagnostics.recentFailures");
+	if (failures.length > 20) reject("diagnostics.recentFailures");
+	return {
+		startedAt: int(s, "startedAt", "diagnostics.startedAt"),
+		recentFailures: failures.map(parseDiagnosticFailure)
+	};
+}
 function parseReport(value) {
 	const s = rec(value, "report");
 	const devices = s.devices;
@@ -8287,7 +8833,8 @@ function parseReport(value) {
 		lanAddresses,
 		local: parseLocal(s.local),
 		remote: parseRemote(s.remote),
-		devices: devices.map(parseDevice)
+		devices: devices.map(parseDevice),
+		...s.diagnostics !== void 0 ? { diagnostics: parseDiagnostics(s.diagnostics) } : {}
 	};
 }
 const reportSchema = { parse: parseReport };
@@ -8756,13 +9303,17 @@ async function loadOrCreateLanTlsIdentity(dir, now = Date.now()) {
 	});
 	const keyPath = join(dir, LAN_TLS_KEY_FILE);
 	const certPath = join(dir, LAN_TLS_CERT_FILE);
-	let key = await readPem(keyPath);
+	let key = await readPem(keyPath, (error) => {
+		console.log(formatLogLine("warn", "LAN TLS private key unreadable, regenerating identity: " + describeFileError(error)));
+	});
 	let regenerated = false;
 	if (key === void 0 || !validPrivateKey(key)) {
 		regenerated = true;
 		key = void 0;
 	}
-	let cert = regenerated ? void 0 : await readPem(certPath);
+	let cert = regenerated ? void 0 : await readPem(certPath, (error) => {
+		console.log(formatLogLine("warn", "LAN TLS certificate unreadable, re-signing with the existing key: " + describeFileError(error)));
+	});
 	let resigned = false;
 	const existing = key !== void 0 && cert !== void 0 ? inspectCertificate(cert, key, now) : void 0;
 	if (existing === void 0) {
@@ -8784,15 +9335,22 @@ async function loadOrCreateLanTlsIdentity(dir, now = Date.now()) {
 		resigned
 	};
 }
-async function readPem(path) {
+async function readPem(path, onError) {
 	try {
 		const text = await readFile(path, "utf8");
 		return text.trim().length > 0 ? text : void 0;
 	} catch (error) {
 		if (error.code === "ENOENT") return void 0;
+		onError?.(error);
 		return;
 	}
 }
+/** 读失败的安全描述：文件名 + errno，不带文件内容。 */
+function describeFileError(error) {
+	const code = error?.code;
+	const message = error instanceof Error ? error.message : String(error);
+	return (typeof code === "string" ? "code=" + code + " " : "") + message.slice(0, 140);
+}
 function validPrivateKey(pem) {
 	try {
 		return createPrivateKey(pem).asymmetricKeyType === "ec";
@@ -8935,9 +9493,7 @@ function readOwnPackageVersion() {
 }
 function apply(ctx, options) {
 	const cfg = normalizeOptions(options);
-	const log = (message) => {
-		console.log("[deeppilot] " + message);
-	};
+	const log = createLogger();
 	const auditSalt = randomBytes(32);
 	const auditLabel = (value) => createHash("sha256").update(auditSalt).update(value).digest("hex").slice(0, 12);
 	let scheduleRemoteReconcile;
@@ -8950,6 +9506,30 @@ function apply(ctx, options) {
 	}));
 	if (currentConfig().enabled !== true) log("disabled via settings; bridge stays inactive (rumors of /phone below are skipped)");
 	const dataDir = bridgeDataDir();
+	/** 插件启动时刻：`/phone/health` 与设置页报告都读它。 */
+	const startedAt = Date.now();
+	/**
+	* 连接诊断事件：内存环形 256 条 + 按天落盘（插件数据目录 diagnostics/，
+	* 保留 7 天、目录上限 5MB）。与 `diagnostics.debug` 完全解耦——失败事件
+	* 无条件记录，否则用户不开调试开关就永远看不到「为什么连不上」。
+	*/
+	const diagnostics = new DiagnosticsStore({
+		dir: join(dataDir, "diagnostics"),
+		write: (line) => {
+			console.log(line);
+		}
+	});
+	/**
+	* 传输层错误（TLS 握手失败 / HTTP 报文解析失败）的统一入口。来源先经
+	* auditLabel 哈希再记录；原始 IP 绝不进入事件或日志。
+	*/
+	const recordTransportError = (event) => {
+		const code = event.error?.code;
+		diagnostics.record("connection-error", event.kind, {
+			...event.remoteAddress !== void 0 ? { source: auditLabel(event.remoteAddress) } : {},
+			detail: typeof code === "string" ? code : event.error instanceof Error ? event.error.message : String(event.error)
+		});
+	};
 	const pushGateway = new PushGateway({
 		config: currentConfig,
 		dataDir,
@@ -8970,7 +9550,7 @@ function apply(ctx, options) {
 				const migratedFrom = await migrateLegacyBridgeDataDir();
 				if (migratedFrom !== null) log(`migrated legacy plugin state from ${migratedFrom} to ${dataDir}`);
 			} catch (error) {
-				log("legacy plugin-state migration skipped: " + String(error));
+				log("legacy plugin-state migration skipped: " + String(error), "warn");
 			}
 			await ensurePrivateBridgeDataDir();
 			auth.audience = await loadOrCreateHostAudience(join(dataDir, "host-id"));
@@ -8982,7 +9562,7 @@ function apply(ctx, options) {
 			}
 			await pushGateway.restore();
 		} catch (error) {
-			log("auth material unavailable, bridge degraded: " + String(error));
+			log("auth material unavailable, bridge degraded: " + String(error), "warn");
 			return {
 				audience: null,
 				devices: null
@@ -9109,7 +9689,19 @@ function apply(ctx, options) {
 			lanAddresses,
 			local: localStatus(lanAddresses),
 			remote: remoteStatus(),
-			devices
+			devices,
+			diagnostics: {
+				startedAt,
+				recentFailures: diagnostics.recentFailures(20).map((event) => ({
+					ts: event.ts,
+					kind: event.kind,
+					reason: event.reason,
+					...event.attemptId !== void 0 ? { attemptId: event.attemptId } : {},
+					...event.source !== void 0 ? { source: event.source } : {},
+					...event.closeCode !== void 0 ? { closeCode: event.closeCode } : {},
+					...event.durationMs !== void 0 ? { durationMs: event.durationMs } : {}
+				}))
+			}
 		};
 	}, beginPairing, async (deviceId) => {
 		return await revokeDevice(deviceId);
@@ -9149,7 +9741,16 @@ function apply(ctx, options) {
 	};
 	const handlePair = async (req, res) => {
 		res.setHeader("Content-Type", "application/json");
+		const source = requestClientIdentity(req);
+		const attemptId = attemptIdFromRequest(req);
+		const reportPairRejected = (reason) => {
+			diagnostics.record("pair-rejected", reason, {
+				source: auditLabel(source),
+				...attemptId !== void 0 ? { attemptId } : {}
+			});
+		};
 		if (!enabledNow()) {
+			reportPairRejected("bridge-disabled");
 			res.statusCode = 503;
 			res.end(JSON.stringify({
 				ok: false,
@@ -9158,6 +9759,7 @@ function apply(ctx, options) {
 			return;
 		}
 		if (req.method !== "POST") {
+			reportPairRejected("method-not-allowed");
 			res.statusCode = 405;
 			res.setHeader("Allow", "POST");
 			res.end(JSON.stringify({
@@ -9166,9 +9768,9 @@ function apply(ctx, options) {
 			}));
 			return;
 		}
-		const source = requestClientIdentity(req);
 		const admission = authRateLimiter.admit(source);
 		if (!admission.ok) {
+			reportPairRejected("rate-limited");
 			res.statusCode = 429;
 			res.setHeader("Retry-After", String(Math.max(1, Math.ceil(admission.retryAfterMs / 1e3))));
 			res.end(JSON.stringify({
@@ -9188,6 +9790,7 @@ function apply(ctx, options) {
 			const appVersion = sanitizeDeviceField(raw.appVersion, 32) || "unknown";
 			const deviceId = deviceIdForPublicKey(publicKey);
 			if (devices.list().length >= 64 && devices.authorized(deviceId) === void 0) {
+				reportPairRejected("registry-full");
 				res.statusCode = 409;
 				res.end(JSON.stringify({
 					ok: false,
@@ -9197,6 +9800,7 @@ function apply(ctx, options) {
 			}
 			if (!pairingCodes.consume(code)) {
 				const failure = authRateLimiter.recordFailure(source);
+				reportPairRejected("invalid-code");
 				res.statusCode = failure.blocked ? 429 : 401;
 				if (failure.retryAfterMs > 0) res.setHeader("Retry-After", String(Math.max(1, Math.ceil(failure.retryAfterMs / 1e3))));
 				res.end(JSON.stringify({
@@ -9224,7 +9828,9 @@ function apply(ctx, options) {
 				...tlsFingerprint ? { tlsFingerprint } : {}
 			}));
 		} catch (error) {
-			res.statusCode = error instanceof SyntaxError || error instanceof TypeError ? 400 : 503;
+			const badRequest = error instanceof SyntaxError || error instanceof TypeError;
+			reportPairRejected(badRequest ? "bad-request" : "internal-error");
+			res.statusCode = badRequest ? 400 : 503;
 			res.end(JSON.stringify({
 				ok: false,
 				error: error instanceof Error ? error.message : "pairing failed"
@@ -9234,14 +9840,24 @@ function apply(ctx, options) {
 		}
 	};
 	const handleUpgrade = (req, socket, head) => {
+		const source = requestClientIdentity(req);
+		const sourceLabel = auditLabel(source);
+		const attemptId = attemptIdFromRequest(req);
+		const reject = (status, reason) => {
+			diagnostics.record("upgrade-rejected", reason, {
+				source: sourceLabel,
+				...attemptId !== void 0 ? { attemptId } : {}
+			});
+			rejectUpgrade(socket, status, reason);
+		};
 		(async () => {
 			try {
 				if (!enabledNow()) {
-					rejectUpgrade(socket, 503, "bridge disabled");
+					reject(503, "bridge disabled");
 					return;
 				}
 				if (connections.size + pendingUpgrades >= MAX_CLIENT_CONNECTIONS) {
-					rejectUpgrade(socket, 429, "too many connections");
+					reject(429, "too many connections");
 					return;
 				}
 				pendingUpgrades += 1;
@@ -9249,30 +9865,36 @@ function apply(ctx, options) {
 				try {
 					const { devices, audience } = await ready;
 					if (!audience || !devices) {
-						rejectUpgrade(socket, 503, "bridge degraded");
+						reject(503, "bridge degraded");
 						return;
 					}
 					const bridge = state.bridge;
 					if (!bridge) {
-						rejectUpgrade(socket, 503, "bridge not ready");
+						reject(503, "bridge not ready");
 						return;
 					}
 					gate = new ConnectionGate({
-						source: requestClientIdentity(req),
+						source,
 						devices,
 						audience,
 						limiter: authRateLimiter,
 						log,
-						auditLabel
+						auditLabel,
+						diagnostics,
+						...attemptId !== void 0 ? { attemptId } : {}
 					});
 					if (!gate.admitted) {
-						rejectUpgrade(socket, 429, "authentication rate limited");
+						reject(429, "authentication rate limited");
 						return;
 					}
 					const live = gate;
 					wss.handleUpgrade(req, socket, head, (ws) => {
 						if (auth.audience !== audience || state.bridge !== bridge) {
 							live.markDead();
+							diagnostics.record("upgrade-rejected", "bridge-changed", {
+								source: sourceLabel,
+								...attemptId !== void 0 ? { attemptId } : {}
+							});
 							ws.close(1012, "bridge changed");
 							return;
 						}
@@ -9287,6 +9909,8 @@ function apply(ctx, options) {
 								source: live.source,
 								rateLimiter: authRateLimiter,
 								auditLabel,
+								diagnostics,
+								...attemptId !== void 0 ? { attemptId } : {},
 								onClosed: (closed) => connections.delete(closed),
 								onDeviceAuthenticated: (deviceId) => {
 									log(`device authenticated id=${auditLabel(deviceId)} source=${auditLabel(live.source)}`);
@@ -9306,7 +9930,12 @@ function apply(ctx, options) {
 					pendingUpgrades -= 1;
 				}
 			} catch (error) {
-				log("upgrade failed: " + String(error));
+				log("upgrade failed: " + String(error), "warn");
+				diagnostics.record("upgrade-rejected", "internal-error", {
+					source: sourceLabel,
+					...attemptId !== void 0 ? { attemptId } : {},
+					detail: error instanceof Error ? error.message : String(error)
+				});
 				rejectUpgrade(socket, 500, "internal error");
 			}
 		})();
@@ -9323,14 +9952,19 @@ function apply(ctx, options) {
 				}));
 				return;
 			}
+			const local = localTransport.status();
 			res.statusCode = 200;
-			res.end(JSON.stringify({
-				ok: true,
+			res.end(JSON.stringify(buildHealthPayload({
+				startedAt,
 				enabled: enabledNow(),
 				protocolVersion: 2,
 				serverVersion: SERVER_VERSION,
-				dataPlane: Boolean(state.bridge)
-			}));
+				dataPlaneActive: Boolean(state.bridge),
+				localPhase: local.phase,
+				localPort: local.port,
+				tlsIdentityRegenerated,
+				lastFailure: diagnostics.lastFailureSummary()
+			})));
 		} catch {
 			res.statusCode = 500;
 			res.end(JSON.stringify({ ok: false }));
@@ -9345,7 +9979,8 @@ function apply(ctx, options) {
 		handlers: phoneHandlers,
 		config: currentConfig,
 		tls: loadLanTls,
-		log
+		log,
+		onTransportError: recordTransportError
 	});
 	const remoteTransport = createRemoteTransport({
 		handlers: phoneHandlers,
@@ -9363,7 +9998,7 @@ function apply(ctx, options) {
 		};
 	};
 	const remoteStatus = () => remoteTransport.status();
-	const originServer = createPhoneServer(phoneHandlers);
+	const originServer = createPhoneServer(phoneHandlers, void 0, { onTransportError: recordTransportError });
 	let originURL;
 	scheduleLocalReconcile = () => localTransport.scheduleReconcile();
 	scheduleRemoteReconcile = () => remoteTransport.scheduleReconcile();
@@ -9375,7 +10010,7 @@ function apply(ctx, options) {
 				originURL = `http://127.0.0.1:${address.port}`;
 				scheduleRemoteReconcile?.();
 			}
-		}, (error) => log("remote origin failed: " + String(error)));
+		}, (error) => log("remote origin failed: " + String(error), "warn"));
 		return async () => {
 			scheduleLocalReconcile = void 0;
 			scheduleRemoteReconcile = void 0;
@@ -9419,7 +10054,7 @@ function apply(ctx, options) {
 		try {
 			proxy = new DshApiProxy(apiCtx, { shouldSurfaceInteraction: hasPairedPhoneSurface });
 		} catch (error) {
-			log("DSH session bridge unavailable: " + String(error));
+			log("DSH session bridge unavailable: " + String(error), "warn");
 			return;
 		}
 		const bridge = new HostBridge(proxy, cfg.historyBufferMax, join(dataDir, "prompt-deliveries-v1.json"), join(dataDir, "schedule-mutations-v1.json"), join(dataDir, "fork-mutations-v1.json"), log);
@@ -9442,6 +10077,7 @@ function apply(ctx, options) {
 		await pushGateway.dispose();
 		const wssClosed = new Promise((resolve) => wss.close(() => resolve()));
 		await Promise.allSettled([wssClosed]);
+		await diagnostics.dispose();
 	}, "deeppilot: process resources");
 }
 //#endregion