arcane-agents 0.1.0

package/dist/server/server/assets/avatarCatalog.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listAvailableAvatarTypes = listAvailableAvatarTypes;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const appRoot_1 = require("../utils/appRoot");
+const requiredAvatarFiles = [
+    "rotations/south.png",
+    "rotations/east.png",
+    "rotations/north.png",
+    "rotations/west.png",
+    "animations/walk/south/0.png",
+    "animations/working/0.png"
+];
+function listAvailableAvatarTypes(assetsRoot = (0, appRoot_1.resolveAppPath)("assets", "characters")) {
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(assetsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name.trim())
+        .filter((avatarType) => avatarType.length > 0)
+        .filter((avatarType) => hasRequiredAvatarFiles(assetsRoot, avatarType))
+        .sort((a, b) => a.localeCompare(b));
+}
+function hasRequiredAvatarFiles(assetsRoot, avatarType) {
+    return requiredAvatarFiles.every((relativeFilePath) => {
+        return node_fs_1.default.existsSync(node_path_1.default.join(assetsRoot, avatarType, relativeFilePath));
+    });
+}

package/dist/server/server/assets/voiceLineCatalog.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listAvatarVoiceLineFiles = listAvatarVoiceLineFiles;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const appRoot_1 = require("../utils/appRoot");
+const voiceLineExtension = ".mp3";
+function listAvatarVoiceLineFiles(avatarType, assetsRoot = (0, appRoot_1.resolveAppPath)("assets", "characters")) {
+    const voiceLinesDir = resolveVoiceLinesDir(assetsRoot, avatarType);
+    if (!voiceLinesDir) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(voiceLinesDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name.trim())
+        .filter((name) => name.length > 0)
+        .filter((name) => name.toLowerCase().endsWith(voiceLineExtension))
+        .sort((a, b) => a.localeCompare(b));
+}
+function resolveVoiceLinesDir(assetsRoot, avatarType) {
+    const trimmedAvatarType = avatarType.trim();
+    if (trimmedAvatarType.length === 0) {
+        return null;
+    }
+    const absoluteAssetsRoot = node_path_1.default.resolve(assetsRoot);
+    const absoluteVoiceLinesDir = node_path_1.default.resolve(absoluteAssetsRoot, trimmedAvatarType, "voice-lines");
+    const expectedPrefix = `${absoluteAssetsRoot}${node_path_1.default.sep}`;
+    if (!absoluteVoiceLinesDir.startsWith(expectedPrefix)) {
+        return null;
+    }
+    return absoluteVoiceLinesDir;
+}

package/dist/server/server/bootstrap/httpApp.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpApp = createHttpApp;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const express_1 = __importDefault(require("express"));
+const errorResponse_1 = require("../http/errorResponse");
+const registerApiRoutes_1 = require("../http/routes/registerApiRoutes");
+const appRoot_1 = require("../utils/appRoot");
+function createHttpApp(context) {
+    const app = (0, express_1.default)();
+    app.use(express_1.default.json());
+    const assetsDir = (0, appRoot_1.resolveAppPath)("assets");
+    if (node_fs_1.default.existsSync(assetsDir)) {
+        app.use("/api/assets", express_1.default.static(assetsDir));
+    }
+    (0, registerApiRoutes_1.registerApiRoutes)(app, {
+        orchestrator: context.orchestrator,
+        hub: context.hub,
+        statusMonitor: context.statusMonitor
+    });
+    const clientDistPath = (0, appRoot_1.resolveAppPath)("dist", "client");
+    if (process.env.NODE_ENV === "production" && node_fs_1.default.existsSync(clientDistPath)) {
+        app.use(express_1.default.static(clientDistPath));
+        app.get("*", (_req, res) => {
+            res.sendFile(node_path_1.default.join(clientDistPath, "index.html"));
+        });
+    }
+    app.use((error, _req, res, _next) => {
+        if (res.headersSent) {
+            return;
+        }
+        (0, errorResponse_1.handleRequestError)(res, error);
+    });
+    return app;
+}

package/dist/server/server/bootstrap/serverContext.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServerContext = createServerContext;
+const node_fs_1 = __importDefault(require("node:fs"));
+const discovery_1 = require("../config/discovery");
+const loadConfig_1 = require("../config/loadConfig");
+const orchestratorService_1 = require("../orchestrator/orchestratorService");
+const workerRepository_1 = require("../persistence/workerRepository");
+const statusMonitor_1 = require("../status/statusMonitor");
+const tmuxAdapter_1 = require("../tmux/tmuxAdapter");
+const realtimeHub_1 = require("../ws/realtimeHub");
+const terminalBridge_1 = require("../ws/terminalBridge");
+async function createServerContext() {
+    const paths = (0, loadConfig_1.getArcaneAgentsPaths)();
+    node_fs_1.default.mkdirSync(paths.configDir, { recursive: true });
+    node_fs_1.default.mkdirSync(paths.stateDir, { recursive: true });
+    node_fs_1.default.mkdirSync(paths.cacheDir, { recursive: true });
+    const baseConfig = (0, loadConfig_1.loadResolvedConfig)(paths);
+    const discoveryService = new discovery_1.DiscoveryService();
+    const initialDiscovery = await discoveryService.discover(baseConfig);
+    for (const warning of initialDiscovery.warnings) {
+        console.warn(`[arcane-agents] ${warning}`);
+    }
+    const workers = new workerRepository_1.WorkerRepository(paths.dbPath);
+    const tmux = new tmuxAdapter_1.TmuxAdapter(baseConfig.backend.tmux.sessionName);
+    await tmux.ensureSessionClipboardDefaults();
+    const orchestrator = new orchestratorService_1.OrchestratorService(baseConfig, workers, tmux);
+    orchestrator.setDiscoveredProjects(initialDiscovery.projects);
+    const hub = new realtimeHub_1.RealtimeHub();
+    await orchestrator.reconcileWithTmux();
+    const statusMonitor = new statusMonitor_1.StatusMonitor(workers, tmux, baseConfig.backend.tmux.pollIntervalMs, (worker) => {
+        hub.broadcast({
+            type: "worker-updated",
+            worker
+        });
+    }, (workerId) => {
+        hub.broadcast({
+            type: "worker-removed",
+            workerId
+        });
+    });
+    const terminalBridge = new terminalBridge_1.TerminalBridge(workers, {
+        onSubmittedInput: () => {
+            statusMonitor.requestPollSoon();
+        }
+    });
+    return {
+        paths,
+        config: baseConfig,
+        workers,
+        tmux,
+        orchestrator,
+        hub,
+        terminalBridge,
+        statusMonitor
+    };
+}

package/dist/server/server/bootstrap/shutdown.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerShutdownHandlers = registerShutdownHandlers;
+exports.createShutdownHandler = createShutdownHandler;
+function registerShutdownHandlers({ statusMonitor, server, workers, wsServers, timeoutMs, exit }) {
+    const shutdown = createShutdownHandler({
+        statusMonitor,
+        server,
+        workers,
+        wsServers,
+        timeoutMs,
+        exit
+    });
+    const forceExit = exit ?? process.exit;
+    let isShuttingDown = false;
+    const handleSignal = (signal) => {
+        const forceCode = signal === "SIGINT" ? 130 : 143;
+        if (!isShuttingDown) {
+            isShuttingDown = true;
+            console.log(`[arcane-agents] received ${signal}; shutting down... (press Ctrl-C again to force exit)`);
+            void shutdown();
+            return;
+        }
+        console.warn(`[arcane-agents] received ${signal} again; forcing exit.`);
+        forceExit(forceCode);
+    };
+    process.on("SIGINT", () => {
+        handleSignal("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        handleSignal("SIGTERM");
+    });
+}
+function createShutdownHandler({ statusMonitor, server, workers, wsServers, timeoutMs = 2_000, exit = process.exit }) {
+    let shutdownPromise;
+    return async () => {
+        if (shutdownPromise) {
+            await shutdownPromise;
+            return;
+        }
+        shutdownPromise = runGracefulShutdown({
+            statusMonitor,
+            server,
+            workers,
+            wsServers,
+            timeoutMs,
+            exit
+        });
+        await shutdownPromise;
+    };
+}
+async function runGracefulShutdown({ statusMonitor, server, workers, wsServers, timeoutMs, exit }) {
+    let exited = false;
+    let timeoutId;
+    const complete = (code) => {
+        if (exited) {
+            return;
+        }
+        exited = true;
+        clearTimeout(timeoutId);
+        exit(code);
+    };
+    const timeoutPromise = new Promise((resolve) => {
+        timeoutId = setTimeout(() => {
+            resolve(1);
+        }, timeoutMs);
+        if (typeof timeoutId.unref === "function") {
+            timeoutId.unref();
+        }
+    });
+    statusMonitor.stop();
+    const cleanupPromise = (async () => {
+        let hadError = false;
+        if (wsServers) {
+            terminateWsClients(wsServers.realtimeWss);
+            terminateWsClients(wsServers.terminalWss);
+            const wsCloseResults = await Promise.allSettled([
+                closeWsServer(wsServers.realtimeWss),
+                closeWsServer(wsServers.terminalWss)
+            ]);
+            if (wsCloseResults.some((result) => result.status === "rejected")) {
+                hadError = true;
+            }
+        }
+        try {
+            await closeHttpServer(server);
+        }
+        catch {
+            hadError = true;
+        }
+        try {
+            workers.close();
+        }
+        catch {
+            hadError = true;
+        }
+        return hadError ? 1 : 0;
+    })();
+    const exitCode = await Promise.race([cleanupPromise, timeoutPromise]);
+    complete(exitCode);
+}
+function closeHttpServer(server) {
+    return new Promise((resolve, reject) => {
+        try {
+            server.close((error) => {
+                if (!error || isServerNotRunningError(error)) {
+                    resolve();
+                    return;
+                }
+                reject(error);
+            });
+            if (typeof server.closeIdleConnections === "function") {
+                server.closeIdleConnections();
+            }
+            if (typeof server.closeAllConnections === "function") {
+                server.closeAllConnections();
+            }
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+function closeWsServer(wsServer) {
+    return new Promise((resolve, reject) => {
+        try {
+            wsServer.close((error) => {
+                if (!error) {
+                    resolve();
+                    return;
+                }
+                reject(error);
+            });
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+function terminateWsClients(wsServer) {
+    for (const client of wsServer.clients) {
+        try {
+            client.terminate();
+        }
+        catch {
+            // no-op
+        }
+    }
+}
+function isServerNotRunningError(error) {
+    return error.code === "ERR_SERVER_NOT_RUNNING";
+}

package/dist/server/server/bootstrap/shutdown.test.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const shutdown_1 = require("./shutdown");
+(0, vitest_1.describe)("createShutdownHandler", () => {
+    (0, vitest_1.it)("stops monitor, closes server, closes workers, then exits", async () => {
+        const statusMonitor = {
+            stop: vitest_1.vi.fn()
+        };
+        const server = {
+            close: vitest_1.vi.fn((callback) => {
+                callback();
+            })
+        };
+        const workers = {
+            close: vitest_1.vi.fn()
+        };
+        const exit = vitest_1.vi.fn();
+        const shutdown = (0, shutdown_1.createShutdownHandler)({
+            statusMonitor,
+            server,
+            workers,
+            timeoutMs: 250,
+            exit
+        });
+        await shutdown();
+        (0, vitest_1.expect)(statusMonitor.stop).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(server.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(workers.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(exit).toHaveBeenCalledWith(0);
+        const stopOrder = statusMonitor.stop.mock.invocationCallOrder[0] ?? 0;
+        const closeOrder = server.close.mock.invocationCallOrder[0] ?? 0;
+        const workersOrder = workers.close.mock.invocationCallOrder[0] ?? 0;
+        const exitOrder = exit.mock.invocationCallOrder[0] ?? 0;
+        (0, vitest_1.expect)(stopOrder).toBeLessThan(closeOrder);
+        (0, vitest_1.expect)(closeOrder).toBeLessThan(workersOrder);
+        (0, vitest_1.expect)(workersOrder).toBeLessThan(exitOrder);
+    });
+    (0, vitest_1.it)("runs shutdown cleanup only once for duplicate invocations", async () => {
+        const statusMonitor = {
+            stop: vitest_1.vi.fn()
+        };
+        const server = {
+            close: vitest_1.vi.fn((callback) => {
+                callback();
+            })
+        };
+        const workers = {
+            close: vitest_1.vi.fn()
+        };
+        const exit = vitest_1.vi.fn();
+        const shutdown = (0, shutdown_1.createShutdownHandler)({
+            statusMonitor,
+            server,
+            workers,
+            timeoutMs: 250,
+            exit
+        });
+        await Promise.all([shutdown(), shutdown()]);
+        (0, vitest_1.expect)(statusMonitor.stop).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(server.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(workers.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(exit).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)("terminates websocket clients and closes websocket servers", async () => {
+        const statusMonitor = {
+            stop: vitest_1.vi.fn()
+        };
+        const server = {
+            close: vitest_1.vi.fn((callback) => {
+                callback();
+            })
+        };
+        const workers = {
+            close: vitest_1.vi.fn()
+        };
+        const exit = vitest_1.vi.fn();
+        const terminateRealtimeClient = vitest_1.vi.fn();
+        const terminateTerminalClient = vitest_1.vi.fn();
+        const realtimeWss = {
+            clients: new Set([{ terminate: terminateRealtimeClient }]),
+            close: vitest_1.vi.fn((callback) => {
+                callback();
+            })
+        };
+        const terminalWss = {
+            clients: new Set([{ terminate: terminateTerminalClient }]),
+            close: vitest_1.vi.fn((callback) => {
+                callback();
+            })
+        };
+        const shutdown = (0, shutdown_1.createShutdownHandler)({
+            statusMonitor,
+            server,
+            workers,
+            wsServers: {
+                realtimeWss,
+                terminalWss
+            },
+            timeoutMs: 250,
+            exit
+        });
+        await shutdown();
+        (0, vitest_1.expect)(terminateRealtimeClient).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(terminateTerminalClient).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(realtimeWss.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(terminalWss.close).toHaveBeenCalledTimes(1);
+        const realtimeTerminateOrder = terminateRealtimeClient.mock.invocationCallOrder[0] ?? 0;
+        const realtimeCloseOrder = realtimeWss.close.mock.invocationCallOrder[0] ?? 0;
+        const serverCloseOrder = server.close.mock.invocationCallOrder[0] ?? 0;
+        (0, vitest_1.expect)(realtimeTerminateOrder).toBeLessThan(realtimeCloseOrder);
+        (0, vitest_1.expect)(realtimeCloseOrder).toBeLessThan(serverCloseOrder);
+    });
+    (0, vitest_1.it)("exits with timeout fallback when server close never resolves", async () => {
+        vitest_1.vi.useFakeTimers();
+        const statusMonitor = {
+            stop: vitest_1.vi.fn()
+        };
+        const server = {
+            close: vitest_1.vi.fn((_callback) => {
+                // Never calls back.
+            })
+        };
+        const workers = {
+            close: vitest_1.vi.fn()
+        };
+        const exit = vitest_1.vi.fn();
+        const shutdown = (0, shutdown_1.createShutdownHandler)({
+            statusMonitor,
+            server,
+            workers,
+            timeoutMs: 50,
+            exit
+        });
+        const pending = shutdown();
+        await vitest_1.vi.advanceTimersByTimeAsync(50);
+        await pending;
+        (0, vitest_1.expect)(exit).toHaveBeenCalledWith(1);
+        (0, vitest_1.expect)(workers.close).not.toHaveBeenCalled();
+        vitest_1.vi.useRealTimers();
+    });
+});

package/dist/server/server/bootstrap/websocketUpgrade.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWsServers = createWsServers;
+exports.attachUpgradeHandler = attachUpgradeHandler;
+exports.decodeTerminalWorkerId = decodeTerminalWorkerId;
+const ws_1 = require("ws");
+const terminalPathPrefix = "/api/terminal/";
+const validWorkerIdPattern = /^[A-Za-z0-9_-]{1,128}$/;
+function createWsServers(context) {
+    const realtimeWss = new ws_1.WebSocketServer({ noServer: true });
+    realtimeWss.on("connection", (socket) => {
+        context.hub.addClient(socket);
+        const initialEvent = {
+            type: "init",
+            workers: context.orchestrator.listWorkers(),
+            config: context.orchestrator.getConfig()
+        };
+        context.hub.sendTo(socket, initialEvent);
+    });
+    const terminalWss = new ws_1.WebSocketServer({ noServer: true });
+    terminalWss.on("connection", (socket) => {
+        const workerId = socket.workerId;
+        if (!workerId) {
+            socket.close(1008, "Invalid agent id");
+            return;
+        }
+        try {
+            context.terminalBridge.connect(workerId, socket);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(`[arcane-agents] terminal connection error for ${workerId}: ${detail}`);
+            if (socket.readyState === socket.OPEN) {
+                socket.close(1011, "Terminal connection failed");
+            }
+        }
+    });
+    return {
+        realtimeWss,
+        terminalWss
+    };
+}
+function attachUpgradeHandler(server, { realtimeWss, terminalWss }) {
+    server.on("upgrade", (request, socket, head) => {
+        const requestUrl = parseRequestUrl(request);
+        if (!requestUrl) {
+            rejectUpgrade(socket, 400, "Bad Request");
+            return;
+        }
+        const pathname = requestUrl.pathname;
+        if (pathname === "/api/ws") {
+            try {
+                realtimeWss.handleUpgrade(request, socket, head, (websocket) => {
+                    realtimeWss.emit("connection", websocket, request);
+                });
+            }
+            catch {
+                rejectUpgrade(socket, 500, "Internal Server Error");
+            }
+            return;
+        }
+        if (pathname.startsWith(terminalPathPrefix)) {
+            const workerId = decodeTerminalWorkerId(pathname.slice(terminalPathPrefix.length));
+            if (!workerId) {
+                rejectUpgrade(socket, 400, "Bad Request");
+                return;
+            }
+            try {
+                terminalWss.handleUpgrade(request, socket, head, (websocket) => {
+                    websocket.workerId = workerId;
+                    terminalWss.emit("connection", websocket, request);
+                });
+            }
+            catch {
+                rejectUpgrade(socket, 500, "Internal Server Error");
+            }
+            return;
+        }
+        rejectUpgrade(socket, 404, "Not Found");
+    });
+}
+function decodeTerminalWorkerId(rawPathToken) {
+    if (!rawPathToken) {
+        return undefined;
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rawPathToken);
+    }
+    catch {
+        return undefined;
+    }
+    if (!validWorkerIdPattern.test(decoded)) {
+        return undefined;
+    }
+    return decoded;
+}
+function parseRequestUrl(request) {
+    try {
+        return new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+function rejectUpgrade(socket, statusCode, statusText) {
+    if (socket.writable) {
+        socket.write(`HTTP/1.1 ${statusCode} ${statusText}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+    }
+    socket.destroy();
+}

package/dist/server/server/bootstrap/websocketUpgrade.test.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_events_1 = require("node:events");
+const vitest_1 = require("vitest");
+const websocketUpgrade_1 = require("./websocketUpgrade");
+class FakeSocket {
+    writable = true;
+    write = vitest_1.vi.fn();
+    destroy = vitest_1.vi.fn();
+}
+function createRequest(url) {
+    return {
+        url,
+        headers: {
+            host: "localhost:7601"
+        }
+    };
+}
+function createWsServers() {
+    const realtimeHandleUpgrade = vitest_1.vi.fn((_request, _socket, _head, callback) => {
+        callback({});
+    });
+    const terminalEmit = vitest_1.vi.fn();
+    const terminalHandleUpgrade = vitest_1.vi.fn((_request, _socket, _head, callback) => {
+        callback({});
+    });
+    return {
+        servers: {
+            realtimeWss: {
+                handleUpgrade: realtimeHandleUpgrade,
+                emit: vitest_1.vi.fn()
+            },
+            terminalWss: {
+                handleUpgrade: terminalHandleUpgrade,
+                emit: terminalEmit
+            }
+        },
+        realtimeHandleUpgrade,
+        terminalHandleUpgrade,
+        terminalEmit
+    };
+}
+(0, vitest_1.describe)("decodeTerminalWorkerId", () => {
+    (0, vitest_1.it)("accepts valid worker IDs and rejects malformed tokens", () => {
+        (0, vitest_1.expect)((0, websocketUpgrade_1.decodeTerminalWorkerId)("worker-1")).toBe("worker-1");
+        (0, vitest_1.expect)((0, websocketUpgrade_1.decodeTerminalWorkerId)("worker_1")).toBe("worker_1");
+        (0, vitest_1.expect)((0, websocketUpgrade_1.decodeTerminalWorkerId)("worker%2F1")).toBeUndefined();
+        (0, vitest_1.expect)((0, websocketUpgrade_1.decodeTerminalWorkerId)("%E0%A4%A")).toBeUndefined();
+        (0, vitest_1.expect)((0, websocketUpgrade_1.decodeTerminalWorkerId)("")).toBeUndefined();
+    });
+});
+(0, vitest_1.describe)("attachUpgradeHandler", () => {
+    (0, vitest_1.it)("rejects malformed terminal worker IDs with a clean 400 response", () => {
+        const server = new node_events_1.EventEmitter();
+        const { servers, terminalHandleUpgrade } = createWsServers();
+        (0, websocketUpgrade_1.attachUpgradeHandler)(server, servers);
+        const socket = new FakeSocket();
+        server.emit("upgrade", createRequest("/api/terminal/%E0%A4%A"), socket, Buffer.alloc(0));
+        (0, vitest_1.expect)(terminalHandleUpgrade).not.toHaveBeenCalled();
+        (0, vitest_1.expect)(socket.write).toHaveBeenCalledWith(vitest_1.expect.stringContaining("400 Bad Request"));
+        (0, vitest_1.expect)(socket.destroy).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)("rejects unknown websocket paths with a clean 404 response", () => {
+        const server = new node_events_1.EventEmitter();
+        const { servers } = createWsServers();
+        (0, websocketUpgrade_1.attachUpgradeHandler)(server, servers);
+        const socket = new FakeSocket();
+        server.emit("upgrade", createRequest("/api/unknown"), socket, Buffer.alloc(0));
+        (0, vitest_1.expect)(socket.write).toHaveBeenCalledWith(vitest_1.expect.stringContaining("404 Not Found"));
+        (0, vitest_1.expect)(socket.destroy).toHaveBeenCalledTimes(1);
+    });
+    (0, vitest_1.it)("upgrades valid terminal websocket requests", () => {
+        const server = new node_events_1.EventEmitter();
+        const { servers, terminalHandleUpgrade, terminalEmit } = createWsServers();
+        (0, websocketUpgrade_1.attachUpgradeHandler)(server, servers);
+        const socket = new FakeSocket();
+        server.emit("upgrade", createRequest("/api/terminal/worker-22"), socket, Buffer.alloc(0));
+        (0, vitest_1.expect)(terminalHandleUpgrade).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(terminalEmit).toHaveBeenCalledTimes(1);
+        const [, websocket] = terminalEmit.mock.calls[0] ?? [];
+        (0, vitest_1.expect)(websocket.workerId).toBe("worker-22");
+    });
+});