@slack/radar-mcp 1.7.0 → 1.9.0

package/dist/shared/db.js

@@ -353,6 +353,24 @@ export function assertReadOnlyQuery(sql) {
         throw new Error("that function/statement is not allowed (read-only, no file access)");
     }
 }
+/**
+ * True for EXPLAIN / EXPLAIN QUERY PLAN, which sqlite3 prints as a text table (ignoring -json).
+ * Leading-token match; assertReadOnlyQuery gates the same leading keyword, so both reject on
+ * comment-prefixed queries before this routing matters.
+ */
+export function isExplainQuery(sql) {
+    return /^\s*explain\b/i.test(sql);
+}
+/**
+ * sqlite3 ignores -json for EXPLAIN (prints text table instead of JSON).
+ * Shape it into row objects so the web grid renders the plan readably.
+ */
+export function parseExplainOutput(out) {
+    return out
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => ({ plan: line }));
+}
 /**
  * Run a read-only query against a (lazily pulled) local copy. The query is gated by
  * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's
@@ -365,6 +383,12 @@ export async function queryDatabase(name, sql, user) {
     const local = localPath(name, u);
     if (!fs.existsSync(local))
         await pullDatabase(name, u);
+    // EXPLAIN / EXPLAIN QUERY PLAN are read-query-shaped (they pass the gate) but sqlite3 IGNORES
+    // -json for them: it prints a fixed-width opcode/plan TEXT table, not JSON, so JSON.parse below
+    // would throw "Unexpected token" and the user sees a confusing parse error for a query that
+    // actually ran. Handle them as text: one result row per output line under a single column, so
+    // the existing grid renders the plan readably instead of choking.
+    const explain = isExplainQuery(sql);
     let out;
     try {
         // Open the pulled copy NORMALLY (not `immutable`, not `-readonly`): pullDatabase brought
@@ -375,14 +399,15 @@ export async function queryDatabase(name, sql, user) {
         // is touched. `-safe` is the load-bearing read-only/exfil control (blocks ATTACH/readfile/
         // writefile/load_extension at the engine level) and holds in normal mode too. The path is
         // URI-encoded so spaces/specials are safe. Async exec so a large query does not block the
-        // event loop.
+        // event loop. -json for normal queries; plain text for EXPLAIN (sqlite ignores -json there).
         const uri = `file:${encodeURI(local)}`;
-        const r = await execFileP(sqliteBin(), ["-safe", "-json", uri, sql], {
+        const args = explain ? ["-safe", uri, sql] : ["-safe", "-json", uri, sql];
+        const r = await execFileP(sqliteBin(), args, {
             timeout: 15000,
             maxBuffer: SQLITE_MAX_BUFFER,
             encoding: "utf8",
         });
-        out = String(r.stdout) || "[]";
+        out = String(r.stdout) || (explain ? "" : "[]");
     }
     catch (e) {
         const err = e;
@@ -390,6 +415,8 @@ export async function queryDatabase(name, sql, user) {
         const m = stderr.match(/(no such table:.*|no such column:.*|near ".*|syntax error.*|.*error.*)/i);
         throw new Error(m ? m[0].trim() : stderr.split("\n")[0] || "query failed");
     }
+    if (explain)
+        return parseExplainOutput(out);
     return JSON.parse(out);
 }
 /** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */

package/dist/shared/event-spool.d.ts

@@ -0,0 +1,75 @@
+import type { ParsedSSE } from "./stream.js";
+/**
+ * Point the spool dir at a per-process-unique path. Call once at startup with
+ * process.pid. Mirrors db.ts initializeDatabasePath: every MCP shares one port,
+ * so a pid key is the collision-free scope.
+ */
+export declare function initializeSpoolDir(scopeKey: number): void;
+/**
+ * Delete spool files older than GC_TTL_MS. Runs at session enable. Bounds disk
+ * usage without losing recent session records. dir + now injectable for tests.
+ * Mirrors gcOldCaptures (logcat-capture.ts). Returns the count removed.
+ */
+export declare function gcOldSpools(dir?: string, now?: number): number;
+export declare function buildSpoolFilePath(now?: number): string;
+export declare function epochFromSpoolPath(filePath: string | null): string;
+export declare function isSpooling(): boolean;
+export declare function getSpoolFilePath(): string | null;
+/**
+ * Read the current session spool back into parsed frames, oldest first (append
+ * order). Separate from the write path; reads the live file by its own handle,
+ * never touching the writer's fd or state. Returns [] when no spool is open, the
+ * file is gone, or it cannot be read. Never throws into the caller: a query over
+ * a missing or damaged spool must degrade to empty, not fail the tool.
+ *
+ * Reads the whole file and lets the query shaper's byte cap bound the OUTPUT,
+ * rather than tailing here: a filter can match an old frame near the top, so a
+ * byte-tail read could drop a frame the caller asked for. Rotation already caps
+ * the live file at a normal-session size, so a whole read is safe.
+ *
+ * A torn final line (the process died mid-append, before the newline) is skipped
+ * so one bad tail line never sinks the whole read. Any line that will not parse
+ * is dropped the same way.
+ */
+export declare function readSpool(): ParsedSSE[];
+/**
+ * Open a fresh spool file for append and set module state. Ensures the dir,
+ * runs gcOldSpools first, returns the path (or null on failure). Idempotent: a
+ * second call while a spool is open returns the current path without reopening.
+ */
+export declare function startSpool(now?: number): string | null;
+/**
+ * Append one frame as a single JSONL line. On the hot path (every streamed
+ * event) and inside the wait_for_events notify path. Synchronous on purpose:
+ * a sync append keeps frames in arrival order with no interleave, which an async
+ * write queue would not guarantee. It is also cheap and never lets an error
+ * reach the caller, so a spool write failure can never break bufferEvent or
+ * waiter delivery. No-op if no spool is open. Errors are swallowed after one
+ * breadcrumb.
+ */
+export declare function writeFrame(frame: ParsedSSE): void;
+/**
+ * Close the fd and clear state, but KEEP the file on disk. Called on explicit
+ * disable and on process exit. The file survives so a just-ended session is
+ * still readable; the GC reclaims it after the TTL. This matches logcat, which
+ * also keeps its capture file on disable and lets the GC reclaim it. Never
+ * called on the transient device-error path.
+ */
+export declare function stopSpool(): void;
+/**
+ * If the open file exceeds ROTATION_BYTES, rename it `.rotated-<ts>` (readable
+ * until the GC reclaims it) and open a fresh file. Rotation is the one place
+ * capture-everything yields to bounded disk: a normal session never rotates,
+ * this is only the disk-safety backstop.
+ *
+ * Safe rename-not-truncate, mirroring rotateCaptureIfNeeded: truncating in
+ * place would leave the next append past EOF. No-op if no spool is open or the
+ * file is under cap. Returns the new path, or null when nothing rotated.
+ */
+export declare function rotateSpoolIfNeeded(now?: number, capBytes?: number): string | null;
+export declare function registerCleanup(): void;
+export declare function _setSpoolDirForTest(dir: string): void;
+export declare function _setRotationBytesForTest(n: number): void;
+export declare function _setWriteCountForTest(n: number): void;
+export declare function _getRotationCheckEveryForTest(): number;
+export declare function _closeFdLeavingStateForTest(): void;

package/dist/shared/event-spool.js

@@ -0,0 +1,366 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+/**
+ * Appends every streamed SSE frame (network, rtm, clog, log, trace) to a
+ * per-session file so the full session record survives buffer eviction. The
+ * device rings and the host push ring both drop the oldest entry once full, so
+ * a long session loses its early events; the spool keeps the whole session. It
+ * does not replace the rings. The device ring stays the source of truth: it
+ * holds full payloads for detail and search, carries history from before the
+ * host connected, and serves the dashboard and every /api endpoint. This spool
+ * is a downstream summary log.
+ *
+ * It captures every frame delivered to the host, not every frame the device
+ * produced. Frames dropped during a transient device reconnect (callRadar tears
+ * the stream down and reconnects) never reach bufferEvent, so they are not
+ * spooled. Capture starts when the stream connects; there is no device backfill.
+ *
+ * A profile switch mid-session (activate_for_user) keeps appending to the same
+ * file, so two profiles' frames merge with no per-frame profile tag. Fine while
+ * nothing reads the spool; splitting by profile is for whoever adds the reader.
+ *
+ * Modeled on logcat-capture.ts: a session-scoped host file with a time-based GC,
+ * exit-handler cleanup, and safe rename-not-truncate rotation. One deliberate
+ * difference: no idle timeout. logcat idles out because a read can come long
+ * after the last write; this spool must hold the entire session, so it stops
+ * only on explicit disable or process exit.
+ *
+ * Lifecycle: startSpool when the session is enabled; stopSpool (which closes the
+ * fd but keeps the file) on explicit disable and on process exit, so a just-ended
+ * session stays readable until the GC reclaims it. Never on a transient device
+ * error. callRadar clears the enabled flag on a device blip; closing the spool
+ * there would cut the record short on a momentary drop.
+ */
+// Under os.tmpdir() (not ~/.slack-radar) so the OS reclaims it if the process
+// dies unclean (crash, kill -9, no disable). Our own stopSpool + exit handlers +
+// the GC still run first; the temp dir is the backstop for the unclean case.
+// Same choice db.ts makes for its pulled-DB scratch, and same reason.
+//
+// Pid-scoped like db.ts's DB_TMP: every MCP shares one RADAR_PORT, so a fixed
+// dir lets two concurrent MCP processes build the same events-<now>.jsonl path
+// and interleave sessions, and one process's gcOldSpools would walk the other's
+// live files. Scoping by pid gives each process its own dir. initializeSpoolDir
+// runs at startup; the default is the unscoped path so unit tests that never
+// call it still get a usable location.
+let SPOOL_DIR = path.join(os.tmpdir(), "slack-radar-events");
+let ROTATION_BYTES = 100 * 1024 * 1024;
+const GC_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// Cheap-cadence rotation check: run needsRotation only every Nth write so the
+// hot path is a plain fd append almost always.
+const ROTATION_CHECK_EVERY = 1000;
+const state = {
+    fd: null,
+    filePath: null,
+    startedAt: null,
+    writeCount: 0,
+};
+// One-time breadcrumb latch: if writeFrame ever fails, log once so a spool that
+// dies mid-session (ENOSPC/EACCES/EBADF) is diagnosable, without spamming a line
+// per frame for the rest of the session. Reset on each startSpool.
+let writeErrorLogged = false;
+/**
+ * Point the spool dir at a per-process-unique path. Call once at startup with
+ * process.pid. Mirrors db.ts initializeDatabasePath: every MCP shares one port,
+ * so a pid key is the collision-free scope.
+ */
+export function initializeSpoolDir(scopeKey) {
+    SPOOL_DIR = path.join(os.tmpdir(), `slack-radar-events-${scopeKey}`);
+}
+function ensureSpoolDir() {
+    if (!fs.existsSync(SPOOL_DIR)) {
+        // 0700: the spool holds raw bodies, auth headers, and message content under
+        // a world-traversable tmpdir, so scope it to the owner. Same choice db.ts
+        // makes for its pulled-DB scratch in the same location.
+        fs.mkdirSync(SPOOL_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Delete spool files older than GC_TTL_MS. Runs at session enable. Bounds disk
+ * usage without losing recent session records. dir + now injectable for tests.
+ * Mirrors gcOldCaptures (logcat-capture.ts). Returns the count removed.
+ */
+export function gcOldSpools(dir = SPOOL_DIR, now = Date.now()) {
+    if (!fs.existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const name of fs.readdirSync(dir)) {
+        // Match the live files and their rotated archives.
+        if (!name.startsWith("events-") || !name.includes(".jsonl"))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const stat = fs.statSync(full);
+            if (now - stat.mtimeMs > GC_TTL_MS) {
+                fs.unlinkSync(full);
+                removed += 1;
+            }
+        }
+        catch {
+            // ignore; file may have vanished between readdir and stat
+        }
+    }
+    return removed;
+}
+export function buildSpoolFilePath(now = Date.now()) {
+    return path.join(SPOOL_DIR, `events-${now}.jsonl`);
+}
+// The epoch that pins a query_session cursor to one spool file: the <ts> in events-<ts>.jsonl. It
+// changes on every rotation and re-enable, so a cursor minted against one file is detectably stale
+// against another. Pure inverse of buildSpoolFilePath's naming; a null path (no spool) yields "".
+// Owned here next to the name it strips so the mint and the check can never drift on the affixes.
+export function epochFromSpoolPath(filePath) {
+    if (filePath === null)
+        return "";
+    return path.basename(filePath).replace(/^events-/, "").replace(/\.jsonl$/, "");
+}
+export function isSpooling() {
+    return state.fd !== null;
+}
+export function getSpoolFilePath() {
+    return state.filePath;
+}
+/**
+ * Read the current session spool back into parsed frames, oldest first (append
+ * order). Separate from the write path; reads the live file by its own handle,
+ * never touching the writer's fd or state. Returns [] when no spool is open, the
+ * file is gone, or it cannot be read. Never throws into the caller: a query over
+ * a missing or damaged spool must degrade to empty, not fail the tool.
+ *
+ * Reads the whole file and lets the query shaper's byte cap bound the OUTPUT,
+ * rather than tailing here: a filter can match an old frame near the top, so a
+ * byte-tail read could drop a frame the caller asked for. Rotation already caps
+ * the live file at a normal-session size, so a whole read is safe.
+ *
+ * A torn final line (the process died mid-append, before the newline) is skipped
+ * so one bad tail line never sinks the whole read. Any line that will not parse
+ * is dropped the same way.
+ */
+export function readSpool() {
+    const filePath = state.filePath;
+    if (filePath === null)
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const frames = [];
+    for (const line of raw.split("\n")) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            // Only a well-formed frame: an object with a string `type` and an `event` object. A bare
+            // null/number/string (valid JSON, wrong shape) is dropped so a reader can dereference
+            // frame.event and frame.type without a guard on every field.
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                typeof parsed.type === "string" &&
+                typeof parsed.event === "object" &&
+                parsed.event !== null) {
+                frames.push(parsed);
+            }
+        }
+        catch {
+            // Torn or malformed line: skip it, keep the rest.
+        }
+    }
+    return frames;
+}
+/**
+ * Open a fresh spool file for append and set module state. Ensures the dir,
+ * runs gcOldSpools first, returns the path (or null on failure). Idempotent: a
+ * second call while a spool is open returns the current path without reopening.
+ */
+export function startSpool(now = Date.now()) {
+    if (isSpooling())
+        return state.filePath;
+    try {
+        ensureSpoolDir();
+        gcOldSpools();
+        const filePath = buildSpoolFilePath(now);
+        // 0600 for the same reason as the 0700 dir: the file is raw captured
+        // traffic, readable only by the owner. Matches db.ts's pulled-DB scratch.
+        const fd = fs.openSync(filePath, "a", 0o600);
+        state.fd = fd;
+        state.filePath = filePath;
+        state.startedAt = now;
+        state.writeCount = 0;
+        writeErrorLogged = false;
+        return filePath;
+    }
+    catch {
+        // Failed to open the spool. Leave state clean so writeFrame no-ops.
+        state.fd = null;
+        state.filePath = null;
+        state.startedAt = null;
+        state.writeCount = 0;
+        return null;
+    }
+}
+/**
+ * Append one frame as a single JSONL line. On the hot path (every streamed
+ * event) and inside the wait_for_events notify path. Synchronous on purpose:
+ * a sync append keeps frames in arrival order with no interleave, which an async
+ * write queue would not guarantee. It is also cheap and never lets an error
+ * reach the caller, so a spool write failure can never break bufferEvent or
+ * waiter delivery. No-op if no spool is open. Errors are swallowed after one
+ * breadcrumb.
+ */
+export function writeFrame(frame) {
+    if (state.fd === null)
+        return;
+    try {
+        // Loop until the whole buffer is written. fs.writeSync can short-write on a
+        // signal or a near-full disk; a partial line with no newline would fuse
+        // onto the next frame and break the JSONL boundary a reader would need.
+        const buf = Buffer.from(JSON.stringify(frame) + "\n");
+        let offset = 0;
+        while (offset < buf.length) {
+            offset += fs.writeSync(state.fd, buf, offset, buf.length - offset);
+        }
+        state.writeCount += 1;
+        if (state.writeCount % ROTATION_CHECK_EVERY === 0) {
+            rotateSpoolIfNeeded();
+        }
+    }
+    catch (err) {
+        // Disk full, EACCES, closed fd: swallow so the caller's waiter delivery is
+        // never affected. Log once so a spool that quietly died mid-session is
+        // diagnosable instead of silent.
+        if (!writeErrorLogged) {
+            writeErrorLogged = true;
+            console.error(`[radar] event spool write failed, spool may be truncated: ${err}`);
+        }
+    }
+}
+/**
+ * Close the fd and clear state, but KEEP the file on disk. Called on explicit
+ * disable and on process exit. The file survives so a just-ended session is
+ * still readable; the GC reclaims it after the TTL. This matches logcat, which
+ * also keeps its capture file on disable and lets the GC reclaim it. Never
+ * called on the transient device-error path.
+ */
+export function stopSpool() {
+    const fd = state.fd;
+    state.fd = null;
+    state.filePath = null;
+    state.startedAt = null;
+    state.writeCount = 0;
+    if (fd !== null) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+}
+/**
+ * If the open file exceeds ROTATION_BYTES, rename it `.rotated-<ts>` (readable
+ * until the GC reclaims it) and open a fresh file. Rotation is the one place
+ * capture-everything yields to bounded disk: a normal session never rotates,
+ * this is only the disk-safety backstop.
+ *
+ * Safe rename-not-truncate, mirroring rotateCaptureIfNeeded: truncating in
+ * place would leave the next append past EOF. No-op if no spool is open or the
+ * file is under cap. Returns the new path, or null when nothing rotated.
+ */
+export function rotateSpoolIfNeeded(now = Date.now(), capBytes = ROTATION_BYTES) {
+    const fd = state.fd;
+    const current = state.filePath;
+    if (fd === null || !current)
+        return null;
+    let size;
+    try {
+        size = fs.fstatSync(fd).size;
+    }
+    catch {
+        return null;
+    }
+    if (size <= capBytes)
+        return null;
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // already closed
+    }
+    state.fd = null;
+    try {
+        fs.renameSync(current, `${current}.rotated-${now}`);
+    }
+    catch {
+        // Rename failure is non-fatal: the file may have vanished. Fall through
+        // and open a fresh spool.
+    }
+    // Reopen a fresh file. startSpool is a no-op while a spool is open, so we
+    // cleared state.fd above first.
+    const reopened = startSpool(now);
+    if (reopened === null) {
+        // Reopen failed (disk full is exactly when rotation fires). state.fd stays
+        // null, so writeFrame no-ops for the rest of the session. Leave one
+        // breadcrumb so a dead-mid-session spool is diagnosable. A reopen-retry is
+        // out of scope here.
+        console.error("[radar] event spool rotation reopen failed; spool stopped");
+    }
+    return reopened;
+}
+/**
+ * Install once at process start so the spool file is deleted when the MCP
+ * server exits. Copies logcat-capture.ts registerCleanup, including the
+ * SIGINT/SIGTERM exit codes 130/143.
+ */
+let cleanupRegistered = false;
+export function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    const cleanup = () => stopSpool();
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+        cleanup();
+        process.exit(143);
+    });
+}
+// Test-only: point the spool at an isolated dir so a test never writes to the
+// real one. Production uses initializeSpoolDir(pid) at startup instead.
+export function _setSpoolDirForTest(dir) {
+    SPOOL_DIR = dir;
+}
+// Test-only: lower the rotation cap so the periodic writeFrame check can drive a
+// real rename without writing 100MB. The internal rotate call reads this default.
+export function _setRotationBytesForTest(n) {
+    ROTATION_BYTES = n;
+}
+// Test-only: lower the write count so a test can trigger the periodic rotation
+// check without writing ROTATION_CHECK_EVERY frames. Not for production use.
+export function _setWriteCountForTest(n) {
+    state.writeCount = n;
+}
+// Test-only: the periodic rotation cadence, so a test can drive writeFrame to
+// the rotation branch without hard-coding the constant.
+export function _getRotationCheckEveryForTest() {
+    return ROTATION_CHECK_EVERY;
+}
+// Test-only: close the underlying fd WITHOUT clearing state, so a test can
+// prove writeFrame swallows a write-to-closed-fd error. Production code must
+// never leave a closed fd in state; only stopSpool/rotate close it, and both
+// null the fd.
+export function _closeFdLeavingStateForTest() {
+    if (state.fd !== null) {
+        try {
+            fs.closeSync(state.fd);
+        }
+        catch {
+            // already closed
+        }
+    }
+}

package/dist/shared/stream.d.ts

@@ -6,11 +6,15 @@ export interface RadarEvent {
     [key: string]: unknown;
 }
 export interface ParsedSSE {
-    type: "network" | "rtm" | "clog" | "log" | "trace";
+    type: "network" | "rtm" | "clog" | "log" | "trace" | `${string}_detail`;
     event: RadarEvent;
 }
 export declare const localNetworkBuffer: RadarEvent[];
 export declare const localRtmBuffer: RadarEvent[];
+/** Set the reconnect hook. Called once after each successful reconnect. Pass null to clear it. */
+export declare function setOnReconnect(fn: (() => void) | null): void;
+export declare function noteStreamConnected(): void;
+export declare function _resetReconnectStateForTest(): void;
 export declare function isStreamConnected(): boolean;
 export declare function clearLocalBuffers(): void;
 export declare function getStreamConnection(): http.ClientRequest | null;

package/dist/shared/stream.js

@@ -1,5 +1,6 @@
 import http from "http";
 import { RADAR_HOST, RADAR_PORT, MAX_LOCAL_BUFFER } from "./constants.js";
+import { writeFrame } from "./event-spool.js";
 let transport = null;
 /** Set the transport used to check forwarding state. Call once at startup. */
 export function setTransport(t) {
@@ -10,6 +11,37 @@ export const localRtmBuffer = [];
 let streamConnection = null;
 let streamConnected = false;
 const eventWaiters = [];
+// Fires once after a RECONNECT (not the first connect), so the owner can backfill the device ring
+// rows the ~2s gap dropped. index.ts sets it to the backfill; unset it is a no-op, so the web
+// server (which shares this module) and tests are unaffected. hasConnectedOnce gates it to a true
+// reconnect: the enable path already backfills the first connect, so firing here too would double
+// the work (dedup would drop it, but the extra device pulls are wasted).
+let onReconnect = null;
+let hasConnectedOnce = false;
+/** Set the reconnect hook. Called once after each successful reconnect. Pass null to clear it. */
+export function setOnReconnect(fn) {
+    onReconnect = fn;
+}
+// Run on every successful stream connect. Fires the reconnect hook only on a true reconnect (a
+// prior connect happened), never on the first connect (the enable path backfills that one). The
+// hook is guarded so it can never throw into the stream. Exported for tests so the fires-on-
+// reconnect / no-op-when-unset logic is checkable without a live socket.
+export function noteStreamConnected() {
+    if (hasConnectedOnce && onReconnect) {
+        try {
+            onReconnect();
+        }
+        catch {
+            // A hook failure must not break the stream read loop.
+        }
+    }
+    hasConnectedOnce = true;
+}
+// Test-only: clear the connect/hook state so a test starts from a known first-connect baseline.
+export function _resetReconnectStateForTest() {
+    onReconnect = null;
+    hasConnectedOnce = false;
+}
 export function isStreamConnected() {
     return streamConnected;
 }
@@ -42,6 +74,10 @@ export function bufferEvent(parsed) {
         if (localRtmBuffer.length > MAX_LOCAL_BUFFER)
             localRtmBuffer.shift();
     }
+    // Spool every frame to the session file. writeFrame swallows its own errors
+    // and no-ops when no spool is open, so this cannot break the buffer or the
+    // waiter-notify path below.
+    writeFrame(parsed);
     notifyWaiters(parsed);
 }
 function notifyWaiters(parsed) {
@@ -100,6 +136,9 @@ export function connectStream() {
         return;
     const req = http.get({ host: RADAR_HOST, port: RADAR_PORT, path: "/api/stream", timeout: 0 }, (res) => {
         streamConnected = true;
+        // Fire the reconnect hook on a true reconnect (not the first connect). Kept in its own fn so
+        // the logic is unit-testable without a live socket.
+        noteStreamConnected();
         let partial = "";
         res.on("data", (chunk) => {
             partial += chunk.toString();

package/dist/web/log-session.js

@@ -47,6 +47,12 @@ export class LogSession {
         }
         this.child = child;
         this.lineBuf = "";
+        // A background diagnostic child must not keep the host process alive on its
+        // own. The listening dashboard socket is what holds the event loop open in
+        // production; when that closes (a test, or a clean shutdown) node should be
+        // free to exit even if a logcat capture is still running. registerCleanup
+        // still kills the child on exit, so unref only removes the loop-blocking ref.
+        child.unref?.();
         child.stdout?.on("data", (c) => this.onData(c));
         // A crashed/killed logcat (device unplugged, adb server restart) clears the
         // child so the next connect() can restart it. The retained ring survives so