@harness-fe/mcp-server 3.0.1

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * CLI entry — boots WS bridge + MCP server (stdio or HTTP).
+ *
+ * Usage:
+ *   npx @harness-fe/mcp-server                # 127.0.0.1, stdio MCP
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto --mcp-transport http
+ *
+ * Leader / follower:
+ *   - first process bound to the WS port = leader (in-process Bridge)
+ *   - subsequent processes (EADDRINUSE) become followers that attach to
+ *     the leader via the `mcp.call` control channel using `RemoteBridge`.
+ *
+ * This lets multiple Claude Code windows share a single dev-bridge daemon
+ * (and thus the same browser / vite-plugin connections).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * CLI entry — boots WS bridge + MCP server (stdio or HTTP).
+ *
+ * Usage:
+ *   npx @harness-fe/mcp-server                # 127.0.0.1, stdio MCP
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto --mcp-transport http
+ *
+ * Leader / follower:
+ *   - first process bound to the WS port = leader (in-process Bridge)
+ *   - subsequent processes (EADDRINUSE) become followers that attach to
+ *     the leader via the `mcp.call` control channel using `RemoteBridge`.
+ *
+ * This lets multiple Claude Code windows share a single dev-bridge daemon
+ * (and thus the same browser / vite-plugin connections).
+ */
+import { randomBytes } from 'node:crypto';
+import { DEFAULT_HOST, DEFAULT_WS_PORT, buildHttpUrl, isLoopbackHost, parseWsUrl, } from '@harness-fe/protocol';
+import { Bridge, defaultDataDir } from './bridge.js';
+import { RemoteBridge } from './remoteBridge.js';
+import { startMcpStdioServer } from './mcp.js';
+import { startMcpHttpServer } from './mcpHttp.js';
+function printHelpAndExit() {
+    const help = `harness-fe — frontend harness MCP daemon
+
+Usage:
+  harness-fe [options]
+
+Options:
+  --host <addr>          Bind address. Default 127.0.0.1.
+                         Use 0.0.0.0 to accept LAN connections (requires --token).
+  --port <number>        TCP port. Default ${DEFAULT_WS_PORT}.
+  --token <value|auto>   Token required for HTTP/WS auth. Pass "auto" to generate one.
+                         Required when --host is not loopback.
+  --mcp-transport <kind> stdio (default) or http. http mounts /mcp on the bridge.
+  --mcp-path <path>      URL path for the MCP HTTP endpoint. Default /mcp.
+  --public-host <addr>   Override the host printed in outbound URLs. Useful when
+                         binding 0.0.0.0 and the auto-detected LAN IP is wrong.
+  -h, --help             Show this help.
+
+Environment:
+  HARNESS_FE_HOST           Same as --host
+  HARNESS_FE_TOKEN          Same as --token (use "auto" to generate)
+  HARNESS_FE_MCP_TRANSPORT  Same as --mcp-transport
+  HARNESS_FE_MCP_PATH       Same as --mcp-path
+  HARNESS_FE_URL            Full ws:// URL (legacy; --host/--port override it)
+`;
+    process.stderr.write(help);
+    process.exit(0);
+}
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let host;
+    let port;
+    let token;
+    let mcpTransport;
+    let mcpPath;
+    let publicHost;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const next = () => {
+            const v = args[++i];
+            if (v == null) {
+                process.stderr.write(`harness-fe: missing value for ${a}\n`);
+                process.exit(2);
+            }
+            return v;
+        };
+        switch (a) {
+            case '-h':
+            case '--help':
+                printHelpAndExit();
+                break;
+            case '--host':
+                host = next();
+                break;
+            case '--port':
+                port = Number(next());
+                if (!Number.isFinite(port) || port <= 0) {
+                    process.stderr.write(`harness-fe: invalid --port\n`);
+                    process.exit(2);
+                }
+                break;
+            case '--token':
+                token = next();
+                break;
+            case '--mcp-transport': {
+                const v = next();
+                if (v !== 'stdio' && v !== 'http') {
+                    process.stderr.write(`harness-fe: invalid --mcp-transport (stdio|http)\n`);
+                    process.exit(2);
+                }
+                mcpTransport = v;
+                break;
+            }
+            case '--mcp-path':
+                mcpPath = next();
+                break;
+            case '--public-host':
+                publicHost = next();
+                break;
+            default:
+                process.stderr.write(`harness-fe: unknown argument ${a}\n`);
+                process.exit(2);
+        }
+    }
+    // Apply env fallbacks, then URL fallback for host/port.
+    const envUrl = process.env.HARNESS_FE_URL;
+    let envHost;
+    let envPort;
+    if (envUrl) {
+        try {
+            const parsed = parseWsUrl(envUrl);
+            envHost = parsed.host;
+            envPort = parsed.port;
+        }
+        catch {
+            // ignore — fall back to defaults below
+        }
+    }
+    const finalHost = host ?? process.env.HARNESS_FE_HOST ?? envHost ?? DEFAULT_HOST;
+    const finalPort = port ?? envPort ?? DEFAULT_WS_PORT;
+    let finalToken = token ?? process.env.HARNESS_FE_TOKEN;
+    if (finalToken === 'auto') {
+        finalToken = randomBytes(24).toString('base64url');
+    }
+    if (finalToken === '')
+        finalToken = undefined;
+    const finalTransport = (mcpTransport ?? process.env.HARNESS_FE_MCP_TRANSPORT) ??
+        'stdio';
+    if (finalTransport !== 'stdio' && finalTransport !== 'http') {
+        process.stderr.write(`harness-fe: invalid mcp transport "${finalTransport}"\n`);
+        process.exit(2);
+    }
+    const finalMcpPath = mcpPath ?? process.env.HARNESS_FE_MCP_PATH ?? '/mcp';
+    // Data dir defaults to port-keyed path. Explicit env override wins.
+    const finalDataDir = process.env.HARNESS_FE_DATA_DIR ?? defaultDataDir(finalPort);
+    const finalLabel = process.env.HARNESS_FE_LABEL || undefined;
+    return {
+        host: finalHost,
+        port: finalPort,
+        token: finalToken,
+        mcpTransport: finalTransport,
+        mcpPath: finalMcpPath,
+        publicHost,
+        label: finalLabel,
+        dataDir: finalDataDir,
+    };
+}
+function validate(_cfg) {
+    // Token requirement is left entirely to the operator. We don't refuse
+    // a non-loopback bind without a token — that's their call, not ours.
+    // Warnings are emitted from the banner so the operator sees them; CI /
+    // automation that pipes stderr can suppress as needed.
+}
+function printBanner(cfg, role, viewerUrl) {
+    const lines = [];
+    const labelSuffix = cfg.label ? `  (${cfg.label})` : '';
+    lines.push(`[harness-fe] ${role}: WS bridge listening on ws://${cfg.host}:${cfg.port}${labelSuffix}`);
+    if (role === 'leader') {
+        // Surface the data dir so the user can see exactly where this
+        // daemon's sessions / recordings / projects are landing.
+        lines.push(`[harness-fe] data:   ${cfg.dataDir}`);
+    }
+    const isLan = !isLoopbackHost(cfg.host);
+    if (isLan) {
+        lines.push(`[harness-fe] WARNING: bound to non-loopback host ${cfg.host}.`);
+        if (cfg.token) {
+            lines.push(`[harness-fe]   anyone reaching this host:port with the token can read console / network / recordings.`);
+        }
+        else {
+            lines.push(`[harness-fe]   no token set — anyone on this network can read console / network / recordings.`);
+            lines.push(`[harness-fe]   add --token auto (or HARNESS_FE_TOKEN=…) to enable auth.`);
+        }
+    }
+    // Always print the dashboard URL. The token (when present) is folded
+    // into the query so the first hit hands it off to a cookie; without a
+    // token, auth is disabled and the URL works on its own.
+    const host = cfg.publicHost ?? viewerHost(viewerUrl) ?? cfg.host;
+    const dashboard = buildHttpUrl({ host, port: cfg.port, token: cfg.token });
+    lines.push(`[harness-fe] dashboard: ${dashboard}`);
+    if (cfg.mcpTransport === 'http') {
+        const mcp = buildHttpUrl({ host, port: cfg.port, token: cfg.token, path: cfg.mcpPath });
+        lines.push(`[harness-fe] mcp http:  ${mcp}`);
+        if (cfg.token) {
+            const mcpNoTok = buildHttpUrl({ host, port: cfg.port, path: cfg.mcpPath });
+            lines.push(`[harness-fe]   agent config: { "url": "${mcpNoTok}", "headers": { "Authorization": "Bearer ${cfg.token}" } }`);
+        }
+        else {
+            lines.push(`[harness-fe]   agent config: { "url": "${mcp}" }   (no auth — token unset)`);
+        }
+    }
+    if (cfg.token) {
+        lines.push(`[harness-fe] token:     ${cfg.token}`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+}
+function viewerHost(viewerUrl) {
+    if (!viewerUrl)
+        return undefined;
+    try {
+        return new URL(viewerUrl).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function main() {
+    const cfg = parseArgs(process.argv);
+    validate(cfg);
+    const { active, shutdown, role } = await startBridgeOrAttach(cfg);
+    printBanner(cfg, role, active.getViewerBaseUrl());
+    let mcpShutdown;
+    if (cfg.mcpTransport === 'stdio') {
+        await startMcpStdioServer(active);
+        process.stderr.write('[harness-fe] MCP stdio server connected\n');
+    }
+    else {
+        if (role === 'follower') {
+            process.stderr.write('[harness-fe] --mcp-transport=http is only supported on the leader. ' +
+                'Another daemon already holds the port; stop it first.\n');
+            await shutdown();
+            process.exit(2);
+        }
+        const handle = await startMcpHttpServer(active, { path: cfg.mcpPath });
+        process.stderr.write(`[harness-fe] MCP http server mounted at ${handle.path}\n`);
+        mcpShutdown = () => handle.close();
+    }
+    const onSignal = async () => {
+        process.stderr.write('[harness-fe] shutting down\n');
+        if (mcpShutdown) {
+            try {
+                await mcpShutdown();
+            }
+            catch { /* swallow */ }
+        }
+        await shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+}
+async function startBridgeOrAttach(cfg) {
+    const bridge = new Bridge({
+        port: cfg.port,
+        host: cfg.host,
+        dataDir: cfg.dataDir,
+        label: cfg.label,
+        auth: cfg.token ? { token: cfg.token } : undefined,
+        publicHost: cfg.publicHost,
+    });
+    try {
+        await bridge.start();
+        return {
+            active: bridge,
+            shutdown: () => bridge.stop(),
+            role: 'leader',
+        };
+    }
+    catch (err) {
+        if (err?.code !== 'EADDRINUSE')
+            throw err;
+    }
+    // Port already taken — attach as follower.
+    const remote = new RemoteBridge({ port: cfg.port, host: cfg.host, token: cfg.token });
+    await remote.connect();
+    return {
+        active: remote,
+        shutdown: () => remote.stop(),
+        role: 'follower',
+    };
+}
+main().catch((err) => {
+    process.stderr.write(`[harness-fe] fatal: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});

package/dist/daemon.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `createDaemon` — programmatic entry point for embedding the harness-fe
+ * daemon inside another Node.js process. Wraps `Bridge` construction +
+ * `startMcpHttpServer` so a host application can boot the daemon with
+ * `import { createDaemon } from '@harness-fe/mcp-server'` instead of
+ * spawning the CLI as a sidecar.
+ *
+ * Scope (v1):
+ *   - Factory mode only — the daemon owns its own HTTP listener on a
+ *     caller-chosen port. Attaching to a host's existing `http.Server`
+ *     (middleware / handle modes) is a follow-up that requires Bridge
+ *     surgery; tracked separately.
+ *   - Resumable SSE — pass through `eventStore` (defaults to
+ *     `MemoryEventStore`; `null` disables resumability).
+ *   - Custom auth — pass `authorize: (req) => boolean` to replace the
+ *     built-in token check. The CLI translates `--token` into one of
+ *     these so the daemon itself has exactly one auth pipeline.
+ *
+ * Standalone CLI use is unchanged: `cli.ts` is a thin caller of this
+ * factory. Anything the CLI does that's specific to a developer's
+ * machine (port-keyed `defaultDataDir`, `HARNESS_FE_*` env, leader /
+ * follower attachment, banner, signal handlers) stays in `cli.ts` —
+ * not pushed into the factory.
+ */
+import type { IncomingMessage } from 'node:http';
+import { Bridge } from './bridge.js';
+import type { EventStore, IStore } from './store/types.js';
+import type { ITaskStore, IMemoryStore } from './store/types.js';
+export interface DaemonOptions {
+    /** TCP port to listen on. Default `DEFAULT_WS_PORT` (see protocol). */
+    port?: number;
+    /** Bind address. Default `127.0.0.1` (loopback only). */
+    host?: string;
+    /**
+     * Override the host used when building outbound URLs (dashboard, replay
+     * viewer). Useful when binding `0.0.0.0` and the auto-detected LAN IP is
+     * wrong, or when the host application sits behind a reverse proxy.
+     */
+    publicHost?: string;
+    /**
+     * Custom request authorizer applied to every HTTP request and WS upgrade.
+     * Return `false` to reject. When supplied, the built-in token check is
+     * skipped — there is exactly one auth pipeline. Synchronous because the
+     * WS upgrade handshake completes inline; async auth should be cached in
+     * a cookie by the host's own middleware and read back here.
+     */
+    authorize?: (req: IncomingMessage) => boolean;
+    /**
+     * IStore implementation. Omit for the default JSONL store at `dataDir`.
+     * Pass `null` to disable session/event persistence entirely.
+     */
+    store?: IStore | null;
+    /** Task store. Omit for default JsonTaskStore. `null` disables. */
+    taskStore?: ITaskStore | null;
+    /** Memory store. Omit for default JsonMemoryStore. `null` disables. */
+    memoryStore?: IMemoryStore | null;
+    /**
+     * EventStore backing resumable SSE streams. Omit for the in-memory
+     * default (1000 events / 5 minutes / 50 MiB). `null` disables
+     * resumability — reconnects after a drop start at the live tail.
+     */
+    eventStore?: EventStore | null;
+    /**
+     * Root data directory for the default stores. Omit to let `Bridge`
+     * compute a port-keyed default; pass explicitly when the host wants
+     * everything at a known location.
+     */
+    dataDir?: string;
+    /** Cosmetic friendly name; surfaces in the dashboard banner. */
+    label?: string;
+    /** URL path the MCP HTTP transport mounts on. Default `/mcp`. */
+    mcpPath?: string;
+    /**
+     * Whether to use stateful MCP sessions (sessionId in headers) or
+     * stateless one-shot requests. Default `true` (stateful — matches what
+     * Claude Code, Cursor, and the MCP spec default expect).
+     */
+    mcpStateful?: boolean;
+}
+export interface DaemonHandle {
+    /**
+     * Start the bridge and mount the MCP HTTP transport. Throws if the port
+     * is already in use — in embedded mode there's no leader/follower
+     * fallback; the host decides how to handle the conflict.
+     */
+    start(): Promise<void>;
+    /** Stop the MCP transport and bridge. Safe to call multiple times. */
+    stop(): Promise<void>;
+    /** Bound TCP port (only meaningful after `start`). */
+    getBoundPort(): number | undefined;
+    /** Outbound base URL for dashboard / replay viewer links. */
+    getViewerBaseUrl(): string | undefined;
+    /** Path the MCP HTTP transport is mounted on. */
+    readonly mcpPath: string;
+    /** Underlying bridge — escape hatch for tests and advanced wiring. */
+    readonly bridge: Bridge;
+}
+export declare function createDaemon(opts?: DaemonOptions): DaemonHandle;

package/dist/daemon.js

@@ -0,0 +1,80 @@
+/**
+ * `createDaemon` — programmatic entry point for embedding the harness-fe
+ * daemon inside another Node.js process. Wraps `Bridge` construction +
+ * `startMcpHttpServer` so a host application can boot the daemon with
+ * `import { createDaemon } from '@harness-fe/mcp-server'` instead of
+ * spawning the CLI as a sidecar.
+ *
+ * Scope (v1):
+ *   - Factory mode only — the daemon owns its own HTTP listener on a
+ *     caller-chosen port. Attaching to a host's existing `http.Server`
+ *     (middleware / handle modes) is a follow-up that requires Bridge
+ *     surgery; tracked separately.
+ *   - Resumable SSE — pass through `eventStore` (defaults to
+ *     `MemoryEventStore`; `null` disables resumability).
+ *   - Custom auth — pass `authorize: (req) => boolean` to replace the
+ *     built-in token check. The CLI translates `--token` into one of
+ *     these so the daemon itself has exactly one auth pipeline.
+ *
+ * Standalone CLI use is unchanged: `cli.ts` is a thin caller of this
+ * factory. Anything the CLI does that's specific to a developer's
+ * machine (port-keyed `defaultDataDir`, `HARNESS_FE_*` env, leader /
+ * follower attachment, banner, signal handlers) stays in `cli.ts` —
+ * not pushed into the factory.
+ */
+import { Bridge } from './bridge.js';
+import { startMcpHttpServer } from './mcpHttp.js';
+export function createDaemon(opts = {}) {
+    const mcpPath = opts.mcpPath ?? '/mcp';
+    const bridge = new Bridge({
+        port: opts.port,
+        host: opts.host,
+        publicHost: opts.publicHost,
+        store: opts.store,
+        taskStore: opts.taskStore,
+        memoryStore: opts.memoryStore,
+        dataDir: opts.dataDir,
+        label: opts.label,
+        auth: opts.authorize ? { authorize: opts.authorize } : undefined,
+    });
+    let mcpHandle;
+    let started = false;
+    let stopped = false;
+    return {
+        mcpPath,
+        bridge,
+        async start() {
+            if (started)
+                return;
+            started = true;
+            await bridge.start();
+            // Forward eventStore as-is so `null` opts out of resumability and
+            // `undefined` falls through to the default MemoryEventStore.
+            mcpHandle = await startMcpHttpServer(bridge, {
+                path: mcpPath,
+                stateful: opts.mcpStateful,
+                eventStore: opts.eventStore,
+            });
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (mcpHandle) {
+                try {
+                    await mcpHandle.close();
+                }
+                catch {
+                    /* swallow — bridge.stop will be called anyway */
+                }
+            }
+            await bridge.stop();
+        },
+        getBoundPort() {
+            return bridge.getBoundPort();
+        },
+        getViewerBaseUrl() {
+            return bridge.getViewerBaseUrl();
+        },
+    };
+}

package/dist/dashboardApi.d.ts

@@ -0,0 +1,40 @@
+/**
+ * JSON API surface consumed by `@harness-fe/dashboard-ui` (the React SPA).
+ *
+ * The shape mirrors what the legacy server-rendered dashboard.ts displayed,
+ * but as JSON so the SPA can render it with proper components and live
+ * updates. Routes live under `/api/*` to keep them clearly separated from
+ * SPA assets (`/dashboard/*`) and the replay viewer (`/replay/*`).
+ *
+ * Reuses `createReplayExport` from replayCreate.ts for the replay POST —
+ * same logic the legacy dashboard's form submission ran through, just
+ * returns JSON instead of redirecting.
+ *
+ * Auth is already enforced by `isAuthorized` in bridge.ts before this
+ * handler runs, so we never need to check tokens here.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IStore, ProjectMeta, RecordingChunkSummary, ReplayExportMeta, SessionMeta, SessionSummary, StoreEvent } from './store/types.js';
+export interface ProjectListEntry {
+    project: ProjectMeta;
+    recentSessions: SessionMeta[];
+}
+export interface SessionDetailResponse {
+    session: SessionMeta;
+    summary: SessionSummary;
+    chunks: RecordingChunkSummary[];
+    timeline: StoreEvent[];
+    exports: ReplayExportMeta[];
+}
+export interface ReplayCreateBody {
+    tabId?: string;
+    ts?: number;
+    windowMs?: number;
+    since?: number;
+    until?: number;
+    label?: string;
+}
+export declare function createDashboardApiHandler(store: IStore, getBaseUrl: () => string | undefined, onExportCreated?: (input: {
+    sessionId: string;
+    projectId?: string;
+}) => void): (req: IncomingMessage, res: ServerResponse) => boolean | Promise<boolean>;

package/dist/dashboardApi.js

@@ -0,0 +1,142 @@
+/**
+ * JSON API surface consumed by `@harness-fe/dashboard-ui` (the React SPA).
+ *
+ * The shape mirrors what the legacy server-rendered dashboard.ts displayed,
+ * but as JSON so the SPA can render it with proper components and live
+ * updates. Routes live under `/api/*` to keep them clearly separated from
+ * SPA assets (`/dashboard/*`) and the replay viewer (`/replay/*`).
+ *
+ * Reuses `createReplayExport` from replayCreate.ts for the replay POST —
+ * same logic the legacy dashboard's form submission ran through, just
+ * returns JSON instead of redirecting.
+ *
+ * Auth is already enforced by `isAuthorized` in bridge.ts before this
+ * handler runs, so we never need to check tokens here.
+ */
+import { createReplayExport } from './replayCreate.js';
+const TIMELINE_DEFAULT_TAIL = 100;
+const SESSIONS_PER_PROJECT = 10;
+export function createDashboardApiHandler(store, getBaseUrl, onExportCreated) {
+    return async (req, res) => {
+        if (!req.url)
+            return false;
+        const url = new URL(req.url, 'http://localhost');
+        const path = url.pathname;
+        if (!path.startsWith('/api/'))
+            return false;
+        const method = req.method ?? 'GET';
+        // GET /api/projects
+        if (method === 'GET' && path === '/api/projects') {
+            const projects = store.listProjects();
+            const entries = projects.map((project) => {
+                const recentSessions = store.listSessions({
+                    projectId: project.id,
+                    limit: SESSIONS_PER_PROJECT,
+                });
+                return { project, recentSessions };
+            });
+            sendJson(res, 200, { projects: entries });
+            return true;
+        }
+        // GET /api/sessions?projectId=&tabId=&buildId=&limit=
+        if (method === 'GET' && path === '/api/sessions') {
+            const sessions = store.listSessions({
+                projectId: url.searchParams.get('projectId') ?? undefined,
+                tabId: url.searchParams.get('tabId') ?? undefined,
+                buildId: url.searchParams.get('buildId') ?? undefined,
+                limit: parseIntOr(url.searchParams.get('limit'), 50),
+            });
+            sendJson(res, 200, { sessions });
+            return true;
+        }
+        // /api/sessions/:id and /api/sessions/:id/replay
+        const sessionMatch = path.match(/^\/api\/sessions\/([^/]+)(\/replay)?$/);
+        if (sessionMatch) {
+            const sessionId = decodeURIComponent(sessionMatch[1]);
+            const isReplay = !!sessionMatch[2];
+            if (isReplay && method === 'POST') {
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch (err) {
+                    sendJson(res, 400, { error: `invalid JSON body: ${err.message}` });
+                    return true;
+                }
+                const result = createReplayExport(store, getBaseUrl(), {
+                    sessionId,
+                    tabId: body.tabId,
+                    ts: body.ts,
+                    windowMs: body.windowMs,
+                    since: body.since,
+                    until: body.until,
+                    label: body.label,
+                });
+                const status = result.error ? 400 : 200;
+                if (!result.error && result.exportId && onExportCreated) {
+                    // Find the session's project so subscribers can filter.
+                    const projectId = store.getSession(sessionId)?.participants[0]?.projectId;
+                    onExportCreated({ sessionId, projectId });
+                }
+                sendJson(res, status, result);
+                return true;
+            }
+            if (method === 'GET') {
+                const session = store.getSession(sessionId);
+                if (!session) {
+                    sendJson(res, 404, { error: 'session not found', sessionId });
+                    return true;
+                }
+                const summary = store.summary(sessionId);
+                const chunks = store.listRecordings(sessionId);
+                const tailN = parseIntOr(url.searchParams.get('timeline'), TIMELINE_DEFAULT_TAIL);
+                const timeline = store.tail(sessionId, { n: tailN });
+                // Exports for the session's owning project (filter by sessionId).
+                const projectId = session.participants[0]?.projectId ?? '';
+                const exports = projectId
+                    ? store.listExports(projectId, 50).filter((e) => e.sessionId === sessionId)
+                    : [];
+                const body = {
+                    session,
+                    summary,
+                    chunks,
+                    timeline,
+                    exports,
+                };
+                sendJson(res, 200, body);
+                return true;
+            }
+        }
+        // Any other /api/ path → 404 (consumed so the legacy handler doesn't try).
+        sendJson(res, 404, { error: 'not found', path });
+        return true;
+    };
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.end(JSON.stringify(body));
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    const MAX = 1024 * 1024; // 1 MB — replay create bodies are tiny; cap to defend against DoS
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX)
+            throw new Error(`request body exceeds ${MAX} bytes`);
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return {};
+    const text = Buffer.concat(chunks).toString('utf-8');
+    return JSON.parse(text);
+}
+function parseIntOr(raw, fallback) {
+    if (raw == null)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}

package/dist/dashboardSpa.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HTTP handler that serves the React SPA built by `@harness-fe/dashboard-ui`.
+ *
+ * Routing rules (after the `isAuthorized` middleware in bridge.ts):
+ *   - GET /                          → 302 to /dashboard/?token=<preserved> (legacy root)
+ *   - GET /sessions/:id              → 302 to /dashboard/sessions/:id?token=… (legacy bookmarks)
+ *   - GET /dashboard                 → 302 to /dashboard/?token=<preserved>
+ *   - GET /dashboard/                → serve index.html (SPA shell)
+ *   - GET /dashboard/<asset.ext>     → serve that file from dist/ (if it exists)
+ *   - GET /dashboard/<other-path>    → serve index.html (SPA client-side routing)
+ *
+ * The dist directory is resolved at module load via `require.resolve()` on
+ * the dashboard-ui package — same trick `replayViewer.ts` uses for
+ * rrweb-player. No copy step needed; pnpm workspace symlinks just work in
+ * dev, and `pnpm deploy` bundles the dist into the published tarball.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function createDashboardSpaHandler(): (req: IncomingMessage, res: ServerResponse) => boolean;