@slack/radar-mcp 1.4.0 → 1.6.0

package/dist/shared/screen.js

@@ -0,0 +1,633 @@
+/**
+ * Live device-screen mirror + record, for the dashboard's Screen overlay.
+ *
+ * Pipeline (scrcpy-lite, no custom decoder): `adb exec-out screenrecord
+ * --output-format=h264` on the active display -> `ffmpeg` transcodes h264 to
+ * MJPEG -> the server pushes JPEG frames to a browser <img> over
+ * multipart/x-mixed-replace. Record tees the same JPEG frames to a second
+ * ffmpeg (mjpeg in -> libx264 mp4), so the live view and the recording share one
+ * screenrecord (the way scrcpy shares one capture).
+ *
+ * SENSITIVE: this mirrors the real device screen, which shows live DMs, message
+ * content, and anything else on screen. It is OFF by default and gated behind an
+ * explicit per-process consent (see consent state below); the server refuses the
+ * stream and record routes until consent is granted.
+ *
+ * DEPENDENCY POLICY: ffmpeg is NOT bundled and NOT a hard dependency (it is large
+ * and license-encumbered; the published package keeps a single runtime dep). The
+ * stream/record paths detect-and-degrade: present -> embedded MJPEG; absent ->
+ * a clear message plus the platform install command, and a scrcpy fallback hint.
+ * The screenshot path uses pure `screencap` (PNG, no transcode) so it MUST keep
+ * working with no ffmpeg.
+ *
+ * Hard-won device facts baked in (Pixel 10 Pro Fold and similar):
+ *  - Active-display detect must be deterministic: pick the powered-ON physical
+ *    panel from `cmd display get-displays`. Byte-probing cannot tell a dozing
+ *    black panel from a live one (a DOZE panel still emits ~1 keyframe).
+ *  - `screencap -p` prepends a "[Warning] Multiple displays were found" text line
+ *    on multi-display devices, corrupting the PNG. Strip everything before the
+ *    PNG magic bytes.
+ *  - screenrecord emits full-range YUV that the mjpeg encoder rejects; `-vf
+ *    format=yuvj420p` fixes it.
+ *  - H.264 emits nothing on a static screen (correct, not a hang). A
+ *    multipart/x-mixed-replace viewer only paints part N when part N+1 arrives,
+ *    so a keepalive re-pushes the last frame while idle to flush it.
+ *  - adb does not reliably SIGKILL the device-side screenrecord on host pipe
+ *    close; orphaned screenrecord procs congest the single adb transport. Kill
+ *    explicitly on cleanup.
+ */
+import { spawn, execFile, execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { promisify } from "util";
+import { resolveAdbPath } from "./android.js";
+const SC_TMP = path.join(os.homedir(), ".slack-radar", "screen");
+/**
+ * Remove all recorded mp4s from the screen tmp dir. Recordings capture sensitive
+ * live screen content and must not linger across sessions on disk. Called on
+ * resetScreenState() (device re-enable) and on process exit — the same posture the
+ * DB-browser uses for its pulled copies. Scoped to the radar_screen_*.mp4 names this
+ * module writes so it never deletes an unrelated file that landed in the dir.
+ */
+export function cleanupRecordings() {
+    try {
+        for (const f of fs.readdirSync(SC_TMP)) {
+            if (/^radar_screen_[\w-]+\.mp4$/.test(f)) {
+                try {
+                    fs.unlinkSync(path.join(SC_TMP, f));
+                }
+                catch {
+                    // best-effort per file
+                }
+            }
+        }
+    }
+    catch {
+        // dir may not exist yet; nothing to clean
+    }
+}
+const SC_SIZE = "720x1612";
+const SC_BITRATE = "8000000";
+const SC_BOUNDARY = "radarframe";
+// PNG magic header: screencap output begins here; anything before it is a prefix
+// warning line that must be stripped.
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function adb() {
+    return resolveAdbPath() ?? "adb";
+}
+// ---- host-binary detection (for the degrade tiers) --------------------------
+const execFileP = promisify(execFile);
+let ffmpegPath; // undefined = not probed, null = absent
+let scrcpyPresent;
+const FFMPEG_CANDIDATES = ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"];
+/** Resolve an ffmpeg binary, or null if none is installed. Cached. */
+export function resolveFfmpeg() {
+    // Test hook: simulate a machine with no ffmpeg so the degrade path can be exercised
+    // on CI/dev machines that do have it. Not for production use.
+    if (process.env.SLACK_RADAR_NO_FFMPEG === "1")
+        return null;
+    if (ffmpegPath !== undefined)
+        return ffmpegPath;
+    for (const c of FFMPEG_CANDIDATES) {
+        try {
+            execFileSync(c, ["-version"], { timeout: 3000, stdio: "ignore" });
+            ffmpegPath = c;
+            return c;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    ffmpegPath = null;
+    return null;
+}
+/** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
+export function hasScrcpy() {
+    if (scrcpyPresent !== undefined)
+        return scrcpyPresent;
+    try {
+        execFileSync("scrcpy", ["--version"], { timeout: 3000, stdio: "ignore" });
+        scrcpyPresent = true;
+    }
+    catch {
+        scrcpyPresent = false;
+    }
+    return scrcpyPresent;
+}
+/**
+ * Re-probe ffmpeg/scrcpy ASYNCHRONOUSLY and update the cache, so the overlay can
+ * recover after a user installs ffmpeg mid-session without restarting the server.
+ *
+ * Why async (not a force flag on the sync probes): the sync `execFileSync` probes are
+ * safe only BECAUSE they are cached and run at most once (see the same rule in db.ts).
+ * Re-running them synchronously on every panel reopen would block the single event loop
+ * (the live MJPEG stream, /health, every tab) for the spawn duration. This path uses
+ * execFile (non-blocking) instead. It also ONLY re-probes a binary that is currently
+ * cached as absent: if ffmpeg was already found there is nothing to recover, so the
+ * common case does no work.
+ */
+export async function refreshScreenCapabilities() {
+    if (process.env.SLACK_RADAR_NO_FFMPEG === "1") {
+        ffmpegPath = null;
+    }
+    else if (ffmpegPath === undefined || ffmpegPath === null) {
+        // Not yet probed, or last probe found nothing: (re-)check now. Probe into a local
+        // and assign the cache only once, at the end, so a concurrent reader (a second tab,
+        // /health) keeps seeing the prior value during the probe instead of a transient
+        // null. Recovery only moves absent -> present, never the reverse.
+        let found = null;
+        for (const c of FFMPEG_CANDIDATES) {
+            try {
+                await execFileP(c, ["-version"], { timeout: 3000 });
+                found = c;
+                break;
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        ffmpegPath = found;
+    }
+    if (scrcpyPresent === undefined || scrcpyPresent === false) {
+        try {
+            await execFileP("scrcpy", ["--version"], { timeout: 3000 });
+            scrcpyPresent = true;
+        }
+        catch {
+            scrcpyPresent = false;
+        }
+    }
+}
+/**
+ * A single runnable command to install ffmpeg on this platform. Never run
+ * automatically. This is presented as a copy-paste command, so it must be ONE
+ * runnable line: no parentheticals or alternatives, which would error if pasted
+ * into a shell. Alternative package managers belong in surrounding prose, not here.
+ */
+export function ffmpegInstallHint() {
+    switch (process.platform) {
+        case "darwin":
+            return "brew install ffmpeg";
+        case "win32":
+            return "winget install ffmpeg";
+        default:
+            return "sudo apt install ffmpeg";
+    }
+}
+/**
+ * Capability summary for /health and /screen/caps: what the screen overlay can do
+ * on this machine. Reads the cached probe result. To recover after a mid-session
+ * ffmpeg install, call refreshScreenCapabilities() first (the /screen/caps?refresh=1
+ * path does this), then read here.
+ */
+export function screenCapabilities() {
+    const ffmpeg = resolveFfmpeg() !== null;
+    return {
+        // screencap path is pure adb, always available when a device is attached.
+        screenshot: true,
+        liveCast: ffmpeg,
+        ffmpeg,
+        scrcpy: hasScrcpy(),
+        installHint: ffmpeg ? null : ffmpegInstallHint(),
+    };
+}
+// ---- consent (server-enforced, per process) ---------------------------------
+let consentGranted = false;
+/** Grant consent to mirror the live screen. Per server process. */
+export function grantScreenConsent() {
+    consentGranted = true;
+}
+export function hasScreenConsent() {
+    return consentGranted;
+}
+/**
+ * Parse `adb shell cmd display get-displays` output into per-display
+ * {on, phys}, dropping any block without a physical id. The active panel is the
+ * one whose block reports state ON.
+ */
+export function parseDisplays(out) {
+    return out
+        .split(/Display id \d+:/)
+        .slice(1)
+        .map((b) => ({
+        on: /committedState ON\b/.test(b) || /\bstate ON\b/.test(b),
+        phys: (b.match(/uniqueId "local:(\d+)"/) ?? [])[1] ?? null,
+    }))
+        .filter((d) => d.phys !== null);
+}
+/** Choose the physical display id to record: the powered-ON panel, else a lone panel, else null. */
+export function pickDisplay(displays) {
+    const on = displays.find((d) => d.on);
+    if (on)
+        return { phys: on.phys, note: "ON panel " + on.phys };
+    if (displays.length === 1)
+        return { phys: displays[0].phys, note: "single panel" };
+    return { phys: null, note: "no ON panel (screen asleep?) — using default" };
+}
+/** Strip any text prefix (e.g. a multi-display warning) before the PNG magic header. */
+export function stripPngPrefix(raw) {
+    const off = raw.indexOf(PNG_MAGIC);
+    return off > 0 ? raw.subarray(off) : raw;
+}
+// ---- active-display detection ------------------------------------------------
+let scDisplay = null;
+let scDetected = false;
+let scNote = "";
+function shAdb(args) {
+    return new Promise((resolve, reject) => {
+        execFile(adb(), args, { timeout: 15000, maxBuffer: 64 * 1024 * 1024 }, (e, so, se) => e ? reject(new Error(se?.toString() || e.message)) : resolve(so.toString()));
+    });
+}
+/** Detect (and cache) the active display id. resetScreenState() forces a re-detect. */
+export async function detectDisplay() {
+    if (scDetected)
+        return scDisplay;
+    try {
+        const out = await shAdb(["shell", "cmd", "display", "get-displays"]);
+        const picked = pickDisplay(parseDisplays(out));
+        scDisplay = picked.phys;
+        scNote = picked.note;
+    }
+    catch (e) {
+        scDisplay = null;
+        scNote = "get-displays failed: " + e.message;
+    }
+    scDetected = true;
+    return scDisplay;
+}
+export function displayNote() {
+    return scNote;
+}
+// ---- screenshot (pure screencap, no ffmpeg) ----------------------------------
+/** Capture a full-resolution PNG of the active display. Works without ffmpeg. */
+export function captureScreenshot() {
+    return new Promise((resolve) => {
+        const args = ["exec-out", "screencap", "-p"];
+        if (scDisplay)
+            args.push("-d", scDisplay);
+        const cap = execFile(adb(), args, { encoding: "buffer", maxBuffer: 64 * 1024 * 1024, timeout: 8000 }, (e, raw) => {
+            if (e || !raw || !raw.length)
+                return resolve(null);
+            resolve(stripPngPrefix(raw));
+        });
+        cap.on("error", () => resolve(null));
+    });
+}
+let scLive = null;
+function screenrecordArgs() {
+    const a = ["exec-out", "screenrecord", "--output-format=h264", "--size", SC_SIZE, "--bit-rate", SC_BITRATE];
+    if (scDisplay)
+        a.push("--display-id", scDisplay);
+    a.push("-");
+    return a;
+}
+/** Prime an instant first frame (screencap -> single mjpeg) so a static screen is not blank. */
+async function primeFrame(ffmpeg) {
+    const png = await captureScreenshot();
+    if (!png)
+        return null;
+    return new Promise((resolve) => {
+        const ff = spawn(ffmpeg, ["-hide_banner", "-loglevel", "error", "-i", "pipe:0", "-vf", "format=yuvj420p", "-q:v", "6", "-frames:v", "1", "-f", "image2pipe", "-c:v", "mjpeg", "pipe:1"], { stdio: ["pipe", "pipe", "ignore"] });
+        let out = Buffer.alloc(0);
+        ff.stdout.on("data", (c) => (out = Buffer.concat([out, c])));
+        ff.on("exit", () => resolve(out.length ? out : null));
+        ff.on("error", () => resolve(null));
+        ff.stdin.write(png);
+        ff.stdin.end();
+    });
+}
+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");
+    for (const r of L.viewers) {
+        try {
+            r.write(head);
+            r.write(frame);
+            r.write(tail);
+        }
+        catch {
+            // viewer disconnected; harmless
+        }
+    }
+    if (L.recording) {
+        try {
+            L.recording.proc.stdin?.write(frame);
+        }
+        catch {
+            // recording ended; harmless
+        }
+    }
+}
+function cleanupLive(L) {
+    if (L.recording)
+        void stopRecording(L);
+    reapCastProcesses(L);
+}
+/**
+ * screenrecord self-exits at its ~180s cap, so this fires routinely for any open
+ * viewer, not just on error. Migrate the viewers and the in-progress recording to a
+ * fresh cast, then FULLY reap the old one: clear its keepalive interval, drop its
+ * retained frame, and kill its (now orphaned) screenrecord + ffmpeg children. Without
+ * this, each ~3-minute cycle leaks a 400ms interval pinning a multi-KB JPEG and leaves
+ * the old ffmpeg to rely on pipe-EOF — the same orphan-on-the-single-transport class
+ * the module header warns about.
+ */
+function relaunch(old) {
+    const migratedRecording = old.recording;
+    old.recording = null; // detach so reaping the old cast does not stop the recording
+    const next = startLive(old.fps);
+    reapCastProcesses(old);
+    if (!next) {
+        // ffmpeg vanished mid-session: nothing to migrate to. Stop the orphaned recording.
+        if (migratedRecording)
+            old.recording = migratedRecording;
+        if (old.recording)
+            void stopRecording(old);
+        return;
+    }
+    for (const v of old.viewers)
+        next.viewers.add(v);
+    old.viewers.clear();
+    if (migratedRecording)
+        next.recording = migratedRecording;
+}
+/** Clear the keepalive + retained frame and SIGKILL the cast's child processes. Does NOT touch recording. */
+function reapCastProcesses(L) {
+    if (L.keepalive) {
+        clearInterval(L.keepalive);
+        L.keepalive = null;
+    }
+    L.lastFrame = null;
+    try {
+        L.sr.kill("SIGKILL");
+    }
+    catch {
+        /* already gone */
+    }
+    try {
+        L.ff.kill("SIGKILL");
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Start (or return the existing) live cast. Returns null if ffmpeg is unavailable
+ * — callers must degrade rather than assume a stream. The boundary string is
+ * SC_BOUNDARY; the route serves multipart/x-mixed-replace with it.
+ */
+export function startLive(fps) {
+    if (scLive)
+        return scLive;
+    const ffmpeg = resolveFfmpeg();
+    if (!ffmpeg)
+        return null;
+    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",
+        "-f", "image2pipe", "-c:v", "mjpeg", "pipe:1",
+    ], { stdio: ["pipe", "pipe", "ignore"] });
+    sr.stdout?.pipe(ff.stdin);
+    const L = {
+        sr,
+        ff,
+        viewers: new Set(),
+        lastFrame: null,
+        lastFrameTs: 0,
+        recording: null,
+        fps: fps || 20,
+        keepalive: null,
+    };
+    let acc = Buffer.alloc(0);
+    ff.stdout?.on("data", (chunk) => {
+        acc = Buffer.concat([acc, chunk]);
+        for (;;) {
+            const soi = acc.indexOf(Buffer.from([0xff, 0xd8]));
+            if (soi < 0) {
+                if (acc.length > 4 << 20)
+                    acc = Buffer.alloc(0);
+                break;
+            }
+            const eoi = acc.indexOf(Buffer.from([0xff, 0xd9]), soi + 2);
+            if (eoi < 0) {
+                if (soi > 0)
+                    acc = acc.subarray(soi);
+                break;
+            }
+            const frame = acc.subarray(soi, eoi + 2);
+            acc = acc.subarray(eoi + 2);
+            L.lastFrame = frame;
+            L.lastFrameTs = Date.now();
+            pushFrame(L, frame);
+        }
+    });
+    const onExit = () => {
+        if (scLive === L) {
+            scLive = null;
+            if (L.viewers.size || L.recording)
+                relaunch(L);
+            else
+                cleanupLive(L);
+        }
+    };
+    sr.on("exit", onExit);
+    ff.on("exit", onExit);
+    // Re-push the last frame while idle so a static screen's final frame paints
+    // (multipart/x-mixed-replace renders part N only when part N+1's boundary arrives).
+    //
+    // KNOWN LIMITATION: screenrecord does not flush its encoder when the screen goes
+    // static, so the last 1-2 motion frames stay buffered on the device and the live
+    // view can sit a beat behind after you stop, catching up on the next motion. This
+    // is cosmetic (no data is lost; the screenshot button always reflects the true
+    // current screen) and self-corrects the instant the screen changes. The only full
+    // fix is scrcpy's MediaCodec KEY_REPEAT_PREVIOUS_FRAME_AFTER, which re-emits frames
+    // encoder-side on a static screen; that is a separate larger change. An idle
+    // screencap-refresh was tried and rejected: on a single adb transport it contends
+    // with the live screenrecord and the radar socket and destabilizes the connection.
+    L.keepalive = setInterval(() => {
+        if (L.lastFrame && Date.now() - L.lastFrameTs > 350)
+            pushFrame(L, L.lastFrame);
+    }, 400);
+    scLive = L;
+    return L;
+}
+/** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
+export function addViewer(L, res) {
+    L.viewers.add(res);
+}
+export function removeViewer(res) {
+    if (!scLive)
+        return;
+    scLive.viewers.delete(res);
+    if (!scLive.viewers.size && !scLive.recording) {
+        cleanupLive(scLive);
+        scLive = null;
+    }
+}
+export function getLive() {
+    return scLive;
+}
+export function lastFrame() {
+    return scLive?.lastFrame ?? null;
+}
+export async function primeIfNeeded() {
+    const ffmpeg = resolveFfmpeg();
+    if (!ffmpeg || !scLive || scLive.lastFrame)
+        return;
+    const f = await primeFrame(ffmpeg);
+    if (f && scLive && !scLive.lastFrame) {
+        scLive.lastFrame = f;
+        scLive.lastFrameTs = Date.now();
+        pushFrame(scLive, f);
+    }
+}
+export const SCREEN_BOUNDARY = SC_BOUNDARY;
+// ---- record to mp4 -----------------------------------------------------------
+export function startRecording() {
+    const ffmpeg = resolveFfmpeg();
+    if (!ffmpeg || !scLive)
+        return null;
+    if (scLive.recording)
+        return scLive.recording.path;
+    // Recordings capture live screen content (open DMs, message text, notifications),
+    // so the dir is owner-only (0700) and each mp4 owner-read/write only (0600) — the
+    // same posture the DB-browser uses for its equally-sensitive pulled copies. Without
+    // this the dir is world-traversable (~0755) and ffmpeg writes the file under the
+    // default umask (~0644, world-readable), exposing captures to other local users.
+    fs.mkdirSync(SC_TMP, { recursive: true, mode: 0o700 });
+    // mkdirSync's `mode` only applies when CREATING the dir; a dir left over from an
+    // earlier session (or created before this posture existed) keeps its old perms
+    // (~0755, world-traversable). chmod unconditionally so the owner-only guarantee
+    // holds regardless of when the dir first appeared.
+    try {
+        fs.chmodSync(SC_TMP, 0o700);
+    }
+    catch {
+        // best-effort; file is still written 0600 below
+    }
+    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"] });
+    scLive.recording = { proc: rec, path: out };
+    return out;
+}
+export function stopRecording(L = scLive) {
+    if (!L?.recording)
+        return Promise.resolve(null);
+    const r = L.recording;
+    L.recording = null;
+    return new Promise((resolve) => {
+        let done = false;
+        const fin = () => {
+            if (!done) {
+                done = true;
+                // The finished mp4 holds captured screen content; restrict to owner before
+                // it is downloadable. The 0700 dir already blocks other-user traversal; this
+                // is defense-in-depth on the file itself (ffmpeg created it under the umask).
+                try {
+                    fs.chmodSync(r.path, 0o600);
+                }
+                catch {
+                    // best-effort; dir perms are the primary control
+                }
+                resolve(r.path);
+            }
+        };
+        r.proc.on("exit", fin);
+        try {
+            r.proc.stdin?.end();
+        }
+        catch {
+            fin();
+        }
+        setTimeout(fin, 8000);
+    });
+}
+/**
+ * Resolve a recording for download. Restricted to the screen tmp dir AND to the
+ * radar_screen_*.mp4 name this module writes: path.basename strips any directory
+ * (no traversal), and the prefix/extension check means a download request can only
+ * ever name a radar recording, never an arbitrary file that happened to land in the dir.
+ */
+export function recordingPath(file) {
+    const base = path.basename(file);
+    if (!/^radar_screen_[\w-]+\.mp4$/.test(base))
+        return null;
+    const p = path.join(SC_TMP, base);
+    return fs.existsSync(p) ? p : null;
+}
+// ---- lifecycle ---------------------------------------------------------------
+/** Reset detection + tear down any live cast. Called on device re-enable and shutdown. */
+export function resetScreenState() {
+    scDetected = false;
+    scDisplay = null;
+    scNote = "";
+    if (scLive) {
+        cleanupLive(scLive);
+        scLive = null;
+    }
+    // Recorded mp4s hold sensitive screen content; do not let them linger across the
+    // session boundary on disk.
+    cleanupRecordings();
+    // Best-effort: clean up orphaned device-side screenrecord procs that the host pipe
+    // close did not kill (they congest the single adb transport). NOTE: `-f screenrecord`
+    // is device-WIDE — it kills every screenrecord on the device, not just radar's. That
+    // is intentional for a debug tool (radar should not leave the transport congested),
+    // but a user running an unrelated manual screenrecord would have it killed too.
+    try {
+        execFile(adb(), ["shell", "pkill", "-9", "-f", "screenrecord"], { timeout: 5000 }, () => { });
+    }
+    catch {
+        // best-effort
+    }
+}
+let cleanupRegistered = false;
+/**
+ * Kill any live cast (and orphaned device-side screenrecord) on process exit. Mirrors
+ * logcat-capture.registerCleanup(); without it, Ctrl-C on an open mirror orphans the
+ * screenrecord + ffmpeg children and leaves the device transport congested for the
+ * next session. Called from createServer().
+ */
+export function registerScreenCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    process.on("exit", () => {
+        if (scLive)
+            reapCastProcesses(scLive);
+    });
+    process.on("SIGINT", () => {
+        signalCleanup();
+        process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+        signalCleanup();
+        process.exit(143);
+    });
+}
+/**
+ * Synchronous teardown for the signal path. resetScreenState()'s device-side
+ * orphan-kill uses async execFile, which does NOT complete before process.exit on
+ * Ctrl-C — so the orphaned device screenrecord the module header warns about would
+ * survive. Reap host children, then kill the device-side screenrecord SYNCHRONOUSLY
+ * (execFileSync, short timeout) so it actually runs before we exit, and clean the
+ * recordings. Best-effort throughout; exit must not be blocked by a cleanup failure.
+ */
+function signalCleanup() {
+    if (scLive) {
+        cleanupLive(scLive);
+        scLive = null;
+    }
+    try {
+        execFileSync(adb(), ["shell", "pkill", "-9", "-f", "screenrecord"], {
+            timeout: 3000,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // best-effort: no adb, no device, or nothing to kill
+    }
+    cleanupRecordings();
+}

package/dist/shared/transport.d.ts

@@ -64,6 +64,16 @@ export interface DeviceTransport {
      * unchecked casts when asking "which profile did this capture?".
      */
     getActiveUserId(): string | null;
+    /**
+     * Resolve the user the debug build is actually running as, never null. Unlike
+     * getActiveUserId() (which returns null when nothing has been detected), this always
+     * resolves to a concrete profile, preferring the non-zero/secondary profile the work
+     * build runs under rather than blindly defaulting to user 0. Callers that need a definite
+     * target (the on-device DB browser) use this so list/pull/query never silently disagree
+     * on which profile's store they touch. On a single-user platform (iOS) this returns the
+     * sole user or an empty string.
+     */
+    resolveActiveUser(): string;
     /**
      * Returns the last error message from an `ensureForward()` failure, or null
      * if the last attempt succeeded or has not happened. Lets callers surface

package/dist/web/bin.d.ts

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Decide whether a /spec response body identifies a Radar dashboard. A Radar /spec
+ * is always a plain object carrying a `viz` array (even a blank spec is
+ * { title, blank, viz: [] }). Requiring both excludes a foreign service that happens
+ * to 200 with arbitrary JSON (a bare array, a string, an unrelated object). Exported
+ * for unit testing. statusCode must be 200.
+ */
+export declare function isRadarSpecBody(statusCode: number | undefined, body: string): boolean;
+/**
+ * Start the web dashboard server, open the browser, and wire shutdown signals.
+ * Extracted so both the dedicated `slack-radar-web` bin and the default bin's
+ * `web` subcommand dispatcher launch the dashboard the same way. Exported so the
+ * dispatcher (mcp/index.ts) calls it explicitly rather than relying on an import
+ * side-effect, which keeps importing this module (e.g. in a test) side-effect-free.
+ */
+export declare function startWebServer(): void;