@slack/radar-mcp 1.3.0 → 1.5.0

package/dist/web/server.js

@@ -1,38 +1,182 @@
 import http from "http";
 import fs from "fs";
+import os from "os";
 import path from "path";
+import { spawn } from "child_process";
 import { fileURLToPath } from "url";
-import { AndroidTransport } from "../shared/android.js";
-import { RADAR_HOST, RADAR_PORT } from "../shared/constants.js";
+import { AndroidTransport, resolveAdbPath } from "../shared/android.js";
+import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT } from "../shared/constants.js";
+import { cleanupPulledDatabases, initializeDatabasePath, listDatabases, pullDatabase, pulledSize, queryDatabase, resetDbState, } from "../shared/db.js";
+import { LogSession } from "./log-session.js";
+import { BLANK_SPEC, coerceSpec, validateSpec } from "./spec.js";
+import { screenCapabilities, grantScreenConsent, hasScreenConsent, detectDisplay, displayNote, captureScreenshot, startLive, addViewer, removeViewer, primeIfNeeded, startRecording, stopRecording, recordingPath, resetScreenState, registerScreenCleanup, resolveFfmpeg, ffmpegInstallHint, SCREEN_BOUNDARY, } from "../shared/screen.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? 8100);
+const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? WEB_PORT_DEFAULT);
 const INDEX_PATH = path.join(__dirname, "public", "index.html");
+// Backpressure ceiling for an SSE connection's unwritten log frames. If a
+// client's socket buffer is already this deep (slow/backgrounded tab), new log
+// frames are dropped for that connection rather than queued without bound. ~4 MB
+// is far above a healthy localhost client's transient buffer but well under a
+// memory problem; a dropped frame is recovered on the client's next reconnect
+// replay. Only the log fan-out is bounded this way — the device proxy stream is
+// already paced by the upstream socket.
+const MAX_SSE_WRITABLE_BYTES = 4 * 1024 * 1024;
+/**
+ * Decide whether to drop a log frame under backpressure. LIVE frames are dropped
+ * when the connection's unwritten buffer is already past the cap (an unbounded
+ * queue to a slow/backgrounded tab). REPLAY frames are NEVER dropped: replay is a
+ * bounded one-time send of the whole ring and IS the connection's purpose; it runs
+ * synchronously so writableLength climbs monotonically, and dropping past the cap
+ * would silently cut the newest history and reintroduce the reconnect log-loss
+ * this feature fixes. Exported pure so the replay-exemption is unit-testable
+ * without a socket. `cap` defaults to the live ceiling.
+ */
+export function shouldDropLogFrame(replay, writableLength, cap = MAX_SSE_WRITABLE_BYTES) {
+    if (replay)
+        return false;
+    return writableLength > cap;
+}
+// The active dashboard spec is session-scoped runtime state, NOT source. It lives
+// under the user's home data dir (never inside the repo / published tarball) so it
+// cannot be accidentally committed. The path is scoped by port so two dashboards
+// running on different ports do not stomp each other's spec (a browser attached to
+// one instance polls /spec and would otherwise overwrite the shared file for all).
+// Each server start resets its own file to blank.
+const SPEC_DIR = path.join(os.homedir(), ".slack-radar");
+const SPEC_PATH = path.join(SPEC_DIR, `web-spec-${WEB_PORT}.json`);
 const transport = new AndroidTransport();
+// One session-long logcat capture shared across every dashboard stream
+// connection. The device cannot replay logcat history to us, so the dashboard
+// keeps its own bounded session ring here and replays it to each newly opened
+// stream — this is what makes a tab switch (which reopens /stream) show the full
+// log history instead of only lines that arrive after the reconnect, matching
+// how Android Studio retains logcat for the whole session. Spawn + parse are
+// injected so the capture logic is unit-testable without a real `adb logcat`.
+const logSession = new LogSession(() => spawn(resolveAdbPath() ?? "adb", ["logcat", "-v", "threadtime", "-T", "1"], {
+    stdio: ["ignore", "pipe", "ignore"],
+}), (line) => parseLogcat(line));
+// Kill the persistent logcat child on process exit so it does not orphan when the
+// dashboard is spawned and later terminated by the open_radar_dashboard MCP tool.
+logSession.registerCleanup();
+// By design the capture is NOT stopped when the last log stream disconnects (e.g.
+// switching to the Network tab): it keeps filling the session ring so returning to
+// a log tab — even much later — still shows the full history, the way Android
+// Studio retains logcat for the whole session. The cost is a logcat reader running
+// while no log tab is open; memory stays bounded by the ring cap and by the
+// per-connection backpressure guard in handleStream (a stalled client drops frames
+// rather than buffering without limit).
+function writeSpec(spec) {
+    try {
+        fs.mkdirSync(SPEC_DIR, { recursive: true });
+        fs.writeFileSync(SPEC_PATH, JSON.stringify(spec, null, 2));
+    }
+    catch {
+        // Best-effort; a failed write just means the next /spec read falls back to blank.
+    }
+}
+function loadSpec() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(SPEC_PATH, "utf8"));
+        const spec = coerceSpec(parsed);
+        return validateSpec(spec) ? BLANK_SPEC : spec;
+    }
+    catch {
+        return BLANK_SPEC;
+    }
+}
+// Start every run from a clean slate so a refresh/restart opens blank — UNLESS the
+// process was spawned with an initial spec (SLACK_RADAR_INITIAL_SPEC). The MCP
+// open_radar_dashboard handler sets that env on a cold spawn so the spec file is
+// already the custom spec BEFORE the browser loads and runs bootDefault(); without
+// this seed the browser's bootDefault (fires only on a blank spec) and the handler's
+// /setspec POST race, and a lost race leaves the Live preset showing while the tool
+// already reported the custom dashboard is live. Seeding makes the handler the sole
+// startup writer and removes the race deterministically. Invalid seed falls back to blank.
+function initialSpec() {
+    const raw = process.env.SLACK_RADAR_INITIAL_SPEC;
+    if (!raw)
+        return BLANK_SPEC;
+    try {
+        const spec = coerceSpec(JSON.parse(raw));
+        return validateSpec(spec) ? BLANK_SPEC : spec;
+    }
+    catch {
+        return BLANK_SPEC;
+    }
+}
+writeSpec(initialSpec());
+// Initialize the database path with the web server port, so concurrent dashboards
+// on different ports do not collide in tmpdir.
+initializeDatabasePath(WEB_PORT);
+// Pulled DB copies are plaintext message stores; never let them linger across runs.
+// Clean on start, and on the process signals the bin wires for shutdown.
+cleanupPulledDatabases();
+for (const sig of ["SIGINT", "SIGTERM", "exit"]) {
+    process.once(sig, cleanupPulledDatabases);
+}
 export function createServer() {
+    registerScreenCleanup(); // tear down any live screen cast on process exit/signals
     const server = http.createServer((req, res) => {
-        if (req.url === "/" || req.url === "/index.html") {
-            try {
-                const html = fs.readFileSync(INDEX_PATH);
-                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                res.end(html);
-            }
-            catch (e) {
-                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
-                res.end(`Failed to read ${INDEX_PATH}: ${e.message}`);
-            }
+        const url = req.url ?? "";
+        if (url === "/" || url === "/index.html") {
+            serveIndex(res);
+            return;
+        }
+        if (url === "/spec" && req.method === "GET") {
+            sendJson(res, 200, loadSpec());
+            return;
+        }
+        if (url === "/setspec" && req.method === "POST") {
+            handleSetSpec(req, res);
+            return;
+        }
+        if (url === "/health" && req.method === "GET") {
+            handleHealth(res);
             return;
         }
-        if (req.url === "/_control/profiles" && req.method === "GET") {
+        if (url === "/enable" && req.method === "POST") {
+            handleEnable(res);
+            return;
+        }
+        if (url === "/stream" && req.method === "GET") {
+            handleStream(req, res);
+            return;
+        }
+        if (url.startsWith("/backfill")) {
+            handleBackfill(req, res);
+            return;
+        }
+        if (url.startsWith("/detail")) {
+            handleDetail(req, res);
+            return;
+        }
+        if (url.startsWith("/dbs") && req.method === "GET") {
+            handleDbList(req, res);
+            return;
+        }
+        if (url.startsWith("/dbtables") && req.method === "GET") {
+            handleDbTables(req, res);
+            return;
+        }
+        if (url.startsWith("/dbquery") && req.method === "GET") {
+            handleDbQuery(req, res);
+            return;
+        }
+        if (url === "/_control/profiles" && req.method === "GET") {
             listProfiles(res);
             return;
         }
-        if (req.url?.startsWith("/_control/activate") && req.method === "POST") {
-            const url = new URL(req.url, `http://localhost:${WEB_PORT}`);
-            const userId = url.searchParams.get("user_id") ?? undefined;
+        if (url.startsWith("/_control/activate") && req.method === "POST") {
+            const parsed = new URL(url, `http://localhost:${WEB_PORT}`);
+            const userId = parsed.searchParams.get("user_id") ?? undefined;
             activateRadar(res, userId);
             return;
         }
-        if (req.url?.startsWith("/api/")) {
+        if (url.startsWith("/screen/")) {
+            handleScreen(req, res);
+            return;
+        }
+        if (url.startsWith("/api/")) {
             proxyToRadar(req, res);
             return;
         }
@@ -41,11 +185,739 @@ export function createServer() {
     });
     return server;
 }
+function serveIndex(res) {
+    try {
+        const html = fs.readFileSync(INDEX_PATH);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end(`Failed to read ${INDEX_PATH}: ${e.message}`);
+    }
+}
+function sendJson(res, status, payload) {
+    // A device probe can fire both "end" and "error"/"timeout" for one request, so its
+    // callbacks may call sendJson twice. The second writeHead would throw
+    // ERR_HTTP_HEADERS_SENT and crash the whole process. Swallow the duplicate.
+    if (res.headersSent || res.writableEnded)
+        return;
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(payload));
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", () => resolve(body));
+    });
+}
+/**
+ * Persist a spec pushed by the client (a pre-built tab, a filter edit, a chip
+ * cancel) or by an MCP caller. Coerce + validate before writing; a bad spec is
+ * rejected with its reason so the UI can surface it rather than render zeros.
+ */
+async function handleSetSpec(req, res) {
+    const body = await readBody(req);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        sendJson(res, 400, { error: "bad json" });
+        return;
+    }
+    const spec = coerceSpec(parsed);
+    const err = validateSpec(spec);
+    if (err) {
+        sendJson(res, 400, { error: err });
+        return;
+    }
+    writeSpec(spec);
+    sendJson(res, 200, {
+        ok: true,
+        url: `http://localhost:${WEB_PORT}`,
+        title: spec.title ?? "",
+    });
+}
+/**
+ * Always-available device-reachability probe, independent of whether a dashboard
+ * is built. Drives the connection dot even on a blank dashboard. Reuses the same
+ * forward/proxy base as the rest of the server.
+ */
+function handleHealth(res) {
+    // A probe can fire BOTH an "end" and an "error"/"timeout" (partial response then socket
+    // drop), so guard the response to exactly one write. Without this the second sendJson
+    // does a second writeHead -> ERR_HTTP_HEADERS_SENT -> uncaught -> the whole server dies.
+    let replied = false;
+    const reply = (device) => {
+        if (replied)
+            return;
+        replied = true;
+        sendJson(res, 200, { device, screen: screenCapabilities() });
+    };
+    const probe = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: "/api/ping",
+        method: "GET",
+        timeout: 2500,
+    }, (up) => {
+        up.resume();
+        up.on("end", () => reply(up.statusCode === 200));
+        up.on("error", () => reply(false));
+    });
+    probe.on("error", () => reply(false));
+    probe.on("timeout", () => {
+        probe.destroy();
+        reply(false);
+    });
+    probe.end();
+}
+/**
+ * Re-arm Radar from the dashboard. Mirrors the recovery sequence: reset cached
+ * forward state, rebuild a clean adb forward, and re-broadcast activation, so the
+ * user never has to drop to a terminal. Delegates entirely to AndroidTransport;
+ * no adb shelling here.
+ */
+function handleEnable(res) {
+    transport.resetState();
+    // A reconnect may be a different device / re-armed profile, so drop the cached DB user
+    // set + sqlite path; the next /dbs re-detects the profiles fresh.
+    resetDbState();
+    resetScreenState(); // re-detect the active display + clear any stale cast on re-arm
+    const forwarded = transport.ensureForward();
+    if (!forwarded) {
+        const reason = transport.getLastForwardError?.() ?? null;
+        sendJson(res, 200, {
+            enabled: false,
+            error: reason ?? "ADB forward failed. Is a device connected?",
+        });
+        return;
+    }
+    try {
+        transport.activate(transport.getTimeoutMinutes());
+    }
+    catch (e) {
+        sendJson(res, 200, {
+            enabled: false,
+            error: `Broadcast failed: ${e.message}. Debug build not running?`,
+        });
+        return;
+    }
+    // Verify by pinging the device the same way /health does. Reply exactly once (an "end"
+    // and an "error"/"timeout" can both fire) to avoid a double writeHead crashing the server.
+    let replied = false;
+    const reply = (enabled) => {
+        if (replied)
+            return;
+        replied = true;
+        sendJson(res, 200, { enabled });
+    };
+    const probe = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: "/api/ping",
+        method: "GET",
+        timeout: 2500,
+    }, (up) => {
+        up.resume();
+        up.on("end", () => reply(up.statusCode === 200));
+        up.on("error", () => reply(false));
+    });
+    probe.on("error", () => reply(false));
+    probe.on("timeout", () => {
+        probe.destroy();
+        reply(false);
+    });
+    probe.end();
+}
+const SOURCE_ARRAY_KEY = {
+    network: "calls",
+    rtm: "events",
+    clog: "clogs",
+};
+/**
+ * Replay the device's recent ring buffers for a source so a freshly-built tab
+ * shows history immediately instead of filling only going forward. The device is
+ * the source of truth. "all" pulls network+rtm+clog and merges them oldest->newest;
+ * "log" is host-side (no device buffer) and so has nothing to replay. Returns
+ * `[{type, event}]` frames mirroring the stream shape.
+ */
+function handleBackfill(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const src = u.searchParams.get("source") ?? "network";
+    const limit = Math.min(500, Number(u.searchParams.get("limit")) || 200);
+    const kinds = src === "all"
+        ? ["network", "rtm", "clog"]
+        : [src].filter((k) => k !== "log" && k in SOURCE_ARRAY_KEY);
+    const fetchKind = (kind) => new Promise((resolve) => {
+        const apiPath = `/api/${kind === "clog" ? "clogs" : kind}?limit=${limit}`;
+        const rq = http.request({
+            host: RADAR_HOST,
+            port: RADAR_PORT,
+            path: apiPath,
+            method: "GET",
+            timeout: 4000,
+        }, (up) => {
+            let b = "";
+            up.on("data", (c) => (b += c));
+            up.on("end", () => {
+                try {
+                    const j = JSON.parse(b);
+                    const arr = j[SOURCE_ARRAY_KEY[kind]] ?? [];
+                    resolve(arr.map((e) => ({ type: kind, event: e })));
+                }
+                catch {
+                    resolve([]);
+                }
+            });
+        });
+        rq.on("error", () => resolve([]));
+        rq.on("timeout", () => {
+            rq.destroy();
+            resolve([]);
+        });
+        rq.end();
+    });
+    Promise.all(kinds.map(fetchKind))
+        .then((lists) => {
+        const merged = lists
+            .flat()
+            .sort((a, b) => (Number(a.event.timestamp) || 0) - (Number(b.event.timestamp) || 0));
+        sendJson(res, 200, { frames: merged });
+    })
+        .catch(() => sendJson(res, 200, { frames: [] }));
+}
+// Detail kinds the inspector may request, mapped to their device route segment. The
+// device serves clog detail at /api/clogs/ (plural); the rest match the kind name.
+const DETAIL_ROUTES = {
+    network: "network",
+    rtm: "rtm",
+    clog: "clogs",
+};
+/**
+ * Finish a /detail proxy response after an upstream error or timeout. The success
+ * callback streams the upstream response, so headers may already be sent when a later
+ * "error"/"timeout" fires (a partial response then the device drops the socket mid-stream,
+ * common when the device idle-shuts). Calling writeHead a second time throws
+ * ERR_HTTP_HEADERS_SENT and crashes the whole process, so only write a status when headers
+ * have not gone out yet; otherwise just end the already-started response. Exported for tests.
+ */
+export function failDetailResponse(res, status) {
+    if (!res.headersSent) {
+        res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+        res.end("{}");
+    }
+    else {
+        res.end();
+    }
+}
+/**
+ * Proxy a single record's full detail from the device ring buffer. Thin pass-through
+ * to `/api/<kind>/<id>` so the inspector can fetch a clicked row's payload.
+ */
+function handleDetail(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const id = u.searchParams.get("id");
+    const kind = u.searchParams.get("kind") ?? "network";
+    const route = DETAIL_ROUTES[kind];
+    if (!id || !route) {
+        res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+        res.end("{}");
+        return;
+    }
+    const upstream = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: `/api/${route}/${encodeURIComponent(id)}`,
+        method: "GET",
+        timeout: 4000,
+    }, (up) => {
+        res.writeHead(up.statusCode ?? 502, {
+            "Content-Type": "application/json; charset=utf-8",
+        });
+        up.on("data", (c) => res.write(c));
+        up.on("end", () => res.end());
+    });
+    upstream.on("error", () => failDetailResponse(res, 502));
+    upstream.on("timeout", () => {
+        upstream.destroy();
+        failDetailResponse(res, 504);
+    });
+    upstream.end();
+}
+// --- On-device SQLite browser (source: "db") ---
+//
+// These delegate to shared/db.ts (run-as + host sqlite3, read-only). Each computes its
+// payload+status BEFORE writing headers so a throw still yields a clean JSON error rather
+// than a half-written response. Errors come back as 200 {error} for the list/tables views
+// (so the UI renders the message in-place) and 400 {error} for a rejected query.
+// The Android user whose store the DB browser targets. Prefer an explicit ?user= (the UI's
+// profile switcher, when a dual-profile device exists), else the profile the dashboard is
+// bound to. Threaded through every db call so list / pull / query never disagree on profile.
+function dbUser(req) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const explicit = u.searchParams.get("user");
+    if (explicit !== null)
+        return explicit;
+    // No explicit pick: default to the profile the debug build is actually running as
+    // (resolveActiveUser prefers the non-zero/secondary profile Radar binds to), not user 0.
+    try {
+        return transport.resolveActiveUser();
+    }
+    catch {
+        return undefined; // let db.ts fall back to its first available user
+    }
+}
+function handleDbList(req, res) {
+    try {
+        sendJson(res, 200, listDatabases(dbUser(req)));
+    }
+    catch (e) {
+        sendJson(res, 200, { error: e.message, names: [], availableUsers: [] });
+    }
+}
+async function handleDbTables(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const db = u.searchParams.get("db") ?? "";
+    const user = dbUser(req);
+    const force = u.searchParams.get("refresh") === "1";
+    let payload;
+    let status;
+    try {
+        await pullDatabase(db, user, force);
+        const tableRows = (await queryDatabase(db, "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name", user));
+        // Row counts: awaited serially against the already-pulled LOCAL copy (each is fast and
+        // keeps the event loop free between calls; 91 parallel sqlite procs would spike).
+        const tables = [];
+        for (const t of tableRows) {
+            let rows = "?";
+            try {
+                rows = (await queryDatabase(db, `SELECT COUNT(*) c FROM "${t.name}"`, user))[0].c;
+            }
+            catch {
+                // a view or virtual table may not count; leave "?"
+            }
+            tables.push({ name: t.name, rows });
+        }
+        payload = { db, sizeBytes: pulledSize(db, user), tables };
+        status = 200;
+    }
+    catch (e) {
+        payload = { error: e.message };
+        status = 200; // surfaced in the tables pane, not a transport error
+    }
+    sendJson(res, status, payload);
+}
+async function handleDbQuery(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const db = u.searchParams.get("db") ?? "";
+    const sql = u.searchParams.get("sql") ?? "";
+    let payload;
+    let status;
+    try {
+        payload = { rows: await queryDatabase(db, sql, dbUser(req)) };
+        status = 200;
+    }
+    catch (e) {
+        payload = { error: String(e.message).split("\n")[0] };
+        status = 400;
+    }
+    sendJson(res, status, payload);
+}
+/**
+ * Screen overlay routes. The live screen shows real DMs and message content, so the
+ * stream and record routes are gated behind an explicit per-process consent (granted
+ * by POST /screen/consent from the in-UI consent panel). The gate is enforced HERE,
+ * server-side, not just in the browser, so a direct request cannot bypass it.
+ *
+ * /screen/caps        capabilities (ffmpeg/scrcpy present, install hint, consent state)
+ * /screen/consent     POST: grant consent for this server process
+ * /screen/shot        full-resolution PNG screenshot (pure screencap; works without ffmpeg)
+ * /screen/stream      multipart/x-mixed-replace MJPEG live cast (needs ffmpeg + consent)
+ * /screen/record/start|stop   record the live cast to mp4 (needs ffmpeg + consent)
+ * /screen/download    download a finished recording
+ * /screen/redetect    re-detect the active display
+ */
+function handleScreen(req, res) {
+    const url = req.url ?? "";
+    // Capabilities + consent state. Always available; drives the overlay's degrade UI.
+    if (url.startsWith("/screen/caps")) {
+        sendJson(res, 200, { ...screenCapabilities(), consent: hasScreenConsent() });
+        return;
+    }
+    // Grant consent for this process. Required before any pixels are mirrored.
+    if (url === "/screen/consent" && req.method === "POST") {
+        grantScreenConsent();
+        sendJson(res, 200, { consent: true });
+        return;
+    }
+    // Screenshot: pure screencap, no ffmpeg. Still consent-gated — it is the live screen.
+    if (url.startsWith("/screen/shot")) {
+        if (!hasScreenConsent()) {
+            sendJson(res, 403, { error: "screen consent required" });
+            return;
+        }
+        void (async () => {
+            await detectDisplay();
+            const png = await captureScreenshot();
+            if (!png) {
+                sendJson(res, 502, { error: "screencap failed; is the device awake and connected?" });
+                return;
+            }
+            res.writeHead(200, {
+                "Content-Type": "image/png",
+                "Content-Disposition": `attachment; filename="radar-screen-${Date.now()}.png"`,
+            });
+            res.end(png);
+        })();
+        return;
+    }
+    // Live MJPEG stream. Needs consent AND ffmpeg.
+    if (url.startsWith("/screen/stream")) {
+        if (!hasScreenConsent()) {
+            sendJson(res, 403, { error: "screen consent required" });
+            return;
+        }
+        if (!resolveFfmpeg()) {
+            sendJson(res, 501, { error: "ffmpeg not installed", installHint: ffmpegInstallHint() });
+            return;
+        }
+        const fps = Number(new URL(url, `http://localhost:${WEB_PORT}`).searchParams.get("fps")) || 20;
+        void (async () => {
+            await detectDisplay();
+            const L = startLive(fps);
+            if (!L) {
+                sendJson(res, 501, { error: "ffmpeg not installed", installHint: ffmpegInstallHint() });
+                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;
+    }
+    if (url === "/screen/record/start" && req.method === "POST") {
+        if (!hasScreenConsent()) {
+            sendJson(res, 403, { error: "screen consent required" });
+            return;
+        }
+        void (async () => {
+            await detectDisplay();
+            if (!startLive(20)) {
+                sendJson(res, 501, { error: "ffmpeg not installed", installHint: ffmpegInstallHint() });
+                return;
+            }
+            const p = startRecording();
+            sendJson(res, 200, { ok: p !== null, file: p ? path.basename(p) : null });
+        })();
+        return;
+    }
+    if (url === "/screen/record/stop" && req.method === "POST") {
+        void (async () => {
+            const p = await stopRecording();
+            const file = p ? path.basename(p) : null;
+            let sizeBytes = 0;
+            if (p) {
+                try {
+                    sizeBytes = fs.statSync(p).size;
+                }
+                catch {
+                    sizeBytes = 0;
+                }
+            }
+            sendJson(res, 200, {
+                ok: true,
+                file,
+                sizeBytes,
+                download: file ? "/screen/download?f=" + encodeURIComponent(file) : null,
+            });
+        })();
+        return;
+    }
+    if (url.startsWith("/screen/download")) {
+        // A recording is device-screen content, so gate download on consent too — a fresh
+        // (unconsented) process must not serve a prior session's screen recording.
+        if (!hasScreenConsent()) {
+            sendJson(res, 403, { error: "screen consent required" });
+            return;
+        }
+        const f = new URL(url, `http://localhost:${WEB_PORT}`).searchParams.get("f") ?? "";
+        const p = recordingPath(f);
+        if (!p) {
+            res.writeHead(404);
+            res.end("Not found");
+            return;
+        }
+        res.writeHead(200, {
+            "Content-Type": "video/mp4",
+            "Content-Disposition": `attachment; filename="${path.basename(p)}"`,
+        });
+        fs.createReadStream(p).pipe(res);
+        return;
+    }
+    if (url === "/screen/redetect") {
+        resetScreenState();
+        void detectDisplay().then(() => sendJson(res, 200, { display: displayNote() }));
+        return;
+    }
+    res.writeHead(404);
+    res.end("Not found");
+}
+// Logcat line parsing for the host-side log merge. Format:
+// "MM-DD HH:MM:SS.mmm  PID  TID  L Tag: message"
+const LOG_LINE_RE = /^(\d\d-\d\d \d\d:\d\d:\d\d\.\d+)\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+([^:]*?):\s?(.*)$/;
+const LOG_LEVELS = {
+    V: "VERBOSE",
+    D: "DEBUG",
+    I: "INFO",
+    W: "WARN",
+    E: "ERROR",
+    F: "FATAL",
+};
+// A logcat line carries a PID, not a package, but the dashboard filters logs by
+// package (e.g. "Slack app only"). Resolve PID -> process name from
+// `adb shell ps -A -o PID,NAME`, cached and refreshed on a miss (rate-limited), so
+// log rows get a readable `package` and the package filter works. Without this the
+// Live/Logs presets (match {package: ...}) drop every log line.
+const pidToPackage = new Map();
+let pidRefreshing = false;
+let lastPidRefresh = 0;
+function refreshPidMap() {
+    if (pidRefreshing)
+        return;
+    const adb = resolveAdbPath();
+    if (!adb)
+        return;
+    pidRefreshing = true;
+    lastPidRefresh = Date.now();
+    const ps = spawn(adb, ["shell", "ps", "-A", "-o", "PID,NAME"]);
+    let out = "";
+    ps.stdout?.on("data", (c) => (out += c.toString()));
+    ps.on("error", () => {
+        pidRefreshing = false;
+    });
+    ps.on("close", () => {
+        pidRefreshing = false;
+        for (const line of out.split("\n")) {
+            const m = line.trim().match(/^(\d+)\s+(\S+)$/);
+            if (m)
+                pidToPackage.set(Number(m[1]), m[2]);
+        }
+    });
+}
+function packageForPid(pid) {
+    const hit = pidToPackage.get(pid);
+    if (hit)
+        return hit;
+    // Unknown pid: trigger a rate-limited refresh so the NEXT line resolves.
+    if (Date.now() - lastPidRefresh > 3000)
+        refreshPidMap();
+    return undefined;
+}
+let logIdSeq = 0;
+/**
+ * Parse one `adb logcat -v threadtime` line into a structured event, or null if it does
+ * not match the format. `resolvePkg` maps a pid to its package name (defaults to the
+ * live adb-backed resolver); injectable so this stays a pure, unit-testable function.
+ * Exported for tests.
+ */
+export function parseLogcat(line, resolvePkg = packageForPid) {
+    const m = line.match(LOG_LINE_RE);
+    if (!m)
+        return null;
+    const [, ts, pid, tid, level, tag, message] = m;
+    const pidN = Number(pid);
+    return {
+        id: ++logIdSeq,
+        timestamp: Date.now(),
+        log_ts: ts,
+        pid: pidN,
+        tid: Number(tid),
+        level: LOG_LEVELS[level] ?? level,
+        tag: tag.trim(),
+        message,
+        package: resolvePkg(pidN),
+    };
+}
+/**
+ * Self-healing SSE proxy. Keeps ONE long-lived response open to the browser and
+ * internally (re)connects to the device `/api/stream` every couple seconds while
+ * it is down, so the browser's EventSource never sees a close and never gives up.
+ * Every other retry it rebuilds the adb forward (the real cause of recurring
+ * "unreachable"), reusing AndroidTransport rather than shelling adb directly.
+ *
+ * When the active spec wants logs (source "log" or "all"), the handler subscribes
+ * to the shared session-long logSession: it is first replayed the entire retained
+ * ring buffer (so a tab switch shows full history), then receives live lines as
+ * they arrive. The logcat process itself is persistent and shared across all
+ * /stream clients, so tab switches never drop history AND the active tab keeps
+ * streaming live. The adb binary is resolved via resolveAdbPath() so GUI launchers
+ * without the user's PATH still work.
+ */
+function handleStream(req, res) {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    let upstream = null;
+    let closed = false;
+    let lastState = "";
+    const announce = (state, msg) => {
+        if (state === lastState)
+            return;
+        lastState = state;
+        res.write(`data: ${JSON.stringify({ type: "_status", event: { state, msg } })}\n\n`);
+    };
+    // Keep the persistent logcat capture armed for the life of this connection.
+    // start() is idempotent, so it is safe to call both on initial setup and from
+    // the device-proxy reconnect path: when the device sleeps/unplugs, `adb logcat`
+    // exits and LogSession clears its child, and without a re-arm the live log feed
+    // would stay dead (until a tab switch) while network/rtm/clog self-heal via the
+    // proxy retry loop. Calling this on reconnect heals logs on the same path.
+    const spec = loadSpec();
+    const wantsLogs = spec.source === "log" || spec.source === "all";
+    const armLogcat = () => {
+        if (!wantsLogs || closed)
+            return;
+        const ok = logSession.start();
+        if (!ok) {
+            // Spawn failed (e.g. no adb on PATH). The capture is a named session-scoped
+            // thing now, so surface the reason rather than showing silent emptiness.
+            announce("waiting", "device logs unavailable (adb not found?)");
+        }
+    };
+    let retries = 0;
+    // One scheduled reconnect per attempt. up.on("end"), up.on("error"), and
+    // upstream.on("error") can all fire for the same attempt; without this guard each
+    // would schedule its own connect(), fanning out duplicate streams (and re-spawning
+    // logcat on the rebuild path). Reset at the top of connect() so the next attempt
+    // can retry again.
+    let settled = false;
+    const retry = () => {
+        if (closed)
+            return;
+        if (settled)
+            return;
+        settled = true;
+        retries++;
+        // Every other retry, rebuild a clean forward before reconnecting. resetState()
+        // drops the cached forward flag so ensureForward() actually re-runs adb forward.
+        if (retries % 2 === 0) {
+            transport.resetState();
+            transport.ensureForward();
+            setTimeout(connect, 1500);
+        }
+        else {
+            setTimeout(connect, 2000);
+        }
+    };
+    const connect = () => {
+        if (closed)
+            return;
+        settled = false;
+        upstream = http.request({
+            host: RADAR_HOST,
+            port: RADAR_PORT,
+            path: "/api/stream",
+            method: "GET",
+        }, (up) => {
+            announce("connected", "device stream connected");
+            // Re-arm logs on the same path the device proxy heals on: if the device
+            // dropped and came back, `adb logcat` had exited; restart it (idempotent)
+            // so the live log feed resumes without needing a browser reconnect.
+            armLogcat();
+            up.on("data", (c) => res.write(c));
+            up.on("end", () => {
+                announce("waiting", "device stream ended, retrying…");
+                retry();
+            });
+            up.on("error", () => {
+                announce("waiting", "device stream error, retrying…");
+                retry();
+            });
+        });
+        upstream.on("error", () => {
+            announce("waiting", "device unreachable, retrying…");
+            retry();
+        });
+        upstream.end();
+    };
+    connect();
+    const heartbeat = setInterval(() => {
+        if (!closed)
+            res.write(": hb\n\n");
+    }, 15000);
+    // Host-side logcat merge for log/all sources. Subscribe to the shared,
+    // session-long logSession: it replays the full retained ring buffer to this
+    // connection first (so a tab switch shows complete history), then delivers
+    // live lines. Both replayed and live frames are written to THIS response, so
+    // the tab you are watching keeps streaming in real time. The logcat process
+    // is persistent and shared, so a tab switch only adds/removes a listener — it
+    // never tears down the capture or loses lines in a reconnect gap.
+    let unsubscribeLogs = null;
+    if (wantsLogs) {
+        refreshPidMap(); // warm PID->package so the first log rows resolve their app
+        armLogcat(); // idempotent start; surfaces a status frame if spawn fails
+        unsubscribeLogs = logSession.subscribe((ev, replay) => {
+            if (closed)
+                return;
+            // Backpressure guard: if this client is slow or its tab is backgrounded
+            // (an EventSource stays subscribed when backgrounded), res.write() queues
+            // unwritten bytes in Node's writable buffer without bound. The ring is
+            // bounded but that per-connection buffer is not, so a stalled consumer
+            // would grow host memory for the whole (now persistent) session. When the
+            // socket buffer is already deep, DROP this frame rather than buffer it —
+            // the client replays the full ring on its next reconnect and catches up.
+            //
+            // EXEMPT replay: the replay burst is a bounded one-time send of the whole
+            // ring (~10 MB worst case at the 20000-frame cap) and IS the connection's
+            // purpose. It runs synchronously oldest->newest, so the I/O phase cannot
+            // drain between writes and writableLength climbs monotonically; gating it
+            // on the 4 MB cap would silently drop the NEWEST history past ~4 MB and
+            // reintroduce the very "log count shrinks on reconnect" loss this feature
+            // fixes. The guard is only meant for the unbounded LIVE queue.
+            if (shouldDropLogFrame(replay, res.writableLength))
+                return;
+            // Tag replayed history with replay:true so the client counts it as history
+            // (live=false) and does NOT fire alerts on it. The client's own cache is
+            // capped (count + TTL) while the server ring is larger, so on a long
+            // session the client can evict frames the ring still holds; without this
+            // flag those replayed-on-reconnect frames would look new and re-fire
+            // `alert {at:N}` and re-count. The flag makes replay alert-safe regardless.
+            const frame = replay
+                ? { type: "log", event: ev, replay: true }
+                : { type: "log", event: ev };
+            res.write(`data: ${JSON.stringify(frame)}\n\n`);
+        });
+    }
+    req.on("close", () => {
+        closed = true;
+        clearInterval(heartbeat);
+        if (unsubscribeLogs)
+            unsubscribeLogs(); // detach listener; capture stays up
+        try {
+            upstream?.destroy();
+        }
+        catch {
+            // already torn down
+        }
+    });
+}
 function listProfiles(res) {
     const profiles = transport.listProfiles();
     const activeUserId = transport.getActiveUserId();
-    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify({ profiles, active_user_id: activeUserId }));
+    sendJson(res, 200, { profiles, active_user_id: activeUserId });
 }
 function activateRadar(res, userId) {
     // Reset cached state so ensureForward() re-runs adb forward. This handles
@@ -53,11 +925,10 @@ function activateRadar(res, userId) {
     transport.resetState();
     const forwarded = transport.ensureForward();
     if (!forwarded) {
-        res.writeHead(502, { "Content-Type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify({
+        sendJson(res, 502, {
             ok: false,
             error: "ADB forward failed. Is a device connected?",
-        }));
+        });
         return;
     }
     try {
@@ -69,15 +940,16 @@ function activateRadar(res, userId) {
         }
     }
     catch (e) {
-        res.writeHead(502, { "Content-Type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify({
+        sendJson(res, 502, {
             ok: false,
             error: `Broadcast failed: ${e.message}. Debug build not running?`,
-        }));
+        });
         return;
     }
-    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify({ ok: true, user_id: userId ?? transport.getActiveUserId() ?? "auto" }));
+    sendJson(res, 200, {
+        ok: true,
+        user_id: userId ?? transport.getActiveUserId() ?? "auto",
+    });
 }
 function proxyToRadar(req, res) {
     const upstream = http.request({