@aoagents/ao-web 0.5.0 → 0.7.0

package/dist-server/mux-websocket.js

@@ -6,9 +6,10 @@
  * every 3s, then broadcast to all subscribed clients via WebSocket.
  */
 import { WebSocketServer, WebSocket } from "ws";
-import { homedir, userInfo } from "node:os";
 import { spawn } from "node:child_process";
-import { findTmux, resolveTmuxSession, validateSessionId } from "./tmux-utils.js";
+import { connect as netConnect } from "node:net";
+import { findTmux, resolveTmuxSession, resolvePipePath, tmuxHasSession, validateSessionId, } from "./tmux-utils.js";
+import { getEnvDefaults, isWindows } from "@aoagents/ao-core";
 /**
  * Manages polling of session patches from Next.js /api/sessions/patches.
  * Broadcasts to all subscribed callbacks.
@@ -141,15 +142,31 @@ catch (err) {
 const RING_BUFFER_MAX = 50 * 1024; // 50KB max per terminal
 const WS_BUFFER_HIGH_WATERMARK = 64 * 1024; // 64KB
 const MAX_REATTACH_ATTEMPTS = 3;
+/**
+ * Grace period a freshly-attached PTY must survive before its successful
+ * attach is allowed to reset the re-attach counter. Prevents tight crash
+ * loops (e.g. attaching to a tmux session that no longer exists) from
+ * gaming the MAX_REATTACH_ATTEMPTS cap by resetting the counter to 0
+ * between every failed attempt.
+ *
+ * 5 s is comfortably longer than the ~40 ms a doomed `tmux attach-session`
+ * takes to exit, while still being short enough that a healthy PTY which
+ * crashes hours later gets a fresh retry budget.
+ */
+const REATTACH_RESET_GRACE_MS = 5_000;
 /**
  * TerminalManager manages PTY processes independently of WebSocket connections.
  * A single manager instance is shared across all mux connections.
  */
-class TerminalManager {
+export class TerminalManager {
     terminals = new Map();
     TMUX;
     constructor(tmuxPath) {
-        this.TMUX = tmuxPath ?? findTmux();
+        const resolved = tmuxPath ?? findTmux();
+        if (!resolved) {
+            throw new Error("tmux not available on this platform");
+        }
+        this.TMUX = resolved;
     }
     terminalKey(id, projectId) {
         return projectId ? `${projectId}:${id}` : id;
@@ -189,33 +206,37 @@ class TerminalManager {
         if (terminal.pty) {
             return tmuxSessionId;
         }
+        // tmux 3.4 only honours the `=` exact-match prefix on has-session and
+        // attach-session; set-option silently ignores it, so we use the bare id
+        // here. The `=`-prefixed form is built below for attach-session.
         // Enable mouse mode
-        const exactTmuxTarget = `=${tmuxSessionId}`;
-        const mouseProc = spawn(this.TMUX, ["set-option", "-t", exactTmuxTarget, "mouse", "on"]);
+        const mouseProc = spawn(this.TMUX, ["set-option", "-t", tmuxSessionId, "mouse", "on"]);
         mouseProc.on("error", (err) => {
             console.error(`[MuxServer] Failed to set mouse mode for ${tmuxSessionId}:`, err.message);
         });
         // Hide the status bar
-        const statusProc = spawn(this.TMUX, ["set-option", "-t", exactTmuxTarget, "status", "off"]);
+        const statusProc = spawn(this.TMUX, ["set-option", "-t", tmuxSessionId, "status", "off"]);
         statusProc.on("error", (err) => {
             console.error(`[MuxServer] Failed to hide status bar for ${tmuxSessionId}:`, err.message);
         });
         // Build environment
-        const homeDir = process.env.HOME || homedir();
-        const currentUser = process.env.USER || userInfo().username;
+        const platformDefaults = getEnvDefaults();
+        const homeDir = platformDefaults.HOME;
         const env = {
-            HOME: homeDir,
-            SHELL: process.env.SHELL || "/bin/bash",
-            USER: currentUser,
-            PATH: process.env.PATH || "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
+            HOME: platformDefaults.HOME,
+            SHELL: platformDefaults.SHELL,
+            USER: platformDefaults.USER,
+            PATH: process.env.PATH || platformDefaults.PATH,
             TERM: "xterm-256color",
             LANG: process.env.LANG || "en_US.UTF-8",
-            TMPDIR: process.env.TMPDIR || "/tmp",
+            TMPDIR: platformDefaults.TMPDIR,
         };
         if (!ptySpawn) {
             throw new Error("node-pty not available");
         }
-        // Spawn PTY
+        // Spawn PTY — use `=`-prefixed exact-match target so we never attach to
+        // a session whose name happens to be a prefix of the requested id.
+        const exactTmuxTarget = `=${tmuxSessionId}`;
         const pty = ptySpawn(this.TMUX, ["attach-session", "-t", exactTmuxTarget], {
             name: "xterm-256color",
             cols: 80,
@@ -224,6 +245,24 @@ class TerminalManager {
             env,
         });
         terminal.pty = pty;
+        // Schedule a grace-period reset of the re-attach counter. We only
+        // consider an attach "really successful" if the PTY survives long
+        // enough to suggest the underlying tmux session is actually usable.
+        // The closure-captured `pty` reference is compared with terminal.pty
+        // so a stale timer cannot reset the counter for a PTY that has
+        // already exited or been replaced by re-attach. Any previously-
+        // scheduled timer (from a now-replaced PTY) is cleared so we don't
+        // keep its closure references reachable until the timer fires.
+        if (terminal.resetTimer) {
+            clearTimeout(terminal.resetTimer);
+        }
+        terminal.resetTimer = setTimeout(() => {
+            terminal.resetTimer = undefined;
+            if (terminal.pty === pty) {
+                terminal.reattachAttempts = 0;
+            }
+        }, REATTACH_RESET_GRACE_MS);
+        terminal.resetTimer.unref();
         // Wire up data events
         pty.onData((data) => {
             // Push to all subscribers — isolate each callback so a throw in one
@@ -246,18 +285,49 @@ class TerminalManager {
             }
         });
         // Handle PTY exit
-        pty.onExit(({ exitCode }) => {
+        //
+        // Async: the has-session probe shells out via promisified execFile and
+        // must be awaited. node-pty fires onExit on the main thread; a sync
+        // probe would freeze the entire web server (every WebSocket, HTTP
+        // request, in-flight terminal) for up to the subprocess timeout when
+        // tmux is slow to respond.
+        pty.onExit(async ({ exitCode }) => {
             console.log(`[MuxServer] PTY exited for ${id} with code ${exitCode}`);
             terminal.pty = null;
+            // Skip the re-attach loop entirely when the underlying tmux session is
+            // gone (e.g. user pressed Ctrl-C in the pane and the launch command
+            // exited, taking the only window with it). Without this guard we
+            // burn three doomed attach-session spawns and emit a noisy
+            // "Max re-attach attempts reached" log line for what is actually a
+            // clean user-initiated termination — see issue #1756. The
+            // MAX_REATTACH_ATTEMPTS bound from #1640 still covers tmux server
+            // hiccups where the session does still exist.
+            if (terminal.subscribers.size > 0 &&
+                !(await tmuxHasSession(this.TMUX, tmuxSessionId))) {
+                console.log(`[MuxServer] tmux session ${tmuxSessionId} is gone, not re-attaching`);
+                if (terminal.resetTimer) {
+                    clearTimeout(terminal.resetTimer);
+                    terminal.resetTimer = undefined;
+                }
+                for (const cb of terminal.exitCallbacks) {
+                    cb(exitCode);
+                }
+                return;
+            }
             // Re-attach if subscribers are still present, up to MAX_REATTACH_ATTEMPTS.
             // The cap prevents an unbounded respawn loop when the PTY crashes immediately
             // after every attach (e.g. resource exhaustion or a broken tmux session).
+            // The counter is reset by a delayed timer in open() once the new PTY has
+            // survived REATTACH_RESET_GRACE_MS — see the comment on that constant.
+            // Resetting here would defeat the cap: when ao stop kills the tmux session
+            // out from under a still-subscribed dashboard, attach-session exits ~40 ms
+            // after spawn and the loop runs at ~80 spawns/sec, exhausting the system
+            // PTY pool in seconds (issue #1639).
             if (terminal.subscribers.size > 0 && terminal.reattachAttempts < MAX_REATTACH_ATTEMPTS) {
                 terminal.reattachAttempts += 1;
                 console.log(`[MuxServer] Re-attaching to ${id} (attempt ${terminal.reattachAttempts}/${MAX_REATTACH_ATTEMPTS})`);
                 try {
                     this.open(id, projectId, tmuxSessionId);
-                    terminal.reattachAttempts = 0; // reset on successful attach
                     return; // re-attached — don't notify exit
                 }
                 catch (err) {
@@ -317,6 +387,10 @@ class TerminalManager {
                 terminal.exitCallbacks.delete(onExit);
             // Kill PTY and clean up when the last subscriber leaves
             if (terminal.subscribers.size === 0) {
+                if (terminal.resetTimer) {
+                    clearTimeout(terminal.resetTimer);
+                    terminal.resetTimer = undefined;
+                }
                 if (terminal.pty) {
                     terminal.pty.kill();
                     terminal.pty = null;
@@ -335,22 +409,163 @@ class TerminalManager {
         return terminal.buffer.join("");
     }
 }
+/**
+ * Handle a Windows terminal message by relaying through named pipes.
+ * Extracted from the WebSocket connection handler for testability.
+ */
+export function handleWindowsPipeMessage(msg, ws, winPipes, winPipeBuffers, deps) {
+    const WS_OPEN = 1; // WebSocket.OPEN
+    const { id, type, projectId } = msg;
+    // MuxProvider keys subscribers under `${projectId}:${id}` when projectId is
+    // provided, so every outbound terminal message must echo projectId back —
+    // otherwise the client routes by id alone and the subscriber bucket
+    // mismatches, leaving the xterm pane blank on /projects/[id]/sessions/[id].
+    const echo = projectId ? { projectId } : {};
+    // Project-scoped pipe-map key: matches the Unix `subscriptionKey` shape so
+    // two projects sharing a sessionId on the same mux connection don't collide
+    // on the same socket/buffer entry.
+    const pipeKey = projectId ? `${projectId}:${id}` : id;
+    // The Unix path validates inside TerminalManager.open(). The Windows pipe
+    // relay bypasses TerminalManager entirely, so validate here too — `id`
+    // becomes a map key and is constructed into a pipe path downstream.
+    if (!validateSessionId(id)) {
+        if (ws.readyState === WS_OPEN) {
+            ws.send(JSON.stringify({
+                ch: "terminal",
+                id,
+                type: "error",
+                message: "invalid session id",
+                ...echo,
+            }));
+        }
+        return;
+    }
+    if (type === "open") {
+        if (winPipes.has(pipeKey)) {
+            ws.send(JSON.stringify({ ch: "terminal", id, type: "opened", ...echo }));
+        }
+        else {
+            const pipePath = deps.resolvePipePath(id, projectId);
+            if (!pipePath) {
+                throw new Error(`No PTY host pipe found for session ${id}`);
+            }
+            const pipeSocket = deps.connect(pipePath);
+            winPipes.set(pipeKey, pipeSocket);
+            winPipeBuffers.set(pipeKey, Buffer.alloc(0));
+            pipeSocket.on("error", (err) => {
+                winPipes.delete(pipeKey);
+                winPipeBuffers.delete(pipeKey);
+                pipeSocket.destroy();
+                if (ws.readyState === WS_OPEN) {
+                    ws.send(JSON.stringify({
+                        ch: "terminal",
+                        id,
+                        type: "error",
+                        message: `PTY host not available: ${err.message}`,
+                        ...echo,
+                    }));
+                }
+            });
+            pipeSocket.on("connect", () => {
+                if (ws.readyState === WS_OPEN) {
+                    ws.send(JSON.stringify({ ch: "terminal", id, type: "opened", ...echo }));
+                }
+                pipeSocket.on("data", (chunk) => {
+                    const existing = winPipeBuffers.get(pipeKey) ?? Buffer.alloc(0);
+                    let buf = Buffer.concat([existing, chunk]);
+                    winPipeBuffers.set(pipeKey, buf);
+                    while (buf.length >= 5) {
+                        const msgType = buf.readUInt8(0);
+                        const length = buf.readUInt32BE(1);
+                        if (buf.length < 5 + length)
+                            break;
+                        const payload = buf.subarray(5, 5 + length);
+                        buf = buf.subarray(5 + length);
+                        winPipeBuffers.set(pipeKey, buf);
+                        if (msgType === 0x01 && ws.readyState === WS_OPEN) {
+                            ws.send(JSON.stringify({
+                                ch: "terminal",
+                                id,
+                                type: "data",
+                                data: payload.toString("utf-8"),
+                                ...echo,
+                            }));
+                        }
+                        if (msgType === 0x07) {
+                            try {
+                                const status = JSON.parse(payload.toString("utf-8"));
+                                if (!status.alive && ws.readyState === WS_OPEN) {
+                                    ws.send(JSON.stringify({ ch: "terminal", id, type: "exited", code: 0, ...echo }));
+                                }
+                            }
+                            catch {
+                                /* ignore parse errors */
+                            }
+                        }
+                    }
+                });
+                pipeSocket.on("close", () => {
+                    winPipes.delete(pipeKey);
+                    winPipeBuffers.delete(pipeKey);
+                    if (ws.readyState === WS_OPEN) {
+                        ws.send(JSON.stringify({ ch: "terminal", id, type: "exited", code: 0, ...echo }));
+                    }
+                });
+            });
+        }
+    }
+    else if (type === "data" && msg.data !== undefined) {
+        const pipeSocket = winPipes.get(pipeKey);
+        if (pipeSocket) {
+            const inputBuf = Buffer.from(msg.data, "utf-8");
+            const header = Buffer.alloc(5);
+            header.writeUInt8(0x02, 0);
+            header.writeUInt32BE(inputBuf.length, 1);
+            pipeSocket.write(Buffer.concat([header, inputBuf]));
+        }
+    }
+    else if (type === "resize" && msg.cols !== undefined && msg.rows !== undefined) {
+        const pipeSocket = winPipes.get(pipeKey);
+        if (pipeSocket) {
+            const resizePayload = Buffer.from(JSON.stringify({ cols: msg.cols, rows: msg.rows }));
+            const header = Buffer.alloc(5);
+            header.writeUInt8(0x03, 0);
+            header.writeUInt32BE(resizePayload.length, 1);
+            pipeSocket.write(Buffer.concat([header, resizePayload]));
+        }
+    }
+    else if (type === "close") {
+        const pipeSocket = winPipes.get(pipeKey);
+        if (pipeSocket) {
+            pipeSocket.end();
+            winPipes.delete(pipeKey);
+            winPipeBuffers.delete(pipeKey);
+        }
+    }
+}
 /**
  * Create a mux WebSocket server (noServer mode).
  * Returns the WebSocketServer instance for manual upgrade routing.
  */
 export function createMuxWebSocket(tmuxPath) {
-    if (!ptySpawn) {
+    // On Windows, we use named pipe relay instead of node-pty/tmux.
+    // Allow the server to be created without ptySpawn on Windows.
+    if (!ptySpawn && !isWindows()) {
         console.warn("[MuxServer] node-pty not available — mux WebSocket will be disabled");
         return null;
     }
-    const terminalManager = new TerminalManager(tmuxPath);
+    // On Windows, terminal I/O goes through named pipe relay — no TerminalManager needed.
+    const terminalManager = ptySpawn && !isWindows() ? new TerminalManager(tmuxPath ?? undefined) : null;
     const nextPort = process.env.PORT || "3000";
     const broadcaster = new SessionBroadcaster(nextPort);
     const wss = new WebSocketServer({ noServer: true });
     wss.on("connection", (ws) => {
         console.log("[MuxServer] New mux connection");
         const subscriptions = new Map();
+        // Windows: named pipe sockets keyed by session ID
+        const winPipes = new Map();
+        // Windows: framing buffers keyed by session ID
+        const winPipeBuffers = new Map();
         let sessionUnsubscribe = null;
         let missedPongs = 0;
         const MAX_MISSED_PONGS = 3;
@@ -390,71 +605,93 @@ export function createMuxWebSocket(tmuxPath) {
                     const subscriptionKey = projectId ? `${projectId}:${id}` : id;
                     try {
                         if (type === "open") {
-                            // Validate session exists
-                            terminalManager.open(id, projectId, "tmuxName" in msg ? msg.tmuxName : undefined);
-                            // Send opened confirmation (idempotent — safe to send on re-open)
-                            const openedMsg = {
-                                ch: "terminal",
-                                id,
-                                type: "opened",
-                                ...(projectId && { projectId }),
-                            };
-                            ws.send(JSON.stringify(openedMsg));
-                            // Subscribe and send history buffer only for new subscribers.
-                            // Skipping the buffer on re-open prevents duplicate output when
-                            // MuxProvider re-sends open for all terminals on reconnect.
-                            if (!subscriptions.has(subscriptionKey)) {
-                                // Send buffered history to catch up the new subscriber
-                                const buffer = terminalManager.getBuffer(id, projectId);
-                                if (buffer) {
-                                    const bufferMsg = {
-                                        ch: "terminal",
-                                        id,
-                                        type: "data",
-                                        data: buffer,
-                                        ...(projectId && { projectId }),
-                                    };
-                                    ws.send(JSON.stringify(bufferMsg));
-                                }
-                                const unsub = terminalManager.subscribe(id, projectId, (data) => {
-                                    const dataMsg = {
-                                        ch: "terminal",
-                                        id,
-                                        type: "data",
-                                        data,
-                                        ...(projectId && { projectId }),
-                                    };
-                                    if (ws.readyState === WebSocket.OPEN) {
-                                        ws.send(JSON.stringify(dataMsg));
-                                    }
-                                }, (exitCode) => {
-                                    const exitedMsg = {
-                                        ch: "terminal",
-                                        id,
-                                        type: "exited",
-                                        code: exitCode,
-                                        ...(projectId && { projectId }),
-                                    };
-                                    if (ws.readyState === WebSocket.OPEN) {
-                                        ws.send(JSON.stringify(exitedMsg));
+                            if (isWindows()) {
+                                handleWindowsPipeMessage(msg, ws, winPipes, winPipeBuffers, { connect: netConnect, resolvePipePath });
+                            }
+                            else {
+                                // --- Unix: tmux path with project scoping ---
+                                if (!terminalManager)
+                                    throw new Error("Terminal manager not available");
+                                terminalManager.open(id, projectId, "tmuxName" in msg ? msg.tmuxName : undefined);
+                                // Send opened confirmation (idempotent — safe to send on re-open)
+                                const openedMsg = {
+                                    ch: "terminal",
+                                    id,
+                                    type: "opened",
+                                    ...(projectId && { projectId }),
+                                };
+                                ws.send(JSON.stringify(openedMsg));
+                                // Subscribe and send history buffer only for new subscribers.
+                                // Skipping the buffer on re-open prevents duplicate output when
+                                // MuxProvider re-sends open for all terminals on reconnect.
+                                if (!subscriptions.has(subscriptionKey)) {
+                                    // Send buffered history to catch up the new subscriber
+                                    const buffer = terminalManager.getBuffer(id, projectId);
+                                    if (buffer) {
+                                        const bufferMsg = {
+                                            ch: "terminal",
+                                            id,
+                                            type: "data",
+                                            data: buffer,
+                                            ...(projectId && { projectId }),
+                                        };
+                                        ws.send(JSON.stringify(bufferMsg));
                                     }
-                                });
-                                subscriptions.set(subscriptionKey, unsub);
+                                    const unsub = terminalManager.subscribe(id, projectId, (data) => {
+                                        const dataMsg = {
+                                            ch: "terminal",
+                                            id,
+                                            type: "data",
+                                            data,
+                                            ...(projectId && { projectId }),
+                                        };
+                                        if (ws.readyState === WebSocket.OPEN) {
+                                            ws.send(JSON.stringify(dataMsg));
+                                        }
+                                    }, (exitCode) => {
+                                        const exitedMsg = {
+                                            ch: "terminal",
+                                            id,
+                                            type: "exited",
+                                            code: exitCode,
+                                            ...(projectId && { projectId }),
+                                        };
+                                        if (ws.readyState === WebSocket.OPEN) {
+                                            ws.send(JSON.stringify(exitedMsg));
+                                        }
+                                    });
+                                    subscriptions.set(subscriptionKey, unsub);
+                                }
                             }
                         }
                         else if (type === "data" && "data" in msg) {
-                            terminalManager.write(id, msg.data, projectId);
+                            if (isWindows()) {
+                                handleWindowsPipeMessage(msg, ws, winPipes, winPipeBuffers, { connect: netConnect, resolvePipePath });
+                            }
+                            else {
+                                terminalManager?.write(id, msg.data, projectId);
+                            }
                         }
                         else if (type === "resize" && "cols" in msg && "rows" in msg) {
-                            terminalManager.resize(id, msg.cols, msg.rows, projectId);
+                            if (isWindows()) {
+                                handleWindowsPipeMessage(msg, ws, winPipes, winPipeBuffers, { connect: netConnect, resolvePipePath });
+                            }
+                            else {
+                                terminalManager?.resize(id, msg.cols, msg.rows, projectId);
+                            }
                         }
                         else if (type === "close") {
-                            // Unsubscribe this client only — TerminalManager is shared across
-                            // all mux connections so we must not kill the PTY here.
-                            const unsub = subscriptions.get(subscriptionKey);
-                            if (unsub) {
-                                unsub();
-                                subscriptions.delete(subscriptionKey);
+                            if (isWindows()) {
+                                handleWindowsPipeMessage(msg, ws, winPipes, winPipeBuffers, { connect: netConnect, resolvePipePath });
+                            }
+                            else {
+                                // Unsubscribe this client only — TerminalManager is shared across
+                                // all mux connections so we must not kill the PTY here.
+                                const unsub = subscriptions.get(subscriptionKey);
+                                if (unsub) {
+                                    unsub();
+                                    subscriptions.delete(subscriptionKey);
+                                }
                             }
                         }
                     }
@@ -515,6 +752,12 @@ export function createMuxWebSocket(tmuxPath) {
                 unsub();
             }
             subscriptions.clear();
+            // Windows: close all open pipe sockets
+            for (const pipeSocket of winPipes.values()) {
+                pipeSocket.destroy();
+            }
+            winPipes.clear();
+            winPipeBuffers.clear();
         });
         // In the ws library, "error" is always followed by "close", so the close
         // handler below handles all cleanup.  Log the error here and nothing more.

package/dist-server/start-all.js

@@ -8,6 +8,7 @@ import { resolve, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
+import { killProcessTree } from "@aoagents/ao-core";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Resolve paths relative to the package root (one level up from dist-server/)
@@ -25,6 +26,7 @@ function spawnProcess(label, command, args, opts) {
             cwd: pkgRoot,
             stdio: ["ignore", "pipe", "pipe"],
             env: process.env,
+            detached: process.platform !== "win32",
         });
         child.stdout?.on("data", (data) => {
             for (const line of data.toString().split("\n").filter(Boolean)) {
@@ -60,10 +62,14 @@ function spawnProcess(label, command, args, opts) {
  * Tries the local .bin shim first (fast), then falls back to require.resolve (hoisted deps).
  */
 function resolveNextBin() {
-    const localBin = resolve(pkgRoot, "node_modules", ".bin", "next");
-    if (existsSync(localBin))
-        return localBin;
-    // Hoisted node_modules — resolve the actual next CLI entry
+    // On Windows, .bin/next is a POSIX shell shim that spawn() cannot execute.
+    // Skip it and go straight to the JS entry point.
+    if (process.platform !== "win32") {
+        const localBin = resolve(pkgRoot, "node_modules", ".bin", "next");
+        if (existsSync(localBin))
+            return localBin;
+    }
+    // Resolve the actual Next.js CLI JS entry point
     const require = createRequire(resolve(pkgRoot, "package.json"));
     try {
         const nextPkg = require.resolve("next/package.json");
@@ -76,7 +82,15 @@ function resolveNextBin() {
 }
 // Start Next.js production server
 const port = process.env["PORT"] || "3000";
-spawnProcess("next", resolveNextBin(), ["start", "-p", port]);
+const nextBin = resolveNextBin();
+if (process.platform === "win32" && nextBin !== "next") {
+    // On Windows, run the JS entry point via the current node binary.
+    // spawn() can't execute .js files directly on Windows.
+    spawnProcess("next", process.execPath, [nextBin, "start", "-p", port]);
+}
+else {
+    spawnProcess("next", nextBin, ["start", "-p", port]);
+}
 // Start direct terminal WebSocket server (auto-restart on crash)
 spawnProcess("direct-terminal", "node", [resolve(__dirname, "direct-terminal-ws.js")], { restart: true });
 // Graceful shutdown — send SIGTERM to children and wait for them to exit
@@ -104,7 +118,15 @@ function cleanup() {
                 process.exit(0);
             }
         });
-        child.kill("SIGTERM");
+        const pid = child.pid;
+        if (pid) {
+            void killProcessTree(pid, "SIGTERM").catch(() => {
+                child.kill("SIGTERM");
+            });
+        }
+        else {
+            child.kill("SIGTERM");
+        }
     }
 }
 process.on("SIGINT", cleanup);