@aoagents/ao-web 0.6.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.
@@ -161,7 +162,11 @@ 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;
@@ -215,16 +220,16 @@ export class TerminalManager {
             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");
@@ -280,9 +285,35 @@ export 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).
@@ -378,22 +409,163 @@ export 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;
@@ -433,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);
+                                }
                             }
                         }
                     }
@@ -558,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);

package/dist-server/tmux-utils.js

@@ -4,10 +4,13 @@
  * Extracted from direct-terminal-ws.ts and terminal-websocket.ts
  * so the logic can be properly unit tested.
  */
-import { execFileSync } from "node:child_process";
-import { readdirSync, existsSync } from "node:fs";
+import { execFile, execFileSync } from "node:child_process";
+import { readdirSync, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { promisify } from "node:util";
+import { isWindows } from "@aoagents/ao-core";
+const execFileAsync = promisify(execFile);
 /** Session ID validation regex — alphanumeric, hyphens, underscores only */
 export const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 /** Hash prefix pattern — 12-char lowercase hex, as generated by generateConfigHash */
@@ -90,6 +93,8 @@ export function validateSessionId(sessionId) {
  * @param execFn - Injectable execFileSync for testing. Defaults to child_process.execFileSync.
  */
 export function findTmux(execFn = execFileSync) {
+    if (isWindows())
+        return null;
     const candidates = [
         "/opt/homebrew/bin/tmux", // macOS ARM (Homebrew)
         "/usr/local/bin/tmux", // macOS Intel (Homebrew)
@@ -106,6 +111,35 @@ export function findTmux(execFn = execFileSync) {
     }
     return "tmux"; // Fall back to bare name
 }
+/**
+ * Check whether a tmux session with the given name exists.
+ *
+ * Uses `=` exact-match prefix so the lookup never falls back to tmux's
+ * default prefix matching (where "ao-1" would match "ao-15"). The caller
+ * must already have the canonical tmux session name (typically the value
+ * returned by `resolveTmuxSession`).
+ *
+ * Async: this runs from inside node-pty's `onExit` callback on every agent
+ * exit, and the WebSocket server is single-threaded. A synchronous
+ * `execFileSync` here would block the event loop — and every WebSocket
+ * connection, HTTP request, and in-flight terminal — for up to the 5 s
+ * subprocess timeout when tmux is slow to respond. Use the promisified
+ * `execFile` form instead.
+ *
+ * @returns true if the session exists, false otherwise (including tmux
+ *   not running, no sessions, or any unexpected error)
+ */
+export async function tmuxHasSession(tmuxPath, tmuxSessionName, execFn = execFileAsync) {
+    if (!tmuxPath)
+        return false;
+    try {
+        await execFn(tmuxPath, ["has-session", "-t", `=${tmuxSessionName}`], { timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Resolve a user-facing session ID to its actual tmux session name.
  *
@@ -132,6 +166,8 @@ export function findTmux(execFn = execFileSync) {
  * @returns The actual tmux session name, or null if not found
  */
 export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync, fs = defaultFs, projectId) {
+    if (!tmuxPath)
+        return null;
     // Try exact match first using = prefix for exact matching (e.g., "ao-orchestrator")
     // Without =, tmux uses prefix matching: "ao-1" would match "ao-15"
     try {
@@ -177,3 +213,89 @@ export function resolveTmuxSession(sessionId, tmuxPath, execFn = execFileSync, f
     }
     return null;
 }
+/**
+ * Resolve a user-facing session ID to its Windows named pipe path.
+ *
+ * V2 layout (current): JSON metadata at
+ *   `~/.agent-orchestrator/projects/{projectId}/sessions/{sessionId}.json`
+ *   with `runtimeHandle.data.pipePath` as a top-level field.
+ *
+ * V1 layout (legacy fallback): line-delimited key=value at
+ *   `~/.agent-orchestrator/{storageKey}/sessions/{sessionId}` where
+ *   storageKey is bare 12-hex or `{hash}-{projectName}`. Kept so users
+ *   who haven't run `ao migrate-storage` still see live sessions.
+ *
+ * When `projectId` is provided, only that project's metadata file is read.
+ * Without it (legacy callers), walks all projects and returns the first
+ * matching pipePath — which can collide when two projects share a sessionId.
+ *
+ * @returns Full pipe path (e.g., "\\\\.\\pipe\\ao-pty-win1-orchestrator"), or null
+ */
+export function resolvePipePath(sessionId, projectId, fs = defaultFs) {
+    if (!isWindows())
+        return null;
+    const readFile = fs.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const aoBase = join(fs.homedir(), ".agent-orchestrator");
+    const readPipeFromV2 = (project) => {
+        const sessionFile = join(aoBase, "projects", project, "sessions", `${sessionId}.json`);
+        if (!fs.exists(sessionFile))
+            return null;
+        try {
+            const meta = JSON.parse(readFile(sessionFile));
+            const pipePath = meta.runtimeHandle?.data?.pipePath;
+            return typeof pipePath === "string" && pipePath.length > 0 ? pipePath : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // V2: prefer the caller's projectId when provided; otherwise walk all projects
+    const projectsDir = join(aoBase, "projects");
+    if (projectId) {
+        const pipe = readPipeFromV2(projectId);
+        if (pipe)
+            return pipe;
+    }
+    else if (fs.exists(projectsDir)) {
+        let projects;
+        try {
+            projects = fs.readdir(projectsDir);
+        }
+        catch {
+            projects = [];
+        }
+        for (const project of projects) {
+            const pipe = readPipeFromV2(project);
+            if (pipe)
+                return pipe;
+        }
+    }
+    // V1 fallback: line-delimited key=value under {storageKey}/sessions/{sessionId}
+    for (const storageKey of findStorageKeysForSession(sessionId, {
+        readdir: fs.readdir,
+        exists: fs.exists,
+        homedir: fs.homedir,
+    })) {
+        const sessionFile = join(aoBase, storageKey, "sessions", sessionId);
+        let content;
+        try {
+            content = readFile(sessionFile);
+        }
+        catch {
+            continue;
+        }
+        const match = content.match(/^runtimeHandle=(.+)$/m);
+        if (!match)
+            continue;
+        try {
+            const handle = JSON.parse(match[1]);
+            const pipePath = handle.data?.pipePath;
+            if (pipePath && pipePath.length > 0)
+                return pipePath;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}