@slack/radar-mcp 1.8.0 → 1.9.1

package/dist/shared/screen.js

@@ -230,6 +230,53 @@ export function stripPngPrefix(raw) {
     const off = raw.indexOf(PNG_MAGIC);
     return off > 0 ? raw.subarray(off) : raw;
 }
+// Bounds for a recording/live-cast frame rate. Client-controlled (?fps=), so clampFps holds
+// the range in one place. MAX 60 = the device panel refresh ceiling (screenrecord cannot feed
+// faster); MIN 1 = a valid non-degenerate rate; DEFAULT 20 = the measured sweet spot the UI
+// uses and the fallback for any out-of-range/non-finite request.
+const MIN_FPS = 1;
+const MAX_FPS = 60;
+const DEFAULT_FPS = 20;
+/**
+ * Clamp a requested frame rate to a safe positive integer for use in an ffmpeg `fps=` filter.
+ * The rate ultimately comes from a client-controlled `?fps=` query param, and a raw number
+ * threaded into `fps=${n}` is a footgun: a negative or Infinity value makes ffmpeg write a
+ * 0-byte file (silent no-recording), a fractional value produces a stuttering near-empty clip,
+ * and a huge value hangs ffmpeg (a leaked, never-exiting encoder). Round to an integer and bound
+ * to [MIN_FPS, MAX_FPS]; anything non-finite or out of range falls back to DEFAULT_FPS.
+ */
+export function clampFps(fps) {
+    const n = Math.round(fps);
+    return Number.isFinite(n) && n >= MIN_FPS && n <= MAX_FPS ? n : DEFAULT_FPS;
+}
+/**
+ * ffmpeg args for the record-to-mp4 pipeline: the live cast's concatenated JPEG stream on
+ * stdin -> a wall-clock-timed, constant-fps H.264 mp4 at `out`. Pure + exported so the arg
+ * SHAPE is unit-testable: the recording is a spawned subprocess with no device-free way to
+ * assert timing, and two arg bugs have hidden here — a fixed input `-r` (stamped every frame
+ * at 1/fps, slow motion) and `-use_wallclock_as_timestamps` paired with `-f image2pipe`
+ * (which ignores the flag and re-stamps a synthetic rate). The invariants the test pins:
+ * no `-r` before `-i`; the wallclock flag paired with the mjpeg demuxer that honors it (NOT
+ * image2pipe); and an output `fps` resample so playback is real-time and CFR. fps is clamped
+ * defensively here too, so the filter string is always a safe integer even if a caller skips
+ * the boundary clamp.
+ */
+export function recordingArgs(fps, out) {
+    return [
+        "-hide_banner", "-loglevel", "error", "-y",
+        // Raw MJPEG demuxer (not image2pipe): only this demuxer honors
+        // -use_wallclock_as_timestamps on a piped JPEG stream, stamping each frame by its true
+        // arrival time regardless of frame size. image2pipe stamps a synthetic fixed rate.
+        "-f", "mjpeg",
+        "-use_wallclock_as_timestamps", "1",
+        "-i", "pipe:0",
+        // Resample the real arrival timeline to a constant fps so the mp4 is CFR (smooth/seekable
+        // everywhere) and its duration matches wall-clock.
+        "-vf", `fps=${clampFps(fps)}`,
+        "-c:v", "libx264", "-pix_fmt", "yuv420p", "-preset", "veryfast",
+        out,
+    ];
+}
 // ---- active-display detection ------------------------------------------------
 let scDisplay = null;
 let scDetected = false;
@@ -275,6 +322,95 @@ export function captureScreenshot() {
     });
 }
 let scLive = null;
+// When the last viewer leaves while a recording is running, wait this long for a clean
+// /screen/record/stop before treating the recording as orphaned (tab closed/crashed
+// before its stop POST landed). The clean stop POST arrives in well under a second; this
+// window comfortably clears it while bounding an orphaned cast to a few seconds instead
+// of looping screenrecord until its next self-exit (or forever, via relaunch).
+const ORPHAN_GRACE_MS = 8000;
+/**
+ * Is this viewer's socket still open and writable? A closed/destroyed response is dead.
+ * Exported for unit testing: this predicate decides whether pushFrame prunes a viewer,
+ * so a regression here would either leak (never prune) or drop live viewers (prune too eagerly).
+ */
+export function viewerAlive(r) {
+    const w = r;
+    return w.writable !== false && w.writableEnded !== true && w.destroyed !== true;
+}
+/**
+ * Arm the orphan-grace timer: if no viewer returns and no clean stop arrives, finalize the
+ * orphaned recording (saved to disk) and reap the cast so screenrecord stops looping. Idempotent
+ * — a second call while armed is a no-op. unref'd so it never keeps the process alive on its own.
+ */
+function armOrphanGrace(L) {
+    if (L.orphanTimer)
+        return;
+    L.orphanTimer = setTimeout(() => {
+        L.orphanTimer = null;
+        if (scLive === L && !L.viewers.size && L.recording) {
+            // .catch is defensive: stopRecording never rejects and reapLiveIfIdle is sync/guarded
+            // today, but this runs in a bare timer callback where an unhandled rejection would be
+            // process-wide, so a future edit that lets either throw must not escape here.
+            void stopRecording(L)
+                .then(() => reapLiveIfIdle())
+                .catch(() => {
+                /* best-effort orphan reap; nothing to recover to */
+            });
+        }
+    }, ORPHAN_GRACE_MS);
+    if (typeof L.orphanTimer.unref === "function")
+        L.orphanTimer.unref();
+}
+function clearOrphanGrace(L) {
+    if (L.orphanTimer) {
+        clearTimeout(L.orphanTimer);
+        L.orphanTimer = null;
+    }
+}
+/**
+ * Pure decision for what to do once a viewer is gone, given how many viewers remain and
+ * whether a recording is running. Extracted from afterViewerRemoved so the loop-closing
+ * logic is unit-testable without spawning: this is the gate that decides between leaking
+ * (keep the cast) and reaping. "watched" = a viewer is still attached, keep the cast as-is;
+ * "arm-grace" = unwatched but recording, hold briefly for a clean stop; "reap" = nothing
+ * left, tear down now.
+ */
+export function nextViewerAction(viewers, recording) {
+    if (viewers > 0)
+        return "watched";
+    return recording ? "arm-grace" : "reap";
+}
+/**
+ * The literal respawn root cause, as a pure predicate: on a screenrecord/ffmpeg exit, relaunch
+ * a fresh cast ONLY while a viewer is still watching. This is the exact gate onExit turns on
+ * ("if (viewers.size || recording) relaunch" was the bug — a recording alone respawned forever
+ * with no viewer). Extracted pure so the root-cause line is unit-testable, not only device-verified.
+ * Note the asymmetry with nextViewerAction: a recording does NOT keep the cast alive here (onExit
+ * lets cleanupLive finalize the clip + reap); it only defers reaping in the viewer-removal path
+ * via the orphan grace. So relaunch depends on viewers ALONE.
+ */
+export function shouldRelaunch(viewers) {
+    return viewers > 0;
+}
+/**
+ * Called after a viewer is removed (leave or dead-viewer prune). If the cast is now
+ * unwatched, either arm the orphan grace (a recording is still running) or reap it outright
+ * (nothing left to keep it alive). This is the single "is anyone still watching?" gate.
+ */
+function afterViewerRemoved() {
+    if (!scLive)
+        return;
+    switch (nextViewerAction(scLive.viewers.size, scLive.recording !== null)) {
+        case "watched":
+            return;
+        case "arm-grace":
+            armOrphanGrace(scLive);
+            return;
+        case "reap":
+            reapLiveIfIdle();
+            return;
+    }
+}
 function screenrecordArgs() {
     const a = ["exec-out", "screenrecord", "--output-format=h264", "--size", SC_SIZE, "--bit-rate", SC_BITRATE];
     if (scDisplay)
@@ -300,16 +436,32 @@ async function primeFrame(ffmpeg) {
 function pushFrame(L, frame) {
     const head = Buffer.from(`--${SC_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${frame.length}\r\n\r\n`);
     const tail = Buffer.from("\r\n");
+    // Prune viewers whose socket died without firing req.on("close") — a half-open TCP
+    // connection (host sleep, network drop, killed browser) leaves the response object in
+    // the set but not writable. Without pruning, a dead viewer keeps the cast "watched"
+    // forever and relaunch respawns screenrecord on every self-exit. This frame loop is the
+    // heartbeat that detects the dead socket. Collect first, mutate the set after iterating.
+    let dead = null;
     for (const r of L.viewers) {
+        if (!viewerAlive(r)) {
+            (dead ??= []).push(r);
+            continue;
+        }
         try {
             r.write(head);
             r.write(frame);
             r.write(tail);
         }
         catch {
-            // viewer disconnected; harmless
+            // write threw on a socket that looked alive; treat it as dead too
+            (dead ??= []).push(r);
         }
     }
+    if (dead) {
+        for (const r of dead)
+            L.viewers.delete(r);
+        afterViewerRemoved();
+    }
     if (L.recording) {
         try {
             L.recording.proc.stdin?.write(frame);
@@ -358,6 +510,7 @@ function reapCastProcesses(L) {
         clearInterval(L.keepalive);
         L.keepalive = null;
     }
+    clearOrphanGrace(L);
     L.lastFrame = null;
     try {
         L.sr.kill("SIGKILL");
@@ -383,10 +536,14 @@ export function startLive(fps) {
     const ffmpeg = resolveFfmpeg();
     if (!ffmpeg)
         return null;
+    // Clamp once at the boundary: fps comes from a client-controlled ?fps= param, and it is used
+    // both in the live filter below and (via scLive.fps) by the recording. A negative/fractional/
+    // huge value would break either pipeline. Store and use only the clamped value.
+    const safeFps = clampFps(fps);
     const sr = spawn(adb(), screenrecordArgs(), { stdio: ["ignore", "pipe", "ignore"] });
     const ff = spawn(ffmpeg, [
         "-hide_banner", "-loglevel", "error", "-f", "h264", "-probesize", "64k", "-i", "pipe:0",
-        "-vf", `format=yuvj420p,fps=${fps || 20}`, "-q:v", "6", "-flush_packets", "1",
+        "-vf", `format=yuvj420p,fps=${safeFps}`, "-q:v", "6", "-flush_packets", "1",
         "-f", "image2pipe", "-c:v", "mjpeg", "pipe:1",
     ], { stdio: ["pipe", "pipe", "ignore"] });
     sr.stdout?.pipe(ff.stdin);
@@ -397,8 +554,9 @@ export function startLive(fps) {
         lastFrame: null,
         lastFrameTs: 0,
         recording: null,
-        fps: fps || 20,
+        fps: safeFps,
         keepalive: null,
+        orphanTimer: null,
     };
     let acc = Buffer.alloc(0);
     ff.stdout?.on("data", (chunk) => {
@@ -426,7 +584,21 @@ export function startLive(fps) {
     const onExit = () => {
         if (scLive === L) {
             scLive = null;
-            if (L.viewers.size || L.recording)
+            // Relaunch ONLY while a viewer is actually watching (shouldRelaunch). A recording with
+            // no viewers must NOT relaunch: that is the orphaned-recording respawn loop (a tab closed
+            // mid-record before its stop POST landed kept screenrecord self-exiting and relaunching
+            // forever). With no viewers, cleanupLive finalizes the in-progress recording (the clip is
+            // saved, not lost) and reaps the pipeline. The orphan-grace timer normally reaps this
+            // within a few seconds, before screenrecord even self-exits.
+            //
+            // Edge (dead-viewer + fully static screen): if the only remaining viewer is a half-open
+            // dead socket, viewers.size is still 1 here, so we relaunch. The dead-viewer prune runs
+            // inside pushFrame, so it needs at least one frame from the fresh cast to fire. A newly
+            // spawned screenrecord emits a startup keyframe even on a static screen (see the module
+            // header's DOZE-panel note), so the fresh cast produces a frame, pushFrame prunes the dead
+            // viewer, and afterViewerRemoved reaps. Worst case is a single bounded relaunch cycle, not
+            // an unbounded loop.
+            if (shouldRelaunch(L.viewers.size))
                 relaunch(L);
             else
                 cleanupLive(L);
@@ -455,13 +627,16 @@ export function startLive(fps) {
 }
 /** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
 export function addViewer(L, res) {
+    // A viewer returned; if the orphan-grace timer was counting down (last viewer had left
+    // while a recording ran), cancel it — the cast is watched again.
+    clearOrphanGrace(L);
     L.viewers.add(res);
 }
 export function removeViewer(res) {
     if (!scLive)
         return;
     scLive.viewers.delete(res);
-    reapLiveIfIdle();
+    afterViewerRemoved();
 }
 /**
  * Tear down the live cast when nothing is keeping it alive: no viewers AND no active
@@ -521,7 +696,20 @@ export function startRecording() {
     }
     const safe = new Date().toISOString().replace(/[:.]/g, "-");
     const out = path.join(SC_TMP, `radar_screen_${safe}.mp4`);
-    const rec = spawn(ffmpeg, ["-hide_banner", "-loglevel", "error", "-y", "-f", "image2pipe", "-r", String(scLive.fps), "-c:v", "mjpeg", "-i", "pipe:0", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-preset", "veryfast", out], { stdio: ["pipe", "ignore", "ignore"] });
+    // Time the recording by real frame arrival, not a fixed input rate (the arg shape + the
+    // reasons it must be exactly this are in recordingArgs). The old args stamped every frame
+    // at a fixed 1/fps, so a clip recorded over N real seconds played back as frames/fps
+    // seconds — slow motion by the real-fps/target ratio.
+    const rec = spawn(ffmpeg, recordingArgs(scLive.fps, out), { stdio: ["pipe", "ignore", "ignore"] });
+    // A ChildProcess with no 'error' listener throws an unhandled 'error' (crashing the process)
+    // if the spawn itself fails — e.g. ffmpeg was removed between resolveFfmpeg() and here, or an
+    // EAGAIN under load. resolveFfmpeg() just succeeded so this is unlikely, but a recording is a
+    // best-effort debug convenience and must never take the server down. Swallow it; the frame
+    // tee in pushFrame already tolerates a dead stdin, and the user simply gets no clip.
+    rec.on("error", () => {
+        if (scLive?.recording?.proc === rec)
+            scLive.recording = null;
+    });
     scLive.recording = { proc: rec, path: out };
     return out;
 }
@@ -530,6 +718,7 @@ export function stopRecording(L = scLive) {
         return Promise.resolve(null);
     const r = L.recording;
     L.recording = null;
+    clearOrphanGrace(L);
     return new Promise((resolve) => {
         let done = false;
         const fin = () => {

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

package/dist/web/server.js

@@ -762,6 +762,13 @@ function handleScreen(req, res) {
             return;
         }
         const fps = Number(new URL(url, `http://localhost:${WEB_PORT}`).searchParams.get("fps")) || 20;
+        // Register the disconnect handler BEFORE the await. A client that aborts during
+        // detectDisplay() would otherwise become a phantom viewer whose close never fires, and
+        // on a static screen (no frames flowing) the frame-loop dead-viewer prune cannot catch
+        // it either — so it would hold the cast and respawn screenrecord. removeViewer is safe
+        // to call whether or not the response ever became a viewer (delete on an absent member
+        // is a no-op), so wiring it early costs nothing when the stream fails to start.
+        req.on("close", () => removeViewer(res));
         void (async () => {
             await detectDisplay();
             const L = startLive(fps);
@@ -769,13 +776,20 @@ function handleScreen(req, res) {
                 sendJson(res, 501, { error: "ffmpeg not installed", installHint: ffmpegInstallHint() });
                 return;
             }
+            // The client may have aborted during the await above (its close handler, wired before
+            // the await, already ran). Do not resurrect a dead socket as a viewer — that would be
+            // the very phantom viewer this reordering prevents. Reap in case startLive spun a cast
+            // up for a viewer that is already gone.
+            if (res.writableEnded || res.destroyed) {
+                reapLiveIfIdle();
+                return;
+            }
             res.writeHead(200, {
                 "Content-Type": `multipart/x-mixed-replace; boundary=${SCREEN_BOUNDARY}`,
                 "Cache-Control": "no-cache",
                 Connection: "keep-alive",
             });
             addViewer(L, res);
-            req.on("close", () => removeViewer(res));
             void primeIfNeeded();
         })();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/radar-mcp",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
   "type": "module",
   "main": "dist/mcp/index.js",
@@ -22,7 +22,8 @@
     "start": "node dist/mcp/index.js",
     "start:web": "node dist/web/bin.js",
     "watch": "tsc --watch",
-    "test": "npm run build && node --test tests/*.test.mjs",
+    "test": "npm run build && node tests/run.mjs",
+    "test:tap": "npm run build && node --test --test-force-exit tests/*.test.mjs",
     "test:smoke": "npm run build && bash tests/smoke.sh",
     "test:all": "npm run test && npm run test:smoke",
     "prepare": "npm run build"