@opencorelabs/lucidity 0.1.0

package/dist/room/client.js

@@ -0,0 +1,677 @@
+import { WebSocket } from 'ws';
+import { HarnessRequestSchema } from '@lucidity/shared';
+import { loadAskContext, loadBriefingContext, } from './context.js';
+import { resolveRepo } from '../coding/repos.js';
+import { listAllowlist } from '../coding/discover.js';
+import { currentBranch, repoWebUrl } from '../coding/worktree.js';
+import { listPrs as resolvePrs } from '../coding/listPrs.js';
+import { combineSignals, consumeResumed, isAbortError, RESUME_FIRST_OUTPUT_MS, } from '../streamDeadline.js';
+import { TurnLogStore } from '../turnLog.js';
+import { RoomTelemetry } from './telemetry.js';
+import { buildIncidentBundle, writeIncidentBundle } from './incidents.js';
+import { writeVoiceDiagBundle } from './voiceDiag.js';
+/** Frame `type`s that carry recoverable turn output — the ones written to the durable
+ *  turn log and stamped with a `seq`. Buffered responses (`kind` replies) and any other
+ *  control frame are forwarded verbatim, unlogged and unstamped. */
+/** How long a composed board is reused before a plain `attention` fetch pays for a new one.
+ *  The Dashboard fetches on every open, so without this a few app switches would each cost a
+ *  model turn to re-say the same thing. Pull-to-refresh bypasses it. */
+const BOARD_CACHE_MS = 15 * 60 * 1000;
+const STREAM_EVENT_TYPES = new Set([
+    'delta',
+    'tool_call',
+    'done',
+    'code_result',
+    'clone_result',
+    'error',
+    'cancelled',
+    // Conductor fleet events — logged + seq-stamped like any turn frame so a mid-fleet `pull`
+    // replays the plan and the workers' progress instead of settling the turn as cut off.
+    'fleet_plan',
+    'worker_status',
+    'fleet_conflict',
+    'worker_pr',
+    'fleet_done',
+]);
+function sendStreamEvent(send, requestId, ev, freshStart = false) {
+    if (ev.type === 'delta')
+        send({ type: 'delta', requestId, text: ev.text });
+    else if (ev.type === 'tool_call')
+        send({ type: 'tool_call', requestId, name: ev.name, phase: ev.phase });
+    else
+        send({
+            type: 'done',
+            requestId,
+            text: ev.text,
+            sessionId: ev.sessionId,
+            costUsd: ev.costUsd,
+            ...(freshStart ? { freshStart: true } : {}),
+        });
+}
+/**
+ * Route one raw wire message to the harness and emit the reply. Pure of any
+ * socket/reconnect concern so it is unit-testable with a fake harness + a
+ * capturing `send`. Unparseable input is dropped (no id to correlate a reply);
+ * a mid-run failure becomes a correlated `error` stream event.
+ */
+export async function dispatchRequest(raw, deps) {
+    const { harness, askContext, briefingContext, send, signal: outerSignal, inFlight, attention, } = deps;
+    const log = deps.logger ?? ((m) => console.error(`[room] ${m}`));
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    const parsed = HarnessRequestSchema.safeParse(json);
+    if (!parsed.success)
+        return;
+    const req = parsed.data;
+    deps.telemetry?.record('request', req.kind, req.id);
+    // The phone shipped its flight-recorder ledger (#314). Join it to the turn log and write a
+    // correlated incident bundle. Runs no model, so it's handled before the AbortController setup.
+    if (req.kind === 'incident') {
+        const bundle = buildIncidentBundle({
+            ledger: req.ledger,
+            turnLogs: deps.turnLogs,
+            timeline: deps.telemetry?.recent() ?? [],
+            machine: deps.machine ?? '',
+            focusRequestId: req.focusRequestId,
+            reason: req.reason,
+            snapshot: req.snapshot,
+            diag: req.diag,
+        });
+        const path = writeIncidentBundle(bundle, deps.incidentsDir);
+        deps.telemetry?.record('incident', bundle.summary, bundle.requestId ?? undefined);
+        send({
+            requestId: req.id,
+            kind: 'incident',
+            written: path != null,
+            ...(path ? { path } : {}),
+            summary: bundle.summary,
+        });
+        return;
+    }
+    // The phone shipped a voice diagnostic capture ("Speak & Diagnose"). Write it beside the
+    // incident bundles for a Claude session to pick apart. Runs no model, like the incident path.
+    if (req.kind === 'voice-diag') {
+        const path = writeVoiceDiagBundle(req);
+        send({
+            requestId: req.id,
+            kind: 'voice-diag',
+            written: path != null,
+            ...(path ? { path } : {}),
+        });
+        return;
+    }
+    if (req.kind === 'cancel') {
+        const controller = inFlight?.get(req.targetId);
+        if (controller) {
+            controller.abort();
+            // Route through `send` so the terminal is logged (shares the turn's seq counter,
+            // landing at maxSeq+1) — a later pull then sees a settled turn.
+            send({ type: 'cancelled', requestId: req.targetId });
+        }
+        return;
+    }
+    // Re-fetch an interrupted turn from its durable log. Runs no model, so it's handled
+    // before the AbortController setup. Everything replays under `targetId` (never this
+    // request's own id), so the phone routes frames back to the existing turn.
+    if (req.kind === 'pull') {
+        const { turnLogs, sendRaw } = deps;
+        const state = turnLogs.read(req.targetId);
+        if (!state.exists) {
+            // Evicted (>24h) or never existed — tell the phone so it can settle + offer Resend.
+            sendRaw({
+                type: 'error',
+                requestId: req.targetId,
+                message: 'This turn is no longer available to resume.',
+            });
+            return;
+        }
+        // Replay the gap verbatim (already logged; don't re-log).
+        for (const frame of state.frames) {
+            if (frame.seq > req.sinceSeq)
+                sendRaw(frame);
+        }
+        // Open log (no terminal) with no live run owning it → the subprocess died (the daemon
+        // restarted mid-turn). Settle it with a synthesized, persisted terminal so the phone
+        // stops waiting and a repeat pull is idempotent. If it's still in `inFlight`, live
+        // frames past maxSeq keep flowing on the current socket (deduped by seq) — leave it.
+        if (!state.terminated && !inFlight?.has(req.targetId)) {
+            sendRaw(turnLogs.append(req.targetId, {
+                type: 'error',
+                requestId: req.targetId,
+                message: 'Lucid restarted before finishing this turn.',
+            }));
+        }
+        return;
+    }
+    // Own abort controller per request, combined with the daemon-shutdown signal, so a
+    // `cancel` message (stop button) can kill just this run without affecting others.
+    const ownController = new AbortController();
+    const signal = combineSignals(outerSignal, ownController.signal);
+    inFlight?.set(req.id, ownController);
+    // Wait for the lane INSIDE the try, and after `inFlight.set` above — a turn waiting its turn
+    // must still be cancellable, and the `signal?.aborted` checks below mean a cancel that lands
+    // while queued drops the run instead of starting it late.
+    const onLane = (lane, fn) => deps.queue ? deps.queue.run(lane, fn) : fn();
+    try {
+        if (req.kind === 'ask') {
+            await onLane('room:ask', async () => {
+                const base = {
+                    ...(await askContext()),
+                    prompt: req.prompt,
+                    images: req.images,
+                    signal,
+                };
+                if (req.stream) {
+                    // Set once we abandon the resume and answer fresh, so the `done` we emit then is
+                    // flagged as memoryless for the phone. Read by `onEvent` at emit time.
+                    let freshStart = false;
+                    const onEvent = (ev) => sendStreamEvent(send, req.id, ev, freshStart);
+                    // Self-heal a dead resume handle: Claude Code's --resume fails silently
+                    // (no result event) when the session id is stale/pruned or predates a cwd
+                    // change — and it *hangs* rather than ending, so we bound the resumed
+                    // attempt with a first-output deadline. Yields nothing in time → retry once
+                    // fresh so the turn still lands and a new session id is captured. A user
+                    // cancel (`signal.aborted`) must not retry. Mirrors runCodeTurn.
+                    const resumed = req.resume
+                        ? await consumeResumed((sig) => harness.askStream({
+                            ...base,
+                            resume: req.resume,
+                            signal: sig,
+                        }), onEvent, {
+                            signal,
+                            deadlineMs: deps.resumeDeadlineMs ?? RESUME_FIRST_OUTPUT_MS,
+                            // A resume that errors before output (session pruned, or created under a
+                            // different cwd) is a dead handle, not a real failure — fall through to fresh.
+                            recoverErrors: true,
+                        })
+                        : false;
+                    if (!resumed && !signal?.aborted) {
+                        freshStart = Boolean(req.resume); // only a "reset" if the user expected continuity
+                        for await (const ev of harness.askStream({
+                            ...base,
+                            resume: undefined,
+                        }))
+                            onEvent(ev);
+                    }
+                }
+                else {
+                    const reply = await harness.ask({ ...base, resume: req.resume });
+                    send({
+                        requestId: req.id,
+                        kind: 'ask',
+                        text: reply.text,
+                        sessionId: reply.sessionId,
+                        costUsd: reply.costUsd,
+                    });
+                }
+            });
+        }
+        else if (req.kind === 'briefing') {
+            const input = { ...(await briefingContext()), signal };
+            if (req.stream) {
+                for await (const ev of harness.briefingStream(input))
+                    sendStreamEvent(send, req.id, ev);
+            }
+            else {
+                const reply = await harness.briefing(input);
+                send({
+                    requestId: req.id,
+                    kind: 'briefing',
+                    text: reply.text,
+                    costUsd: reply.costUsd,
+                });
+            }
+        }
+        else if (req.kind === 'attention') {
+            // The Dashboard asking for its board (#320). Serve the cached one when it's recent enough
+            // — the screen fetches on every open, and spending a model turn to re-say what Lucid said
+            // four minutes ago is pure cost. Pull-to-refresh sets `refresh` to bypass that.
+            const cached = attention?.latest();
+            const fresh = cached &&
+                Date.now() - new Date(cached.writtenAt).getTime() < BOARD_CACHE_MS;
+            const cachedReply = cached
+                ? { boards: cached.boards, writtenAt: cached.writtenAt }
+                : null;
+            if (cached && fresh && !req.refresh) {
+                send({ requestId: req.id, kind: 'attention', board: cachedReply });
+            }
+            else {
+                const writtenAt = new Date();
+                let composed = null;
+                try {
+                    const reply = await harness.attentionBoard({
+                        ...(await briefingContext()),
+                        signal,
+                    });
+                    // publish() rather than replying alone: it caches for the next pull and pushes to any
+                    // other device, so boards composed for one phone aren't invisible to the rest.
+                    if (reply.boards.length) {
+                        attention?.publish(reply.boards, writtenAt);
+                        composed = {
+                            boards: reply.boards,
+                            writtenAt: writtenAt.toISOString(),
+                        };
+                    }
+                }
+                catch (err) {
+                    log(`attention board failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                // Null leaves the phone's cached boards alone — a failed refresh shouldn't blank the
+                // Deck. Falls back to whatever was cached here if the compose produced nothing.
+                send({
+                    requestId: req.id,
+                    kind: 'attention',
+                    board: composed ?? cachedReply,
+                });
+            }
+        }
+        else if (req.kind === 'journal') {
+            const result = await harness.journal({
+                limit: req.limit,
+                before: req.before,
+            });
+            send({
+                requestId: req.id,
+                kind: 'journal',
+                entries: result.entries,
+                nextBefore: result.nextBefore,
+            });
+        }
+        else if (req.kind === 'repos') {
+            send({
+                requestId: req.id,
+                kind: 'repos',
+                repos: (await deps.listRepos?.()) ?? [],
+            });
+        }
+        else if (req.kind === 'prs') {
+            const r = (await deps.listPrs?.(req.repoId, req.mode)) ?? { prs: [] };
+            send({
+                requestId: req.id,
+                kind: 'prs',
+                branch: r.branch,
+                prs: r.prs,
+                error: r.error,
+            });
+        }
+        else if (req.kind === 'clone') {
+            if (deps.cloneHandler)
+                await deps.cloneHandler({ id: req.id, url: req.url }, { send, signal });
+            else
+                send({
+                    type: 'error',
+                    requestId: req.id,
+                    message: 'Cloning is not enabled on this daemon yet.',
+                });
+        }
+        else if (req.kind === 'getConfig') {
+            // Daemon Settings read: reply with the redacted config (secrets stripped).
+            if (deps.getConfig)
+                send({ requestId: req.id, kind: 'config', config: deps.getConfig() });
+            else
+                send({
+                    type: 'error',
+                    requestId: req.id,
+                    message: 'Config is not available on this daemon.',
+                });
+        }
+        else if (req.kind === 'setConfig') {
+            // Daemon Settings write: persist + live-apply, ack with the new config, THEN (if the
+            // patch touched a boot-wired field and a restart was requested) relaunch — the ack
+            // must go out before the socket drops, so requestRestart runs after send.
+            if (!deps.setConfig) {
+                send({
+                    type: 'error',
+                    requestId: req.id,
+                    message: 'Editing config is not available on this daemon.',
+                });
+            }
+            else {
+                const r = deps.setConfig(req.patch, req.restart ?? false);
+                send({
+                    requestId: req.id,
+                    kind: 'config',
+                    config: r.config,
+                    needsRestart: r.needsRestart,
+                    restarting: r.restarting,
+                });
+                if (r.restarting)
+                    deps.requestRestart?.();
+            }
+        }
+        else if (req.kind === 'conduct') {
+            if (deps.conductHandler) {
+                // The whole fleet holds the repo's lane: its workers write isolated worktrees, but
+                // integration resets and merges onto lucid/<repo>, so no other turn on this repo (a
+                // bare code turn, or a second fleet) may run meanwhile.
+                await onLane(`room:code:${req.repoId}`, () => deps.conductHandler({
+                    id: req.id,
+                    repoId: req.repoId,
+                    phase: req.phase,
+                    prompt: req.prompt,
+                    images: req.images,
+                    plan: req.plan,
+                    resume: req.resume,
+                    // Forward it or a quick spawn silently mints a parent task + subtask anyway: the
+                    // phone sends `ephemeral`, conduct honours it, and this hop used to drop it.
+                    ephemeral: req.ephemeral,
+                }, { send, signal }));
+            }
+            else {
+                send({
+                    type: 'error',
+                    requestId: req.id,
+                    message: 'The conductor is not enabled on this daemon.',
+                });
+            }
+        }
+        else if (deps.codeHandler) {
+            // Per-worktree lane: two turns sharing a worktree/cwd must serialize, but genuinely
+            // independent work runs in parallel. The bare repo session and each conductor worker
+            // (`workerId`) own separate worktrees, so each gets its own lane — a phone turn drilled
+            // into worker A can't collide with worker B, and a bare turn keeps today's exact key.
+            const lane = req.workerId
+                ? `room:code:${req.repoId}:${req.workerId}`
+                : `room:code:${req.repoId}`;
+            await onLane(lane, () => deps.codeHandler({
+                id: req.id,
+                repoId: req.repoId,
+                prompt: req.prompt,
+                images: req.images,
+                resume: req.resume,
+                mode: req.mode,
+                expectedBranch: req.expectedBranch,
+                workerId: req.workerId,
+            }, { send, signal }));
+        }
+        else {
+            send({
+                type: 'error',
+                requestId: req.id,
+                message: 'Coding is not enabled on this daemon yet.',
+            });
+        }
+    }
+    catch (err) {
+        // A deadline/cancel abort surfaces as an AbortError ("The operation was aborted").
+        // Never forward that literal text to the phone — end the turn quietly instead.
+        if (isAbortError(err))
+            return;
+        const message = err instanceof Error ? err.message : String(err);
+        deps.telemetry?.record('dispatch-error', message, req.id);
+        send({ type: 'error', requestId: req.id, message });
+    }
+    finally {
+        inFlight?.delete(req.id);
+    }
+}
+const MAX_BACKOFF_MS = 30_000;
+// Last-resort re-dial watchdog. Reconnection used to hang off exactly ONE event — 'close' —
+// so any path that skipped it left the daemon alive but permanently out of the room, with the
+// phone showing "Connecting to Mac Mini…" forever. Seen for real on a Wi-Fi switch: a bare
+// `socket error:` with no message, no 'close' after it, and nothing re-dialed for 11 minutes
+// until the daemon was kicked by hand. The half-open heartbeat (#146) can't save that case —
+// it only ticks while readyState is OPEN. So we also sweep on a timer and re-dial whenever no
+// live socket exists and no attempt is already armed.
+const REDIAL_WATCHDOG_MS = 30_000;
+/**
+ * Should we dial again right now? Pure so the "daemon never came back" class of bug is
+ * testable without a socket: `readyState` is the current socket's (undefined = no socket).
+ */
+export function needsRedial(state) {
+    if (state.stopped || state.reconnectPending)
+        return false;
+    return state.readyState !== WebSocket.OPEN && state.readyState !== WebSocket.CONNECTING;
+}
+// Client-side liveness watchdog (#146). The `ws` package auto-answers the server's
+// protocol pings, so the SERVER always sees us as alive — but nothing tells the daemon
+// when its OWN socket has gone half-open (the Mac's Wi-Fi dropped or its LAN IP changed,
+// leaving a zombie ESTABLISHED socket the OS never RSTs). No 'close'/'error' ever fires,
+// so the server reaps that socket in ~15s and the phone shows daemon=false while the
+// daemon sits "connected" forever and never re-dials. So we ping on our own interval and
+// force a reconnect when pings go unanswered. 15s matches the server's sweep cadence; two
+// missed pongs ≈ 30-45s of silence before we terminate — tolerant of one dropped pong.
+const HEARTBEAT_MS = 15_000;
+const DEAD_AFTER_MISSES = 2;
+/**
+ * Build a liveness watchdog for one open socket. Each {@link Heartbeat.tick} either
+ * forces the socket closed (once `deadAfterMisses` pings have gone unanswered — the
+ * signature of a half-open zombie) or sends the next ping; {@link Heartbeat.markAlive}
+ * resets the miss counter. `terminate()` surfaces as the socket's `close`, which drives
+ * the existing backoff reconnect.
+ */
+export function createHeartbeat(socket, deadAfterMisses = DEAD_AFTER_MISSES) {
+    let missed = 0;
+    return {
+        markAlive() {
+            missed = 0;
+        },
+        tick() {
+            if (missed >= deadAfterMisses) {
+                socket.terminate();
+                return;
+            }
+            missed++;
+            socket.ping();
+        },
+    };
+}
+/** Build the daemon's room URL from the API base, upgrading the scheme to ws/wss.
+ *  `machine` is advertised to the server for the phone's presence UI. */
+export function roomUrl(apiUrl, machine) {
+    const u = new URL('/api/room', apiUrl);
+    u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+    u.searchParams.set('role', 'daemon');
+    if (machine)
+        u.searchParams.set('machine', machine);
+    return u.toString();
+}
+/**
+ * Start the room client. Returns a handle whose `stop()` closes the socket and
+ * halts reconnection. Also stops automatically if `signal` aborts.
+ */
+export function startRoomClient(opts) {
+    const { config, harness, vault, signal, codeHandler, conductHandler, cloneHandler, queue, getConfig, setConfig, requestRestart, } = opts;
+    const log = opts.logger ?? ((m) => console.error(`[room] ${m}`));
+    const url = roomUrl(config.apiUrl, config.machineName);
+    const askContext = () => loadAskContext(config, vault);
+    const briefingContext = () => loadBriefingContext(config, vault);
+    const turnLogs = opts.turnLogs ?? new TurnLogStore();
+    // The daemon's side of an incident bundle (#314): a rolling connection timeline the
+    // `incident` handler joins to the turn log. In-memory — the durable evidence is the turn log.
+    const telemetry = new RoomTelemetry();
+    let stopped = false;
+    let socket = null;
+    let reconnectTimer = null;
+    let attempt = 0;
+    // Survives reconnects — an in-flight run outlives a dropped socket, so a `cancel`
+    // sent after re-dialing must still be able to find and abort it.
+    const inFlight = new Map();
+    // Send to whatever socket is CURRENT, read fresh each call — an in-flight turn started
+    // on a socket that later dropped must deliver its remaining frames to the reconnected
+    // socket, not the dead closure it began with (the frames are also in the turn log, so a
+    // gap the phone missed is still pullable).
+    const sendRaw = (obj) => {
+        if (socket && socket.readyState === WebSocket.OPEN)
+            socket.send(JSON.stringify(obj));
+    };
+    // The turn-aware send: a recoverable stream frame is logged (and stamped with `seq`)
+    // before it goes on the wire; everything else (buffered `kind` replies, control frames)
+    // passes through verbatim, unlogged.
+    const turnSend = (obj) => {
+        if (obj && typeof obj === 'object') {
+            const rec = obj;
+            if (typeof rec.type === 'string' &&
+                STREAM_EVENT_TYPES.has(rec.type) &&
+                typeof rec.requestId === 'string') {
+                sendRaw(turnLogs.append(rec.requestId, rec));
+                return;
+            }
+        }
+        sendRaw(obj);
+    };
+    // The phone's repo list — recomputed live so a freshly-cloned repo appears with no restart, and
+    // each row carries its current branch (what an in-place turn commits onto, #121). Shared by the
+    // `repos` request handler and the unsolicited pushRepos() refresh below.
+    const listRepos = async () => {
+        const allow = listAllowlist(config);
+        const resolved = allow.flatMap((r) => resolveRepo(r.id, allow) ?? []);
+        return Promise.all(resolved.map(async (r) => {
+            // A detached HEAD reports the literal "HEAD" — not a branch, so send none.
+            const [branch, htmlUrl] = await Promise.all([
+                currentBranch(r.root).catch(() => ''),
+                repoWebUrl(r.root).catch(() => undefined),
+            ]);
+            return {
+                id: r.id,
+                branch: branch && branch !== 'HEAD' ? branch : undefined,
+                allowInPlace: config.allowInPlace,
+                htmlUrl,
+            };
+        }));
+    };
+    // Unsolicited repo refresh (#121 follow-up): the branch watcher fires this when the Mac's
+    // checkout moves, so the phone's header updates without waiting for its next `repos` poll. A raw
+    // push — no requestId, like the attention board (#320); a dropped one heals on the next poll.
+    const pushRepos = async () => {
+        sendRaw({ kind: 'repos', repos: await listRepos() });
+    };
+    function scheduleReconnect() {
+        if (stopped || reconnectTimer)
+            return;
+        const delay = Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS) +
+            Math.floor(Math.random() * 500);
+        telemetry.record('reconnect', `#${attempt + 1} in ${delay}ms`);
+        attempt++;
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            // connect() can throw synchronously while the network is mid-switch (DNS/interface in
+            // flux). Unguarded, that escapes the timer with no timer left to fire and nothing
+            // rearms — the daemon is out of the room for good. Catch it and back off instead.
+            try {
+                connect();
+            }
+            catch (err) {
+                log(`re-dial failed: ${err instanceof Error ? err.message : String(err)}`);
+                scheduleReconnect();
+            }
+        }, delay);
+        reconnectTimer.unref?.();
+    }
+    function connect() {
+        if (stopped)
+            return;
+        const ws = new WebSocket(url, {
+            headers: { Authorization: `Bearer ${config.apiKey}` },
+        });
+        socket = ws;
+        const heartbeat = createHeartbeat(ws);
+        let heartbeatTimer = null;
+        ws.on('open', () => {
+            attempt = 0;
+            telemetry.record('open', url);
+            log(`connected to ${url}`);
+            // Watch our own liveness (#146): a half-open socket never fires 'close', so without
+            // this ping loop a dropped network leaves the daemon falsely "connected" and offline
+            // to the phone. A terminate() from the watchdog surfaces as 'close' → reconnect.
+            heartbeat.markAlive();
+            heartbeatTimer = setInterval(() => {
+                if (ws.readyState === WebSocket.OPEN)
+                    heartbeat.tick();
+            }, HEARTBEAT_MS);
+            heartbeatTimer.unref?.();
+        });
+        ws.on('pong', () => heartbeat.markAlive());
+        ws.on('message', (data) => {
+            heartbeat.markAlive();
+            const raw = Array.isArray(data)
+                ? Buffer.concat(data).toString()
+                : data.toString();
+            void dispatchRequest(raw, {
+                harness,
+                askContext,
+                briefingContext,
+                send: turnSend,
+                sendRaw,
+                turnLogs,
+                signal,
+                codeHandler,
+                conductHandler,
+                cloneHandler,
+                queue,
+                inFlight,
+                attention: opts.attention,
+                logger: log,
+                // Live allowlist (#78) + each row's live branch (#121); shared with pushRepos above.
+                listRepos,
+                listPrs: (repoId, mode) => resolvePrs(repoId, mode, config),
+                getConfig,
+                setConfig,
+                requestRestart,
+                telemetry,
+                machine: config.machineName,
+                incidentsDir: opts.incidentsDir,
+            }).catch((err) => {
+                log(`dispatch error: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        });
+        ws.on('close', (code, reason) => {
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            if (socket === ws)
+                socket = null;
+            const why = reason?.length
+                ? `${code} ${reason.toString()}`
+                : String(code);
+            telemetry.record('close', why);
+            scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            telemetry.record('error', err.message);
+            log(`socket error: ${err.message}`);
+            // 'close' USUALLY follows and drives reconnection — but a Wi-Fi switch produced an
+            // error with an empty message and no close at all, and the daemon never re-dialed.
+            // Arm it here too; scheduleReconnect is a no-op when an attempt is already pending,
+            // so the ordinary error-then-close path still dials exactly once.
+            if (socket === ws)
+                socket = null;
+            scheduleReconnect();
+        });
+    }
+    // The sweep that makes "out of the room forever" unreachable, whatever the socket did.
+    const redialWatchdog = setInterval(() => {
+        if (!needsRedial({ stopped, readyState: socket?.readyState, reconnectPending: !!reconnectTimer }))
+            return;
+        log('watchdog: no live socket and nothing pending — re-dialing');
+        scheduleReconnect(); // records its own 'reconnect' telemetry
+    }, REDIAL_WATCHDOG_MS);
+    redialWatchdog.unref?.();
+    function stop() {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(redialWatchdog);
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        socket?.close();
+        socket = null;
+    }
+    if (signal) {
+        if (signal.aborted)
+            stopped = true;
+        else
+            signal.addEventListener('abort', stop, { once: true });
+    }
+    if (!stopped)
+        connect();
+    return { stop, push: sendRaw, pushRepos };
+}