@slack/radar-mcp 1.4.0 → 1.6.0

package/dist/web/server.js

@@ -5,11 +5,37 @@ import path from "path";
 import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 import { AndroidTransport, resolveAdbPath } from "../shared/android.js";
-import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT } from "../shared/constants.js";
+import { RADAR_HOST, RADAR_PORT, RADAR_VERSION, 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, refreshScreenCapabilities, 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 ?? 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
@@ -19,6 +45,26 @@ const INDEX_PATH = path.join(__dirname, "public", "index.html");
 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 });
@@ -58,15 +104,56 @@ function initialSpec() {
         return BLANK_SPEC;
     }
 }
-writeSpec(initialSpec());
+/**
+ * Write the starting spec for a server that is taking ownership of this port. MUST be
+ * called only AFTER a successful listen() bind, never at module load: importing this
+ * module (which bin.ts does before it knows whether the port is free) must not touch
+ * the shared spec file, or a second launcher would wipe the spec of the dashboard that
+ * already owns the port. The post-bind caller is the sole legitimate writer.
+ */
+export function seedInitialSpec() {
+    writeSpec(initialSpec());
+}
+// Initialize the database path with the web server port, so concurrent dashboards on
+// different ports do not collide in tmpdir. This only COMPUTES a path string (no filesystem
+// write), so it is safe to run at module load even for a launcher that loses the port bind.
+initializeDatabasePath(WEB_PORT);
+/**
+ * Wipe stale pulled-DB copies and arm the cleanup-on-exit handlers for THIS process. MUST be
+ * called only AFTER a successful listen() bind, never at module load: the pulled-DB tmp dir is
+ * scoped by WEB_PORT, so it is SHARED by every launcher that imports this module on the same
+ * port. A second launcher that loses the bind must not rmSync that dir, or it wipes the
+ * running dashboard's pulled-DB cache and breaks its open DB-browser tab until it re-pulls.
+ * Same post-bind discipline as seedInitialSpec: the port owner is the sole legitimate writer.
+ */
+export function cleanupOnBind() {
+    // Pulled DB copies are plaintext message stores; never let them linger across runs.
+    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) => {
         const url = req.url ?? "";
-        if (url === "/" || url === "/index.html") {
+        const urlPath = url.split("?")[0];
+        if (urlPath === "/" || urlPath === "/index.html") {
             serveIndex(res);
             return;
         }
+        // Dashboard client modules (vendor/, next/). GET serves the body; HEAD serves headers
+        // only (a proxy/cache validator hitting a real asset should not get a 404).
+        const inm = req.headers["if-none-match"];
+        if ((req.method === "GET" || req.method === "HEAD") && serveStatic(urlPath, res, req.method === "HEAD", Array.isArray(inm) ? inm[0] : inm)) {
+            return;
+        }
         if (url === "/spec" && req.method === "GET") {
+            // Version marker for a second launcher's adopt path: it can compare this against its own
+            // RADAR_VERSION and warn on a mismatch (it still adopts; it never kills the holder).
+            // A header, not a body field, so the /spec fingerprint and the client's change-detection
+            // key (JSON.stringify of the body) stay byte-identical.
+            res.setHeader("X-Radar-Version", RADAR_VERSION);
             sendJson(res, 200, loadSpec());
             return;
         }
@@ -94,6 +181,18 @@ export function createServer() {
             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;
@@ -104,6 +203,10 @@ export function createServer() {
             activateRadar(res, userId);
             return;
         }
+        if (url.startsWith("/screen/")) {
+            handleScreen(req, res);
+            return;
+        }
         if (url.startsWith("/api/")) {
             proxyToRadar(req, res);
             return;
@@ -124,6 +227,88 @@ function serveIndex(res) {
         res.end(`Failed to read ${INDEX_PATH}: ${e.message}`);
     }
 }
+// Static assets for the dashboard client. The dashboard was historically one
+// self-contained index.html; the UI is being migrated to Preact components (container by
+// container), which the browser fetches as ES modules over HTTP. This serves only the
+// vendored runtime (vendor/) and the UI modules (next/): locked to those two dirs, .js
+// only, no path traversal, from the known public root. The listener is already
+// loopback-only (bin.ts), so this adds no network exposure.
+const PUBLIC_DIR = path.join(__dirname, "public");
+// vendor/ exists today; next/ is populated by the in-progress Preact UI migration (the very
+// next PRs). Keeping it here now means those module fetches resolve the moment they land; until
+// then a /next/* request is a harmless 404 (the dir does not exist, readFileSync misses).
+const STATIC_DIRS = ["vendor", "next"];
+// Canonicalized public root, resolved once at module load. The realpath containment check
+// below compares a resolved file path against this; if we compared against the raw PUBLIC_DIR
+// while the install prefix itself is a symlink (a global npm prefix, or macOS /tmp ->
+// /private/tmp), realpathSync(full) would resolve the prefix too and never start with the
+// un-resolved PUBLIC_DIR, so EVERY legitimate module would 403 and the UI would silently fail
+// to load. Resolve the root the same way so the comparison is apples-to-apples. Falls back to
+// PUBLIC_DIR if the dir does not exist yet (e.g. a build without vendored assets).
+const PUBLIC_REAL = (() => {
+    try {
+        return fs.realpathSync(PUBLIC_DIR);
+    }
+    catch {
+        return PUBLIC_DIR;
+    }
+})();
+// Cache policy for vendored modules: revalidate every time (no-cache), but serve a cheap 304
+// when the file is unchanged via an ETag derived from its size+mtime. This cuts redundant
+// transfers WITHOUT the stale-after-upgrade footgun a plain max-age would create: the module
+// URLs are version-less and have no content hash, so an npm upgrade that swaps vendor/ would
+// otherwise serve stale JS from a long-lived cache for up to the max-age window.
+// `clean` is the already-query-stripped request path. `isHead` sends headers with no body.
+function serveStatic(clean, res, isHead, ifNoneMatch) {
+    const top = clean.split("/")[1];
+    if (!STATIC_DIRS.includes(top))
+        return false;
+    if (!clean.endsWith(".js"))
+        return false; // only JS modules; no arbitrary file types
+    const full = path.normalize(path.join(PUBLIC_DIR, clean));
+    // Lexical containment: the normalized path must stay under PUBLIC_DIR (defeats ../).
+    if (full !== PUBLIC_DIR && !full.startsWith(PUBLIC_DIR + path.sep)) {
+        res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("forbidden");
+        return true;
+    }
+    try {
+        // path.normalize is lexical only; a symlink inside vendor/ could still point outside the
+        // root. Resolve the real path and re-check containment against the canonicalized root
+        // (PUBLIC_REAL, not the raw PUBLIC_DIR) before reading.
+        const real = fs.realpathSync(full);
+        if (real !== PUBLIC_REAL && !real.startsWith(PUBLIC_REAL + path.sep)) {
+            res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("forbidden");
+            return true;
+        }
+        // Weak ETag from size + mtime: changes whenever the file is rebuilt/upgraded, so a stale
+        // browser copy revalidates to a fresh body instead of being served from cache.
+        const st = fs.statSync(real);
+        const etag = `W/"${st.size.toString(16)}-${Math.round(st.mtimeMs).toString(16)}"`;
+        if (ifNoneMatch === etag) {
+            res.writeHead(304, { ETag: etag, "Cache-Control": "no-cache" });
+            res.end();
+            return true;
+        }
+        const body = fs.readFileSync(real);
+        // Set Content-Length explicitly so a HEAD mirrors the GET's framing (RFC 7230): a
+        // cache validator doing HEAD gets the size, and GET returns a real length not chunked.
+        // no-cache = always revalidate (cheap 304 above); never serve a stale module after upgrade.
+        res.writeHead(200, {
+            "Content-Type": "text/javascript; charset=utf-8",
+            "Content-Length": body.length,
+            "Cache-Control": "no-cache",
+            ETag: etag,
+        });
+        res.end(isHead ? undefined : body);
+    }
+    catch {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("not found");
+    }
+    return true;
+}
 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
@@ -177,6 +362,25 @@ async function handleSetSpec(req, res) {
  * 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;
+    // The bound profile, read from the device ping body. This is the TRUTH about which
+    // profile owns the socket (the app that bound first), unlike the host-side activate
+    // guess in getActiveUserId() which can drift. The dashboard shows this so it never
+    // claims a profile you are not actually seeing.
+    const reply = (device, boundUserId, boundProfile) => {
+        if (replied)
+            return;
+        replied = true;
+        sendJson(res, 200, {
+            device,
+            screen: screenCapabilities(),
+            boundUserId: boundUserId ?? null,
+            boundProfile: boundProfile ?? null,
+        });
+    };
     const probe = http.request({
         host: RADAR_HOST,
         port: RADAR_PORT,
@@ -184,13 +388,44 @@ function handleHealth(res) {
         method: "GET",
         timeout: 2500,
     }, (up) => {
-        up.resume();
-        up.on("end", () => sendJson(res, 200, { device: up.statusCode === 200 }));
+        // The ping body is the device's own small JSON status. Bound the accumulation anyway so
+        // a misbehaving/compromised local endpoint cannot grow it without limit (matches the
+        // bounded-read posture elsewhere in this file). 64KB is far above any real ping body;
+        // once tripped we stop appending and parse what we have (a truncated body simply fails
+        // the JSON.parse below and falls back to no bound profile, which is the safe default).
+        const MAX_PING_BODY = 64 * 1024;
+        let body = "";
+        up.on("data", (c) => {
+            if (body.length < MAX_PING_BODY)
+                body += c;
+        });
+        up.on("end", () => {
+            const ok = up.statusCode === 200;
+            let uid = null;
+            let profile = null;
+            // Only trust the body on a 200. A device 5xx-ing with a stale ping body must NOT
+            // surface a bound profile while device:false — that would let the dashboard show a
+            // confident profile label for an unhealthy device.
+            if (ok) {
+                try {
+                    const p = JSON.parse(body);
+                    if (p.android_user_id != null)
+                        uid = String(p.android_user_id);
+                    if (typeof p.profile === "string")
+                        profile = p.profile;
+                }
+                catch {
+                    // non-JSON / partial body: device is up but we cannot name the profile
+                }
+            }
+            reply(ok, uid, profile);
+        });
+        up.on("error", () => reply(false));
     });
-    probe.on("error", () => sendJson(res, 200, { device: false }));
+    probe.on("error", () => reply(false));
     probe.on("timeout", () => {
         probe.destroy();
-        sendJson(res, 200, { device: false });
+        reply(false);
     });
     probe.end();
 }
@@ -202,6 +437,10 @@ function handleHealth(res) {
  */
 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;
@@ -221,7 +460,15 @@ function handleEnable(res) {
         });
         return;
     }
-    // Verify by pinging the device the same way /health does.
+    // 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,
@@ -230,12 +477,13 @@ function handleEnable(res) {
         timeout: 2500,
     }, (up) => {
         up.resume();
-        up.on("end", () => sendJson(res, 200, { enabled: up.statusCode === 200 }));
+        up.on("end", () => reply(up.statusCode === 200));
+        up.on("error", () => reply(false));
     });
-    probe.on("error", () => sendJson(res, 200, { enabled: false }));
+    probe.on("error", () => reply(false));
     probe.on("timeout", () => {
         probe.destroy();
-        sendJson(res, 200, { enabled: false });
+        reply(false);
     });
     probe.end();
 }
@@ -354,6 +602,249 @@ function handleDetail(req, res) {
     });
     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.
+    // ?refresh=1 re-probes ffmpeg/scrcpy (asynchronously, so it never blocks the event
+    // loop / live stream) before reading, so a user who installs ffmpeg then reopens the
+    // overlay is detected without a server restart. Without refresh it reads the cache.
+    if (url.startsWith("/screen/caps")) {
+        const refresh = new URL(url, "http://localhost").searchParams.get("refresh") === "1";
+        if (refresh) {
+            void (async () => {
+                // refreshScreenCapabilities cannot throw today, but a future edit that lets a rejection
+                // escape would leave this request hanging until the client's 3s timeout. Guard it: on a
+                // failed re-probe, still answer with the (cached) capabilities rather than nothing.
+                try {
+                    await refreshScreenCapabilities();
+                }
+                catch {
+                    // fall through to the cached capabilities below
+                }
+                sendJson(res, 200, { ...screenCapabilities(), consent: hasScreenConsent() });
+            })();
+        }
+        else {
+            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?(.*)$/;
@@ -437,10 +928,13 @@ export function parseLogcat(line, resolvePkg = packageForPid) {
  * 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"), it also spawns a
- * host-side `adb logcat -v threadtime -T 1` and merges parsed lines as
- * `type: "log"` frames. The adb binary is resolved via resolveAdbPath() so GUI
- * launchers without the user's PATH still work.
+ * 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, {
@@ -457,6 +951,24 @@ function handleStream(req, res) {
         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
@@ -493,6 +1005,10 @@ function handleStream(req, res) {
             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…");
@@ -514,53 +1030,60 @@ function handleStream(req, res) {
         if (!closed)
             res.write(": hb\n\n");
     }, 15000);
-    // Host-side logcat merge for log/all sources. -T 1 streams only NEW lines;
-    // without it logcat replays the entire existing buffer on connect and floods
-    // the browser.
-    let logcat = null;
-    const spec = loadSpec();
-    const wantsLogs = spec.source === "log" || spec.source === "all";
-    const adb = resolveAdbPath();
-    if (wantsLogs && adb) {
-        try {
-            refreshPidMap(); // warm PID->package so the first log rows resolve their app
-            logcat = spawn(adb, ["logcat", "-v", "threadtime", "-T", "1"], {
-                stdio: ["ignore", "pipe", "ignore"],
-            });
-            let lineBuf = "";
-            logcat.stdout?.on("data", (c) => {
-                lineBuf += c.toString();
-                let nl;
-                while ((nl = lineBuf.indexOf("\n")) >= 0) {
-                    const line = lineBuf.slice(0, nl);
-                    lineBuf = lineBuf.slice(nl + 1);
-                    const ev = parseLogcat(line);
-                    if (ev && !closed) {
-                        res.write(`data: ${JSON.stringify({ type: "log", event: ev })}\n\n`);
-                    }
-                }
-            });
-            logcat.on("error", () => { });
-        }
-        catch {
-            logcat = null;
-        }
+    // 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
         }
-        try {
-            logcat?.kill();
-        }
-        catch {
-            // already dead
-        }
     });
 }
 function listProfiles(res) {