pi-web-ui 0.22.0 → 0.23.0

package/README.md

@@ -68,8 +68,31 @@ pi-web-ui server stop                       # stop (auto-start stays)
 pi-web-ui server start                      # start again
 pi-web-ui server uninstall                  # remove the service entirely
 pi-web-ui server shortcut                   # desktop one-click launch icon
+pi-web-ui server quiesce                    # drain: refuse NEW chats/messages, let running ones finish
+pi-web-ui server unquiesce                  # reopen admission
 ```
 
+`server status` also shows live stats via a local control socket (version,
+PID, quiesce state, connected browsers, running conversations) — the same
+socket drives `quiesce`/`unquiesce`.
+
+## Security
+
+- **Loopback-only by default** — the server binds `127.0.0.1` and is not
+  reachable from the network unless you explicitly set `PI_WEB_HOST=0.0.0.0`
+  (e.g. LAN access, Docker port mapping — the compose file sets it for you).
+- **WebSocket origin check** — browser pages connecting to `/ws` must present
+  an `Origin` whose hostname **and port** match the request `Host`;
+  cross-origin pages are rejected with 403. Non-browser clients (no `Origin`)
+  are unaffected. Add `PI_WEB_ALLOW_ORIGINS=http://your-host:port` for
+  reverse-proxy setups.
+- **Quiesce** — `server quiesce` refuses new prompts/forks/session resumes
+  until you `server unquiesce`; in-flight runs finish cleanly (useful before
+  upgrades/backups).
+- **Credentials stay server-side** — provider `headers` (which may carry
+  `Authorization` / API keys) are never sent to the browser; the model
+  management UI edits everything else and the server preserves the headers.
+
 - **macOS** → launchd agent (no sudo), logs to `/tmp/pi-web-ui.log` / `.err`
 - **Linux** → systemd unit (`systemctl enable --now`), logs via `journalctl -u pi-web-ui -f`
 - **Windows** → Task Scheduler logon task (hidden PowerShell window, no black console)

package/README.zh-CN.md

@@ -64,8 +64,25 @@ pi-web-ui server stop                       # 停止（开机自启保留）
 pi-web-ui server start                      # 再次启动
 pi-web-ui server uninstall                  # 彻底移除服务
 pi-web-ui server shortcut                   # 桌面一键启动图标
+pi-web-ui server quiesce                    # 排空：拒绝新的对话/消息，存量运行继续跑完
+pi-web-ui server unquiesce                  # 解除排空，恢复接收新工作
 ```
 
+`server status` 还会经本地控制 socket 显示实时状态（版本、PID、排空状态、
+浏览器连接数、运行中对话数）——`quiesce`/`unquiesce` 也走同一个 socket。
+
+## 安全
+
+- **默认只绑 loopback** —— 服务器只监听 `127.0.0.1`，不暴露到网络；需要局域网访问或
+  Docker 端口映射时显式设置 `PI_WEB_HOST=0.0.0.0`（docker-compose.yml 已内置）。
+- **WebSocket Origin 校验** —— 浏览器页面连 `/ws` 时其 Origin 的 hostname **和端口**
+  必须与请求 Host 一致，跨源页面直接 403；无 Origin 的非浏览器客户端不受影响。
+  反向代理场景可用 `PI_WEB_ALLOW_ORIGINS=http://你的域名:端口` 放行。
+- **Quiesce 排空** —— `server quiesce` 后拒绝新的 prompt/编辑重问/会话恢复，存量运行
+  跑完为止（升级/备份前用）；`server unquiesce` 恢复。
+- **凭据不下发浏览器** —— provider 的 `headers`（可能含 Authorization / API key）
+  永不发给浏览器；模型管理 UI 编辑其他字段，服务端自动保留 headers。
+
 - **macOS** → launchd 代理（无需 sudo），日志 `/tmp/pi-web-ui.log` / `.err`
 - **Linux** → systemd unit（`systemctl enable --now`），日志 `journalctl -u pi-web-ui -f`
 - **Windows** → 计划任务（登录自启，隐藏 PowerShell 窗口，无黑窗）

package/bin/pi-web-ui.mjs

@@ -23,6 +23,7 @@
  * PI_CODING_AGENT_DIR。
  */
 import { spawnSync } from "node:child_process";
+import { createConnection } from "node:net";
 import { get as httpGet } from "node:http";
 import {
 	chmodSync,
@@ -60,6 +61,8 @@ const HELP = `pi-web-ui v${pkg.version} — web chat for the pi coding agent
   pi-web-ui server shortcut [选项]        在桌面创建「一键启动」图标（启动服务并打开浏览器）
   pi-web-ui server uninstall [选项]       卸载系统服务（同时移除桌面图标）
   pi-web-ui server start|stop|restart|status [选项]
+  pi-web-ui server quiesce [选项]          进入排空模式：拒绝新的对话/消息/编辑，存量运行继续跑完
+  pi-web-ui server unquiesce [选项]        解除排空模式，恢复接收新工作
   pi-web-ui --version / --help
 
 server 选项:
@@ -1069,6 +1072,90 @@ function uninstallWindows(opts) {
 	console.log(`🗑  已移除桌面快捷方式`);
 }
 
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Local control socket (status / quiesce / unquiesce). The server listens on
+// a mode-0600 Unix socket (POSIX) or a named pipe (Windows) under its data
+// dir; same path rules as server/control-socket.ts so the CLI and server
+// always agree without sharing code.
+// ---------------------------------------------------------------------------
+
+/** Resolve the control socket path for the given options. */
+function controlPath(opts) {
+	const dir = opts.dataDir
+		? resolve(opts.dataDir)
+		: process.env.PI_WEB_DATA_DIR
+			? resolve(process.env.PI_WEB_DATA_DIR)
+			: join(homedir(), ".pi-web");
+	return isWin
+		? `\\\\.\\pipe\\pi-web-ui-${String(opts.port ?? process.env.PORT ?? "8787")}`
+		: join(dir, "pi-web-ui.sock");
+}
+
+/** Send one control command to a RUNNING server; resolves null if unreachable. */
+function controlCommand(opts, cmd) {
+	const path = controlPath(opts);
+	return new Promise((resolvePromise) => {
+		const sock = createConnection(path);
+		let done = false;
+		const finish = (v) => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			sock.destroy();
+			resolvePromise(v);
+		};
+		const timer = setTimeout(() => finish(null), 3000);
+		let buf = "";
+		sock.on("connect", () => sock.write(JSON.stringify({ cmd }) + "\n"));
+		sock.on("data", (chunk) => {
+			buf += chunk.toString("utf8");
+			const nl = buf.indexOf("\n");
+			if (nl >= 0) {
+				try {
+					finish(JSON.parse(buf.slice(0, nl)));
+				} catch {
+					finish(null);
+				}
+			}
+		});
+		sock.on("error", () => finish(null));
+		sock.on("close", () => finish(null));
+	});
+}
+
+/** Append the live server status (via the control socket) to `server status`. */
+async function printLiveStatus(opts) {
+	const st = await controlCommand(opts, "status");
+	if (!st || !st.ok) {
+		console.log("   (服务器未运行或控制通道不可达 — 启动后可查 server status 实时信息)");
+		return;
+	}
+	console.log("   --- 实时状态 (control socket) ---");
+	console.log(`   版本 : ${st.version} · PID ${st.pid}`);
+	console.log(`   目录 : ${st.cwd}`);
+	console.log(
+		`   排空 : ${st.quiesced ? `是（自 ${new Date(st.quiescedSince).toLocaleString()}）` : "否"}`,
+	);
+	console.log(
+		`   连接 : ${st.connectedClients} 个浏览器 · ${st.activeConversations} 个运行中对话 · ${st.pendingMessages} 条排队消息`,
+	);
+}
+
+/** `server quiesce|unquiesce` — toggle the admission gate on a RUNNING server. */
+async function setQuiesce(opts, on) {
+	const st = await controlCommand(opts, on ? "quiesce" : "unquiesce");
+	if (!st || !st.ok) {
+		fail(`服务器未运行或控制通道不可达（${controlPath(opts)}）`);
+	}
+	console.log(
+		on
+			? "⏸  已进入排空模式（quiesce）：拒绝新的对话/消息/编辑，存量运行继续跑完。\n" +
+				"    跑完后用 pi-web-ui server unquiesce 恢复。"
+			: "▶  已解除排空模式（unquiesce）：恢复接收新的对话/消息/编辑。",
+	);
+}
+
 function controlService(action, opts) {
 	const name = opts.name ?? "pi-web-ui";
 
@@ -1279,12 +1366,21 @@ async function serverCmd(argv) {
 		case "start":
 		case "stop":
 		case "restart":
-		case "status":
 			controlService(action, opts);
 			break;
+		case "status":
+			controlService("status", opts);
+			await printLiveStatus(opts);
+			break;
+		case "quiesce":
+			await setQuiesce(opts, true);
+			break;
+		case "unquiesce":
+			await setQuiesce(opts, false);
+			break;
 		default:
 			fail(
-				`未知操作: ${action}（install / shortcut / uninstall / start / stop / restart / status）`,
+				`未知操作: ${action}（install / shortcut / uninstall / start / stop / restart / status / quiesce / unquiesce）`,
 			);
 	}
 }

package/dist/server/agent-service.js

@@ -14,7 +14,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createLocalBashOperations, defineTool, getAgentDir, ModelRuntime, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
@@ -23,6 +23,18 @@ const WIDGET_REFRESH_MS = 2000;
 const WIDGET_WIDTH = 80;
 /** Preview panel cap: only the first 512KB of a file is ever read/sent. */
 const MAX_PREVIEW_BYTES = 512 * 1024;
+/** Thrown when the service is quiesced (draining) and the request is NEW work
+ *  the admission controller refuses: a brand-new client attach, a prompt,
+ *  a fork, a session resume, or a goal wizard start. index.ts closes the
+ *  WebSocket with 4403 so the browser reconnect loop can retry after the
+ *  server reopens admission (see AgentService.quiesce). */
+export class QuiesceRejectedError extends Error {
+    code = "QUIESCED";
+    constructor(detail) {
+        super(`服务器正在排空存量工作（quiesce）——${detail}`);
+        this.name = "QuiesceRejectedError";
+    }
+}
 const PREVIEW_IMAGE_EXTS = new Set([
     "png",
     "jpg",
@@ -931,6 +943,9 @@ function conversationTitle(session) {
 }
 export class ClientSession {
     clientId;
+    /** Set by AgentService.attach: reflects the SERVICE-wide quiesce flag
+     *  (server draining — new work rejected). Default false for direct use. */
+    isQuiesced = () => false;
     cwd;
     /** pi config dir (auth/models/skills). */
     agentDir;
@@ -2042,7 +2057,8 @@ export class ClientSession {
                 baseUrl: p.baseUrl,
                 apiKey: p.apiKey,
                 authHeader: p.authHeader,
-                headers: p.headers,
+                // headers are intentionally NOT sent to the browser — they may
+                // contain Authorization / API-key values; kept server-side only.
                 models,
             };
         });
@@ -2075,14 +2091,17 @@ export class ClientSession {
         }
         try {
             const { providers } = this.readModelsConfig();
+            // headers never reach the browser, so the incoming config can't carry
+            // them — preserve the previously stored values when they are absent.
+            const prevHeaders = providers[pid]?.headers;
             providers[pid] = {
                 ...(config.name?.trim() ? { name: config.name.trim() } : {}),
                 ...(config.api?.trim() ? { api: config.api.trim() } : {}),
                 ...(config.baseUrl?.trim() ? { baseUrl: config.baseUrl.trim() } : {}),
                 ...(config.apiKey?.trim() ? { apiKey: config.apiKey.trim() } : {}),
                 ...(config.authHeader ? { authHeader: true } : {}),
-                ...(config.headers && Object.keys(config.headers).length > 0
-                    ? { headers: config.headers }
+                ...(prevHeaders && Object.keys(prevHeaders).length > 0
+                    ? { headers: prevHeaders }
                     : {}),
                 models,
             };
@@ -2572,6 +2591,44 @@ export class ClientSession {
     // ---------------------------------------------------------------------------
     // Commands
     // ---------------------------------------------------------------------------
+    /** True when the service is draining (quiesced): emits a rejection notice
+     *  and returns true. Guards every NEW-work entry point (prompt / new chat /
+     *  edit-resend / session resume / goal wizard) — existing runs keep going.
+     *  Called BEFORE any LLM/token work starts so quiesce is a hard admission
+     *  gate, not a best-effort hint. */
+    quiesceBlocked() {
+        if (!this.isQuiesced())
+            return false;
+        this.emit({
+            type: "notice",
+            level: "error",
+            text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-web-ui server unquiesce 可恢复。",
+        });
+        this.flushSnapshot();
+        return true;
+    }
+    /** Conversations with an in-flight run — active work for quiesce status. */
+    activeConversations() {
+        let n = 0;
+        for (const c of this.convs.values()) {
+            try {
+                if (c.session.isStreaming)
+                    n += 1;
+            }
+            catch {
+                // session being replaced — not running
+            }
+        }
+        return n;
+    }
+    /** Messages queued in the SDK (steer + follow-up) — pending work for
+     *  quiesce status. Quiesce refuses to add more, so this only drains. */
+    pendingMessages() {
+        let n = 0;
+        for (const c of this.convs.values())
+            n += c.queueFollowUp + c.queueSteering;
+        return n;
+    }
     async prompt(text, attachments) {
         try {
             const s = this.session;
@@ -2583,6 +2640,11 @@ export class ClientSession {
                 this.flushSnapshot();
                 return;
             }
+            // Native commands above are pure config tweaks (no tokens) — allow them
+            // even while quiesced. Everything that reaches the SDK is NEW work and
+            // is refused until admission reopens.
+            if (this.quiesceBlocked())
+                return;
             // Attach files as independent nextTurn context messages (asides) so the
             // user message stays clean; they render as separate attachment cards.
             const asides = await this.buildAttachmentMessages(attachments);
@@ -3255,6 +3317,8 @@ export class ClientSession {
         }
     }
     async newChat() {
+        if (this.quiesceBlocked())
+            return;
         // Reuse an already-open blank conversation instead of piling up new ones
         // on every click: if the active chat has no messages it IS the new chat
         // (focus already on it); otherwise switch to the first blank one (under
@@ -3438,6 +3502,8 @@ export class ClientSession {
     }
     /** Switch the active session to a persisted one (from listSessions). */
     async switchSession(path) {
+        if (this.quiesceBlocked())
+            return;
         try {
             await this.runtime.switchSession(path);
             await this.bindSession();
@@ -3496,6 +3562,8 @@ export class ClientSession {
      * session list, so nothing is ever lost.
      */
     async editMessage(messageId, text) {
+        if (this.quiesceBlocked())
+            return;
         const trimmed = text.trim();
         if (!trimmed) {
             this.emit({
@@ -4035,6 +4103,8 @@ export class ClientSession {
      * Mutually exclusive with the review loop.
      */
     async startGoalWizard(text, opts) {
+        if (this.quiesceBlocked())
+            return;
         const draft = (text ?? "").trim();
         if (!draft)
             return;
@@ -4726,6 +4796,15 @@ export class ClientSession {
 export class AgentService {
     cwd;
     clients = new Map();
+    /** Quiesce (draining) state — the service refuses NEW work (prompts, forks,
+     *  session resumes, new clients) so a deploy/upgrade/backup can stop cleanly
+     *  once existing runs finish. Controlled via the local control socket:
+     *  `pi-web-ui server quiesce|unquiesce`. */
+    quiesced = false;
+    quiescedAt = 0;
+    /** Attached browser sockets (reported by index.ts on open/close) — the
+     *  control socket reports real sockets, not cached client-session objects. */
+    socketCount = 0;
     pending = new Map();
     stateStore;
     /**
@@ -4740,6 +4819,60 @@ export class AgentService {
         this.stateStore = new ClientStateStore(stateFile);
     }
     /** Get or create the session for a client, racing attach calls safely. */
+    /** True while the service is draining — new work is refused. */
+    isQuiesced() {
+        return this.quiesced;
+    }
+    /** Enter quiesce: stop admitting new work. Existing runs keep going. */
+    quiesce() {
+        this.quiesced = true;
+        this.quiescedAt = Date.now();
+    }
+    /** Leave quiesce: admit new work again. */
+    unquiesce() {
+        this.quiesced = false;
+        this.quiescedAt = 0;
+    }
+    /** Snapshot for the control socket / status command. */
+    quiesceInfo() {
+        return this.quiesced
+            ? { quiesced: true, quiescedSince: this.quiescedAt }
+            : { quiesced: false };
+    }
+    /** Aggregate across every client session: conversations with in-flight runs. */
+    activeConversations() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.activeConversations();
+        return n;
+    }
+    /** Aggregate across every client session: messages queued in the SDK. */
+    pendingMessages() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.pendingMessages();
+        return n;
+    }
+    /** index.ts calls this when a browser socket opens/closes. */
+    noteSocketOpen() {
+        this.socketCount += 1;
+    }
+    noteSocketClose() {
+        this.socketCount = Math.max(0, this.socketCount - 1);
+    }
+    /** Full status for the control socket / `server status` command. */
+    serviceStatus() {
+        return {
+            pid: process.pid,
+            version: VERSION,
+            cwd: this.cwd,
+            ...this.quiesceInfo(),
+            connectedClients: this.socketCount,
+            activeConversations: this.activeConversations(),
+            pendingMessages: this.pendingMessages(),
+        };
+    }
+    /** Get or create the session for a client, racing attach calls safely. */
     async attach(clientId, send) {
         let cs = this.clients.get(clientId);
         if (!cs) {
@@ -4749,6 +4882,13 @@ export class AgentService {
             }
             else {
                 // Restore this client's last-used workspace when it still exists;
+                // Admission gate: while quiesced, only clients with an EXISTING
+                // session may attach (they can watch their runs drain); brand-new
+                // clients are refused — index.ts closes their socket (4403) and the
+                // browser reconnect loop retries after admission reopens.
+                if (this.quiesced) {
+                    throw new QuiesceRejectedError("新连接被拒绝，请等服务器恢复后重试");
+                }
                 // otherwise fall back to the server's configured default cwd.
                 let cwd = this.cwd;
                 const saved = this.stateStore.get(clientId);
@@ -4783,6 +4923,7 @@ export class AgentService {
         // Forward hooks (set once by index.ts) to every session.
         cs.onUpdateReady = this.onUpdateReady;
         cs.onQuit = this.onQuit;
+        cs.isQuiesced = () => this.quiesced;
         return cs;
     }
     /** Remove a socket from a client's broadcast set (called on socket close). */

package/dist/server/control-socket.js

@@ -0,0 +1,177 @@
+/**
+ * Local control socket for the pi-web-ui server.
+ *
+ * Lets the CLI (and humans) query status and quiesce/unquiesce the server
+ * WITHOUT opening a network port or exposing an unauthenticated HTTP
+ * endpoint. Only the local OS user can reach it:
+ *   - POSIX: a mode-0600 Unix domain socket at <dataDir>/pi-web-ui.sock
+ *   - Windows: a named pipe  \\.\pipe\pi-web-ui-<port>
+ *
+ * Protocol: one JSON object per line.
+ *   → {"cmd":"status"}        ← {"ok":true, ...serviceStatus}
+ *   → {"cmd":"quiesce"}       ← {"ok":true}
+ *   → {"cmd":"unquiesce"}     ← {"ok":true}
+ *   → anything else           ← {"ok":false,"error":"..."}
+ *
+ * Idle connections are closed after a short timeout so a stuck CLI never
+ * holds the socket.
+ */
+import { createServer, createConnection } from "node:net";
+import { chmodSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** How long a control connection may sit idle before the server closes it. */
+const CONTROL_IDLE_TIMEOUT_MS = 5_000;
+/** How long the CLI waits for a reply before giving up. */
+const CONTROL_CLIENT_TIMEOUT_MS = 3_000;
+/** Socket path (POSIX) or pipe name (Windows). */
+export function controlPath(dataDir, port) {
+    return process.platform === "win32"
+        ? `\\\\.\\pipe\\pi-web-ui-${port}`
+        : join(dataDir, "pi-web-ui.sock");
+}
+/** Start the control socket; returns a stop function. */
+export function startControlServer(opts) {
+    const { service, dataDir, port } = opts;
+    const path = controlPath(dataDir, port);
+    let server;
+    let stop = false;
+    if (process.platform === "win32") {
+        server = createServer(handleConnection);
+    }
+    else {
+        // Remove a stale socket left by a previous crash (only if it's ours —
+        // an existing socket file that refuses connections is stale).
+        if (existsSync(path)) {
+            try {
+                rmSync(path);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        server = createServer(handleConnection);
+    }
+    // A second instance on the same data dir / port would fail to bind — don't
+    // crash the server over it, just log and run without a control socket.
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.warn(`[control] socket ${path} already in use — control socket disabled`);
+        }
+        else {
+            console.warn(`[control] socket error: ${err.message}`);
+        }
+    });
+    function handleConnection(sock) {
+        let buf = "";
+        const timer = setTimeout(() => {
+            sock.destroy();
+        }, CONTROL_IDLE_TIMEOUT_MS);
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line)
+                    continue;
+                timer.refresh();
+                let req;
+                try {
+                    req = JSON.parse(line);
+                }
+                catch {
+                    sock.write(JSON.stringify({ ok: false, error: "bad json" }) + "\n");
+                    continue;
+                }
+                let resp;
+                switch (req.cmd) {
+                    case "status":
+                        resp = { ok: true, ...service.serviceStatus() };
+                        break;
+                    case "quiesce":
+                        service.quiesce();
+                        resp = { ok: true };
+                        break;
+                    case "unquiesce":
+                        service.unquiesce();
+                        resp = { ok: true };
+                        break;
+                    default:
+                        resp = { ok: false, error: `unknown cmd: ${String(req.cmd)}` };
+                        break;
+                }
+                sock.write(JSON.stringify(resp) + "\n");
+            }
+        });
+        sock.on("error", () => {
+            /* client vanished */
+        });
+        sock.on("close", () => clearTimeout(timer));
+    }
+    if (process.platform === "win32") {
+        // net.Server on a named pipe: listen on the pipe name directly.
+        server.listen(path, () => {
+            console.log(`  control    : ${path}`);
+        });
+    }
+    else {
+        server.listen(path, () => {
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                /* best-effort */
+            }
+            console.log(`  control    : ${path}`);
+        });
+    }
+    return () => {
+        stop = true;
+        server.close();
+        try {
+            if (process.platform !== "win32" && existsSync(path))
+                rmSync(path);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+}
+/**
+ * CLI-side client: send one command and return the parsed reply (or null if
+ * the server is unreachable / timed out).
+ */
+export function sendControlCommand(dataDir, port, cmd) {
+    const path = controlPath(dataDir, port);
+    return new Promise((resolve) => {
+        const sock = createConnection(path);
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            sock.destroy();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), CONTROL_CLIENT_TIMEOUT_MS);
+        let buf = "";
+        sock.on("connect", () => {
+            sock.write(JSON.stringify({ cmd }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const nl = buf.indexOf("\n");
+            if (nl >= 0) {
+                try {
+                    finish(JSON.parse(buf.slice(0, nl)));
+                }
+                catch {
+                    finish(null);
+                }
+            }
+        });
+        sock.on("error", () => finish(null));
+        sock.on("close", () => finish(null));
+    });
+}