@slack/radar-mcp 1.3.0 → 1.5.0

package/dist/shared/screen.js

@@ -0,0 +1,576 @@
+/**
+ * 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 { 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) --------------------------
+let ffmpegPath; // undefined = not probed, null = absent
+let scrcpyPresent;
+/** 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", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"]) {
+        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;
+}
+/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+export function ffmpegInstallHint() {
+    switch (process.platform) {
+        case "darwin":
+            return "brew install ffmpeg";
+        case "win32":
+            return "winget install ffmpeg   (or: choco install ffmpeg)";
+        default:
+            return "sudo apt install ffmpeg   (or your distro's package manager)";
+    }
+}
+/** Capability summary for /health: what the screen overlay can do on this machine. */
+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/web/bin.js

@@ -1,35 +1,69 @@
 #!/usr/bin/env node
-import { createServer, WEB_PORT } from "./server.js";
 import { execSync } from "child_process";
-const server = createServer();
-server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-        console.error(`Port ${WEB_PORT} is already in use. Another instance may be running.\n` +
-            `Kill it with: lsof -ti :${WEB_PORT} | xargs kill\n` +
-            `Or set a different port: SLACK_RADAR_WEB_PORT=8101 slack-radar-web`);
-        process.exit(1);
-    }
-    throw err;
-});
-server.listen(WEB_PORT, () => {
-    const url = `http://localhost:${WEB_PORT}`;
-    console.log(`Slack Radar Web running at ${url}`);
-    try {
-        if (process.platform === "darwin") {
-            execSync(`open ${url}`, { stdio: "ignore" });
+import { createServer, WEB_PORT } from "./server.js";
+/**
+ * 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.
+ */
+function startWebServer() {
+    // Safety net: a single route handler must never take the whole dashboard down. An async
+    // callback (e.g. a device-probe that both ends and errors) can otherwise throw
+    // ERR_HTTP_HEADERS_SENT outside any try/catch and kill the process. Log and keep serving;
+    // handlers still guard their own writes, this is the backstop for anything they miss.
+    process.on("uncaughtException", (err) => {
+        console.error("uncaughtException (kept alive):", err);
+    });
+    process.on("unhandledRejection", (err) => {
+        console.error("unhandledRejection (kept alive):", err);
+    });
+    const server = createServer();
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`Port ${WEB_PORT} is already in use. Another instance may be running.\n` +
+                `Kill it with: lsof -ti :${WEB_PORT} | xargs kill\n` +
+                `Or set a different port: SLACK_RADAR_WEB_PORT=8101 slack-radar web`);
+            process.exit(1);
+        }
+        throw err;
+    });
+    // Bind loopback-only. The dashboard serves sensitive device data with no auth:
+    // live ring buffers, the on-device message store via the DB browser, and the live
+    // screen mirror (open DMs, notifications). Omitting the host arg binds all
+    // interfaces (0.0.0.0/::), which would let any same-network peer hit /dbquery or
+    // grant screen consent (a single unauthenticated process boolean) and watch the
+    // device. The consent gate only raises the bar for the local user; 127.0.0.1 is
+    // what actually closes the network. The device-side connection is already
+    // loopback-scoped (constants.ts); the dashboard's own listener must match. Remote
+    // access, if ever needed, belongs in a separate token-gated feature.
+    server.listen(WEB_PORT, "127.0.0.1", () => {
+        const url = `http://localhost:${WEB_PORT}`;
+        console.log(`Slack Radar Web running at ${url}`);
+        // Auto-open the browser for the HUMAN launcher (`slack-radar web` / `slack-radar-web`),
+        // but NOT when spawned as a bridge child by the open_radar_dashboard MCP tool
+        // (SLACK_RADAR_NO_OPEN=1). The Claude Code session must not pop a browser window the user
+        // did not ask for — the same no-auto-open-browser rule the SERVER_INSTRUCTIONS state for
+        // /radar-ui. The tool returns the URL instead, for the Claude Code session to surface.
+        if (process.env.SLACK_RADAR_NO_OPEN)
+            return;
+        try {
+            if (process.platform === "darwin") {
+                execSync(`open ${url}`, { stdio: "ignore" });
+            }
+            else if (process.platform === "linux") {
+                execSync(`xdg-open ${url}`, { stdio: "ignore" });
+            }
         }
-        else if (process.platform === "linux") {
-            execSync(`xdg-open ${url}`, { stdio: "ignore" });
+        catch {
+            // Browser open is best-effort
         }
-    }
-    catch {
-        // Browser open is best-effort
-    }
-});
-function shutdown() {
-    console.log("\nShutting down…");
-    server.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 2000);
+    });
+    const shutdown = () => {
+        console.log("\nShutting down…");
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 2000);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
 }
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
+startWebServer();