dsh-deeppilot 0.9.7 → 0.9.9

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";
@@ -98,6 +98,24 @@ const DOMAIN_TABLES = {
 		"frequency_too_high": "E_PROTOCOL",
 		"schedule_ended": "E_PROTOCOL",
 		"subagent_session": "E_PROTOCOL"
+	},
+	command: {
+		"command/not-found": "E_NOT_FOUND",
+		"command/definition-changed": "E_NOT_FOUND",
+		"command/attachments-unsupported": "E_PROTOCOL",
+		"command/export-unavailable": "E_INTERNAL",
+		"command/export-cancelled": "E_INTERNAL",
+		"command/export-unsupported": "E_UNSUPPORTED",
+		"command/invalid-response": "E_INTERNAL",
+		"command/permissions-unsupported": "E_UNSUPPORTED",
+		"gateway/bad-request": "E_PROTOCOL",
+		"session/not-found": "E_NOT_FOUND",
+		"session/agent-busy": "E_BUSY",
+		"session/writer-held": "E_BUSY",
+		"session/conflict": "E_BUSY",
+		"session-not-found": "E_NOT_FOUND",
+		"agent-busy": "E_BUSY",
+		"session-conflict": "E_BUSY"
 	}
 };
 /**
@@ -127,6 +145,24 @@ function wireErrorOf(domain, error) {
 	};
 }
 /**
+* 把任意抛出物收敛成 `HostFailure`，供 `catch` 分支复用同一张域表。
+*
+* 指令链路里有两种失败来源：`DshApiProxy.call` 把插件的失败码放在
+* `{result:{ok:false,error}}` 里正常返回，而导出的归档流是直接抛出的
+* （`AbortError`、主机侧 `Error` 都算）。把「取形状」和「查表」分开，是为了让
+* 两条路都只经一次翻译；没有 code 的抛出物用调用方给的 fallback，避免把
+* `undefined` 当码送进 lookupCode 而落进无法解释的兜底。
+*/
+function hostFailureOf(error, fallbackCode) {
+	const value = error;
+	const code = typeof value?.code === "string" && value.code.length > 0 ? value.code : fallbackCode;
+	const message = typeof value?.message === "string" && value.message.length > 0 ? value.message : void 0;
+	return message === void 0 ? { code } : {
+		code,
+		message
+	};
+}
+/**
 * 组装给手机看的那句话。
 *
 * DSH 把 prompt 准入的**任意**内部失败包成 `session/agent-busy`，真实原因只留在
@@ -213,6 +249,9 @@ function isEnvelope(value) {
 */
 const PUSH_SCOPE_BY_TYPE = {
 	"s2c.session.event": "sessions.read",
+	"s2c.skills.changed": "sessions.read",
+	"s2c.commands.changed": "sessions.read",
+	"s2c.models.changed": "sessions.read",
 	"s2c.sessions.delta": "sessions.read",
 	"s2c.session.tail": "sessions.read",
 	"s2c.history.page": "sessions.read",
@@ -355,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;
@@ -380,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) {
@@ -644,6 +1011,11 @@ var DeviceStore = class DeviceStore {
 	filePath;
 	devices = /* @__PURE__ */ new Map();
 	flushTail = Promise.resolve();
+	/**
+	* 注册表写失败的日志节流：磁盘只读 / 空间不足时每次 flush 都会失败，
+	* 不节流会把「写不进去」变成新的刷屏源。同一条错误 60s 只报一次。
+	*/
+	lastWriteFailureLogAt = 0;
 	constructor(filePath) {
 		this.filePath = filePath;
 	}
@@ -653,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;
 	}
@@ -686,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;
@@ -850,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
@@ -2067,6 +2462,26 @@ const sessionRows = [
 			ctx.send("s2c.ack", image);
 		}
 	},
+	{
+		type: "c2s.session.skills",
+		stage: "authenticated",
+		scopes: READ,
+		capability: "skills",
+		doc: "PROTOCOL.md c2s.session.skills",
+		validate: (payload) => {
+			const checked = payloadObject(payload);
+			if (!checked.ok) return checked;
+			return requireSessionId(checked.value) ?? checked;
+		},
+		handle: async (ctx, payload) => {
+			const result = await ctx.bridge.sessionSkills(payload.sessionId);
+			if (!result.ok) return ctx.fail(result.code, result.message);
+			ctx.send("s2c.session.skills", {
+				sessionId: payload.sessionId,
+				...result.value
+			});
+		}
+	},
 	{
 		type: "c2s.session.models",
 		stage: "authenticated",
@@ -2219,6 +2634,121 @@ const sessionRows = [
 		}
 	}
 ];
+//#endregion
+//#region src/wire-command.ts
+function sessionPayload(value) {
+	const result = payloadObject(value);
+	return result.ok && !isText(result.value.sessionId) ? reject$1("E_PROTOCOL", "会话标识无效") : result;
+}
+const categories = [
+	"task-result",
+	"instruction-following",
+	"product-interaction",
+	"service-stability",
+	"resource-cost",
+	"security-privacy-permission",
+	"other"
+];
+const commandRows = [...[
+	"commands",
+	"permissions",
+	"feedback",
+	"command"
+].map((name) => ({
+	type: `c2s.session.${name}`,
+	stage: "authenticated",
+	capability: "commands",
+	scopes: name === "commands" || name === "permissions" ? ["sessions.read"] : ["prompt.send"],
+	doc: `PROTOCOL.md c2s.session.${name}`,
+	validate: (value) => {
+		const result = sessionPayload(value);
+		if (!result.ok) return result;
+		const p = result.value;
+		if (name === "command") {
+			if (typeof p.line !== "string" || p.line.length > 65536 || !/^\/[a-z][a-z0-9_-]*(?:\s|$)/.test(p.line)) return reject$1("E_PROTOCOL", "指令格式无效");
+			if (p.expectedDefinitionId !== void 0 && (typeof p.expectedDefinitionId !== "string" || !p.expectedDefinitionId || p.expectedDefinitionId.length > 512)) return reject$1("E_PROTOCOL", "指令定义标识无效");
+			const attachments = p.attachments ?? [];
+			if (!Array.isArray(attachments) || attachments.length > 4) return reject$1("E_PROTOCOL", "附件数量无效");
+			for (const item of attachments) if (!item || !["image", "document"].includes(item.type) || typeof item.name !== "string" || item.name.length > 512 || typeof item.mediaType !== "string" || typeof item.data !== "string" || item.data.length > 16777216 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(item.data) || item.type === "image" && ![
+				"image/png",
+				"image/jpeg",
+				"image/webp",
+				"image/gif"
+			].includes(item.mediaType)) return reject$1("E_PROTOCOL", "附件格式无效");
+			return {
+				ok: true,
+				value: {
+					...p,
+					attachments
+				}
+			};
+		}
+		if (name === "feedback" && (typeof p.text !== "string" || p.text.length > 65536 || p.category !== void 0 && !categories.includes(String(p.category)))) return reject$1("E_PROTOCOL", "反馈内容无效");
+		return result;
+	},
+	handle: async (ctx, payload) => {
+		const operation = name === "commands" ? "list" : name === "command" ? "execute" : name;
+		const result = await ctx.bridge.commandOperation(operation, payload);
+		if (!result.ok) return ctx.fail(result.code, result.message);
+		const type = name === "commands" ? "s2c.session.commands" : name === "permissions" ? "s2c.session.permissions" : name === "command" ? "s2c.session.commandResult" : "s2c.ack";
+		ctx.send(type, {
+			sessionId: payload.sessionId,
+			...result.value
+		});
+	}
+})), {
+	type: "c2s.session.export",
+	stage: "authenticated",
+	scopes: ["sessions.read"],
+	capability: "commands",
+	doc: "PROTOCOL.md c2s.session.export",
+	validate: sessionPayload,
+	handle: async (ctx, payload) => {
+		const signal = AbortSignal.any([ctx.signal ?? new AbortController().signal, AbortSignal.timeout(6e5)]);
+		let reader;
+		const cancel = () => {
+			reader?.cancel().catch(() => {});
+		};
+		try {
+			reader = (await ctx.bridge.exportSession(payload.sessionId, signal)).body.getReader();
+			signal.addEventListener("abort", cancel, { once: true });
+			let index = 0, bytes = 0;
+			while (true) {
+				signal.throwIfAborted();
+				const next = await reader.read();
+				if (next.done) break;
+				for (let offset = 0; offset < next.value.length; offset += 49152) {
+					const chunk = next.value.subarray(offset, offset + 49152);
+					bytes += chunk.length;
+					await ctx.waitForWritable?.();
+					ctx.send("s2c.session.export.chunk", {
+						index: index++,
+						data: Buffer.from(chunk).toString("base64")
+					});
+				}
+			}
+			signal.throwIfAborted();
+			ctx.send("s2c.ack", {
+				sessionId: payload.sessionId,
+				fileName: "dsh-session-log.zip",
+				chunks: index,
+				bytes
+			});
+		} catch (error) {
+			const failure = hostFailureOf(error, "command/export-cancelled");
+			const message = failure.code === "command/export-cancelled" ? "会话日志导出失败，请重试" : failure.message;
+			const mapped = wireErrorOf("command", {
+				...failure,
+				message
+			});
+			ctx.fail(mapped.code, mapped.message);
+		} finally {
+			signal.removeEventListener("abort", cancel);
+			await reader?.cancel().catch(() => {});
+			reader?.releaseLock();
+		}
+	}
+}];
 /** 第一个缺失的 scope；消息与迁移前一致（`scope <name> required`）。 */
 function scopeRejection(row, scopes) {
 	for (const scope of row.scopes) if (!scopes.has(scope)) return {
@@ -2297,6 +2827,7 @@ function accept(value) {
 /** 全部入站行。装配是静态的：新增特性 module 必须在这里显式出现。 */
 const WIRE_FRAME_ROWS = [
 	...sessionRows,
+	...commandRows,
 	...scheduleRows,
 	...interactionRows,
 	...pushRows,
@@ -2329,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 {
@@ -2389,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();
@@ -2478,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, {
@@ -2499,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;
@@ -2521,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;
@@ -2545,6 +3121,8 @@ var ConnectionGate = class {
 		const host = this.host;
 		return {
 			frame: env,
+			signal: host.signal,
+			waitForWritable: host.waitForWritable?.bind(host),
 			deviceId: this.deviceId,
 			widgetClient: this.widgetClient,
 			bridge: host.bridge,
@@ -2604,6 +3182,11 @@ var BridgeConnection = class {
 	liveActivityRegistrationGeneration = 0;
 	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;
@@ -2618,12 +3201,24 @@ 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 () => {
+				while (this.ws.bufferedAmount > 262144) {
+					this.streamAbort.signal.throwIfAborted();
+					await new Promise((resolve) => setTimeout(resolve, 10));
+				}
+				this.streamAbort.signal.throwIfAborted();
+			},
 			get bridge() {
 				return connection.deps.bridge;
 			},
@@ -2676,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() {
@@ -2766,9 +3372,18 @@ 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);
 		this.openSessions.clear();
@@ -3422,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: {
@@ -3431,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) {
@@ -3758,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. */
@@ -3779,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();
 	}
@@ -3843,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.",
@@ -4484,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);
@@ -4506,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) {
@@ -4606,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));
 		}
 	}
 	/** 进程收尾：标记销毁、拆掉实例、等在途的那一次完成。 */
@@ -4647,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");
@@ -4685,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 {
@@ -5225,6 +5866,8 @@ function unwrapStreamItem(item) {
 /** 每位一行：Host 上必须存在的依赖。缺失即该位为 false，相关帧回 E_UNSUPPORTED。 */
 const HOST_CAPABILITY_PROBES = {
 	models: (proxy) => typeof proxy.sessions.models === "function",
+	skills: (proxy) => typeof proxy.sessions.skills === "function",
+	commands: (proxy) => typeof proxy.commands?.list === "function" && typeof proxy.commands?.execute === "function",
 	sessionManagement: (proxy) => typeof proxy.sessions.rename === "function" && typeof proxy.workspace?.archiveSession === "function",
 	sessionFork: (proxy) => typeof proxy.sessions.fork === "function",
 	sessionRestore: (proxy) => typeof proxy.workspace?.unarchiveSession === "function",
@@ -5245,6 +5888,8 @@ function capabilityBits(proxy, pushOutlet) {
 		promptDelivery: true,
 		notifyAllCategories: true,
 		models: HOST_CAPABILITY_PROBES.models(proxy),
+		skills: HOST_CAPABILITY_PROBES.skills(proxy),
+		commands: HOST_CAPABILITY_PROBES.commands(proxy),
 		sessionManagement: HOST_CAPABILITY_PROBES.sessionManagement(proxy),
 		sessionFork: HOST_CAPABILITY_PROBES.sessionFork(proxy),
 		sessionRestore: HOST_CAPABILITY_PROBES.sessionRestore(proxy),
@@ -5333,7 +5978,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;
@@ -5377,12 +6022,17 @@ var HostBridge = class {
 	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 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({
@@ -5390,7 +6040,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. */
@@ -5550,12 +6201,19 @@ var HostBridge = class {
 	}
 	onMuxFrame(frame) {
 		switch (frame.type) {
+			case "skills/changed":
+				this.record("s2c.skills.changed", {});
+				break;
+			case "commands/changed":
+				this.record("s2c.commands.changed", {});
+				break;
 			case "session/event": {
 				const event = frame.event;
 				const sessionId = String(frame.sessionId ?? "");
 				if (!event || !sessionId) break;
 				if (frame.isSubagent === true) this.subagentSessionIds.add(sessionId);
 				if (this.subagentSessionIds.has(sessionId)) break;
+				if (event.type === "agent-preset/selected") this.record("s2c.skills.changed", { sessionId });
 				this.noteActivity(sessionId, event);
 				this.captureAssistantText(sessionId, event);
 				const projection = projectEvent(sessionId, event);
@@ -5572,6 +6230,19 @@ var HostBridge = class {
 			case "session/projection": {
 				const p = frame;
 				if (!p.sessionId) break;
+				if (p.key === "workingDirectory" || p.key === "agentPreset") this.record("s2c.skills.changed", { sessionId: p.sessionId });
+				if (p.key === "modelSelection") {
+					const next = p.value?.next;
+					const current = next && typeof next.provider === "string" && typeof next.model === "string" ? {
+						provider: next.provider,
+						model: next.model,
+						...typeof next.reasoningEffort === "string" ? { reasoningEffort: next.reasoningEffort } : {}
+					} : void 0;
+					this.record("s2c.models.changed", {
+						sessionId: p.sessionId,
+						...current ? { current } : {}
+					});
+				}
 				this.applyProjection(p.sessionId, String(p.key ?? ""), p.value);
 				break;
 			}
@@ -5600,7 +6271,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;
@@ -5948,6 +6621,75 @@ var HostBridge = class {
 			return null;
 		}
 	}
+	async commandOperation(operation, payload) {
+		const api = this.apiProxy.commands;
+		if (!api) return {
+			ok: false,
+			code: "E_UNSUPPORTED",
+			message: "当前主机不支持手机指令"
+		};
+		try {
+			const response = await api[operation].call(api, {
+				rpcId: randomUUID(),
+				payload
+			});
+			if (response.result?.ok) return {
+				ok: true,
+				value: response.result.value ?? {}
+			};
+			return wireErrorOf("command", response.result?.error ?? { code: "command/invalid-response" });
+		} catch (error) {
+			return wireErrorOf("command", hostFailureOf(error, "command/invalid-response"));
+		}
+	}
+	async exportSession(sessionId, signal) {
+		const api = this.apiProxy.commands;
+		if (!api) throw Object.assign(/* @__PURE__ */ new Error("当前主机不支持日志导出"), { code: "command/export-unsupported" });
+		return api.export({
+			rpcId: randomUUID(),
+			payload: { sessionId }
+		}, signal);
+	}
+	/** 由会话目录决定技能可见性；不读取正文，也不把本机路径发给移动端。 */
+	async sessionSkills(sessionId) {
+		const read = this.apiProxy.sessions.skills;
+		if (!read) return {
+			ok: false,
+			code: "E_UNSUPPORTED",
+			message: "当前主机不支持技能目录"
+		};
+		try {
+			const response = await read.call(this.apiProxy.sessions, {
+				rpcId: randomUUID(),
+				payload: { sessionId }
+			});
+			if (!response.result) return {
+				ok: false,
+				code: "E_INTERNAL",
+				message: "技能目录响应无效"
+			};
+			if (!response.result.ok) return wireErrorOf("session", response.result.error);
+			const seen = /* @__PURE__ */ new Set();
+			return {
+				ok: true,
+				value: { skills: response.result.value.skills.map((skill) => {
+					if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(skill.name) || seen.has(skill.name) || typeof skill.description !== "string" || typeof skill.modelInvocable !== "boolean") throw new Error("技能目录条目无效");
+					seen.add(skill.name);
+					return {
+						name: skill.name,
+						description: skill.description,
+						modelInvocable: skill.modelInvocable
+					};
+				}) }
+			};
+		} catch {
+			return {
+				ok: false,
+				code: "E_INTERNAL",
+				message: "无法读取当前会话的技能目录"
+			};
+		}
+	}
 	async sessionModels(sessionId) {
 		const models = this.apiProxy.sessions.models;
 		if (typeof models !== "function") return {
@@ -7083,6 +7825,145 @@ async function startDshRemoteInteractions(hostCtx, handlers) {
 	}
 }
 //#endregion
+//#region src/command-api.ts
+/**
+* 给本域自造的失败带上 Host 风格的码。
+*
+* 这些失败不是上游返回的，而是插件在这里判定出来的，所以必须自己声明语义：
+* 没有码的抛出物在 wire-errors 的域表里查不到，一律落进 `E_INTERNAL`，手机端
+* 便无法区分「指令不存在」「定义已变化」「这个指令不收附件」——它们对用户的
+* 下一步动作要求完全不同。码的取值见 `src/wire-errors.ts` 的 `command` 域表。
+*/
+function fail(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+/** 只经官方 Gateway 调用命令，保留其 Agent 解析、作用域覆盖和生命周期记录。 */
+var DshCommandApi = class {
+	ctx;
+	peer;
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	get available() {
+		return this.ctx.get("commands") !== void 0 && typeof this.ctx.get("typertGateway")?.invoke === "function";
+	}
+	connection() {
+		return this.ctx.get("connection");
+	}
+	owner() {
+		const connection = this.connection();
+		return this.peer ??= connection?.createPeer?.({
+			principal: { kind: "owner" },
+			interactions: "none"
+		}) ?? connection?.operator;
+	}
+	invoke(namespace, method, args) {
+		return this.ctx.get("typertGateway").invoke({
+			namespace,
+			method,
+			args,
+			peer: this.owner(),
+			signal: AbortSignal.timeout(6e5)
+		});
+	}
+	async list(sessionId) {
+		const rows = await this.invoke("commands", "list", { agentId: sessionId });
+		const names = /* @__PURE__ */ new Set();
+		return {
+			commands: rows.map((row) => {
+				if (!/^[a-z][a-z0-9_-]{0,127}$/.test(row.name) || names.has(row.name) || typeof row.description !== "string") throw fail("command/invalid-response", "命令目录无效");
+				names.add(row.name);
+				return {
+					name: row.name,
+					description: row.description,
+					...typeof row.definitionId === "string" ? { definitionId: row.definitionId } : {},
+					...row.input && typeof row.input.hint === "string" ? { input: {
+						hint: row.input.hint,
+						attachments: row.input.attachments === true
+					} } : {}
+				};
+			}),
+			permissions: this.ctx.get("permissionPresets") !== void 0,
+			export: typeof this.connection()?.createSharedFetchHandler === "function"
+		};
+	}
+	async execute(sessionId, line, attachments, expectedDefinitionId) {
+		const catalog = await this.list(sessionId);
+		const name = /^\/([a-z][a-z0-9_-]*)(?=\s|$)/.exec(line)?.[1];
+		const command = catalog.commands.find((row) => row.name === name);
+		if (!command) throw fail("command/not-found", "当前会话没有这个指令");
+		if (expectedDefinitionId !== void 0 && command.definitionId !== expectedDefinitionId) throw fail("command/definition-changed", "指令定义已变化，请重新选择");
+		if (attachments.length && command.input?.attachments !== true) throw fail("command/attachments-unsupported", "这个指令不接受附件");
+		const submittedAttachments = [];
+		for (const item of attachments) if (item.type === "image") submittedAttachments.push({
+			type: "image",
+			mediaType: item.mediaType,
+			data: item.data
+		});
+		else {
+			const uploaded = await this.invoke("fileUploads", "upload", {
+				agentId: sessionId,
+				request: {
+					name: item.name + ".txt",
+					data: item.data
+				}
+			});
+			submittedAttachments.push({
+				type: "file",
+				receiptId: uploaded.receiptId
+			});
+		}
+		const result = await this.invoke("commands", "execute", {
+			agentId: sessionId,
+			line,
+			submittedAttachments
+		});
+		if (!result || typeof result.commandId !== "string" || !["success", "error"].includes(result.result?.kind)) throw fail("command/invalid-response", "指令执行响应无效");
+		return {
+			commandId: result.commandId,
+			result: {
+				kind: result.result.kind,
+				...typeof result.result.text === "string" ? { text: result.result.text } : {},
+				...Number.isSafeInteger(result.result.sourceEventSeq) && result.result.sourceEventSeq >= 0 ? { sourceEventSeq: result.result.sourceEventSeq } : {}
+			}
+		};
+	}
+	async permissions(sessionId) {
+		const service = this.ctx.get("permissionPresets");
+		if (!service) throw fail("command/permissions-unsupported", "当前主机不支持权限预设");
+		const catalog = await this.invoke("permissionPresets", "catalog", {});
+		const currentValue = (await this.ctx.get("sessionController").projections({ sessionId }, new AbortController().signal))?.values?.permissions?.currentValue;
+		const seen = /* @__PURE__ */ new Set();
+		const options = catalog.options.map((option) => {
+			if (typeof option.value !== "string" || !option.value.trim() || option.value.length > 512 || /[\r\n]/.test(option.value) || seen.has(option.value) || typeof option.name !== "string") throw fail("command/invalid-response", "权限目录无效");
+			seen.add(option.value);
+			return {
+				value: option.value,
+				name: option.name,
+				...typeof option.description === "string" ? { description: option.description } : {},
+				confirmation: option.value === "auto" || service.resolve(option.value).sandbox === "danger-full-access"
+			};
+		});
+		return {
+			...typeof currentValue === "string" ? { currentValue } : {},
+			options
+		};
+	}
+	async feedback(sessionId, text, category) {
+		const result = await this.invoke("sessionFeedback", "record", { request: {
+			sessionId,
+			...text.trim() ? { text: text.trim() } : {},
+			...category ? { category } : {}
+		} });
+		if (result?.ok !== true) throw fail(typeof result?.error?.code === "string" ? result.error.code : "command/invalid-response", typeof result?.error?.message === "string" ? result.error.message : "反馈未能保存");
+	}
+	async export(sessionId, signal) {
+		const response = await this.connection().createSharedFetchHandler("/api").fetch(new Request("http://localhost/api/session.export?includeDescendants=true&sessionId=" + encodeURIComponent(sessionId), { signal }), this.owner());
+		if (!response.ok || !response.body || !response.headers.get("content-type")?.includes("application/zip")) throw fail("command/export-unavailable", "主机未能生成会话日志归档");
+		return response;
+	}
+};
+//#endregion
 //#region src/dsh-api-proxy.ts
 /**
 * Adapter for the DSH rc.2 controller API.
@@ -7095,6 +7976,17 @@ async function startDshRemoteInteractions(hostCtx, handlers) {
 /** Direct-controller adapter with the shape HostBridge consumes. */
 var DshApiProxy = class {
 	ctx;
+	commandApi;
+	get commands() {
+		if (!this.commandApi.available) return void 0;
+		return {
+			list: (request) => this.call(() => this.commandApi.list(request.payload.sessionId)),
+			execute: (request) => this.call(() => this.commandApi.execute(request.payload.sessionId, request.payload.line, request.payload.attachments, request.payload.expectedDefinitionId)),
+			permissions: (request) => this.call(() => this.commandApi.permissions(request.payload.sessionId)),
+			feedback: (request) => this.call(() => this.commandApi.feedback(request.payload.sessionId, request.payload.text, request.payload.category)),
+			export: (request, signal) => this.commandApi.export(request.payload.sessionId, signal)
+		};
+	}
 	session;
 	workspaceController;
 	scheduleController;
@@ -7104,6 +7996,7 @@ var DshApiProxy = class {
 	shouldSurfaceInteraction;
 	constructor(ctx, options = {}) {
 		this.ctx = ctx;
+		this.commandApi = new DshCommandApi(ctx);
 		const session = ctx.get("sessionController");
 		if (session === void 0) throw new Error("DSH sessionController is unavailable");
 		this.session = session;
@@ -7112,6 +8005,12 @@ var DshApiProxy = class {
 		this.directoryPicker = ctx.get("directoryPickerController");
 		this.shouldSurfaceInteraction = options.shouldSurfaceInteraction ?? (() => true);
 		this.resolveSchedule();
+		Object.defineProperty(this.sessions, "skills", { get: () => {
+			const catalog = ctx.get("sessionSkillCatalog");
+			if (typeof catalog?.list !== "function") return void 0;
+			const read = async (request) => this.call(() => catalog.list({ sessionId: request.payload.sessionId }, new AbortController().signal));
+			return read;
+		} });
 	}
 	/**
 	* Resolve the optional Schedule service lazily, on every read.
@@ -7307,6 +8206,10 @@ var DshApiProxy = class {
 				value
 			});
 		});
+		const offSkills = this.ctx.on("skills/change", (() => {
+			queue.push({ type: "skills/changed" });
+		}), { global: true });
+		const offCommands = ["commands/change", "permission-presets/catalog-changed"].map((event) => this.ctx.on(event, (() => queue.push({ type: "commands/changed" })), { global: true }));
 		let disposeInteractions;
 		try {
 			disposeInteractions = await startDshRemoteInteractions(this.ctx, {
@@ -7321,6 +8224,8 @@ var DshApiProxy = class {
 		} finally {
 			offEvent();
 			offProjection?.();
+			offSkills();
+			offCommands.forEach((dispose) => dispose());
 			await disposeInteractions?.();
 			queue.close();
 		}
@@ -7823,6 +8728,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;
@@ -7844,7 +8783,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 };
@@ -8313,13 +9253,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) {
@@ -8341,15 +9285,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";
@@ -8492,9 +9443,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;
@@ -8507,6 +9456,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,
@@ -8527,7 +9500,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"));
@@ -8539,7 +9512,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
@@ -8666,7 +9639,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);
@@ -8706,7 +9691,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,
@@ -8715,6 +9709,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({
@@ -8723,9 +9718,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({
@@ -8745,6 +9740,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,
@@ -8754,6 +9750,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({
@@ -8781,7 +9778,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"
@@ -8791,14 +9790,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;
@@ -8806,30 +9815,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;
 						}
@@ -8844,6 +9859,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)}`);
@@ -8863,7 +9880,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");
 			}
 		})();
@@ -8880,14 +9902,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 }));
@@ -8902,7 +9929,8 @@ function apply(ctx, options) {
 		handlers: phoneHandlers,
 		config: currentConfig,
 		tls: loadLanTls,
-		log
+		log,
+		onTransportError: recordTransportError
 	});
 	const remoteTransport = createRemoteTransport({
 		handlers: phoneHandlers,
@@ -8920,7 +9948,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();
@@ -8932,7 +9960,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;
@@ -8976,7 +10004,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);
@@ -8999,6 +10027,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