@harness-fe/mcp-server 3.0.1

package/src/bridge.ts

@@ -0,0 +1,1804 @@
+/**
+ * WS bridge — accepts connections from vite-plugin and runtime-client.
+ *
+ * Protocol: see @harness-fe/protocol.
+ *
+ * Responsibilities:
+ *   - Handshake: `hello` frame → register peer in SessionRouter, reply `hello.ack`
+ *   - sendCommand(): forward a CommandFrame to the target tab, return a
+ *     Promise that resolves when the matching ResponseFrame arrives
+ *   - onEvent(): broadcast event frames to subscribers (mcp tools / future
+ *     recorder)
+ */
+
+import { WebSocket, WebSocketServer } from 'ws';
+import { randomUUID } from 'node:crypto';
+import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http';
+import { networkInterfaces } from 'node:os';
+import {
+    DEFAULT_LOGIN_PATH,
+    handleLoginPost,
+    isAuthorized,
+    sendUnauthorized,
+    type AuthOptions,
+} from './auth.js';
+import { join as joinPath } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+    DEFAULT_WS_PORT,
+    EVENT_NAME,
+    PROTOCOL_VERSION,
+    isLoopbackHost,
+    pageLoadPayloadSchema,
+    rrwebChunkPayloadSchema,
+    taskSubmitPayloadSchema,
+    type CommandFrame,
+    type EventFrame,
+    type Frame,
+    type HelloAckFrame,
+    type HttpBatch,
+    type McpCallFrame,
+    type McpReturnFrame,
+    type QueryFrame,
+    type QueryResponseFrame,
+    type TabInfo,
+    type Task,
+    type TaskAttachment,
+    type TaskStatus,
+    frameSchema,
+} from '@harness-fe/protocol';
+import { SessionRouter, type PeerSession } from './sessionRouter.js';
+import { createReplayHandler } from './replayViewer.js';
+import { createDashboardApiHandler } from './dashboardApi.js';
+import { createDashboardSpaHandler } from './dashboardSpa.js';
+import { createEventsHandler } from './eventsHandler.js';
+import {
+    JsonlStore,
+    JsonTaskStore,
+    JsonMemoryStore,
+    sanitizeId as sanitizeStoreId,
+    type IStore,
+    type ITaskStore,
+    type IMemoryStore,
+    type RetentionPolicy,
+} from './store/index.js';
+
+/**
+ * Surface used by the stdio MCP layer. Same shape whether the underlying
+ * implementation is an in-process `Bridge` (leader) or a `RemoteBridge`
+ * proxying over WS to another daemon (follower).
+ *
+ * All methods are async so the same call site works in both modes.
+ */
+export interface IBridge {
+    sendCommand(
+        command: string,
+        args: unknown,
+        opts?: SendCommandOptions,
+    ): Promise<unknown>;
+    listTabs(): Promise<TabInfo[]>;
+    listTasks(filter?: { status?: TaskStatus | 'all'; limit?: number }): Promise<Task[]>;
+    claimTask(id: string): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    getMemoryStore(): IMemoryStore;
+    /**
+     * Base URL (e.g. http://127.0.0.1:47729) where the replay viewer is reachable.
+     * Returns undefined when the bridge does not serve HTTP (e.g. follower mode).
+     */
+    getViewerBaseUrl(): string | undefined;
+    /**
+     * The configured auth token, or undefined if auth is disabled. Used to
+     * compose URLs that the user (or agent) can hit without an extra
+     * authentication step.
+     */
+    getAuthToken(): string | undefined;
+    /**
+     * Read an attachment PNG for a task. Returns base64-encoded PNG or null.
+     * The task must exist in the in-memory map so we can look up its projectId.
+     */
+    getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
+}
+
+export interface SendCommandOptions {
+    tabId?: string;
+    timeoutMs?: number;
+    target?: 'runtime-client' | 'vite-plugin';
+    projectId?: string;
+}
+
+const COMMAND_TIMEOUT_MS = 30_000;
+const TASK_QUEUE_CAP = 200;
+
+/**
+ * Default data directory for all persistence stores, keyed by the port the
+ * daemon listens on. Identity of a daemon = its listening address; same
+ * port → same on-disk store; different ports → independent stores.
+ *
+ * This lets users opt into isolation simply by configuring a different
+ * `--port` in their `mcp.json`, and lets multiple IDEs targeting the same
+ * port automatically share state through the existing leader/follower
+ * mechanism in `cli.ts`. No cwd / project-root detection involved.
+ */
+export function defaultDataDir(port: number): string {
+    return joinPath(homedir(), '.harness', 'daemons', String(port), 'data');
+}
+
+interface PendingCommand {
+    resolve(payload: unknown): void;
+    reject(err: Error): void;
+    timer: NodeJS.Timeout;
+}
+
+export interface BridgeOptions {
+    port?: number;
+    /** Bind address. Default 127.0.0.1 (no remote exposure). */
+    host?: string;
+    /**
+     * Token-based auth applied to every HTTP route and WS upgrade. Empty
+     * token disables auth (only valid when bound to a loopback host).
+     */
+    auth?: AuthOptions;
+    /**
+     * Override the host used when building outbound URLs (dashboard links,
+     * replay viewer URLs). When omitted and `host` is `0.0.0.0` / `::`, the
+     * first non-internal IPv4 address from the OS network interfaces is
+     * used so other LAN devices can follow the links. For loopback binds the
+     * literal `host` is reused.
+     */
+    publicHost?: string;
+    /**
+     * Store instance for JSONL persistence. If omitted, a default JsonlStore
+     * is created at `dataDir` (or `defaultDataDir(port)` when `dataDir` is
+     * also omitted). Pass null to disable persistence.
+     */
+    store?: IStore | null;
+    /**
+     * Task store instance for JSON task persistence. If omitted, a default
+     * JsonTaskStore is created at `dataDir`. Pass null to disable task
+     * persistence (useful in tests).
+     */
+    taskStore?: ITaskStore | null;
+    /**
+     * Memory store instance for agent memory persistence. If omitted, a default
+     * JsonMemoryStore is created at `dataDir`. Pass null to disable memory
+     * persistence (useful in tests).
+     */
+    memoryStore?: IMemoryStore | null;
+    /**
+     * Root data directory for task attachment binaries. Defaults to the same
+     * `~/.harness/data` directory used by the stores. Override in tests.
+     */
+    attachmentsDataDir?: string;
+    /**
+     * Root data directory for the default stores (when `store` / `taskStore`
+     * / `memoryStore` are not supplied). When omitted, computed from `port`
+     * via `defaultDataDir(port)`. Set explicitly to point all stores at a
+     * non-default location (useful for tests or migration).
+     */
+    dataDir?: string;
+    /**
+     * Optional friendly label surfaced in the startup banner and (later) the
+     * dashboard title. Purely cosmetic — has no effect on data isolation,
+     * routing, or auth. Identity is always the listening port.
+     */
+    label?: string;
+    /**
+     * Automatic retention policy enforcement.
+     *
+     * Without this, manual `session.purge` MCP calls are the only thing that
+     * trims the on-disk store — so a long-running daemon will eventually fill
+     * the user's disk. Default: run `store.purge()` once shortly after start
+     * and every hour thereafter. Set `enabled: false` for tests / one-shot runs.
+     */
+    autoPurge?: {
+        enabled?: boolean;          // default true
+        /** Period between purges in ms. Default 1 hour. */
+        intervalMs?: number;
+        /** Override the retention policy. Default uses store's built-in defaults. */
+        policy?: RetentionPolicy;
+        /** Skip the startup purge (still runs the periodic timer). Default false. */
+        skipInitial?: boolean;
+    };
+}
+
+export type EventListener = (event: EventFrame, session: PeerSession) => void;
+
+export class Bridge implements IBridge {
+    readonly router = new SessionRouter();
+    readonly store: IStore | null;
+    readonly taskStore: ITaskStore | null;
+    readonly memoryStore: IMemoryStore;
+    private wss?: WebSocketServer;
+    private httpServer?: HttpServer;
+    /**
+     * Optional HTTP handler invoked for non-WebSocket requests. Set via
+     * `setHttpHandler()`. Allows higher layers (e.g. replay viewer) to serve
+     * routes on the same port as the WS bridge without coupling Bridge to them.
+     */
+    private httpHandler?: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    private sockets = new Map<string, WebSocket>();
+    private pending = new Map<string, PendingCommand>();
+    private eventListeners = new Set<EventListener>();
+    private tasks = new Map<string, Task>();
+    private opts: Required<Omit<BridgeOptions, 'store' | 'taskStore' | 'memoryStore' | 'autoPurge' | 'attachmentsDataDir' | 'auth' | 'publicHost' | 'dataDir' | 'label'>>;
+    private auth: AuthOptions;
+    private publicHostOverride: string | undefined;
+    private readonly attachDataDir: string;
+    private autoPurgeOpts: Required<NonNullable<BridgeOptions['autoPurge']>>;
+    /** Set by start() when auto-purge is enabled; cleared by stop(). */
+    private autoPurgeTimer?: NodeJS.Timeout;
+    /**
+     * Map from connectionId → buildId (for build-plugin connections)
+     * or sessionId (for runtime-client connections).
+     */
+    private connToStoreId = new Map<string, string>();
+    /** Connections that already logged a "no store session" warning. */
+    private warnedNoSession = new Set<string>();
+    /**
+     * Grace period timers: projectId → timer handle.
+     * When a build plugin disconnects, a 30-second timer is started.
+     * If the same project reconnects within that window, the timer is cancelled.
+     */
+    private graceTimers = new Map<string, NodeJS.Timeout>();
+    /**
+     * Pending build end info: projectId → { buildId, closedAt }.
+     * Tracks builds waiting for the grace period to expire.
+     */
+    private pendingEndBuild = new Map<string, { buildId: string; closedAt: number }>();
+    /**
+     * Dashboard SPA subscribers — connections that sent `hello` with
+     * role: 'dashboard-client'. Receive `dashboard.update` frames whenever
+     * session state changes; never receive commands and never send events.
+     */
+    private dashboardSubscribers = new Set<WebSocket>();
+    /** Debounce per-session 'session.update' broadcasts so chatty rrweb chunks don't spam subscribers. */
+    private dashboardDebounceTimers = new Map<string, NodeJS.Timeout>();
+
+    /** Optional friendly label (HARNESS_FE_LABEL). Cosmetic only. */
+    readonly label: string | undefined;
+
+    constructor(opts: BridgeOptions = {}) {
+        const port = opts.port ?? DEFAULT_WS_PORT;
+        const dataDir = opts.dataDir ?? defaultDataDir(port);
+        this.label = opts.label;
+        this.store = opts.store === null ? null : (opts.store ?? new JsonlStore(dataDir));
+        this.taskStore = opts.taskStore === null ? null : (opts.taskStore ?? new JsonTaskStore(dataDir));
+        this.memoryStore = opts.memoryStore === null
+            ? new JsonMemoryStore(dataDir)
+            : (opts.memoryStore ?? new JsonMemoryStore(dataDir));
+        this.attachDataDir = opts.attachmentsDataDir ?? dataDir;
+        this.opts = {
+            port: opts.port ?? DEFAULT_WS_PORT,
+            host: opts.host ?? '127.0.0.1',
+        };
+        this.auth = opts.auth ?? {};
+        this.publicHostOverride = opts.publicHost;
+        // Default auto-purge ON. CI / tests pass `enabled: false` (or set
+        // env HARNESS_FE_PURGE_DISABLED=1) to opt out.
+        const envDisabled = process.env.HARNESS_FE_PURGE_DISABLED === '1';
+        this.autoPurgeOpts = {
+            enabled: opts.autoPurge?.enabled ?? !envDisabled,
+            intervalMs: opts.autoPurge?.intervalMs ?? 60 * 60 * 1000,
+            policy: opts.autoPurge?.policy ?? {},
+            skipInitial: opts.autoPurge?.skipInitial ?? false,
+        };
+        this.loadTasks();
+
+        // Auto-install dashboard + replay viewer + events HTTP handlers.
+        {
+            const events = createEventsHandler(this);
+            if (this.store) {
+                const store = this.store;
+                const replay = createReplayHandler(store);
+                const dashboardApi = createDashboardApiHandler(
+                    store,
+                    () => this.getViewerBaseUrl(),
+                    ({ sessionId, projectId }) => this.notifyDashboard({ kind: 'export.new', sessionId, projectId }),
+                );
+                const dashboardSpa = createDashboardSpaHandler();
+                this.setHttpHandler(async (req, res) => {
+                    if (replay(req, res)) return;
+                    // dashboardApi handles /api/* (must come before SPA so a
+                    // future SPA route doesn't accidentally shadow it).
+                    if (await dashboardApi(req, res)) return;
+                    // dashboardSpa owns /dashboard/* plus the legacy /
+                    // and /sessions/:id redirects into the SPA.
+                    if (dashboardSpa(req, res)) return;
+                    if (await events(req, res)) return;
+                    res.statusCode = 404;
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end('Not Found');
+                });
+            } else {
+                this.setHttpHandler(async (req, res) => {
+                    if (await events(req, res)) return;
+                    res.statusCode = 404;
+                    res.setHeader('content-type', 'text/plain; charset=utf-8');
+                    res.end('Not Found');
+                });
+            }
+        }
+    }
+
+    /**
+     * Returns the memory store instance for use by mcp.ts and other callers.
+     */
+    getMemoryStore(): IMemoryStore {
+        return this.memoryStore;
+    }
+
+    private loadTasks(): void {
+        // Tasks are loaded lazily per-project when a project connects.
+        // See loadTasksForProject() which is called in handleFrame on hello.
+    }
+
+    private persistTasks(projectId?: string): void {
+        if (!this.taskStore) return;
+        if (projectId) {
+            // Save only the tasks for the given project
+            const projectTasks = Array.from(this.tasks.values()).filter(
+                (t) => t.projectId === projectId,
+            );
+            this.taskStore.saveTasks(projectId, projectTasks);
+        } else {
+            // Group all tasks by projectId and save each group
+            const byProject = new Map<string, Task[]>();
+            for (const task of this.tasks.values()) {
+                const pid = task.projectId;
+                if (!byProject.has(pid)) byProject.set(pid, []);
+                byProject.get(pid)!.push(task);
+            }
+            for (const [pid, projectTasks] of byProject) {
+                this.taskStore.saveTasks(pid, projectTasks);
+            }
+        }
+    }
+
+    /**
+     * Load tasks for a specific project from the task store into the in-memory map.
+     * Called when a project connects so its tasks are available immediately.
+     */
+    private loadTasksForProject(projectId: string): void {
+        if (!this.taskStore) return;
+        const projectTasks = this.taskStore.loadTasks(projectId);
+        for (const task of projectTasks) {
+            if (task && typeof task.id === 'string') {
+                this.tasks.set(task.id, task);
+            }
+        }
+    }
+
+    private taskDedupKey(tabId: string, payload: { question: string; selector: { css?: string; comp?: string; loc?: string } }): string {
+        const sel = payload.selector;
+        const selKey = sel.loc ?? sel.comp ?? sel.css ?? '';
+        return `${tabId}::${selKey}::${payload.question.trim()}`;
+    }
+
+    /**
+     * Register an HTTP request handler that runs for non-WebSocket requests on
+     * the same port. Only one handler is supported; later calls replace prior
+     * ones. WS upgrades bypass this handler.
+     */
+    setHttpHandler(handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>): void {
+        this.httpHandler = handler;
+    }
+
+    /**
+     * Insert a handler that runs *before* the main HTTP handler. Return `true`
+     * if the request was consumed (no further processing); return `false` to
+     * fall through to the existing handler. Allows mcpHttp.ts to mount on
+     * `/mcp` without owning the whole HTTP surface.
+     */
+    prependHttpHandler(
+        handler: (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean,
+    ): void {
+        const existing = this.httpHandler;
+        this.httpHandler = async (req, res) => {
+            const handled = await handler(req, res);
+            if (handled) return;
+            if (existing) await existing(req, res);
+        };
+    }
+
+    async start(): Promise<void> {
+        await new Promise<void>((resolve, reject) => {
+            const loginPath = this.auth.loginPath ?? DEFAULT_LOGIN_PATH;
+            const httpServer = createServer((req, res) => {
+                // POST {loginPath} handles token submission from the login form.
+                // It runs *before* the auth check because that's how the user
+                // gets authorised in the first place.
+                if (req.method === 'POST' && req.url && pathnameOf(req.url) === loginPath) {
+                    handleLoginPost(req, res, this.auth).catch((err) => {
+                        if (!res.headersSent) {
+                            res.statusCode = 500;
+                            res.setHeader('content-type', 'text/plain; charset=utf-8');
+                            res.end(`auth error: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    });
+                    return;
+                }
+                if (!isAuthorized(req, this.auth)) {
+                    sendUnauthorized(req, res, this.auth);
+                    return;
+                }
+                if (this.httpHandler) {
+                    Promise.resolve(this.httpHandler(req, res)).catch((err) => {
+                        if (!res.headersSent) {
+                            res.statusCode = 500;
+                            res.setHeader('content-type', 'text/plain; charset=utf-8');
+                            res.end(`Internal error: ${err instanceof Error ? err.message : String(err)}`);
+                        } else {
+                            try { res.end(); } catch { /* swallow */ }
+                        }
+                    });
+                    return;
+                }
+                res.statusCode = 404;
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                res.end('Not Found');
+            });
+
+            const wss = new WebSocketServer({ noServer: true });
+            wss.on('connection', (ws) => this.onConnection(ws));
+
+            httpServer.on('upgrade', (req, socket, head) => {
+                if (!isAuthorized(req, this.auth)) {
+                    // Spec-compliant 401 on the upgrade reply so client sees a
+                    // proper status rather than a half-open socket.
+                    socket.write(
+                        'HTTP/1.1 401 Unauthorized\r\n' +
+                            'WWW-Authenticate: Bearer realm="harness-fe"\r\n' +
+                            'Content-Length: 0\r\n' +
+                            'Connection: close\r\n\r\n',
+                    );
+                    socket.destroy();
+                    return;
+                }
+                wss.handleUpgrade(req, socket, head, (ws) => {
+                    wss.emit('connection', ws, req);
+                });
+            });
+
+            httpServer.once('error', reject);
+            httpServer.listen(this.opts.port, this.opts.host, () => {
+                this.httpServer = httpServer;
+                this.wss = wss;
+                httpServer.off('error', reject);
+                resolve();
+            });
+        });
+
+        // Schedule auto-purge after the listen socket is up. Skipped when:
+        //   - no store configured (in-memory only)
+        //   - explicitly disabled via opts / env
+        if (this.store && this.autoPurgeOpts.enabled) {
+            if (!this.autoPurgeOpts.skipInitial) {
+                this.runAutoPurge('startup');
+            }
+            const timer = setInterval(
+                () => this.runAutoPurge('periodic'),
+                this.autoPurgeOpts.intervalMs,
+            );
+            // unref so the timer never holds the Node process alive on its own.
+            timer.unref();
+            this.autoPurgeTimer = timer;
+        }
+    }
+
+    async stop(): Promise<void> {
+        if (this.autoPurgeTimer) {
+            clearInterval(this.autoPurgeTimer);
+            this.autoPurgeTimer = undefined;
+        }
+        for (const ws of this.sockets.values()) {
+            try {
+                ws.close();
+            } catch {
+                /* swallow */
+            }
+        }
+        this.sockets.clear();
+        await new Promise<void>((resolve) => {
+            if (!this.wss) return resolve();
+            this.wss.close(() => resolve());
+        });
+        await new Promise<void>((resolve) => {
+            if (!this.httpServer) return resolve();
+            this.httpServer.close(() => resolve());
+        });
+    }
+
+    /**
+     * Run `store.purge()` defensively. Errors are logged but never bubble out
+     * — the daemon must continue serving even if disk is full or files are
+     * locked.
+     */
+    private runAutoPurge(trigger: 'startup' | 'periodic'): void {
+        if (!this.store) return;
+        try {
+            const result = this.store.purge(this.autoPurgeOpts.policy);
+            const removed =
+                result.sessionsDeleted +
+                result.recordingsDeleted +
+                result.exportsDeleted +
+                (result.buildsDeleted ?? 0);
+            if (removed > 0 || result.bytesFreed > 0) {
+                const mb = (result.bytesFreed / 1024 / 1024).toFixed(2);
+                process.stderr.write(
+                    `[harness-fe] auto-purge (${trigger}): freed ${mb} MB · ` +
+                        `${result.sessionsDeleted} sessions, ` +
+                        `${result.recordingsDeleted} rrweb chunks, ` +
+                        `${result.buildsDeleted ?? 0} builds, ` +
+                        `${result.exportsDeleted} exports\n`,
+                );
+            }
+        } catch (err) {
+            process.stderr.write(
+                `[harness-fe] auto-purge failed (${trigger}): ${
+                    err instanceof Error ? err.message : String(err)
+                }\n`,
+            );
+        }
+    }
+
+    /** Expose the bound port (useful when port:0 was passed for tests). */
+    getBoundPort(): number | undefined {
+        if (!this.httpServer) return undefined;
+        const addr = this.httpServer.address();
+        if (addr && typeof addr === 'object') return addr.port;
+        return undefined;
+    }
+
+    getViewerBaseUrl(): string | undefined {
+        const port = this.getBoundPort() ?? this.opts.port;
+        if (!port) return undefined;
+        return `http://${this.getPublicHost()}:${port}`;
+    }
+
+    getAuthToken(): string | undefined {
+        return this.auth.token;
+    }
+
+    /**
+     * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
+     *
+     * `kind: 'session.update'` is debounced per-sessionId (200ms) so chatty
+     * rrweb chunk appends don't spam every subscriber. Other kinds fire
+     * immediately because they represent rare state transitions (new
+     * session, session closed, export created).
+     */
+    notifyDashboard(payload: {
+        kind: 'session.new' | 'session.update' | 'session.closed' | 'project.update' | 'export.new';
+        sessionId?: string;
+        projectId?: string;
+    }): void {
+        if (this.dashboardSubscribers.size === 0) return;
+        const debounceKey = payload.kind === 'session.update'
+            ? `${payload.kind}:${payload.sessionId ?? ''}`
+            : undefined;
+        if (debounceKey) {
+            const existing = this.dashboardDebounceTimers.get(debounceKey);
+            if (existing) clearTimeout(existing);
+            const timer = setTimeout(() => {
+                this.dashboardDebounceTimers.delete(debounceKey);
+                this.flushDashboardUpdate(payload);
+            }, 200);
+            this.dashboardDebounceTimers.set(debounceKey, timer);
+            return;
+        }
+        this.flushDashboardUpdate(payload);
+    }
+
+    private flushDashboardUpdate(payload: {
+        kind: 'session.new' | 'session.update' | 'session.closed' | 'project.update' | 'export.new';
+        sessionId?: string;
+        projectId?: string;
+    }): void {
+        const frame = {
+            type: 'dashboard.update' as const,
+            id: randomUUID(),
+            kind: payload.kind,
+            sessionId: payload.sessionId,
+            projectId: payload.projectId,
+            ts: Date.now(),
+        };
+        const json = JSON.stringify(frame);
+        for (const ws of this.dashboardSubscribers) {
+            try {
+                if (ws.readyState === ws.OPEN) ws.send(json);
+            } catch {
+                // Failed sends will be cleaned up on next close event.
+            }
+        }
+    }
+
+    /**
+     * Host string used when handing out URLs that other machines need to
+     * reach. Loopback binds keep the literal address; wildcard binds
+     * (0.0.0.0 / ::) prefer the first non-internal IPv4. Explicit
+     * `publicHost` always wins.
+     */
+    private getPublicHost(): string {
+        if (this.publicHostOverride) return this.publicHostOverride;
+        const h = this.opts.host;
+        if (h === '0.0.0.0' || h === '::' || h === '::0') {
+            return firstNonInternalIpv4() ?? '127.0.0.1';
+        }
+        return h;
+    }
+
+    onEvent(listener: EventListener): () => void {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+
+    /**
+     * Handle an HTTP-batch POST /events request (Edge Runtime path).
+     *
+     * Stateless: each call is a self-contained hello+events sequence.
+     * The hello is used to register the peer (or look up the existing session)
+     * and the events are persisted to the session timeline — same paths as the
+     * WS handler.
+     */
+    handleHttpBatch(
+        hello: HttpBatch['hello'],
+        events: HttpBatch['events'],
+    ): void {
+        const projectId = hello.projectId;
+        const sessionId = hello.sessionId ?? `server-orphans:${sanitizeStoreId(projectId)}`;
+
+        // Persist to store if available
+        if (this.store) {
+            // Upsert project metadata
+            if (hello.displayName !== undefined) {
+                try {
+                    this.store.upsertProject(projectId, {
+                        displayName: hello.displayName,
+                    });
+                } catch {
+                    // ignore cycle / validation errors
+                }
+            }
+
+            // Ensure session exists — if sessionId was provided by caller the
+            // runtime-client typically already created it; we use upsertSession
+            // so a server-only session (no browser client) also gets bootstrapped.
+            this.store.upsertSession(sessionId, {
+                tabId: 'http-batch',
+                startedAt: Date.now(),
+                participants: [{ projectId, buildId: hello.buildId, joinedAt: Date.now() }],
+            });
+
+            // Persist each event
+            for (const ev of events) {
+                const evName: string = typeof ev.name === 'string' ? ev.name : 'unknown';
+                // app.log events get the canonical short type code 'app-log'
+                const evType: string = evName === 'app.log' ? 'app-log' : evName;
+                this.store.appendEvent(sessionId, {
+                    ts: typeof ev.ts === 'number' ? ev.ts : Date.now(),
+                    t: evType,
+                    projectId,
+                    buildId: ev.buildId ?? hello.buildId,
+                    d: ev.payload,
+                });
+            }
+        }
+
+        // Fire event listeners so MCP tools can observe HTTP-batch events in real time
+        for (const ev of events) {
+            const evName: string = typeof ev.name === 'string' ? ev.name : 'unknown';
+            const fullFrame: import('@harness-fe/protocol').EventFrame = {
+                type: 'event',
+                id: ev.id ?? randomUUID(),
+                name: evName,
+                ts: typeof ev.ts === 'number' ? ev.ts : Date.now(),
+                projectId,
+                sessionId,
+                buildId: ev.buildId ?? hello.buildId,
+                payload: ev.payload,
+            };
+            // Use a synthetic PeerSession so listeners have consistent shape
+            const syntheticPeer: import('./sessionRouter.js').PeerSession = {
+                connectionId: `http:${sessionId}`,
+                role: 'node-runtime',
+                projectId,
+                tabId: undefined,
+                sessionId,
+                visitorId: undefined,
+                userId: hello.userId,
+                page: undefined,
+                lastActive: Date.now(),
+            };
+            for (const listener of this.eventListeners) {
+                try {
+                    listener(fullFrame, syntheticPeer);
+                } catch {
+                    /* swallow */
+                }
+            }
+        }
+
+        process.stderr.write(
+            `[harness-fe] http-batch: project=${projectId}` +
+            ` session=${sessionId.slice(0, 8)} events=${events.length}\n`,
+        );
+    }
+
+    async listTabs(): Promise<TabInfo[]> {
+        return this.router.listTabs();
+    }
+
+    async listTasks(
+        filter: { status?: TaskStatus | 'all'; limit?: number } = {},
+    ): Promise<Task[]> {
+        const status = filter.status ?? 'pending';
+        const limit = filter.limit ?? 50;
+        const all = Array.from(this.tasks.values());
+        const filtered = status === 'all' ? all : all.filter((t) => t.status === status);
+        filtered.sort((a, b) => b.createdAt - a.createdAt);
+        return filtered.slice(0, limit);
+    }
+
+    async claimTask(id: string): Promise<Task | undefined> {
+        const task = this.tasks.get(id);
+        if (!task) return undefined;
+        task.status = 'claimed';
+        task.claimedAt = Date.now();
+        this.persistTasks();
+        // Persist status change to store
+        this.persistTaskEvent(task, 'task:claim');
+        return task;
+    }
+
+    async getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null> {
+        const task = this.tasks.get(taskId);
+        if (!task) return null;
+        return this.readTaskAttachment(task.projectId, taskId, attachmentId);
+    }
+
+    async resolveTask(id: string, note?: string): Promise<Task | undefined> {
+        const task = this.tasks.get(id);
+        if (!task) return undefined;
+        task.status = 'resolved';
+        task.resolvedAt = Date.now();
+        if (note !== undefined) task.note = note;
+        this.persistTasks();
+        // Persist status change to store
+        this.persistTaskEvent(task, 'task:resolve');
+        return task;
+    }
+
+    private persistTaskEvent(task: Task, eventType: string): void {
+        if (!this.store) return;
+        // Find the most recent session for this task's project
+        const sessions = this.store.listSessions({ projectId: task.projectId, limit: 1 });
+        const sessionId = sessions[0]?.id;
+        if (!sessionId) return;
+        this.store.appendEvent(sessionId, {
+            ts: Date.now(),
+            t: eventType,
+            tab: task.tabId,
+            load: task.sessionId,
+            d: { id: task.id, status: task.status, question: task.question, note: task.note },
+        });
+    }
+
+    private recordTask(frame: EventFrame, peer: PeerSession): void {
+        const parsed = taskSubmitPayloadSchema.safeParse(frame.payload);
+        if (!parsed.success) return;
+        const tabId = peer.tabId ?? frame.tabId ?? 'unknown';
+        // Dedup: collapse a fresh submit onto an existing pending task with
+        // identical tab + selector + question. Refresh its timestamp and
+        // overwrite the captured element snapshot, but keep the same id so
+        // claim/resolve flows don't fork.
+        const dedupKey = this.taskDedupKey(tabId, parsed.data);
+        for (const existing of this.tasks.values()) {
+            if (existing.status !== 'pending') continue;
+            if (this.taskDedupKey(existing.tabId, existing) !== dedupKey) continue;
+            existing.createdAt = frame.ts ?? Date.now();
+            existing.element = parsed.data.element;
+            existing.url = parsed.data.url;
+            this.persistTasks();
+            return;
+        }
+        const id = randomUUID().slice(0, 10);
+        const projectId = peer.projectId ?? frame.projectId ?? 'unknown';
+
+        // Process attachments: decode base64, write to disk, store pointer.
+        let persistedAttachments: TaskAttachment[] | undefined;
+        if (parsed.data.attachments && parsed.data.attachments.length > 0) {
+            persistedAttachments = this.writeTaskAttachments(projectId, id, parsed.data.attachments);
+        }
+
+        const task: Task = {
+            id,
+            tabId,
+            sessionId: peer.sessionId,
+            visitorId: peer.visitorId,
+            userId: peer.userId,
+            projectId,
+            url: parsed.data.url,
+            status: 'pending',
+            question: parsed.data.question,
+            selector: parsed.data.selector,
+            element: parsed.data.element,
+            createdAt: frame.ts ?? Date.now(),
+            attachments: persistedAttachments,
+        };
+        this.tasks.set(id, task);
+        if (this.tasks.size > TASK_QUEUE_CAP) {
+            // FIFO eviction by insertion order.
+            const oldest = this.tasks.keys().next().value;
+            if (oldest !== undefined) this.tasks.delete(oldest);
+        }
+        this.persistTasks();
+    }
+
+    /**
+     * Write attachment data to disk and return persisted pointer objects.
+     * Drops attachments if the total decoded size exceeds 4 MB.
+     */
+    private writeTaskAttachments(projectId: string, taskId: string, attachments: TaskAttachment[]): TaskAttachment[] {
+        const MAX_BYTES = 4 * 1024 * 1024;
+        const result: TaskAttachment[] = [];
+
+        // Calculate total bytes first
+        let totalBytes = 0;
+        const buffers: Buffer[] = [];
+        for (const att of attachments) {
+            if (!att.data) continue;
+            try {
+                const buf = Buffer.from(att.data, 'base64');
+                totalBytes += buf.length;
+                buffers.push(buf);
+            } catch {
+                buffers.push(Buffer.alloc(0));
+            }
+        }
+
+        if (totalBytes > MAX_BYTES) {
+            process.stderr.write(
+                `[harness-fe] task ${taskId}: attachments total ${(totalBytes / 1024 / 1024).toFixed(2)} MB exceeds 4 MB limit — dropping attachments\n`,
+            );
+            return [];
+        }
+
+        const attachDir = joinPath(this.attachDataDir, 'projects', sanitizeStoreId(projectId), 'task-attachments', taskId);
+        try {
+            mkdirSync(attachDir, { recursive: true });
+        } catch {
+            return [];
+        }
+
+        let bufIdx = 0;
+        for (const att of attachments) {
+            if (!att.data) {
+                bufIdx++;
+                continue;
+            }
+            const buf = buffers[bufIdx++];
+            if (!buf || buf.length === 0) continue;
+            const filePath = joinPath(attachDir, `${att.id}.png`);
+            try {
+                writeFileSync(filePath, buf);
+                const relPath = `task-attachments/${taskId}/${att.id}.png`;
+                result.push({
+                    id: att.id,
+                    kind: att.kind,
+                    width: att.width,
+                    height: att.height,
+                    path: relPath,
+                    // data is intentionally omitted — tasks.json stays small
+                });
+            } catch (err) {
+                process.stderr.write(
+                    `[harness-fe] failed to write attachment ${att.id}: ${err instanceof Error ? err.message : String(err)}\n`,
+                );
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Read an attachment from disk for a given task.
+     * Returns the base64 data if found, null otherwise.
+     */
+    readTaskAttachment(projectId: string, taskId: string, attachmentId: string): string | null {
+        const filePath = joinPath(
+            this.attachDataDir,
+            'projects',
+            sanitizeStoreId(projectId),
+            'task-attachments',
+            taskId,
+            `${attachmentId}.png`,
+        );
+        if (!existsSync(filePath)) return null;
+        try {
+            const buf = readFileSync(filePath);
+            return buf.toString('base64');
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Send a command to a specific tab and await its response.
+     * `tabId` falls back to the most-recent active tab if omitted.
+     */
+    async sendCommand(
+        command: string,
+        args: unknown,
+        opts: SendCommandOptions = {},
+    ): Promise<unknown> {
+        const target = opts.target ?? 'runtime-client';
+        const session =
+            target === 'vite-plugin'
+                ? this.router.findVitePlugin(opts.projectId)
+                : this.router.findTab(opts.tabId);
+        if (!session) {
+            throw new Error(
+                target === 'vite-plugin'
+                    ? 'bridge: no vite-plugin connected. Start the dev server first.'
+                    : opts.tabId
+                      ? `bridge: no runtime-client connected for tabId="${opts.tabId}"`
+                      : 'bridge: no runtime-client connected. Open the dev page first.',
+            );
+        }
+        const socket = this.sockets.get(session.connectionId);
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            throw new Error('bridge: target socket is not open');
+        }
+
+        const id = randomUUID();
+        const cmdTs = Date.now();
+        const frame: CommandFrame = {
+            type: 'command',
+            id,
+            tabId: session.tabId,
+            command,
+            args,
+        };
+
+        // Persist command to store — runtime-client connections store a sessionId
+        const storeId = this.connToStoreId.get(session.connectionId);
+        // For runtime-client, storeId is the sessionId; for plugins storeId is the buildId.
+        // Commands are sent to runtime-clients, so storeId here is always a sessionId.
+        const storeSessionId = (session.role === 'runtime-client') ? storeId : undefined;
+        if (this.store && storeSessionId) {
+            this.store.appendEvent(storeSessionId, {
+                ts: cmdTs, t: 'cmd', tab: session.tabId,
+                d: { id, command, args, target },
+            });
+        }
+
+        const timeoutMs = opts.timeoutMs ?? COMMAND_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                // Persist timeout as failed response
+                if (this.store && storeSessionId) {
+                    this.store.appendEvent(storeSessionId, {
+                        ts: Date.now(), t: 'resp', tab: session.tabId,
+                        d: { id, ok: false, error: `timeout after ${timeoutMs}ms`, durationMs: timeoutMs },
+                    });
+                }
+                reject(new Error(`bridge: command "${command}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (result) => {
+                    // Persist successful response (strip screenshot dataUrl to save space)
+                    if (this.store && storeSessionId) {
+                        const safeResult = stripLargePayloads(result);
+                        this.store.appendEvent(storeSessionId, {
+                            ts: Date.now(), t: 'resp', tab: session.tabId,
+                            d: { id, ok: true, result: safeResult, durationMs: Date.now() - cmdTs },
+                        });
+                    }
+                    resolve(result);
+                },
+                reject: (err) => {
+                    // Persist error response
+                    if (this.store && storeSessionId) {
+                        this.store.appendEvent(storeSessionId, {
+                            ts: Date.now(), t: 'resp', tab: session.tabId,
+                            d: { id, ok: false, error: err.message, durationMs: Date.now() - cmdTs },
+                        });
+                    }
+                    reject(err);
+                },
+                timer,
+            });
+            try {
+                socket.send(JSON.stringify(frame));
+            } catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(err as Error);
+            }
+        });
+    }
+
+    /**
+     * Returns true if there is an active build for the given projectId.
+     * Checks both in-memory grace period builds and the store.
+     */
+    private hasActiveBuild(projectId: string): boolean {
+        // Check if there's a build in the grace period (still considered active)
+        if (this.pendingEndBuild.has(projectId)) return true;
+        // Check if any connection currently maps to a build for this project
+        for (const [connId] of this.connToStoreId) {
+            const peer = this.router.getByConnectionId(connId);
+            if (peer?.projectId === projectId && (peer.role === 'vite-plugin' || peer.role === 'webpack-plugin')) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private onConnection(ws: WebSocket): void {
+        const connectionId = randomUUID();
+        this.sockets.set(connectionId, ws);
+
+        ws.on('message', (raw) => {
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(raw.toString());
+            } catch {
+                return; // ignore non-JSON
+            }
+            const frame = frameSchema.safeParse(parsed);
+            if (!frame.success) return;
+            this.handleFrame(connectionId, ws, frame.data);
+        });
+
+        ws.on('close', () => {
+            this.sockets.delete(connectionId);
+            this.warnedNoSession.delete(connectionId);
+            // Dashboard subscribers don't have a router/session — just drop them.
+            this.dashboardSubscribers.delete(ws);
+            // Close store session/tab if applicable
+            const storeId = this.connToStoreId.get(connectionId);
+            if (storeId && this.store) {
+                const peer = this.router.getByConnectionId(connectionId);
+                if (peer?.role === 'runtime-client' && peer.tabId) {
+                    // Close the session and tab for this runtime-client.
+                    // storeId is the sessionId for runtime-clients.
+                    this.store.closeSession(storeId);
+                    this.store.closeTab(peer.tabId);
+                    this.connToStoreId.delete(connectionId);
+                    this.notifyDashboard({
+                        kind: 'session.closed',
+                        sessionId: storeId,
+                        projectId: peer.projectId,
+                    });
+                } else if (peer?.role === 'vite-plugin' || peer?.role === 'webpack-plugin') {
+                    // storeId is the buildId for build-plugins.
+                    // Start grace period instead of closing build immediately.
+                    const projectId = peer.projectId;
+                    if (projectId) {
+                        const closedAt = Date.now();
+                        this.pendingEndBuild.set(projectId, { buildId: storeId, closedAt });
+                        const timer = setTimeout(() => {
+                            this.graceTimers.delete(projectId);
+                            const pending = this.pendingEndBuild.get(projectId);
+                            if (pending && pending.buildId === storeId) {
+                                this.pendingEndBuild.delete(projectId);
+                                this.store?.closeBuild(storeId, pending.closedAt);
+                            }
+                        }, 30_000);
+                        this.graceTimers.set(projectId, timer);
+                    } else {
+                        // No projectId — close build immediately
+                        this.store.closeBuild(storeId);
+                    }
+                    this.connToStoreId.delete(connectionId);
+                }
+            }
+            this.router.unregister(connectionId);
+        });
+
+        ws.on('error', () => {
+            /* swallow; close will follow */
+        });
+    }
+
+    private handleFrame(connectionId: string, ws: WebSocket, frame: Frame): void {
+        switch (frame.type) {
+            case 'hello': {
+                // Dashboard-client is a read-only subscriber — it never sends
+                // commands or events. Skip the entire router/session-setup
+                // path; just register for broadcast and ack.
+                if (frame.role === 'dashboard-client') {
+                    this.dashboardSubscribers.add(ws);
+                    const ack: HelloAckFrame = {
+                        type: 'hello.ack',
+                        id: frame.id,
+                        serverVersion: PROTOCOL_VERSION,
+                    };
+                    try { ws.send(JSON.stringify(ack)); } catch { /* swallow */ }
+                    return;
+                }
+
+                // Runtime-client MUST carry a sessionId so every emitted event is
+                // attributable to a specific page load. Reject explicitly so
+                // misconfigured clients surface during development.
+                if (frame.role === 'runtime-client' && !frame.sessionId) {
+                    console.warn(
+                        '[harness-fe] rejecting runtime-client hello — missing sessionId',
+                        { projectId: frame.projectId, tabId: frame.tabId },
+                    );
+                    const errorAck: HelloAckFrame = {
+                        type: 'hello.ack',
+                        id: frame.id,
+                        serverVersion: PROTOCOL_VERSION,
+                        error: 'runtime-client hello missing sessionId',
+                    };
+                    ws.send(JSON.stringify(errorAck));
+                    return;
+                }
+
+                // NOTE: runtime-client is allowed to bootstrap a project on its
+                // own (no plugin required). This is the standard mode for the
+                // @harness-fe/next + jsxImportSource integration and for any
+                // production / staging deployment where the bundler plugin is
+                // absent. The runtime-client branch below opens its own store
+                // session if one does not already exist for this project.
+
+                const session = this.router.register({
+                    role: frame.role,
+                    projectId: frame.projectId,
+                    tabId: frame.tabId,
+                    sessionId: frame.sessionId,
+                    visitorId: frame.visitorId,
+                    userId: frame.userId,
+                    connectionId,
+                    page: frame.page,
+                });
+                // Persist to store
+                if (this.store) {
+                    // Project tree: record parentProjectId / displayName / tags
+                    // the moment we learn about them via any hello frame.
+                    if (
+                        frame.parentProjectId !== undefined ||
+                        frame.displayName !== undefined
+                    ) {
+                        try {
+                            this.store.upsertProject(frame.projectId, {
+                                parentProjectId: frame.parentProjectId,
+                                displayName: frame.displayName,
+                            });
+                        } catch (err) {
+                            // Cycle detection or other validation failure —
+                            // log and continue; the peer still gets registered.
+                            console.warn(
+                                '[harness-fe] upsertProject failed:',
+                                err instanceof Error ? err.message : err,
+                            );
+                        }
+                    }
+                    // Build artifact: record buildId metadata on first sight (runtime-client only;
+                    // plugin openBuild() already handles the build-plugin case).
+                    if (frame.buildId && frame.role === 'runtime-client') {
+                        this.store.upsertBuild(frame.projectId, frame.buildId, {
+                            bundler: undefined,
+                        });
+                    }
+                    // Visitor metadata (0.5+) — write once per hello. The
+                    // runtime sends visitorId+env on every connect; we count
+                    // sessions only on runtime-client hellos to avoid
+                    // double-counting plugin reconnects.
+                    if (frame.visitorId && frame.role === 'runtime-client') {
+                        try {
+                            this.store.upsertVisitor(frame.visitorId, {
+                                userId: frame.userId,
+                                incrementSession: true,
+                                addTabId: frame.tabId,
+                                addProjectId: frame.projectId,
+                                lastEnv: frame.env,
+                            });
+                        } catch (err) {
+                            console.warn(
+                                '[harness-fe] upsertVisitor failed:',
+                                err instanceof Error ? err.message : err,
+                            );
+                        }
+                    }
+
+                    if (frame.role === 'vite-plugin' || frame.role === 'webpack-plugin') {
+                        const projectId = frame.projectId;
+                        // Check if there's a pending grace period for this project
+                        const pendingTimer = projectId ? this.graceTimers.get(projectId) : undefined;
+                        const pendingBuild = projectId ? this.pendingEndBuild.get(projectId) : undefined;
+                        if (pendingTimer !== undefined && pendingBuild !== undefined && projectId) {
+                            // Reconnect within grace period — cancel timer and reuse existing build
+                            clearTimeout(pendingTimer);
+                            this.graceTimers.delete(projectId);
+                            this.pendingEndBuild.delete(projectId);
+                            this.connToStoreId.set(connectionId, pendingBuild.buildId);
+                        } else {
+                            // Open a new build for this dev-server start
+                            const buildId = this.store.openBuild(frame.projectId, {
+                                bundler: frame.role === 'vite-plugin' ? 'vite' : 'webpack',
+                            });
+                            this.connToStoreId.set(connectionId, buildId);
+                        }
+                    } else if (frame.role === 'runtime-client' && frame.tabId) {
+                        // Runtime-client: upsert the pageload session identified by frame.sessionId.
+                        // frame.sessionId is the shared sessionId (shared across same-origin iframes).
+                        const sessionId = frame.sessionId ?? randomUUID();
+                        this.store.upsertTab(frame.tabId, {
+                            connectedAt: Date.now(),
+                            userAgent: frame.page?.userAgent,
+                        });
+                        // Build participants list: use frame.buildId if the plugin already told us about it
+                        const participants: Array<{ projectId: string; buildId?: string; joinedAt: number }> = [
+                            { projectId: frame.projectId, buildId: frame.buildId, joinedAt: Date.now() },
+                        ];
+                        const sessionExisted = this.store.getSession(sessionId) !== undefined;
+                        this.store.upsertSession(sessionId, {
+                            tabId: frame.tabId,
+                            startedAt: Date.now(),
+                            url: frame.page?.url,
+                            title: frame.page?.title,
+                            referrer: undefined,
+                            userAgent: frame.page?.userAgent,
+                            participants,
+                        });
+                        this.connToStoreId.set(connectionId, sessionId);
+                        this.notifyDashboard({
+                            kind: sessionExisted ? 'session.update' : 'session.new',
+                            sessionId,
+                            projectId: frame.projectId,
+                        });
+                    } else if (frame.role === 'node-runtime') {
+                        // Node SDK: server-side events are linked to the per-request sessionId
+                        // when present (the session was already created by the browser runtime-client).
+                        // Process-level events without a sessionId use a per-project orphan bucket.
+                        const sessionId = frame.sessionId
+                            ?? `server-orphans:${sanitizeStoreId(frame.projectId)}`;
+                        if (!frame.sessionId) {
+                            // Ensure the orphan bucket session exists. We use a synthetic
+                            // tabId so upsertSession's required field is satisfied.
+                            this.store.upsertSession(sessionId, {
+                                tabId: 'server-orphans',
+                                startedAt: Date.now(),
+                                participants: [{ projectId: frame.projectId, joinedAt: Date.now() }],
+                            });
+                        }
+                        // For the shared-session case, the runtime-client already created it;
+                        // no upsert needed — we just route events there via connToStoreId.
+                        this.connToStoreId.set(connectionId, sessionId);
+                    }
+                }
+                // If store is null but taskStore is available, load tasks for build plugins
+                // and node-runtime (so MCP tools can serve tasks from both kinds of peers).
+                if (!this.store && this.taskStore && (
+                    frame.role === 'vite-plugin' ||
+                    frame.role === 'webpack-plugin' ||
+                    frame.role === 'node-runtime'
+                )) {
+                    const projectId = frame.projectId;
+                    if (projectId) this.loadTasksForProject(projectId);
+                }
+                const ack: HelloAckFrame = {
+                    type: 'hello.ack',
+                    id: frame.id,
+                    tabId: session.tabId,
+                    serverVersion: PROTOCOL_VERSION,
+                };
+                ws.send(JSON.stringify(ack));
+                // One concise line per accepted peer. Visibility for "is the
+                // runtime actually talking to me?" without needing wireshark.
+                process.stderr.write(
+                    `[harness-fe] peer connected: role=${frame.role} project=${frame.projectId}` +
+                    `${frame.tabId ? ` tab=${frame.tabId.slice(0, 8)}` : ''}` +
+                    `${frame.sessionId ? ` load=${frame.sessionId.slice(0, 8)}` : ''}\n`,
+                );
+                break;
+            }
+            case 'response': {
+                const pending = this.pending.get(frame.id);
+                if (!pending) return; // late response or unknown; drop
+                clearTimeout(pending.timer);
+                this.pending.delete(frame.id);
+                if (frame.ok) pending.resolve(frame.result);
+                else
+                    pending.reject(
+                        new Error(frame.error?.message ?? 'unknown bridge error'),
+                    );
+                break;
+            }
+            case 'event': {
+                this.router.touch(connectionId);
+                const peer = this.router.getByConnectionId(connectionId);
+                if (!peer) return;
+                if (frame.name === EVENT_NAME.TASK_SUBMIT) {
+                    this.recordTask(frame, peer);
+                }
+                // Persist to store
+                if (this.store) {
+                    const storeId = this.connToStoreId.get(connectionId);
+                    // For runtime-clients storeId is the sessionId.
+                    // For build plugins storeId is the buildId — events from plugins
+                    // are appended to the most recent session for that project.
+                    let storeSessionId: string | undefined;
+                    if (peer.role === 'runtime-client' || peer.role === 'node-runtime') {
+                        // For these roles, storeId IS the sessionId (or the orphan bucket id).
+                        storeSessionId = storeId;
+                    } else if (storeId) {
+                        // Build plugin: find most recent session for this project
+                        const sessions = this.store.listSessions({ projectId: peer.projectId, limit: 1 });
+                        storeSessionId = sessions[0]?.id;
+                    }
+
+                    if (!storeSessionId) {
+                        // Should not happen after the hello-time bootstrap above.
+                        // Warn once per connection so silent data loss surfaces.
+                        if (!this.warnedNoSession.has(connectionId)) {
+                            this.warnedNoSession.add(connectionId);
+                            console.warn(
+                                '[harness-fe] dropping event — no store session for connection',
+                                { projectId: peer.projectId, role: peer.role, eventName: frame.name },
+                            );
+                        }
+                    }
+                    if (storeSessionId) {
+                        const tabId = frame.tabId ?? peer.tabId;
+                        // Row-level stamps for multi-project / multi-visitor mixed timelines.
+                        // Prefer the frame's own values (set by the runtime per-event)
+                        // and fall back to the registered peer's identity.
+                        const projectId = peer.projectId;
+                        const buildId = (peer.role === 'vite-plugin' || peer.role === 'webpack-plugin')
+                            ? storeId
+                            : (frame.buildId ?? undefined);
+                        const visitorId = frame.visitorId ?? peer.visitorId;
+
+                        if (frame.name === EVENT_NAME.PAGE_LOAD && tabId) {
+                            const parsed = pageLoadPayloadSchema.safeParse(frame.payload);
+                            const ts = frame.ts ?? Date.now();
+                            const page = parsed.success ? parsed.data.page : undefined;
+                            const viewport = parsed.success ? parsed.data.viewport : undefined;
+                            const storageData = parsed.success ? parsed.data.storage : undefined;
+                            // Update session meta with page info
+                            this.store.upsertSession(storeSessionId, {
+                                tabId: tabId,
+                                startedAt: ts,
+                                url: page?.url ?? peer.page?.url,
+                                title: page?.title ?? peer.page?.title,
+                                referrer: page?.referrer,
+                                userAgent: page?.userAgent ?? peer.page?.userAgent,
+                                initial: {
+                                    viewport,
+                                    storageKeys: storageData
+                                        ? {
+                                            local: storageData.local ? Object.keys(storageData.local).length : 0,
+                                            session: storageData.session ? Object.keys(storageData.session).length : 0,
+                                            cookie: storageData.cookie ? storageData.cookie.length : 0,
+                                        }
+                                        : undefined,
+                                    storageTruncated: storageData?.truncated,
+                                },
+                            });
+                            this.store.appendEvent(storeSessionId, {
+                                ts, t: 'load', tab: tabId,
+                                projectId, buildId, visitorId,
+                                d: frame.payload,
+                            });
+                        } else if (frame.name === EVENT_NAME.RRWEB && tabId) {
+                            const parsed = rrwebChunkPayloadSchema.safeParse(frame.payload);
+                            if (parsed.success) {
+                                // v0.4.0: each session has one recording.jsonl — no tabId/loadId needed
+                                this.store.appendRecording(storeSessionId, parsed.data);
+                                this.notifyDashboard({
+                                    kind: 'session.update',
+                                    sessionId: storeSessionId,
+                                    projectId,
+                                });
+                                this.store.appendEvent(storeSessionId, {
+                                    ts: frame.ts ?? Date.now(),
+                                    t: 'rrweb',
+                                    tab: tabId,
+                                    projectId,
+                                    buildId,
+                                    visitorId,
+                                    d: {
+                                        chunkId: parsed.data.chunkId,
+                                        startTs: parsed.data.startTs,
+                                        endTs: parsed.data.endTs,
+                                        eventCount: parsed.data.eventCount,
+                                    },
+                                });
+                            }
+                        } else {
+                            // app.log events from @harness-fe/log get the canonical
+                            // short type code 'app-log' (consistent with 'server-log',
+                            // 'server-err', 'server-action') rather than the raw frame
+                            // name 'app.log' with a dot.
+                            const eventType: string = frame.name === 'app.log' ? 'app-log' : frame.name as string;
+                            this.store.appendEvent(storeSessionId, {
+                                ts: frame.ts ?? Date.now(),
+                                t: eventType,
+                                tab: tabId,
+                                projectId,
+                                buildId,
+                                visitorId,
+                                d: frame.payload,
+                            });
+                        }
+                        const marker = deriveRecordingMarker(frame, tabId);
+                        if (marker) {
+                            this.store.appendEvent(storeSessionId, {
+                                ts: frame.ts ?? Date.now(),
+                                t: 'rrweb:marker',
+                                tab: tabId,
+                                projectId,
+                                buildId,
+                                d: marker,
+                            });
+                        }
+                    }
+                }
+                for (const listener of this.eventListeners) {
+                    try {
+                        listener(frame, peer);
+                    } catch {
+                        /* swallow listener errors */
+                    }
+                }
+                break;
+            }
+            case 'mcp.call': {
+                void this.handleMcpCall(ws, frame);
+                break;
+            }
+            case 'query': {
+                void this.handleQuery(ws, connectionId, frame);
+                break;
+            }
+            case 'hello.ack':
+            case 'command':
+            case 'mcp.return':
+            case 'query.response':
+                // Server doesn't expect to receive these; ignore.
+                break;
+        }
+    }
+
+    /**
+     * Runtime → daemon query dispatcher (0.5+). Whitelisted methods only.
+     * Owner check: tasks.update / tasks.get / tasks.delete refuse to touch
+     * tasks whose `visitorId` doesn't match the caller's `peer.visitorId`.
+     */
+    private async handleQuery(ws: WebSocket, connectionId: string, frame: QueryFrame): Promise<void> {
+        const reply = (body: Omit<QueryResponseFrame, 'type' | 'id'>): void => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const out: QueryResponseFrame = { type: 'query.response', id: frame.id, ...body };
+            try { ws.send(JSON.stringify(out)); } catch { /* swallow */ }
+        };
+        const peer = this.router.getByConnectionId(connectionId);
+        if (!peer) {
+            reply({ ok: false, error: { code: 'unauthenticated', message: 'no peer for connection' } });
+            return;
+        }
+        if (peer.role !== 'runtime-client' || !peer.visitorId) {
+            reply({ ok: false, error: { code: 'forbidden', message: 'only runtime-client with visitorId may query' } });
+            return;
+        }
+        if (!this.taskStore) {
+            reply({ ok: false, error: { code: 'unavailable', message: 'no task store' } });
+            return;
+        }
+        const projectId = peer.projectId;
+        const callerVisitor = peer.visitorId;
+
+        try {
+            switch (frame.method) {
+                case 'tasks.mine': {
+                    const args = (frame.args ?? {}) as { status?: string; limit?: number };
+                    const all = this.taskStore.loadTasks(projectId);
+                    let mine = all.filter((t) => t.visitorId === callerVisitor);
+                    if (args.status) mine = mine.filter((t) => t.status === args.status);
+                    mine.sort((a, b) => b.createdAt - a.createdAt);
+                    if (args.limit) mine = mine.slice(0, args.limit);
+                    // Inline first attachment's base64 if ≤ 200 KB
+                    const MAX_INLINE = 200 * 1024; // base64 chars
+                    const withThumbs = mine.map((t) => {
+                        if (!t.attachments || t.attachments.length === 0) return t;
+                        const first = t.attachments[0];
+                        if (!first.path) return t;
+                        const b64 = this.readTaskAttachment(t.projectId, t.id, first.id);
+                        if (!b64 || b64.length > MAX_INLINE) return t;
+                        const inlined = { ...first, data: b64 };
+                        return { ...t, attachments: [inlined, ...t.attachments.slice(1)] };
+                    });
+                    reply({ ok: true, result: { tasks: withThumbs } });
+                    return;
+                }
+                case 'tasks.get': {
+                    const args = (frame.args ?? {}) as { id?: string };
+                    if (!args.id) {
+                        reply({ ok: false, error: { code: 'bad_request', message: 'id required' } });
+                        return;
+                    }
+                    const task = this.taskStore.loadTasks(projectId).find((t) => t.id === args.id);
+                    if (!task) {
+                        reply({ ok: false, error: { code: 'not_found', message: `no task ${args.id}` } });
+                        return;
+                    }
+                    if (task.visitorId !== callerVisitor) {
+                        reply({ ok: false, error: { code: 'forbidden', message: 'not your task' } });
+                        return;
+                    }
+                    reply({ ok: true, result: { task } });
+                    return;
+                }
+                case 'tasks.update': {
+                    const args = (frame.args ?? {}) as { id?: string; question?: string };
+                    if (!args.id || typeof args.question !== 'string') {
+                        reply({ ok: false, error: { code: 'bad_request', message: 'id + question required' } });
+                        return;
+                    }
+                    const tasks = this.taskStore.loadTasks(projectId);
+                    const idx = tasks.findIndex((t) => t.id === args.id);
+                    if (idx === -1) {
+                        reply({ ok: false, error: { code: 'not_found', message: `no task ${args.id}` } });
+                        return;
+                    }
+                    if (tasks[idx].visitorId !== callerVisitor) {
+                        reply({ ok: false, error: { code: 'forbidden', message: 'not your task' } });
+                        return;
+                    }
+                    tasks[idx] = { ...tasks[idx], question: args.question.trim(), updatedAt: Date.now() };
+                    this.taskStore.saveTasks(projectId, tasks);
+                    reply({ ok: true, result: { task: tasks[idx] } });
+                    return;
+                }
+                case 'tasks.delete': {
+                    const args = (frame.args ?? {}) as { id?: string };
+                    if (!args.id) {
+                        reply({ ok: false, error: { code: 'bad_request', message: 'id required' } });
+                        return;
+                    }
+                    const tasks = this.taskStore.loadTasks(projectId);
+                    const target = tasks.find((t) => t.id === args.id);
+                    if (!target) {
+                        reply({ ok: false, error: { code: 'not_found', message: `no task ${args.id}` } });
+                        return;
+                    }
+                    if (target.visitorId !== callerVisitor) {
+                        reply({ ok: false, error: { code: 'forbidden', message: 'not your task' } });
+                        return;
+                    }
+                    const remaining = tasks.filter((t) => t.id !== args.id);
+                    this.taskStore.saveTasks(projectId, remaining);
+                    // Also remove from in-memory queue so MCP tasks.pending stays in sync.
+                    this.tasks.delete(args.id);
+                    reply({ ok: true, result: { deleted: args.id } });
+                    return;
+                }
+                default:
+                    reply({ ok: false, error: { code: 'unknown_method', message: `unknown query method` } });
+            }
+        } catch (err) {
+            reply({
+                ok: false,
+                error: { code: 'internal', message: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+
+    private async handleMcpCall(ws: WebSocket, frame: McpCallFrame): Promise<void> {
+        const reply = (payload: Omit<McpReturnFrame, 'type' | 'id'>): void => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const out: McpReturnFrame = { type: 'mcp.return', id: frame.id, ...payload };
+            try {
+                ws.send(JSON.stringify(out));
+            } catch {
+                /* swallow */
+            }
+        };
+        try {
+            const result = await this.invokeMcpMethod(frame.method, frame.args);
+            reply({ ok: true, result });
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            reply({ ok: false, error: { message } });
+        }
+    }
+
+    private async invokeMcpMethod(method: McpCallFrame['method'], args: unknown): Promise<unknown> {
+        switch (method) {
+            case 'sendCommand': {
+                const a = (args ?? {}) as {
+                    command: string;
+                    args?: unknown;
+                    opts?: SendCommandOptions;
+                };
+                return this.sendCommand(a.command, a.args, a.opts);
+            }
+            case 'listTabs':
+                return this.listTabs();
+            case 'listTasks': {
+                const a = (args ?? {}) as { status?: TaskStatus | 'all'; limit?: number };
+                return this.listTasks(a);
+            }
+            case 'claimTask': {
+                const a = args as { id: string };
+                return this.claimTask(a.id);
+            }
+            case 'resolveTask': {
+                const a = args as { id: string; note?: string };
+                return this.resolveTask(a.id, a.note);
+            }
+            // ─── Store methods (proxied from follower) ─────────────────────
+            case 'storeListProjects': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                return this.store.listProjects();
+            }
+            case 'storeListSessions': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as { projectId?: string; tabId?: string; buildId?: string; limit?: number };
+                return this.store.listSessions({ projectId: a.projectId, tabId: a.tabId, buildId: a.buildId, limit: a.limit });
+            }
+            case 'storeSummary': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as { sessionId: string };
+                return this.store.summary(a.sessionId);
+            }
+            case 'storeTail': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as {
+                    sessionId: string;
+                    opts?: import('./store/index.js').TailOptions;
+                };
+                return this.store.tail(a.sessionId, a.opts);
+            }
+            case 'storeSearch': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as {
+                    sessionId: string;
+                    query: string;
+                    opts?: import('./store/index.js').SearchOptions;
+                };
+                return this.store.search(a.sessionId, a.query, a.opts);
+            }
+            case 'storeRecordingsList': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as { sessionId: string };
+                return this.store.listRecordings(a.sessionId);
+            }
+            case 'storeRecordingsSlice': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = args as { sessionId: string; since: number; until: number };
+                return this.store.sliceRecordings(a.sessionId, a.since, a.until);
+            }
+            case 'storeReplayCreate': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const { createReplayExport } = await import('./replayCreate.js');
+                return createReplayExport(this.store, this.getViewerBaseUrl(), args as Parameters<typeof createReplayExport>[2]);
+            }
+            case 'storePurge': {
+                if (!this.store) throw new Error('bridge: store is not enabled');
+                const a = (args ?? {}) as import('./store/index.js').RetentionPolicy;
+                return this.store.purge(a);
+            }
+            // ─── Memory methods (proxied from follower) ────────────────────
+            case 'memorySet': {
+                const a = args as { projectId: string; key: string; value: string };
+                return this.memoryStore.set(a.projectId, a.key, a.value);
+            }
+            case 'memoryGet': {
+                const a = args as { projectId: string; key: string };
+                return this.memoryStore.get(a.projectId, a.key);
+            }
+            case 'memoryList': {
+                const a = args as { projectId: string };
+                return this.memoryStore.list(a.projectId);
+            }
+            case 'memoryDelete': {
+                const a = args as { projectId: string; key: string };
+                return this.memoryStore.delete(a.projectId, a.key);
+            }
+        }
+    }
+}
+
+function deriveRecordingMarker(frame: EventFrame, tabId?: string): Record<string, unknown> | undefined {
+    if (!tabId) return undefined;
+
+    if (frame.name === 'error') {
+        const payload = frame.payload as { message?: unknown; source?: unknown } | undefined;
+        return {
+            markerId: `rrm_${frame.id}`,
+            kind: 'error',
+            ts: frame.ts,
+            tabId,
+            label: typeof payload?.message === 'string' ? payload.message : 'Runtime error',
+            relatedEventType: 'error',
+            source: typeof payload?.source === 'string' ? payload.source : undefined,
+        };
+    }
+
+    if (frame.name === 'network') {
+        const payload = frame.payload as { status?: unknown; method?: unknown; url?: unknown } | undefined;
+        const status = typeof payload?.status === 'number' ? payload.status : undefined;
+        if (status === undefined || (status > 0 && status < 400)) return undefined;
+        const method = typeof payload?.method === 'string' ? payload.method : 'REQUEST';
+        const url = typeof payload?.url === 'string' ? payload.url : 'unknown URL';
+        return {
+            markerId: `rrm_${frame.id}`,
+            kind: 'network',
+            ts: frame.ts,
+            tabId,
+            label: `${method} ${url} -> ${status ?? 'ERR'}`,
+            relatedEventType: 'network',
+            status,
+        };
+    }
+
+    if (frame.name === 'console') {
+        const payload = frame.payload as { level?: unknown; args?: unknown } | undefined;
+        if (payload?.level !== 'error') return undefined;
+        const firstArg = Array.isArray(payload.args) ? payload.args[0] : undefined;
+        return {
+            markerId: `rrm_${frame.id}`,
+            kind: 'console',
+            ts: frame.ts,
+            tabId,
+            label: typeof firstArg === 'string' ? firstArg : 'console.error',
+            relatedEventType: 'console',
+        };
+    }
+
+    if (frame.name === EVENT_NAME.TASK_SUBMIT) {
+        const parsed = taskSubmitPayloadSchema.safeParse(frame.payload);
+        if (!parsed.success) return undefined;
+        return {
+            markerId: `rrm_${frame.id}`,
+            kind: 'task',
+            ts: frame.ts,
+            tabId,
+            label: parsed.data.question,
+            relatedEventType: EVENT_NAME.TASK_SUBMIT,
+        };
+    }
+
+    return undefined;
+}
+
+/** Extract the pathname portion of a request URL (without query string). */
+function pathnameOf(url: string): string {
+    const qi = url.indexOf('?');
+    return qi < 0 ? url : url.slice(0, qi);
+}
+
+/** Return the first non-internal IPv4 address from the OS interfaces. */
+function firstNonInternalIpv4(): string | undefined {
+    const ifaces = networkInterfaces();
+    for (const list of Object.values(ifaces)) {
+        if (!list) continue;
+        for (const info of list) {
+            if (info.family === 'IPv4' && !info.internal) return info.address;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Strip large binary payloads (e.g. screenshot dataUrls) from command results
+ * before persisting to the store, to avoid bloating timeline files.
+ */
+function stripLargePayloads(value: unknown): unknown {
+    if (typeof value === 'string' && value.startsWith('data:') && value.length > 1024) {
+        return '[large data url omitted]';
+    }
+    if (value !== null && typeof value === 'object') {
+        const result: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            result[k] = stripLargePayloads(v);
+        }
+        return result;
+    }
+    return value;
+}