hivehq 2.0.0

package/dist/src/server/terminal-flow-control.js

@@ -0,0 +1,116 @@
+export const FLOW_CONTROL = {
+    BATCH_INTERVAL_MS: 4,
+    LOW_LATENCY_THRESHOLD_BYTES: 256,
+    WS_BUFFERED_HIGH_WATER: 16 * 1024,
+    WS_BUFFERED_LOW_WATER: 8 * 1024,
+    UNACKED_HIGH_WATER: 100 * 1024,
+    UNACKED_LOW_WATER: 50 * 1024,
+};
+const LOW_LATENCY_IDLE_WINDOW_MS = 5;
+const RESUME_CHECK_INTERVAL_MS = 16;
+const getTransportSocket = (ws) => {
+    return (ws._socket ?? null);
+};
+const byteLength = (chunk) => Buffer.byteLength(chunk, 'utf8');
+export const createTerminalOutputFlow = (ws, { onBackpressureChange }) => {
+    let closed = false;
+    let flushTimer = null;
+    let lastSentAt = 0;
+    let pendingChunks = [];
+    let resumeCheckTimer = null;
+    let paused = false;
+    let unackedBytes = 0;
+    const shouldPause = () => {
+        return (ws.bufferedAmount >= FLOW_CONTROL.WS_BUFFERED_HIGH_WATER ||
+            unackedBytes >= FLOW_CONTROL.UNACKED_HIGH_WATER);
+    };
+    const canResume = () => {
+        return (ws.bufferedAmount < FLOW_CONTROL.WS_BUFFERED_LOW_WATER &&
+            unackedBytes < FLOW_CONTROL.UNACKED_LOW_WATER);
+    };
+    const clearResumeCheck = () => {
+        if (resumeCheckTimer)
+            clearTimeout(resumeCheckTimer);
+        resumeCheckTimer = null;
+        getTransportSocket(ws)?.removeListener('drain', checkResume);
+    };
+    const scheduleResumeCheck = () => {
+        if (!paused || closed)
+            return;
+        clearResumeCheck();
+        getTransportSocket(ws)?.once('drain', checkResume);
+        resumeCheckTimer = setTimeout(checkResume, RESUME_CHECK_INTERVAL_MS);
+    };
+    const checkResume = () => {
+        if (!paused || closed) {
+            clearResumeCheck();
+            return;
+        }
+        if (canResume()) {
+            paused = false;
+            clearResumeCheck();
+            onBackpressureChange(false);
+            return;
+        }
+        scheduleResumeCheck();
+    };
+    const afterSend = (bytes) => {
+        if (closed || paused)
+            return;
+        unackedBytes += bytes;
+        if (shouldPause()) {
+            paused = true;
+            onBackpressureChange(true);
+            scheduleResumeCheck();
+        }
+    };
+    const sendChunk = (chunk) => {
+        if (closed || ws.readyState !== ws.OPEN)
+            return;
+        ws.send(chunk);
+        lastSentAt = Date.now();
+        afterSend(byteLength(chunk));
+    };
+    const flush = () => {
+        flushTimer = null;
+        if (pendingChunks.length === 0)
+            return;
+        const chunk = pendingChunks.join('');
+        pendingChunks = [];
+        sendChunk(chunk);
+    };
+    return {
+        ack(bytes) {
+            unackedBytes = Math.max(0, unackedBytes - Math.max(0, Math.floor(bytes)));
+            checkResume();
+        },
+        close() {
+            closed = true;
+            if (flushTimer)
+                clearTimeout(flushTimer);
+            flushTimer = null;
+            clearResumeCheck();
+            if (paused) {
+                paused = false;
+                onBackpressureChange(false);
+            }
+            pendingChunks = [];
+        },
+        enqueue(chunk) {
+            if (closed)
+                return;
+            const now = Date.now();
+            const isLowLatency = pendingChunks.length === 0 &&
+                flushTimer === null &&
+                byteLength(chunk) < FLOW_CONTROL.LOW_LATENCY_THRESHOLD_BYTES &&
+                now - lastSentAt >= LOW_LATENCY_IDLE_WINDOW_MS;
+            if (isLowLatency) {
+                sendChunk(chunk);
+                return;
+            }
+            pendingChunks.push(chunk);
+            if (!flushTimer)
+                flushTimer = setTimeout(flush, FLOW_CONTROL.BATCH_INTERVAL_MS);
+        },
+    };
+};

package/dist/src/server/terminal-input-profile.d.ts

@@ -0,0 +1,10 @@
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+export type TerminalInputProfile = 'default' | 'opencode';
+export interface TerminalRunSummary {
+    agent_id: string;
+    agent_name: string;
+    run_id: string;
+    status: string;
+    terminal_input_profile: TerminalInputProfile;
+}
+export declare const resolveTerminalInputProfile: (config: AgentLaunchConfigInput | undefined) => TerminalInputProfile;

package/dist/src/server/terminal-input-profile.js

@@ -0,0 +1,9 @@
+import { normalizeExecutableToken } from './startup-command-parser.js';
+export const resolveTerminalInputProfile = (config) => {
+    if (!config)
+        return 'default';
+    if (config.commandPresetId === 'opencode')
+        return 'opencode';
+    const executable = normalizeExecutableToken(config.interactiveCommand) ?? normalizeExecutableToken(config.command);
+    return executable === 'opencode' ? 'opencode' : 'default';
+};

package/dist/src/server/terminal-protocol.d.ts

@@ -0,0 +1,29 @@
+type TerminalControlClientMessage = {
+    type: 'output_ack';
+    bytes: number;
+} | {
+    type: 'resize';
+    cols: number;
+    rows: number;
+    pixelWidth?: number;
+    pixelHeight?: number;
+} | {
+    type: 'restore_complete';
+} | {
+    type: 'stop';
+};
+type TerminalControlServerMessage = {
+    type: 'error';
+    message: string;
+} | {
+    type: 'exit';
+    code: number | null;
+} | {
+    type: 'restore';
+    snapshot: string;
+};
+export declare const parseTerminalControlMessage: (raw: Buffer | string) => TerminalControlClientMessage;
+export declare const serializeTerminalError: (message: string) => string;
+export declare const serializeTerminalExit: (code: number | null) => string;
+export declare const serializeTerminalRestore: (snapshot: string) => string;
+export type { TerminalControlClientMessage, TerminalControlServerMessage };

package/dist/src/server/terminal-protocol.js

@@ -0,0 +1,47 @@
+const asInteger = (value) => {
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+};
+export const parseTerminalControlMessage = (raw) => {
+    const parsed = JSON.parse(raw.toString());
+    const { bytes, cols, rows, pixelHeight, pixelWidth } = parsed;
+    if (parsed.type === 'stop')
+        return { type: 'stop' };
+    if (parsed.type === 'restore_complete')
+        return { type: 'restore_complete' };
+    const ackBytes = asInteger(bytes);
+    if (parsed.type === 'output_ack' && ackBytes !== undefined && ackBytes >= 0) {
+        return { type: 'output_ack', bytes: ackBytes };
+    }
+    const resizeCols = asInteger(cols);
+    const resizeRows = asInteger(rows);
+    if (parsed.type === 'resize' &&
+        resizeCols !== undefined &&
+        resizeRows !== undefined &&
+        resizeCols > 0 &&
+        resizeRows > 0) {
+        const message = {
+            type: 'resize',
+            cols: resizeCols,
+            rows: resizeRows,
+        };
+        const parsedPixelWidth = asInteger(pixelWidth);
+        const parsedPixelHeight = asInteger(pixelHeight);
+        if (parsedPixelWidth !== undefined && parsedPixelWidth >= 0) {
+            message.pixelWidth = parsedPixelWidth;
+        }
+        if (parsedPixelHeight !== undefined && parsedPixelHeight >= 0) {
+            message.pixelHeight = parsedPixelHeight;
+        }
+        return message;
+    }
+    throw new Error('Invalid terminal control message');
+};
+export const serializeTerminalError = (message) => {
+    return JSON.stringify({ type: 'error', message });
+};
+export const serializeTerminalExit = (code) => {
+    return JSON.stringify({ type: 'exit', code });
+};
+export const serializeTerminalRestore = (snapshot) => {
+    return JSON.stringify({ type: 'restore', snapshot });
+};

package/dist/src/server/terminal-state-mirror.d.ts

@@ -0,0 +1,21 @@
+export declare const TERMINAL_SCROLLBACK = 10000;
+export interface TerminalMirrorSize {
+    cols: number;
+    rows: number;
+}
+export declare class TerminalStateMirror {
+    private readonly serializeAddon;
+    private readonly terminal;
+    private operationQueue;
+    constructor(size?: TerminalMirrorSize);
+    dispose(): void;
+    getSnapshot(): Promise<string>;
+    /**
+     * Returns the most recent non-empty scrollback line (trimmed, ANSI-stripped,
+     * truncated to `maxLen`). Returns `null` when scrollback has no printable
+     * content, so the wire protocol can express "no output yet" as a null.
+     */
+    lastPtyLine(maxLen?: number): string | null;
+    resize(cols: number, rows: number): void;
+    write(chunk: string): void;
+}

package/dist/src/server/terminal-state-mirror.js

@@ -0,0 +1,67 @@
+import serializeAddonModule from '@xterm/addon-serialize';
+import headlessTerminalModule from '@xterm/headless';
+const { SerializeAddon } = serializeAddonModule;
+const { Terminal } = headlessTerminalModule;
+export const TERMINAL_SCROLLBACK = 10_000;
+const normalizeTerminalSize = ({ cols, rows }) => ({
+    cols: Math.max(1, Math.floor(cols)),
+    rows: Math.max(1, Math.floor(rows)),
+});
+// Strips CSI escape sequences emitted by interactive CLIs (color, cursor moves,
+// etc.) before exposing a single line of scrollback to JSON consumers. Built
+// from a String so the regex source does not embed a literal control character
+// (lint/suspicious/noControlCharactersInRegex would otherwise flag the file).
+const ANSI_CSI_PATTERN = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;?]*[a-zA-Z]`, 'g');
+export class TerminalStateMirror {
+    serializeAddon = new SerializeAddon();
+    terminal;
+    operationQueue = Promise.resolve();
+    constructor(size = { cols: 80, rows: 24 }) {
+        const normalized = normalizeTerminalSize(size);
+        this.terminal = new Terminal({
+            allowProposedApi: true,
+            cols: normalized.cols,
+            rows: normalized.rows,
+            scrollback: TERMINAL_SCROLLBACK,
+        });
+        this.terminal.loadAddon(this.serializeAddon);
+    }
+    dispose() {
+        this.terminal.dispose();
+    }
+    async getSnapshot() {
+        await this.operationQueue;
+        return this.serializeAddon.serialize();
+    }
+    /**
+     * Returns the most recent non-empty scrollback line (trimmed, ANSI-stripped,
+     * truncated to `maxLen`). Returns `null` when scrollback has no printable
+     * content, so the wire protocol can express "no output yet" as a null.
+     */
+    lastPtyLine(maxLen = 60) {
+        const buffer = this.terminal.buffer.active;
+        for (let row = buffer.length - 1; row >= 0; row -= 1) {
+            const raw = buffer.getLine(row)?.translateToString(true) ?? '';
+            const cleaned = raw.replace(ANSI_CSI_PATTERN, '').trim();
+            if (cleaned.length === 0)
+                continue;
+            return cleaned.slice(0, maxLen);
+        }
+        return null;
+    }
+    resize(cols, rows) {
+        const normalized = normalizeTerminalSize({ cols, rows });
+        this.operationQueue = this.operationQueue
+            .catch(() => undefined)
+            .then(() => {
+            this.terminal.resize(normalized.cols, normalized.rows);
+        });
+    }
+    write(chunk) {
+        this.operationQueue = this.operationQueue
+            .catch(() => undefined)
+            .then(() => new Promise((resolve) => {
+            this.terminal.write(chunk, () => resolve());
+        }));
+    }
+}

package/dist/src/server/terminal-stream-hub.d.ts

@@ -0,0 +1,9 @@
+import type WebSocket from 'ws';
+import type { RuntimeStore } from './runtime-store.js';
+import { type TerminalMirrorSize } from './terminal-state-mirror.js';
+export interface TerminalStreamHub {
+    attachControl: (runId: string, clientId: string, socket: WebSocket, initialSize?: TerminalMirrorSize) => void;
+    attachIo: (runId: string, clientId: string, socket: WebSocket, initialSize?: TerminalMirrorSize) => void;
+    close: () => void;
+}
+export declare const createTerminalStreamHub: (store: RuntimeStore) => TerminalStreamHub;

package/dist/src/server/terminal-stream-hub.js

@@ -0,0 +1,192 @@
+import { createTerminalOutputFlow } from './terminal-flow-control.js';
+import { parseTerminalControlMessage, serializeTerminalError, serializeTerminalExit, serializeTerminalRestore, } from './terminal-protocol.js';
+import { TerminalStateMirror } from './terminal-state-mirror.js';
+import { attachWebSocketErrorHandler, sendWebSocketMessage } from './websocket-upgrade-safety.js';
+const normalizeTerminalInput = (raw, isBinary) => {
+    const bytes = Buffer.isBuffer(raw)
+        ? raw
+        : Array.isArray(raw)
+            ? Buffer.concat(raw)
+            : Buffer.from(raw);
+    return isBinary ? Buffer.from(bytes) : bytes.toString();
+};
+export const createTerminalStreamHub = (store) => {
+    const runStates = new Map();
+    const maybeResumeRun = (runId, state, clientId) => {
+        if (!state.backpressuredViewerIds.delete(clientId))
+            return;
+        if (state.backpressuredViewerIds.size === 0)
+            store.resumeTerminalRun(runId);
+    };
+    const cleanupRun = (runId) => {
+        const state = runStates.get(runId);
+        if (!state?.exited || state.viewers.size > 0)
+            return;
+        state.outputUnsubscribe?.();
+        if (state.exitInterval)
+            clearInterval(state.exitInterval);
+        state.mirror.dispose();
+        runStates.delete(runId);
+    };
+    const getOrCreateViewer = (state, clientId) => {
+        let viewer = state.viewers.get(clientId);
+        if (!viewer) {
+            viewer = { clientId, controlSocket: null, flowState: null, ioSocket: null };
+            state.viewers.set(clientId, viewer);
+        }
+        return viewer;
+    };
+    const getOrCreateState = (runId, initialSize) => {
+        let state = runStates.get(runId);
+        if (!state) {
+            state = {
+                backpressuredViewerIds: new Set(),
+                exited: false,
+                exitInterval: null,
+                // runId is globally unique, so it is semantically equivalent to workspaceId:runId.
+                mirror: new TerminalStateMirror(initialSize),
+                outputUnsubscribe: null,
+                viewers: new Map(),
+            };
+            runStates.set(runId, state);
+            const liveRun = store.getLiveRun(runId);
+            if (liveRun.output.length > 0)
+                state.mirror.write(liveRun.output);
+            const nextState = state;
+            nextState.outputUnsubscribe = store.getPtyOutputBus().subscribe(runId, (chunk) => {
+                nextState.mirror.write(chunk);
+                for (const viewer of nextState.viewers.values())
+                    viewer.flowState?.enqueue(chunk);
+            });
+        }
+        else if (initialSize) {
+            state.mirror.resize(initialSize.cols, initialSize.rows);
+        }
+        return state;
+    };
+    const cleanupViewer = (runId, state, clientId) => {
+        const viewer = state.viewers.get(clientId);
+        if (!viewer || viewer.controlSocket || viewer.ioSocket)
+            return;
+        state.viewers.delete(clientId);
+        maybeResumeRun(runId, state, clientId);
+        cleanupRun(runId);
+    };
+    const startExitWatcher = (runId, state) => {
+        if (state.exitInterval)
+            return;
+        state.exitInterval = setInterval(() => {
+            try {
+                const run = store.getLiveRun(runId);
+                if (run.status !== 'exited' && run.status !== 'error')
+                    return;
+                state.exited = true;
+                state.outputUnsubscribe?.();
+                state.outputUnsubscribe = null;
+                const payload = serializeTerminalExit(run.exitCode);
+                for (const viewer of state.viewers.values()) {
+                    const controlSocket = viewer.controlSocket;
+                    if (controlSocket)
+                        sendWebSocketMessage(controlSocket, payload, `terminal ${runId} exit`);
+                }
+                if (state.exitInterval)
+                    clearInterval(state.exitInterval);
+                state.exitInterval = null;
+                cleanupRun(runId);
+            }
+            catch {
+                if (state.exitInterval)
+                    clearInterval(state.exitInterval);
+                state.exitInterval = null;
+            }
+        }, 25);
+    };
+    return {
+        attachControl(runId, clientId, socket, initialSize) {
+            const state = getOrCreateState(runId, initialSize);
+            attachWebSocketErrorHandler(socket, `terminal ${runId} control`);
+            const viewer = getOrCreateViewer(state, clientId);
+            viewer.controlSocket = socket;
+            startExitWatcher(runId, state);
+            void state.mirror
+                .getSnapshot()
+                .then((snapshot) => {
+                sendWebSocketMessage(socket, serializeTerminalRestore(snapshot), `terminal ${runId} restore`);
+            })
+                .catch(() => {
+                sendWebSocketMessage(socket, serializeTerminalRestore(''), `terminal ${runId} restore`);
+            });
+            socket.on('message', (raw) => {
+                try {
+                    const message = parseTerminalControlMessage(raw);
+                    if (message.type === 'output_ack')
+                        viewer.flowState?.ack(message.bytes);
+                    if (message.type === 'resize') {
+                        state.mirror.resize(message.cols, message.rows);
+                        store.resizeAgentRun(runId, message.cols, message.rows);
+                    }
+                    if (message.type === 'stop')
+                        store.stopAgentRun(runId);
+                    if (message.type === 'restore_complete')
+                        return;
+                }
+                catch (error) {
+                    sendWebSocketMessage(socket, serializeTerminalError(error instanceof Error ? error.message : 'Invalid control message'), `terminal ${runId} control error`);
+                }
+            });
+            socket.on('close', () => {
+                if (viewer.controlSocket === socket)
+                    viewer.controlSocket = null;
+                cleanupViewer(runId, state, clientId);
+            });
+        },
+        attachIo(runId, clientId, socket, initialSize) {
+            const state = getOrCreateState(runId, initialSize);
+            attachWebSocketErrorHandler(socket, `terminal ${runId} io`);
+            const viewer = getOrCreateViewer(state, clientId);
+            viewer.ioSocket = socket;
+            viewer.flowState?.close();
+            viewer.flowState = createTerminalOutputFlow(socket, {
+                onBackpressureChange(backpressured) {
+                    if (backpressured) {
+                        const wasEmpty = state.backpressuredViewerIds.size === 0;
+                        state.backpressuredViewerIds.add(clientId);
+                        if (wasEmpty)
+                            store.pauseTerminalRun(runId);
+                        return;
+                    }
+                    maybeResumeRun(runId, state, clientId);
+                },
+            });
+            socket.on('message', (raw, isBinary) => {
+                try {
+                    store.writeRunInput(runId, normalizeTerminalInput(raw, isBinary));
+                }
+                catch (error) {
+                    sendWebSocketMessage(socket, serializeTerminalError(error instanceof Error ? error.message : 'Failed to write terminal input'), `terminal ${runId} input error`);
+                }
+            });
+            socket.on('close', () => {
+                if (viewer.ioSocket === socket)
+                    viewer.ioSocket = null;
+                viewer.flowState?.close();
+                viewer.flowState = null;
+                cleanupViewer(runId, state, clientId);
+            });
+        },
+        close() {
+            for (const [runId, state] of runStates) {
+                state.outputUnsubscribe?.();
+                if (state.exitInterval)
+                    clearInterval(state.exitInterval);
+                state.mirror.dispose();
+                for (const viewer of state.viewers.values()) {
+                    viewer.flowState?.close();
+                    viewer.ioSocket?.terminate();
+                    viewer.controlSocket?.terminate();
+                }
+                runStates.delete(runId);
+            }
+        },
+    };
+};

package/dist/src/server/terminal-ws-server.d.ts

@@ -0,0 +1,6 @@
+import type { Server } from 'node:http';
+import type { RuntimeStore } from './runtime-store.js';
+import type { TasksFileService } from './tasks-file.js';
+export declare const createTerminalWebSocketServer: (server: Server, store: RuntimeStore, tasksFileService: Pick<TasksFileService, "readTasks">) => {
+    close: () => void;
+};

package/dist/src/server/terminal-ws-server.js

@@ -0,0 +1,115 @@
+import { WebSocketServer } from 'ws';
+import { getLocalRequestRejection } from './local-request-guard.js';
+import { createTasksWebSocketServer } from './tasks-websocket-server.js';
+import { createTerminalStreamHub } from './terminal-stream-hub.js';
+import { readCookie } from './ui-auth-helpers.js';
+import { attachRawSocketErrorHandler, attachWebSocketServerErrorHandler, rejectWebSocketUpgrade, } from './websocket-upgrade-safety.js';
+const matchTerminalPath = (pathname) => {
+    const match = /^\/ws\/terminal\/(?<runId>[^/]+)\/(?<channel>io|control)$/.exec(pathname);
+    const groups = match?.groups;
+    if (!groups?.runId || !groups.channel)
+        return null;
+    return {
+        channel: groups.channel,
+        runId: decodeURIComponent(groups.runId),
+    };
+};
+const getClientId = (url) => {
+    return url.searchParams.get('clientId')?.trim() || 'legacy';
+};
+const getInitialSize = (url) => {
+    const cols = Number(url.searchParams.get('cols'));
+    const rows = Number(url.searchParams.get('rows'));
+    if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols <= 0 || rows <= 0) {
+        return undefined;
+    }
+    return { cols, rows };
+};
+export const createTerminalWebSocketServer = (server, store, tasksFileService) => {
+    const ioWss = new WebSocketServer({ noServer: true });
+    const controlWss = new WebSocketServer({ noServer: true });
+    attachWebSocketServerErrorHandler(ioWss, 'terminal io');
+    attachWebSocketServerErrorHandler(controlWss, 'terminal control');
+    const tasksWss = createTasksWebSocketServer(server, store, tasksFileService);
+    const hub = createTerminalStreamHub(store);
+    const disposeTasksListener = store.registerTasksListener((workspaceId, content) => {
+        tasksWss.publish(workspaceId, content);
+    });
+    const validateUpgradeSession = (request) => {
+        // Tunnel-originated upgrades carry the per-boot secret (invariant 2). A
+        // request with no secret header falls straight to the cookie path, so
+        // browser behavior is unchanged. getLocalRequestRejection still runs in
+        // front (loopback Host), so this is reachable only from 127.0.0.1.
+        if (store.authorizeRemoteTunnelRequest(request))
+            return true;
+        const cookieHeader = Array.isArray(request.headers.cookie)
+            ? request.headers.cookie.join('; ')
+            : request.headers.cookie;
+        const token = readCookie(cookieHeader, 'hive_ui_token');
+        return store.validateUiToken(token);
+    };
+    let closed = false;
+    const closeAll = () => {
+        if (closed)
+            return;
+        closed = true;
+        // Order matters: dispose the publisher first so no new frames are
+        // queued onto sockets that are about to be torn down. Then forcibly
+        // terminate any open WS clients (terminate() skips the close
+        // handshake, which is what we need — a polite ws.close() would wait
+        // on the remote side and re-introduce the hang we're fixing).
+        disposeTasksListener();
+        for (const ws of ioWss.clients)
+            ws.terminate();
+        for (const ws of controlWss.clients)
+            ws.terminate();
+        tasksWss.close();
+        ioWss.close();
+        controlWss.close();
+        hub.close();
+    };
+    server.on('upgrade', (request, socket, head) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        const pathname = url.pathname;
+        const match = matchTerminalPath(pathname);
+        if (!match) {
+            if (/^\/ws\/tasks\/.+/.test(pathname)) {
+                return;
+            }
+            attachRawSocketErrorHandler(socket, 'terminal upgrade');
+            rejectWebSocketUpgrade(socket, '404 Not Found');
+            return;
+        }
+        const detachRawSocketErrorHandler = attachRawSocketErrorHandler(socket, 'terminal upgrade');
+        if (getLocalRequestRejection(request)) {
+            rejectWebSocketUpgrade(socket, '403 Forbidden');
+            return;
+        }
+        if (!validateUpgradeSession(request)) {
+            rejectWebSocketUpgrade(socket, '401 Unauthorized');
+            return;
+        }
+        try {
+            store.getLiveRun(match.runId);
+        }
+        catch {
+            rejectWebSocketUpgrade(socket, '404 Not Found');
+            return;
+        }
+        const wss = match.channel === 'io' ? ioWss : controlWss;
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            detachRawSocketErrorHandler();
+            const clientId = getClientId(url);
+            if (match.channel === 'io')
+                hub.attachIo(match.runId, clientId, ws, getInitialSize(url));
+            else
+                hub.attachControl(match.runId, clientId, ws, getInitialSize(url));
+        });
+    });
+    // Kept as an idempotent fallback for callers that drive
+    // `app.server.close()` directly (e.g. unit tests in tests/server/*)
+    // and never see the runHiveCommand close path. closeAll() is guarded
+    // by `closed` so calling both is a no-op.
+    server.on('close', closeAll);
+    return { close: closeAll };
+};

package/dist/src/server/ui-auth-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage } from 'node:http';
+import type { RuntimeStore } from './runtime-store.js';
+export declare const readCookie: (cookieHeader: string | undefined, name: string) => string | undefined;
+export declare const requireUiTokenFromRequest: (request: IncomingMessage, validateUiToken: RuntimeStore["validateUiToken"], authorizeTunnel?: RuntimeStore["authorizeRemoteTunnelRequest"]) => void;

package/dist/src/server/ui-auth-helpers.js

@@ -0,0 +1,28 @@
+import { ForbiddenError } from './http-errors.js';
+export const readCookie = (cookieHeader, name) => {
+    if (!cookieHeader) {
+        return undefined;
+    }
+    for (const part of cookieHeader.split(';')) {
+        const [key, value] = part.trim().split('=');
+        if (key === name) {
+            return value;
+        }
+    }
+    return undefined;
+};
+export const requireUiTokenFromRequest = (request, validateUiToken, authorizeTunnel) => {
+    // Tunnel-originated requests carry the per-boot secret and short-circuit here
+    // (invariant 2). A request with no secret header — every browser, every
+    // existing test — gets authorizeTunnel === false and falls straight to the
+    // cookie path, so cookie behavior is byte-identical (invariant 4).
+    if (authorizeTunnel?.(request))
+        return;
+    const cookieHeader = Array.isArray(request.headers.cookie)
+        ? request.headers.cookie.join('; ')
+        : request.headers.cookie;
+    const token = readCookie(cookieHeader, 'hive_ui_token');
+    if (!validateUiToken(token)) {
+        throw new ForbiddenError('UI endpoint requires valid UI token');
+    }
+};

package/dist/src/server/ui-auth.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage } from 'node:http';
+export interface UiAuth {
+    getToken: () => string;
+    validate: (token: string | undefined) => boolean;
+    isTunnelRequest: (request: IncomingMessage) => boolean;
+    getTunnelSecret: () => string;
+}
+export declare const createUiAuth: () => UiAuth;