pi-maestro-mobile 0.2.13 → 0.3.0

package/dist/server/mobile-host-server.js

@@ -9,6 +9,7 @@ import { projectMonitorState } from "../monitor-projection.js";
 import { readSettingsOverview, updateSettingsJson } from "../maestro-settings.js";
 import { validateClientCommand } from "../vendor/shared/index.js";
 import { HostSessionListService } from "./helpers.js";
+import { injectMessageToActiveTui } from "../workspace-peer-injector.js";
 /**
  * MobileHostServer — 移动端直连服务器（HTTP REST + WebSocket）
  *
@@ -22,62 +23,285 @@ export class MobileHostServer {
     controller;
     options;
     server;
-    webSocketServer = new WebSocketServer({ noServer: true, maxPayload: 8 * 1024 * 1024 });
+    webSocketServer;
     clients = new Set();
     /** 单客户端并发命令上限：超过则拒绝，防命令洪泛（DoS） */
     static MAX_CONNECTIONS = 32;
     static MAX_CONCURRENT_COMMANDS = 8;
+    /** 软高水位：best_effort 帧越阈即丢；required 帧持续越阈达宽限期才断线。
+     * 必须显著低于硬顶，否则「required 宽限投递」区间被压缩到几乎不存在 */
+    static HIGH_WATER_MARK_BYTES = 1 * 1024 * 1024;
+    /** 硬上限：约束队列驻留（buffered + 新帧）。默认 32MB：实测合法最大帧（4000 条 snapshot）≈7.4MB，
+     * 留 4× 余量；单帧自身越顶不阻断（防重连死循环），只告警 */
+    static HARD_LIMIT_BYTES = 32 * 1024 * 1024;
+    static SLOW_GRACE_MS = 5_000;
+    static DROP_LOG_INTERVAL_MS = 60_000;
+    /** 连续未应答次数上限：3 = 容忍两次漏答（默认 30s 周期即约 90s 无响应/无数据才判定死连） */
+    static HEARTBEAT_MAX_MISSES = 3;
     unsubscribeController;
+    /** listen() 等待中的错误回调；非空表示正在绑定端口 */
+    listenError;
     boundHost = "0.0.0.0";
     hostSessionList = new HostSessionListService({
         indexPath: join(homedir(), ".pi", "agent", "mobile-session-index.json"),
     });
+    /** 背压参数（构造时从 options 解析，默认取静态常量） */
+    highWaterMarkBytes;
+    hardLimitBytes;
+    slowGraceMs;
     constructor(controller, options = {}) {
         this.controller = controller;
         this.options = options;
+        this.webSocketServer = new WebSocketServer({ noServer: true, maxPayload: this.options.maxPayload ?? 8 * 1024 * 1024 });
+        this.highWaterMarkBytes = this.options.highWaterMarkBytes ?? MobileHostServer.HIGH_WATER_MARK_BYTES;
+        this.hardLimitBytes = this.options.hardLimitBytes ?? MobileHostServer.HARD_LIMIT_BYTES;
+        this.slowGraceMs = this.options.slowGraceMs ?? MobileHostServer.SLOW_GRACE_MS;
         this.server = createServer((request, response) => {
             void this.handleHttp(request, response);
         });
         this.server.on("upgrade", (request, socket, head) => {
             this.handleUpgrade(request, socket, head);
         });
+        // 常驻单一 error 入口：启动期错误只交给 listen() 的 reject，以免与友好提示重复打印原始错误；
+        // listen 成功后的 server error（EMFILE 等）无监听者时会以 uncaughtException 崩掉守护进程，故仅记录不抛出。
+        this.server.on("error", (error) => {
+            const pending = this.listenError;
+            this.listenError = undefined;
+            if (pending)
+                pending(error);
+            else
+                console.error("[maestro-mobile] http server error:", error);
+        });
         this.webSocketServer.on("connection", (ws) => {
             if (this.clients.size >= MobileHostServer.MAX_CONNECTIONS) {
+                console.warn(`[maestro-mobile] ws rejected: too many connections (limit=${MobileHostServer.MAX_CONNECTIONS})`);
                 ws.close(1013, "too many connections");
                 return;
             }
-            const client = { id: crypto.randomUUID(), ws, inflight: 0 };
+            const client = { id: crypto.randomUUID(), ws, inflight: 0, closing: false, droppedFrames: 0, lastDropLogAt: 0, slowSince: 0, heartbeatMisses: 0 };
             this.clients.add(client);
-            // P2-1：host_status 契约是 status: string；HostStatus 对象走独立的 host_info 事件
-            ws.send(JSON.stringify({ type: "host_status", status: "connected", seq: 0 }));
-            ws.send(JSON.stringify({ type: "host_info", info: this.controller.getStatus(), seq: 0 }));
+            // 故障隔离到连接粒度（本 run 主根因）：此前无 error listener，超限/非法帧的 error 事件直接变
+            // uncaughtException → cli fatal() → 整个 host 退出（单手机一帧崩掉所有客户端）。现在只断该连接，
+            // 其余连接无感。listener 必须先于任何 send 注册。
+            ws.on("error", (error) => {
+                // 注意：ws 在协议错误路径（receiverOnError）已同步发过 close 帧，此处不得 terminate，
+                // 否则抢掉 1009 通知，客户端只能看到裸 TCP 断。幂等 closing 标记下走 graceful 重复 close（无副作用）。
+                console.error(`[maestro-mobile] ws error client=${client.id} code=${error.code ?? "-"} message=${sanitizeWsErrorMessage(error.message, [this.options.token ?? ""])} (isolated)`);
+                this.closeClient(client, "ws_error");
+            });
+            // 活性由标准 ping/pong 心跳维护（见 startHeartbeat）：客户端栈（RN OkHttp/浏览器/Node ws）
+            // 均自动应答 pong，无需改协议。半开连接、死 socket 在下个周期被 terminate，
+            // 也封住 close() 等失联连接 graceful close 的≈30s 悬挂。
+            ws.on("pong", () => {
+                client.heartbeatMisses = 0;
+            });
             ws.on("message", (data) => {
+                // 收到任何入站数据即证明连接存活，清零漏答计数（防止 iOS/RN 客户端因底层 pong 延迟被心跳误杀）
+                client.heartbeatMisses = 0;
                 if (client.inflight >= MobileHostServer.MAX_CONCURRENT_COMMANDS) {
-                    this.sendError(client, "too_many_commands", "");
+                    // 限流拒绝也要回 in_reply_to：否则客户端那条命令挂 30s 超时。
+                    // 此处解析一次只为取 id；解析失败回空（真正的 invalid_json 判定在 handleClientMessage 里）
+                    let replyTo = "";
+                    try {
+                        const parsed = JSON.parse(data.toString());
+                        if (typeof parsed?.id === "string")
+                            replyTo = parsed.id;
+                    }
+                    catch { /* 非 JSON：无 id 可回 */ }
+                    this.sendError(client, "too_many_commands", undefined, replyTo);
                     return;
                 }
                 client.inflight++;
-                void this.handleClientMessage(client, data).finally(() => {
+                // .catch 不可省：void 链上任何 rejection（含未来新增分支）都会经 unhandledRejection 冒到 cli fatal() 退进程
+                void this.handleClientMessage(client, data)
+                    .catch((error) => {
+                    console.error(`[maestro-mobile] ws command crashed client=${client.id}:`, error instanceof Error ? sanitizeWsErrorMessage(error.message, [this.options.token ?? ""]) : error);
+                })
+                    .finally(() => {
                     client.inflight--;
                 });
             });
-            ws.on("close", () => {
+            ws.on("close", (code, reason) => {
+                client.closing = true;
+                if (client.droppedFrames > 0) {
+                    console.warn(`[maestro-mobile] ws closed client=${client.id} code=${code} droppedTotal=${client.droppedFrames}`);
+                }
+                else if (code !== 1000 && code !== 1001) {
+                    console.warn(`[maestro-mobile] ws closed client=${client.id} code=${code} reason=${sanitizeWsErrorMessage(reason.toString(), [this.options.token ?? ""]).slice(0, 60)}`);
+                }
                 this.clients.delete(client);
             });
+            // P2-1：host_status 契约是 status: string；HostStatus 对象走独立的 host_info 事件
+            this.sendFrame(client, { type: "host_status", status: "connected", seq: 0 }, "required");
+            this.sendFrame(client, { type: "host_info", info: this.controller.getStatus(), seq: 0 }, "required");
         });
         this.unsubscribeController = this.controller.onEvent((event) => {
-            const payload = JSON.stringify(event);
-            for (const client of this.clients) {
-                if (client.ws.readyState === client.ws.OPEN) {
-                    client.ws.send(payload);
-                }
+            let payload;
+            try {
+                payload = JSON.stringify(event);
+            }
+            catch (error) {
+                // 序列化失败（循环引用/BigInt）属事件自身缺陷：只记一次不抛出（controller 侧已有 per-listener 防护，
+                // 但本 listener 抛错会使本事件对其后客户端丢失——提前 return 避免半途截断）
+                console.error(`[maestro-mobile] ws broadcast serialize failed type=${event.type ?? "?"}:`, error instanceof Error ? error.message : error);
+                return;
+            }
+            // 协议层可丢性（packages/shared/src/protocol.ts:324-328）：只有 timeline_delta 声明「尚不存在可忽略，
+            // 终态由 timeline_item 补齐」。其余事件无 server 侧重放保证，一律 required（宁断不默丢）。
+            const delivery = event.type === "timeline_delta" ? "best_effort" : "required";
+            for (const client of [...this.clients]) {
+                this.sendFrame(client, payload, delivery, event.type);
             }
         });
     }
+    remoteOf(ws) {
+        return ws._socket?.remoteAddress ?? "-";
+    }
+    /** 心跳周期句柄 */
+    heartbeatTimer;
+    /**
+     * 服务端心跳：每周期对无响应的连接 terminate（半开/死 socket），有响应则 ping。
+     * 替代此前没用的 ws.setTimeout（WebSocket 对象无此方法）；也让 close():「graceful 等待」不再被失联连接拖≈30s。
+     */
+    startHeartbeat(intervalMs) {
+        if (this.heartbeatTimer)
+            return; // 幂等：重复 listen 不得叠加 interval（否则多路 ping/terminate）
+        this.heartbeatTimer = setInterval(() => {
+            for (const client of [...this.clients]) {
+                // 必须容忍一次漏答：本机 event loop 卡顶（实测 load>150）会让 pong 排队跨过半个周期，
+                // 单次未应答即 terminate 会误杀健康连接（表现为手机无端断线，需重连+补拉）。
+                if (client.heartbeatMisses >= MobileHostServer.HEARTBEAT_MAX_MISSES) {
+                    console.warn(`[maestro-mobile] ws heartbeat lost client=${client.id} remote=${this.remoteOf(client.ws)} misses=${client.heartbeatMisses} → terminate`);
+                    this.closeClient(client, "heartbeat_lost");
+                    continue;
+                }
+                client.heartbeatMisses++;
+                try {
+                    client.ws.ping();
+                }
+                catch {
+                    this.closeClient(client, "ping_failed");
+                }
+            }
+        }, intervalMs);
+        this.heartbeatTimer.unref?.(); // 不阻止进程退出
+    }
+    /**
+     * 单一发送出口（故障隔离 + 背压收口）：所有 WS 写出必须经此，不得直接 ws.send。
+     * - required（command_result/握手/协议错误/timeline_item/session_updated/raw_event/…）：
+     *   越阈不静默丢；持续越阈达宽限期 close(1013)，由客户端重连 + P2-2 snapshot 补拉自愈。
+     *   不自研排队/drain 补发：消除 close×drain 竞态，局域网工具不值得该复杂度。
+     * - best_effort（仅 timeline_delta）：越阈直接丢弃并计数，终态由后续 timeline_item 补齐，不断线。
+     */
+    sendFrame(client, message, delivery, kind = "object") {
+        if (client.closing || client.ws.readyState !== client.ws.OPEN)
+            return false;
+        let payload;
+        try {
+            payload = typeof message === "string" ? message : JSON.stringify(message);
+        }
+        catch (error) {
+            console.error(`[maestro-mobile] ws sendFrame serialize failed kind=${kind} client=${client.id}:`, error instanceof Error ? error.message : error);
+            return false;
+        }
+        const buffered = client.ws.bufferedAmount;
+        // 硬顶语义：约束的是「队列驻留」，不是「单帧大小」。
+        // 实测合法最大帧 = 4000 条 timeline 的 snapshot ≈ 7.4MB（本机 164MB 会话），
+        // 若把超限单帧也断线，客户端重连后会再次拉到同一帧 → 重连死循环，比 OOM 更糟。
+        // 因此：单帧自身越顶 → 照发（它是唯一副本）+ 告警；积压+新帧越顶 → 断线重连自愈。
+        const payloadBytes = Buffer.byteLength(payload);
+        if (payloadBytes > this.hardLimitBytes) {
+            console.warn(`[maestro-mobile] ws oversized required frame client=${client.id} kind=${kind} bytes=${payloadBytes} limit=${this.hardLimitBytes} (sent anyway; data-layer budget is separate concern)`);
+            return this.rawSend(client, payload);
+        }
+        if (buffered + payloadBytes > this.hardLimitBytes) {
+            // 硬顶：无论何种投递都先断线；required 走到这里绝不静默丢数据（断线重连才是既定自愈路径）
+            console.warn(`[maestro-mobile] ws buffer hard limit client=${client.id} remote=${this.remoteOf(client.ws)} buffered=${buffered} frame=${payloadBytes} → close(1013)`);
+            this.closeClient(client, "slow_consumer");
+            return false;
+        }
+        if (buffered >= this.highWaterMarkBytes) {
+            if (delivery === "best_effort") {
+                client.droppedFrames++;
+                const now = Date.now();
+                if (now - client.lastDropLogAt >= MobileHostServer.DROP_LOG_INTERVAL_MS) {
+                    client.lastDropLogAt = now;
+                    console.warn(`[maestro-mobile] ws slow consumer client=${client.id} remote=${this.remoteOf(client.ws)} buffered=${buffered} droppedSinceLastLog (best_effort frames, continuing)`);
+                }
+                return false;
+            }
+            if (!client.slowSince) {
+                client.slowSince = Date.now();
+            }
+            else if (Date.now() - client.slowSince >= this.slowGraceMs) {
+                // required 帧无法送达：与其默默丢，不如在可重连边界上断线（1013 = retryable，与满载拒绝同码）
+                console.warn(`[maestro-mobile] ws slow consumer exceeded grace client=${client.id} remote=${this.remoteOf(client.ws)} buffered=${buffered} → close(1013)`);
+                this.closeClient(client, "slow_consumer");
+            }
+            // 宽限期内：不丢、不断，交给 ws 内部缓冲（软/硬双阈值 + 5s 宽限，驻留有界）
+            return this.rawSend(client, payload);
+        }
+        client.slowSince = 0;
+        return this.rawSend(client, payload);
+    }
+    rawSend(client, payload) {
+        // 关闭可能就在本次 sendFrame 判定内发生（硬顶/宽限到期）：此时不得再写，
+        // 否则「已判定必须送达」的那一帧反而静默丢失（ws 对 CLOSING 只累加计数不报错）。
+        if (client.closing)
+            return false;
+        try {
+            client.ws.send(payload);
+            return true;
+        }
+        catch (error) {
+            // 理论上仅 CONNECTING 态会同步抛（服务端不可达）；保留隔离防未来分支变化
+            console.error(`[maestro-mobile] ws send threw client=${client.id}:`, error instanceof Error ? error.message : error);
+            this.closeClient(client, "send_failed");
+            return false;
+        }
+    }
+    /**
+     * 幂等关闭：只由首个调用者真正关。默认 graceful close（让 close 帧送达，客户端能看到 1013/reason）；
+     * ws 内部已在协议错误路径自行发过 close 帧（receiverOnError），重复 close 无副作用。
+     * heartbeat_lost/ping_failed 等对端已死的场景直接 terminate 强制拆。
+     */
+    closeClient(client, reason) {
+        if (client.closing)
+            return;
+        client.closing = true;
+        this.clients.delete(client);
+        try {
+            if (reason === "heartbeat_lost" || reason === "ping_failed" || reason === "send_failed") {
+                client.ws.terminate();
+            }
+            else {
+                client.ws.close(1013, reason);
+                // graceful close 对端不应答时不等≈30s closeTimeout：2s 后强制拆
+                setTimeout(() => {
+                    try {
+                        client.ws.terminate();
+                    }
+                    catch { /* 已清理 */ }
+                }, 2_000).unref?.();
+            }
+        }
+        catch (error) {
+            console.error(`[maestro-mobile] ws close failed client=${client.id} reason=${reason}:`, error instanceof Error ? error.message : error);
+        }
+    }
     listen(port, hostname = "0.0.0.0") {
         this.boundHost = hostname;
-        return new Promise((resolve) => {
-            this.server.listen(port, hostname, () => resolve());
+        return new Promise((resolve, reject) => {
+            // EADDRINUSE / EACCES / 非法绑定地址都以 server 的 error 事件产生。此前无监听者：
+            // 该 Promise 永不 settle，错误以 uncaughtException 裸崩（而此时 cli 的 handler 尚未注册）。
+            this.listenError = reject;
+            this.server.listen(port, hostname, () => {
+                this.listenError = undefined;
+                // 心跳必须在绑定成功后启动：放在 listen() 之前时，EADDRINUSE 会留下一个无人 cleanup 的 interval，
+                // 且同实例重试 listen() 会覆盖 heartbeatTimer，使 close() 只能清最后一个。
+                this.startHeartbeat(this.options.heartbeatIntervalMs ?? 30_000);
+                resolve();
+            });
         });
     }
     address() {
@@ -88,12 +312,30 @@ export class MobileHostServer {
         return { port: address.port };
     }
     async close() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined; // 必须置空：否则幂等守卫会阻止下次 listen() 重启心跳
+        }
         this.unsubscribeController?.();
         for (const client of this.clients) {
             client.ws.close();
         }
         this.clients.clear();
         this.webSocketServer.close();
+        // 失联/半开连接的 graceful close 帧无应答，wss.close 会等 ws 内部≈30s closeTimeout：
+        // 优雅等待有界（3s），超时后强拆残留 socket，shutdown 不再悬挂。
+        await new Promise((resolve) => {
+            const forceSockets = () => {
+                for (const socket of this.webSocketServer.clients) {
+                    try {
+                        socket.terminate();
+                    }
+                    catch { /* 已断开 */ }
+                }
+            };
+            const timer = setTimeout(() => { forceSockets(); resolve(); }, 3_000);
+            this.webSocketServer.once("close", () => { clearTimeout(timer); resolve(); });
+        });
         await new Promise((resolve, reject) => {
             this.server.close((error) => (error ? reject(error) : resolve()));
         });
@@ -256,7 +498,26 @@ export class MobileHostServer {
             this.webSocketServer.emit("connection", ws, request);
         });
     }
-    /** WS 握手 Origin 白名单：loopback 变体 + 绑定 host（非 0.0.0.0 时）+ 显式配置 */
+    /**
+     * WS 握手 Origin 白名单：scheme 限定 + loopback 变体 + 绑定 host（非 0.0.0.0 时）
+     * + 同源 Host 头 + 显式配置。
+     *
+     * ISS-20260910-005 收紧（以下均为实测 new URL() 行为，非推断）：
+     *  1. scheme 必须落在 http/https/ws/wss：旧实现完全不看 protocol，
+     *     `file://`、`data:` 等只要 hostname 对上就放行。
+     *  2. 同源比较改用 parsed.host。旧写法 `${hostname}:${parsed.port}` 在无端口时
+     *     产生尾冒号（`new URL("http://192.168.1.10").port === ""`）⇒ 永不匹配，
+     *     是无效果死比较。parsed.host 已含非默认端口、并规范掉默认端口
+     *     （`https://a.example:443`.host === "a.example"），语义止于「主机+非默认端口」。
+     *  3. allowedOrigins 支持两种写法：完整 URL（可精确到端口）或裸 hostname。
+     *     旧实现用 new URL(o) 解析，而 `new URL("trusted.example.com")` 抛错 ⇒ 该配置
+     *     静默永不生效（只能配成完整 URL 才有效），属配置陷阱。
+     *
+     * 不变的两条（刻意的宽松，改它们会锁死现有使用）：
+     *  - 无 Origin 一律放行（:552 原样保留）：RN/原生客户端不发 Origin，仍有 token 把关。
+     *  - loopback 与 boundHost 分支只看 hostname、忽略 port：本地开发页面常在随机端口
+     *    （http://localhost:3000 连 4739 的 host），纳port 比较会直接打断现有用法。
+     */
     isOriginAllowed(origin, requestHost = "") {
         if (!origin)
             return true; // 非浏览器客户端
@@ -267,29 +528,64 @@ export class MobileHostServer {
         catch {
             return false;
         }
+        // scheme 限定：Origin 只可能是页面来源（http/https）或原生客户端回填的 WS URL 自身（ws/wss）
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:"
+            && parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+            return false;
+        }
         const hostname = parsed.hostname.toLowerCase();
+        const originHost = parsed.host.toLowerCase(); // hostname + 非默认端口（无端口时即 hostname）
         if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]") {
             return true;
         }
         // 原生客户端（React Native OkHttp 等）会把 Origin 设为 WS URL 自身（= 本机地址）。
         // 这类请求 host 头与 origin 同源，放行；浏览器跨站 drive-by 的 origin 不会等于本机地址。
+        // 只比 originHost：实测 new URL("http://[::1]:80").hostname 已带方括号，
+        // 再拼 `[${hostname}]` 会得到 `[[::1]]` ⇒ 永不匹配（同族死比较，已删除）；
+        // 而 hostHeader === hostname 也冗余（无端口时 parsed.host 本来就 === hostname）。
         const hostHeader = requestHost.toLowerCase();
-        if (hostHeader && (hostHeader === hostname || hostHeader === `${hostname}:${parsed.port}`)) {
+        if (hostHeader && hostHeader === originHost) {
             return true;
         }
         const bound = this.boundHost.toLowerCase();
-        if (bound !== "0.0.0.0" && bound !== "::" && hostname === bound) {
+        if (bound !== "0.0.0.0" && bound !== "::" && bareHost(hostname) === bareHost(bound)) {
+            // IPv6 归一：boundHost 来自 server.address()/命令行（无括号），Origin 的 hostname 带括号
             return true;
         }
         const allowed = this.options.allowedOrigins ?? [];
-        return allowed.some((o) => {
-            try {
-                return new URL(o).hostname.toLowerCase() === hostname;
+        return allowed.some((o) => this.matchesAllowedOrigin(o, hostname, parsed.port));
+    }
+    /**
+     * 白名单条目匹配：借助标准 new URL() 归一化解析 scheme/host/port。
+     * 裸 hostname 或未带 scheme 的写法统一垫入 "http://" 代理解析，避免易碎的手工切片。
+     */
+    matchesAllowedOrigin(configured, hostname, originPort) {
+        const entry = configured.trim().toLowerCase();
+        if (!entry)
+            return false;
+        let urlStr = entry;
+        if (!urlStr.includes("://")) {
+            const colons = (urlStr.match(/:/g) || []).length;
+            if (colons > 1 && !urlStr.startsWith("[")) {
+                urlStr = `http://[${urlStr}]`;
             }
-            catch {
-                return false;
+            else {
+                urlStr = `http://${urlStr}`;
             }
-        });
+        }
+        try {
+            const u = new URL(urlStr);
+            const entryHost = bareHost(u.hostname);
+            const entryPort = u.port || undefined; // 默认端口规范化为空串即 undefined
+            if (entryHost !== bareHost(hostname))
+                return false;
+            if (entryPort !== undefined && entryPort !== originPort)
+                return false;
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     // ── WS 命令 ───────────────────────────────────────────────────────────────
     async handleClientMessage(client, data) {
@@ -298,19 +594,38 @@ export class MobileHostServer {
             command = JSON.parse(data.toString());
         }
         catch {
-            client.ws.send(JSON.stringify({ type: "error", code: "invalid_json", message: "Invalid JSON" }));
+            // seq 是 HostEvent 必填字段（protocol.ts:336），且客户端 host-client.ts:255 只派发
+            // typeof seq === "number" 的帧——缺 seq 会使本错误帧被客户端丢弃。与 :173-174 握手帧同用 0
+            // （已核：全客户端域无任何 seq 数值比较，0 不干扰回放语义）。
+            // 不进 EventLog：那是跳连接增量回放日志，单连接协议层错误不应回放给其他客户端。
+            this.sendFrame(client, { type: "error", code: "invalid_json", message: "Invalid JSON", seq: 0 }, "required", "error");
             return;
         }
         // P3-2：分发前真正走 shared 校验（激活 validation 模块，拦截缺 type 的任意载荷）
         try {
             command = validateClientCommand(command);
         }
-        catch {
-            client.ws.send(JSON.stringify({ type: "error", code: "invalid_command", message: "Invalid ClientCommand: missing type" }));
+        catch (error) {
+            // JSON 已解析成功→可取 id：必须回 command_result 而非裸 error 事件，
+            // 否则客户端 pendingCommands 匹配不到，该命令挂满 30s 超时
+            const rawId = command?.id;
+            const replyTo = typeof rawId === "string" ? rawId : "";
+            // 文案跟随实际拒因（缺 type / id 非 string），不再硬编码 “missing type” 误报
+            const reason = error instanceof Error ? error.message : "Invalid ClientCommand";
+            this.sendFrame(client, {
+                type: "command_result",
+                in_reply_to: replyTo,
+                ok: false,
+                error: { code: "invalid_command", message: reason },
+            }, "required", "command_result");
             return;
         }
         try {
             switch (command.type) {
+                case "ping": {
+                    this.sendAck(client, command, { pong: true });
+                    break;
+                }
                 case "list_live_sessions": {
                     const list = await this.controller.listLiveSessions();
                     this.sendAck(client, command, list);
@@ -319,7 +634,7 @@ export class MobileHostServer {
                 case "load_more_history": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     const result = await runner.loadMoreHistory(command.count);
@@ -329,17 +644,20 @@ export class MobileHostServer {
                 case "search_history": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
-                    const result = await runner.searchHistory(command.keyword, command.maxResults, command.previewLength);
+                    // 服务端硬上限：客户端可传任意值（全扫 165MB 会话 + 无界结果集），不信任入参
+                    const maxResults = clampCommandInt(command.maxResults, 50, MAX_SEARCH_RESULTS);
+                    const previewLength = clampCommandInt(command.previewLength, 120, MAX_SEARCH_PREVIEW_LENGTH);
+                    const result = await runner.searchHistory(command.keyword, maxResults, previewLength);
                     this.sendAck(client, command, result);
                     break;
                 }
                 case "list_models": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     const models = typeof runner.listModels === "function" ? runner.listModels() : [];
@@ -349,7 +667,7 @@ export class MobileHostServer {
                 case "list_skills": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     // 优先走 SDK resourceLoader（与 TUI 一致），回退到文件扫描
@@ -375,7 +693,7 @@ export class MobileHostServer {
                 case "set_model": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     if (typeof runner.setModel !== "function") {
@@ -389,7 +707,7 @@ export class MobileHostServer {
                 case "set_thinking": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     if (typeof runner.setThinking !== "function") {
@@ -403,7 +721,7 @@ export class MobileHostServer {
                 case "compact": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     if (typeof runner.compact !== "function") {
@@ -417,7 +735,7 @@ export class MobileHostServer {
                 case "rename_session": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     if (typeof runner.renameSession !== "function") {
@@ -450,7 +768,7 @@ export class MobileHostServer {
                 case "prompt": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     // P1-3：透传图片（此前被静默丢弃），非法元素显式报错而非静默丢失
@@ -459,14 +777,31 @@ export class MobileHostServer {
                         this.sendError(client, "invalid_image", "images 元素必须是 base64 data 与 mime 字段齐全的图片", command.id ?? "");
                         break;
                     }
-                    await runner.prompt(command.message, undefined, images);
-                    this.sendAck(client, command, {});
+                    // 方案 A 双端实时协同：
+                    // 1. 优先检查当前会话所在的 cwd 是否正是当前桌面活跃的 TUI 窗口（通过 workspace-telemetry）
+                    // 2. 如果是当前活跃桌面窗口，通过 teammate 跨进程信箱直接注入 steer 到桌面终端！
+                    //    桌面终端屏幕立刻打字动起来并回答，写盘后由 Watcher 实时推回手机，实现真正的同屏双向同步！
+                    // 3. 如果当前没有活跃桌面窗口，或者会话已在流式生成中，走已有 runner 驱动逻辑。
+                    const activeTuiOwner = await this.controller.findActiveOwnerForCwd(runner.state.cwd);
+                    let injectedToTui = false;
+                    if (activeTuiOwner && (!images || images.length === 0)) {
+                        injectedToTui = await injectMessageToActiveTui(activeTuiOwner, command.message);
+                    }
+                    if (!injectedToTui) {
+                        if (runner.state.runState === "streaming") {
+                            await runner.steer(command.message);
+                        }
+                        else {
+                            await runner.prompt(command.message, undefined, images);
+                        }
+                    }
+                    this.sendAck(client, command, { injectedToTui });
                     break;
                 }
                 case "steer": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     await runner.steer(command.message);
@@ -496,7 +831,7 @@ export class MobileHostServer {
                 case "follow_up": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     await runner.followUp(command.message);
@@ -506,7 +841,7 @@ export class MobileHostServer {
                 case "abort": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     await runner.abort();
@@ -519,7 +854,7 @@ export class MobileHostServer {
                         this.sendAck(client, command, {});
                     }
                     else {
-                        this.sendError(client, "request_not_found", command.id ?? "");
+                        this.sendError(client, "request_not_found", undefined, command.id ?? "");
                     }
                     break;
                 }
@@ -537,22 +872,22 @@ export class MobileHostServer {
                 case "get_snapshot": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     const snapshot = runner.snapshot();
-                    client.ws.send(JSON.stringify({
+                    this.sendFrame(client, {
                         type: "command_result",
                         in_reply_to: command.id ?? "",
                         ok: true,
                         result: snapshot,
-                    }));
+                    }, "required", "command_result");
                     break;
                 }
                 case "get_session_usage": {
                     const runner = this.controller.getSession(command.sessionId);
                     if (!runner) {
-                        this.sendError(client, "session_not_found", command.id ?? "");
+                        this.sendError(client, "session_not_found", undefined, command.id ?? "");
                         break;
                     }
                     const usage = typeof runner.getUsage === "function" ? await runner.getUsage() : { entries: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, totalTokens: 0, cost: 0 };
@@ -561,30 +896,75 @@ export class MobileHostServer {
                     break;
                 }
                 default:
-                    this.sendError(client, "unsupported_command", command.id ?? "");
+                    this.sendError(client, "unsupported_command", undefined, command.id ?? "");
             }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            this.sendError(client, "command_failed", message);
+            // 必须带 in_reply_to：客户端靠它匹配 pendingCommands，空值会让命令挂满 30s 超时
+            this.sendError(client, "command_failed", message, command.id ?? "");
         }
     }
     sendAck(client, command, result) {
-        client.ws.send(JSON.stringify({
+        this.sendFrame(client, {
             type: "command_result",
             in_reply_to: command.id ?? "",
             ok: true,
             result,
-        }));
+        }, "required", "command_result");
     }
     sendError(client, code, message, replyTo = "") {
-        client.ws.send(JSON.stringify({
+        this.sendFrame(client, {
             type: "command_result",
             in_reply_to: replyTo,
             ok: false,
-            error: { code, message: message ?? code },
-        }));
+            // 回传网络的唯一脉络：必须带上本实例 token 作为已知密串（底层错误文本可能回显含 ?token= 的 URL）
+            error: { code, message: message ? sanitizeWsErrorMessage(message, [this.options.token ?? ""]) : code },
+        }, "required", "command_result");
+    }
+}
+const MAX_SEARCH_RESULTS = 200;
+const MAX_SEARCH_PREVIEW_LENGTH = 400;
+/**
+ * 命令参数钳制（导出以供回归测试直接钉本函数，避免测试复制一份算式假通过）：
+ * 非有限值（NaN/Infinity/null/字符串形态）落默认值，有限值夹到 [1, max]。
+ */
+export function clampCommandInt(raw, dflt, max) {
+    return Number.isFinite(raw) ? Math.min(Math.max(1, Math.floor(raw)), max) : dflt;
+}
+/**
+ * 去 IPv6 方括号。实测 new URL("http://[::1]:80").hostname === "[::1]"（带括号），
+ * 而 server.address().address / 命令行传入的绑定地址不带括号，两侧必须归一后才能比较。
+ */
+function bareHost(host) {
+    return host.replace(/^\[(.*)\]$/, "$1");
+}
+/**
+ * WS/日志/响应用错误文本脱敏：限长 + 去换行 + 抹掉已知敏感根。
+ * 背景：command_failed 曾把底层 fs/SDK 的 Error.message（含用户目录绝对路径）原样回传网络。
+ *
+ * 设计：只替换「已知敏感值」（token 本体、home 目录、cwd、盘符路径），不用泛用正则猜“这段像不像路径”——
+ * 后者会把 `/api/v1/users`、`http://host/api/v1` 这类诊断信息误删（独立评审 RV-002）。
+ * 完整堆栈只进服务端日志的结构化字段，不经此函数回传客户端。
+ */
+export function sanitizeWsErrorMessage(raw, secrets = []) {
+    if (!raw)
+        return "";
+    let out = raw.replace(/[ \t\r\n]+/g, " ").slice(0, 200);
+    // 1) 显式已知密串（如本实例 token）：只要出现在文本里就抹掉，不限形态
+    for (const secret of secrets) {
+        if (secret && secret.length >= 8)
+            out = out.split(secret).join("[redacted]");
+    }
+    // 2) 用户主目录与进程 cwd：局域网工具里这两个值会泄露用户名/项目位置
+    for (const root of [homedir(), process.cwd()]) {
+        if (root && root.length > 1)
+            out = out.split(root).join("~");
     }
+    // 3) Windows 盘符路径形态无歧义，可直接折叠到文件名。负向后顾防 URL scheme 误伤：
+    //    "http://host/x" 里的 p:// 会被 [A-Za-z]:[\/] 命中，但它前面是字母 t → 排除
+    out = out.replace(/(?<![A-Za-z0-9])[A-Za-z]:[\\/][^\s"']*/g, (m) => m.split(/[\\/]/).filter(Boolean).pop() ?? "[path]");
+    return out;
 }
 function writeJson(response, status, body) {
     response.writeHead(status, {