@zswarm/core 0.1.7 → 0.1.8

package/dist/ops/serve.js

@@ -1,18 +1,67 @@
 import { createServer, connect } from "node:net";
-import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { hostname } from "node:os";
 import { ZellijError } from "../errors.js";
-import { encodePowerShellCommand } from "../zellij/ipc.js";
+import { authorizeServeListen, SERVE_BIND_REMEDY, SERVE_BIND_VERIFY_TIMEOUT_MS, } from "./serve-bind.js";
 export const DEFAULT_SERVE_LISTEN = "127.0.0.1:9419";
 export const SERVE_TASK_NAME = "zswarm-serve";
 /** One JSONL request; a client that never sends newline cannot grow forever. */
 export const SERVE_MAX_REQUEST_BYTES = 1024 * 1024;
+/**
+ * Zellij `execFile` capture budget (`maxBuffer`). `dump --max 0` can return
+ * that much pane text; serve JSONL is UTF-8 and may expand (newlines → `\n`).
+ */
+export const SERVE_CAPTURE_BUDGET_BYTES = 8 * 1024 * 1024;
+/**
+ * Ordinary JSONL reply cap, UTF-8 bytes of the complete frame including the
+ * terminating newline. Sized for an 8MiB capture with newline escaping (2×)
+ * plus envelope slack. Not a silent truncate: over-cap fails with
+ * `serve_protocol`. Override with `ZSWARM_SERVE_MAX_REPLY_BYTES`.
+ */
+export const SERVE_MAX_REPLY_BYTES = SERVE_CAPTURE_BUDGET_BYTES * 2 + 256 * 1024;
+/** Hello is a small control reply; keep it independent of dump-sized ops. */
+export const SERVE_MAX_HELLO_BYTES = 16 * 1024;
 /** Drop a socket that never finishes a JSONL line. */
 export const SERVE_IDLE_TIMEOUT_MS = 30_000;
 /** Concurrent TCP clients, including in-flight wait ops. */
 export const SERVE_MAX_CONNECTIONS = 32;
 /** Wait/await allow 15 minutes; this is that plus slack. */
 export const SERVE_CALL_TIMEOUT_CAP_MS = 16 * 60_000;
+/** TCP connect is bounded even when the op wait budget is long. */
+export const SERVE_CONNECT_TIMEOUT_MS = 15_000;
+/** Hello probe wait is bounded within the overall deadline. */
+export const SERVE_HELLO_TIMEOUT_MS = 15_000;
+/** Wire protocol number returned by hello. */
+export const SERVE_PROTOCOL = 1;
+export const SERVE_CONTROL_FIELD = "serveControl";
+export const SERVE_HELLO_CONTROL = "hello";
+export const SERVE_CAPABILITY_HELLO = "hello";
+/** Per-launch identity for Windows install verification. Additive hello field. */
+export const SERVE_LAUNCH_ID_ENV = "ZSWARM_SERVE_LAUNCH_ID";
+/** Package version baked into the Windows logon-task command so upgrades restart. */
+export const SERVE_CORE_VERSION = readCoreVersion();
 const SERVE_TOKEN_FIELD = "serveToken";
+const CORE_VERSION = SERVE_CORE_VERSION;
+function readCoreVersion() {
+    const pkg = createRequire(import.meta.url)("../../package.json");
+    if (typeof pkg.version !== "string" || !pkg.version.trim()) {
+        throw new Error("@zswarm/core package.json is missing version");
+    }
+    return pkg.version.trim();
+}
+export const SERVE_REMEDY = {
+    connect: "Check that zswarm serve is running and the tunnel still forwards to this endpoint. Serve does not fall back to SSH.",
+    unauthorized: "Set the same ZSWARM_SERVE_TOKEN on the server and this caller.",
+    helloUnsupported: "This endpoint does not speak serve hello (protocol 1). Upgrade zswarm serve. Ordinary commands still work without probing hello first.",
+    incompatible: "This serve protocol is not supported by this client. Upgrade zswarm on both sides.",
+    protocol: "The endpoint returned a malformed or unexpected serve reply. Do not echo or retry blindly.",
+    timeoutConnect: "The TCP connection did not complete in time. Check the tunnel and that zswarm serve is listening.",
+    timeoutHello: "Connected but serve hello did not finish. Check the tunnel; do not treat this as a completed command.",
+    timeoutRequest: "The request was sent but no reply arrived. Treat the remote outcome as uncertain; do not retry automatically.",
+    incomplete: "The connection closed before a complete reply. If a request was already sent, treat the remote outcome as uncertain; do not retry automatically.",
+    cancelled: "The caller cancelled this serve call. If a request was already sent, treat the remote outcome as uncertain; do not retry automatically.",
+};
 export function isLoopbackHost(host) {
     const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
     return (h === "127.0.0.1" ||
@@ -75,6 +124,15 @@ function unauthorized() {
         },
     };
 }
+function protocolError(message) {
+    return {
+        ok: false,
+        error: {
+            code: "serve_protocol",
+            message,
+        },
+    };
+}
 function takeServeToken(args) {
     const token = typeof args[SERVE_TOKEN_FIELD] === "string"
         ? args[SERVE_TOKEN_FIELD]
@@ -83,21 +141,116 @@ function takeServeToken(args) {
     delete request[SERVE_TOKEN_FIELD];
     return { token, request };
 }
-export function startServe(listen, dispatch, options = {}) {
-    const { host, port } = parseListenAddress(listen);
-    if (!isLoopbackHost(host)) {
-        return Promise.reject(new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`));
+function helloData(serverId, launchId) {
+    const data = {
+        protocol: SERVE_PROTOCOL,
+        serverId,
+        hostname: hostname() || "unknown",
+        platform: process.platform,
+        version: CORE_VERSION,
+        capabilities: [SERVE_CAPABILITY_HELLO],
+    };
+    const id = launchId?.trim();
+    if (id)
+        data.launchId = id;
+    return data;
+}
+function isHelloOp(op) {
+    return typeof op === "string" && op.trim() === SERVE_HELLO_CONTROL;
+}
+/** Control plane after auth; never dispatches an application op for hello. */
+function handleServeControl(request, hello) {
+    const hasControl = Object.prototype.hasOwnProperty.call(request, SERVE_CONTROL_FIELD);
+    const hasOp = Object.prototype.hasOwnProperty.call(request, "op");
+    if (hasControl && hasOp) {
+        return {
+            handled: true,
+            result: protocolError("serve request cannot include both serveControl and op"),
+        };
+    }
+    if (hasControl) {
+        const control = request[SERVE_CONTROL_FIELD];
+        if (typeof control !== "string" || !control.trim()) {
+            return {
+                handled: true,
+                result: protocolError("serveControl must be a non-empty string"),
+            };
+        }
+        const name = control.trim();
+        if (name !== SERVE_HELLO_CONTROL) {
+            return {
+                handled: true,
+                result: protocolError(`unknown serve control (${name})`),
+            };
+        }
+        return {
+            handled: true,
+            result: { ok: true, data: { ...hello, capabilities: [...hello.capabilities] } },
+        };
+    }
+    if (isHelloOp(request.op)) {
+        return {
+            handled: true,
+            result: { ok: true, data: { ...hello, capabilities: [...hello.capabilities] } },
+        };
     }
+    return { handled: false };
+}
+export async function startServe(listen, dispatch, options = {}) {
+    const { host, port } = parseListenAddress(listen);
+    // Token and basic input before any Tailscale CLI / listen effects.
     const token = options.token?.trim() || undefined;
     if (!token) {
-        return Promise.reject(new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1"));
+        throw new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1", { remedy: SERVE_BIND_REMEDY.token });
     }
+    const now = options.now ?? Date.now;
+    const timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? SERVE_BIND_VERIFY_TIMEOUT_MS));
+    const deadline = now() + timeoutMs;
+    const assertStartupOpen = (stage) => {
+        if (options.signal?.aborted) {
+            throw new ZellijError("cancelled", "serve startup cancelled before listen", {
+                phase: "bind",
+                cause: "cancelled",
+                stage,
+                remedy: SERVE_BIND_REMEDY.cancelled,
+            });
+        }
+        if (now() >= deadline) {
+            throw new ZellijError("serve_auth", `zswarm serve startup timed out during ${stage} before listen`, {
+                phase: "bind",
+                cause: "timeout",
+                stage,
+                remedy: SERVE_BIND_REMEDY.timeout,
+            });
+        }
+    };
+    // Share the absolute startup deadline with verification; do not refresh a
+    // new relative allowance after time has already elapsed.
+    assertStartupOpen("authorize");
+    const authorized = await authorizeServeListen(host, {
+        env: options.env,
+        signal: options.signal,
+        deadline,
+        now,
+        tailscaleStatus: options.tailscaleStatus,
+        networkInterfaces: options.networkInterfaces,
+    });
+    // Abort queued during authorization must be observed before listener effects.
+    assertStartupOpen("authorize");
+    const bindHost = authorized.bindHost;
     const maxRequestBytes = options.maxRequestBytes ?? SERVE_MAX_REQUEST_BYTES;
     const idleTimeoutMs = options.idleTimeoutMs ?? SERVE_IDLE_TIMEOUT_MS;
     const maxConnections = options.maxConnections ?? SERVE_MAX_CONNECTIONS;
+    const hello = helloData(randomUUID(), options.launchId);
+    const makeServer = options.createServer ?? createServer;
+    // Recheck immediately before allocating a listener (microtask aborts land here).
+    assertStartupOpen("listen");
     return new Promise((resolve, reject) => {
+        let settled = false;
+        let startupTimer;
+        let onAbort;
         const sockets = new Set();
-        const server = createServer((socket) => {
+        const server = makeServer((socket) => {
             socket.on("error", () => {
                 socket.destroy();
             });
@@ -143,20 +296,36 @@ export function startServe(listen, dispatch, options = {}) {
                         buf = buf.slice(nl + 1);
                         if (line) {
                             let result;
+                            let parsed;
                             try {
-                                const parsed = JSON.parse(line);
-                                const taken = takeServeToken(parsed);
-                                if (taken.token !== token) {
-                                    result = unauthorized();
+                                parsed = JSON.parse(line);
+                            }
+                            catch {
+                                result = { ok: false, error: { code: "bad_arg", message: "serve request is not JSON" } };
+                            }
+                            if (!result) {
+                                try {
+                                    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                                        result = protocolError("serve request must be a JSON object");
+                                    }
+                                    else {
+                                        const taken = takeServeToken(parsed);
+                                        if (taken.token !== token) {
+                                            result = unauthorized();
+                                        }
+                                        else {
+                                            const control = handleServeControl(taken.request, hello);
+                                            result = control.handled
+                                                ? control.result
+                                                : await dispatch(taken.request);
+                                        }
+                                    }
                                 }
-                                else {
-                                    result = await dispatch(taken.request);
+                                catch (err) {
+                                    const message = err instanceof Error ? err.message : "serve dispatch failed";
+                                    result = { ok: false, error: { code: "failed", message } };
                                 }
                             }
-                            catch (err) {
-                                const message = err instanceof Error ? err.message : String(err);
-                                result = { ok: false, error: { code: "bad_arg", message } };
-                            }
                             if (!socket.destroyed) {
                                 socket.write(`${JSON.stringify(result)}\n`);
                             }
@@ -177,177 +346,474 @@ export function startServe(listen, dispatch, options = {}) {
                 }
             }
         });
-        server.on("error", reject);
-        server.listen(port, host, () => {
-            const addr = server.address();
-            const actualPort = typeof addr === "object" && addr ? addr.port : port;
-            resolve({
-                label: formatListenLabel(host, actualPort),
-                close: () => new Promise((done, fail) => {
-                    for (const open of sockets)
-                        open.destroy();
-                    server.close((err) => (err ? fail(err) : done()));
-                }),
-            });
+        const clearStartupWatchers = () => {
+            if (startupTimer !== undefined) {
+                clearTimeout(startupTimer);
+                startupTimer = undefined;
+            }
+            if (onAbort && options.signal) {
+                options.signal.removeEventListener("abort", onAbort);
+                onAbort = undefined;
+            }
+        };
+        const closeStartupListener = () => {
+            for (const open of sockets)
+                open.destroy();
+            try {
+                server.close(() => { });
+            }
+            catch {
+                // ignore close races on fake/test listeners
+            }
+        };
+        const rejectStartup = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearStartupWatchers();
+            closeStartupListener();
+            reject(err);
+        };
+        const resolveStartup = (handle) => {
+            if (settled) {
+                closeStartupListener();
+                return;
+            }
+            settled = true;
+            clearStartupWatchers();
+            resolve(handle);
+        };
+        server.on("error", (err) => {
+            const code = typeof err.code === "string" ? err.code : "listen_failed";
+            rejectStartup(new ZellijError("serve_auth", `zswarm serve failed to bind ${formatListenLabel(bindHost, port)} (${code}); no fallback listen address`, {
+                phase: "bind",
+                cause: code,
+                host: bindHost,
+                port,
+                remedy: SERVE_BIND_REMEDY.bind,
+            }));
         });
+        // Active ownership while listen completion is pending: do not wait for the
+        // listening callback to observe cancel/expiry. Cleared on success so the
+        // startup budget is not a lifetime timer for a healthy server.
+        onAbort = () => {
+            rejectStartup(new ZellijError("cancelled", "serve startup cancelled before listen completed", {
+                phase: "bind",
+                cause: "cancelled",
+                stage: "listening",
+                remedy: SERVE_BIND_REMEDY.cancelled,
+            }));
+        };
+        if (options.signal) {
+            if (options.signal.aborted) {
+                onAbort();
+                return;
+            }
+            options.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        const remainingMs = deadline - now();
+        if (remainingMs <= 0) {
+            rejectStartup(new ZellijError("serve_auth", "zswarm serve startup timed out before listen completed", {
+                phase: "bind",
+                cause: "timeout",
+                stage: "listening",
+                remedy: SERVE_BIND_REMEDY.timeout,
+            }));
+            return;
+        }
+        startupTimer = setTimeout(() => {
+            // Re-read injected clocks so tests can advance `now` after listen starts.
+            if (now() >= deadline) {
+                rejectStartup(new ZellijError("serve_auth", "zswarm serve startup timed out before listen completed", {
+                    phase: "bind",
+                    cause: "timeout",
+                    stage: "listening",
+                    remedy: SERVE_BIND_REMEDY.timeout,
+                }));
+            }
+        }, Math.max(1, remainingMs));
+        // Ensure the timer does not keep the process alive after success on Node.
+        startupTimer.unref?.();
+        try {
+            assertStartupOpen("listen");
+        }
+        catch (err) {
+            rejectStartup(err);
+            return;
+        }
+        // Exact verified address only — never 0.0.0.0 / :: / a different host.
+        // Startup budget ends once listening succeeds; it is not a lifetime timer.
+        try {
+            server.listen(port, bindHost, () => {
+                if (settled) {
+                    closeStartupListener();
+                    return;
+                }
+                if (options.signal?.aborted) {
+                    rejectStartup(new ZellijError("cancelled", "serve startup cancelled before listen completed", {
+                        phase: "bind",
+                        cause: "cancelled",
+                        stage: "listening",
+                        remedy: SERVE_BIND_REMEDY.cancelled,
+                    }));
+                    return;
+                }
+                if (now() >= deadline) {
+                    rejectStartup(new ZellijError("serve_auth", "zswarm serve startup timed out before listen completed", {
+                        phase: "bind",
+                        cause: "timeout",
+                        stage: "listening",
+                        remedy: SERVE_BIND_REMEDY.timeout,
+                    }));
+                    return;
+                }
+                const addr = server.address();
+                const actualPort = typeof addr === "object" && addr ? addr.port : port;
+                resolveStartup({
+                    label: formatListenLabel(bindHost, actualPort),
+                    close: () => new Promise((done, fail) => {
+                        for (const open of sockets)
+                            open.destroy();
+                        server.close((err) => (err ? fail(err) : done()));
+                    }),
+                });
+            });
+        }
+        catch (err) {
+            // Synchronous listen failures must clear abort/timer watchers and close
+            // the owned listener; preserve the original error cause/message.
+            rejectStartup(err);
+        }
     });
 }
+/** Direct host:port / tcp:// only. ssh:// URIs are resolved by serve-tunnel. */
 export function parseServeTarget(raw) {
     return parseListenAddress(raw);
 }
-export function callServe(target, args, timeoutMs = 15_000, token) {
-    const { host, port } = parseServeTarget(target);
-    const payload = token && token.trim()
-        ? { ...args, [SERVE_TOKEN_FIELD]: token.trim() }
-        : args;
+function serveFail(code, message, details) {
+    return { ok: false, error: { code, message, details } };
+}
+function remedyFor(code, phase, delivery) {
+    if (code === "serve_unauthorized")
+        return SERVE_REMEDY.unauthorized;
+    if (code === "cancelled")
+        return SERVE_REMEDY.cancelled;
+    if (code === "serve_unreachable")
+        return SERVE_REMEDY.connect;
+    if (code === "serve_hello_unsupported")
+        return SERVE_REMEDY.helloUnsupported;
+    if (code === "serve_incompatible")
+        return SERVE_REMEDY.incompatible;
+    if (code === "timeout") {
+        if (phase === "connect")
+            return SERVE_REMEDY.timeoutConnect;
+        if (phase === "hello")
+            return SERVE_REMEDY.timeoutHello;
+        if (delivery === "uncertain")
+            return SERVE_REMEDY.timeoutRequest;
+        return SERVE_REMEDY.timeoutConnect;
+    }
+    if (delivery === "uncertain")
+        return SERVE_REMEDY.incomplete;
+    return SERVE_REMEDY.protocol;
+}
+function asOpsResult(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const v = value;
+    if (v.ok === true) {
+        if (!Object.prototype.hasOwnProperty.call(v, "data"))
+            return null;
+        return value;
+    }
+    if (v.ok !== false || !v.error || typeof v.error !== "object")
+        return null;
+    const error = v.error;
+    if (typeof error.code !== "string" || typeof error.message !== "string")
+        return null;
+    return value;
+}
+/** CLI/MCP inherit `process.env`; a positive integer overrides the default reply cap. */
+export function serveMaxReplyBytes(env = process.env) {
+    const raw = env.ZSWARM_SERVE_MAX_REPLY_BYTES?.trim();
+    if (!raw)
+        return SERVE_MAX_REPLY_BYTES;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        return SERVE_MAX_REPLY_BYTES;
+    return Math.floor(n);
+}
+function replyByteLimit(phase, override) {
+    if (typeof override === "number" && Number.isFinite(override) && override > 0) {
+        return Math.floor(override);
+    }
+    if (phase === "hello")
+        return SERVE_MAX_HELLO_BYTES;
+    return serveMaxReplyBytes();
+}
+function isServeHelloData(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    return (typeof d.protocol === "number" &&
+        Number.isFinite(d.protocol) &&
+        typeof d.serverId === "string" &&
+        d.serverId.trim() !== "" &&
+        typeof d.hostname === "string" &&
+        d.hostname.trim() !== "" &&
+        typeof d.platform === "string" &&
+        d.platform.trim() !== "" &&
+        typeof d.version === "string" &&
+        d.version.trim() !== "" &&
+        Array.isArray(d.capabilities) &&
+        d.capabilities.every((cap) => typeof cap === "string" && cap.trim() !== ""));
+}
+function attachToken(args, token) {
+    return token && token.trim() ? { ...args, [SERVE_TOKEN_FIELD]: token.trim() } : args;
+}
+function exchangeServe(input) {
+    const { host, port } = parseServeTarget(input.target);
+    const endpoint = formatListenLabel(host, port);
+    const timeoutMs = Math.max(1, input.timeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    const maxReplyBytes = replyByteLimit(input.phase, input.maxReplyBytes);
+    const remaining = () => Math.max(0, deadline - Date.now());
     return new Promise((resolve) => {
-        const socket = connect({ host, port });
-        let buf = "";
+        let phase = "connect";
+        let sent = false;
         let settled = false;
+        let pending = Buffer.alloc(0);
+        let connectTimer;
+        let waitTimer;
+        let overallTimer;
+        let socket;
+        const delivery = () => (sent ? "uncertain" : "not_sent");
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
-            clearTimeout(timer);
-            socket.destroy();
+            if (connectTimer)
+                clearTimeout(connectTimer);
+            if (waitTimer)
+                clearTimeout(waitTimer);
+            if (overallTimer)
+                clearTimeout(overallTimer);
+            input.signal?.removeEventListener("abort", onAbort);
+            if (socket) {
+                socket.removeAllListeners();
+                socket.destroy();
+            }
             resolve(result);
         };
-        const timer = setTimeout(() => {
-            finish({
-                ok: false,
-                error: {
-                    code: "timeout",
-                    message: `zswarm serve at ${host}:${port} timed out after ${timeoutMs}ms`,
-                },
-            });
+        const fail = (code, message, state = delivery()) => {
+            finish(serveFail(code, message, {
+                phase,
+                endpoint,
+                delivery: state,
+                remedy: remedyFor(code, phase, state),
+            }));
+        };
+        const onAbort = () => {
+            fail("cancelled", "operation cancelled");
+        };
+        if (input.signal?.aborted) {
+            fail("cancelled", "operation cancelled");
+            return;
+        }
+        if (remaining() <= 0) {
+            fail("timeout", `zswarm serve at ${endpoint} timed out after ${timeoutMs}ms`);
+            return;
+        }
+        socket = connect({ host, port });
+        input.signal?.addEventListener("abort", onAbort, { once: true });
+        overallTimer = setTimeout(() => {
+            fail("timeout", `zswarm serve at ${endpoint} timed out after ${timeoutMs}ms`);
         }, timeoutMs);
-        socket.setEncoding("utf8");
+        connectTimer = setTimeout(() => {
+            fail("timeout", `zswarm serve at ${endpoint} timed out after ${timeoutMs}ms`);
+        }, Math.max(1, Math.min(input.connectTimeoutMs ?? SERVE_CONNECT_TIMEOUT_MS, remaining())));
         socket.on("error", (err) => {
-            finish({
-                ok: false,
-                error: {
-                    code: "serve_unreachable",
-                    message: `cannot reach zswarm serve at ${host}:${port}: ${err.message}`,
-                },
-            });
+            if (phase === "connect" && !sent) {
+                fail("serve_unreachable", `cannot reach zswarm serve at ${endpoint}: ${err.message}`);
+                return;
+            }
+            fail("serve_protocol", `zswarm serve at ${endpoint} closed before a complete reply`);
         });
-        socket.on("data", (chunk) => {
-            buf += chunk;
-            const nl = buf.indexOf("\n");
-            if (nl === -1)
+        socket.on("connect", () => {
+            if (settled || !socket)
                 return;
-            const line = buf.slice(0, nl).trim();
+            if (connectTimer) {
+                clearTimeout(connectTimer);
+                connectTimer = undefined;
+            }
+            phase = input.phase;
+            const waitBound = phase === "hello" ? Math.min(SERVE_HELLO_TIMEOUT_MS, remaining()) : remaining();
+            if (waitBound <= 0) {
+                fail("timeout", `zswarm serve at ${endpoint} timed out after ${timeoutMs}ms`);
+                return;
+            }
+            if (phase === "hello") {
+                waitTimer = setTimeout(() => {
+                    fail("timeout", `zswarm serve at ${endpoint} timed out after ${timeoutMs}ms`);
+                }, Math.max(1, waitBound));
+            }
+            sent = true;
             try {
-                finish(JSON.parse(line));
+                socket.write(`${JSON.stringify(input.payload)}\n`);
             }
             catch {
-                finish({
-                    ok: false,
-                    error: { code: "failed", message: `serve returned non-JSON: ${line}` },
-                });
+                fail("serve_protocol", `zswarm serve at ${endpoint} closed before a complete reply`);
             }
         });
-        socket.on("connect", () => {
-            socket.write(`${JSON.stringify(payload)}\n`);
+        socket.on("data", (chunk) => {
+            if (settled)
+                return;
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+            pending = Buffer.concat([pending, bytes]);
+            // Cap counts the complete JSONL frame in UTF-8, including the newline.
+            if (pending.length > maxReplyBytes) {
+                fail("serve_protocol", `serve reply exceeded ${maxReplyBytes} bytes`);
+                return;
+            }
+            while (!settled) {
+                const nl = pending.indexOf(0x0a);
+                if (nl === -1)
+                    return;
+                const line = pending.subarray(0, nl).toString("utf8").trim();
+                pending = pending.subarray(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    const parsed = asOpsResult(JSON.parse(line));
+                    if (!parsed) {
+                        fail("serve_protocol", `zswarm serve at ${endpoint} returned an invalid reply`, "replied");
+                        return;
+                    }
+                    finish(parsed);
+                }
+                catch {
+                    fail("serve_protocol", `zswarm serve at ${endpoint} returned non-JSON`, "replied");
+                }
+                return;
+            }
         });
+        const onClosed = () => {
+            if (settled)
+                return;
+            if (pending.length > 0) {
+                fail("serve_protocol", `zswarm serve at ${endpoint} returned a truncated reply`);
+                return;
+            }
+            fail("serve_protocol", `zswarm serve at ${endpoint} closed before a complete reply`);
+        };
+        socket.on("end", onClosed);
+        socket.on("close", onClosed);
+    });
+}
+function interpretServeHello(result, endpoint) {
+    if (!result.ok) {
+        if (result.error.code === "serve_unauthorized" ||
+            result.error.code === "serve_unreachable" ||
+            result.error.code === "timeout" ||
+            result.error.code === "cancelled" ||
+            result.error.code === "serve_protocol" ||
+            result.error.code === "serve_incompatible" ||
+            result.error.code === "serve_hello_unsupported") {
+            return result;
+        }
+        return serveFail("serve_hello_unsupported", `zswarm serve at ${endpoint} does not speak hello (protocol ${SERVE_PROTOCOL})`, {
+            phase: "hello",
+            endpoint,
+            delivery: "replied",
+            remedy: SERVE_REMEDY.helloUnsupported,
+        });
+    }
+    const data = result.data;
+    if (data && typeof data === "object" && typeof data.protocol === "number") {
+        const protocol = data.protocol;
+        if (protocol !== SERVE_PROTOCOL) {
+            return serveFail("serve_incompatible", `zswarm serve at ${endpoint} speaks protocol ${protocol}; this client supports ${SERVE_PROTOCOL}`, {
+                phase: "hello",
+                endpoint,
+                delivery: "replied",
+                remedy: SERVE_REMEDY.incompatible,
+            });
+        }
+        if (!isServeHelloData(data) ||
+            !data.capabilities.includes(SERVE_CAPABILITY_HELLO)) {
+            return serveFail("serve_protocol", `zswarm serve at ${endpoint} returned an invalid hello`, {
+                phase: "hello",
+                endpoint,
+                delivery: "replied",
+                remedy: SERVE_REMEDY.protocol,
+            });
+        }
+        return { ok: true, data };
+    }
+    return serveFail("serve_hello_unsupported", `zswarm serve at ${endpoint} does not speak hello (protocol ${SERVE_PROTOCOL})`, {
+        phase: "hello",
+        endpoint,
+        delivery: "replied",
+        remedy: SERVE_REMEDY.helloUnsupported,
     });
 }
+export function callServe(target, args, timeoutMsOrOptions = 15_000, token, signal) {
+    const options = typeof timeoutMsOrOptions === "object" && timeoutMsOrOptions !== null
+        ? timeoutMsOrOptions
+        : { timeoutMs: timeoutMsOrOptions, token, signal };
+    return exchangeServe({
+        target,
+        payload: attachToken(args, options.token),
+        timeoutMs: options.timeoutMs ?? 15_000,
+        phase: "request",
+        signal: options.signal,
+        maxReplyBytes: options.maxReplyBytes,
+        connectTimeoutMs: options.connectTimeoutMs,
+    });
+}
+/** Authenticated hello probe. Never reports a legacy or incompatible endpoint as healthy. */
+export function probeServe(target, options = {}) {
+    const { label: endpoint } = parseListenAddress(target);
+    return exchangeServe({
+        target,
+        payload: attachToken({ [SERVE_CONTROL_FIELD]: SERVE_HELLO_CONTROL }, options.token),
+        timeoutMs: options.timeoutMs ?? 15_000,
+        phase: "hello",
+        signal: options.signal,
+    }).then((result) => interpretServeHello(result, endpoint));
+}
 export function redactServeSecret(command, token) {
     const secret = token.trim();
     if (!secret)
         return command;
     return command.split(secret).join("***");
 }
-export function serveLogonCommand(execPath, scriptPath, listen, token) {
+export function serveLogonCommand(execPath, scriptPath, listen, token, extraEnv = {}) {
+    for (const path of [execPath, scriptPath]) {
+        if (/[\0\r\n"]/.test(path)) {
+            throw new ZellijError("bad_arg", "serve executable/script path must not contain quotes or newlines");
+        }
+    }
     const launch = `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+    const env = { ...extraEnv };
     const secret = token?.trim();
-    if (!secret)
-        return launch;
-    if (/[\0\r\n"%]/.test(secret)) {
-        throw new ZellijError("bad_arg", "ZSWARM_SERVE_TOKEN must not contain quotes, newlines, or %");
-    }
-    return `set "ZSWARM_SERVE_TOKEN=${secret}"&& ${launch}`;
-}
-function serveInstallToken(input) {
-    const raw = input.token ??
-        (input.env ? input.env.ZSWARM_SERVE_TOKEN : process.env.ZSWARM_SERVE_TOKEN);
-    const secret = raw?.trim() ?? "";
-    if (!secret) {
-        throw new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1");
-    }
-    return secret;
-}
-function runPowerShell(script) {
-    return new Promise((resolve) => {
-        execFile("powershell.exe", [
-            "-NoProfile",
-            "-ExecutionPolicy",
-            "Bypass",
-            "-EncodedCommand",
-            encodePowerShellCommand(script),
-        ], { windowsHide: true, timeout: 20_000 }, (error, stdout, stderr) => {
-            const code = error && typeof error.code === "number"
-                ? error.code
-                : error
-                    ? 1
-                    : 0;
-            resolve({
-                code,
-                stdout: String(stdout ?? ""),
-                stderr: String(stderr ?? ""),
-            });
-        });
-    });
-}
-export async function installServeLogon(input) {
-    if ((input.platform ?? process.platform) !== "win32") {
-        throw new ZellijError("usage", "serve --install registers a Windows logon task; on Unix start `zswarm serve --listen` in the session that owns Zellij");
-    }
-    const { host, label } = parseListenAddress(input.listen);
-    if (!isLoopbackHost(host)) {
-        throw new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`);
-    }
-    const token = serveInstallToken(input);
-    const execPath = input.execPath ?? process.execPath;
-    const scriptPath = input.scriptPath ?? process.argv[1];
-    if (!scriptPath) {
-        throw new ZellijError("usage", "cannot resolve the zswarm script path for the logon task");
-    }
-    const command = serveLogonCommand(execPath, scriptPath, label, token);
-    const commandB64 = Buffer.from(command, "utf8").toString("base64");
-    const script = [
-        "$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" +
-            commandB64 +
-            "'))",
-        "$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument \"/c $cmd\"",
-        "$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Limited",
-        "$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME",
-        `Register-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Action $action -Principal $principal -Trigger $trigger -Force | Out-Null`,
-        `Start-ScheduledTask -TaskName '${SERVE_TASK_NAME}'`,
-    ].join("\n");
-    const result = await runPowerShell(script);
-    if (result.code !== 0) {
-        throw new ZellijError("zellij_failed", `serve --install failed: ${(result.stderr || result.stdout).trim() || "no output"}`);
-    }
-    return { task: SERVE_TASK_NAME, listen: label, command: redactServeSecret(command, token) };
-}
-export async function uninstallServeLogon(input = {}) {
-    if ((input.platform ?? process.platform) !== "win32") {
-        throw new ZellijError("usage", "serve --clear is Windows-only");
-    }
-    const script = [
-        "$ProgressPreference = 'SilentlyContinue'",
-        "try {",
-        `  Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false`,
-        "} catch {",
-        "  if ($_.CategoryInfo.Category -eq 'ObjectNotFound') { exit 0 }",
-        "  [Console]::Error.Write(($_ | Out-String).Trim())",
-        "  exit 1",
-        "}",
-    ].join("\n");
-    const result = await runPowerShell(script);
-    if (result.code !== 0) {
-        throw new ZellijError("zellij_failed", `serve --clear failed: ${(result.stderr || result.stdout).trim() || "no output"}`);
+    if (secret)
+        env.ZSWARM_SERVE_TOKEN = secret;
+    const assignments = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (!value)
+            continue;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new ZellijError("bad_arg", `cannot persist environment key ${key} in the logon task`);
+        }
+        if (/[\0\r\n"%]/.test(value)) {
+            throw new ZellijError("bad_arg", key === "ZSWARM_SERVE_TOKEN"
+                ? "ZSWARM_SERVE_TOKEN must not contain quotes, newlines, or %"
+                : `${key} must not contain quotes, newlines, or %`);
+        }
+        assignments.push(`set "${key}=${value}"`);
     }
-    return { task: SERVE_TASK_NAME, cleared: true };
+    if (assignments.length === 0)
+        return launch;
+    return `${assignments.join("&& ")}&& ${launch}`;
 }