@slack/radar-mcp 1.5.0 → 1.6.0

package/dist/shared/debug-log.d.ts

@@ -0,0 +1,50 @@
+/**
+ * On-device app log buffer reader (host-side, read-only).
+ *
+ * The Slack app plants a Timber tree (`DebugMenuLoggingTree`) on debug builds that
+ * captures every DEBUG-and-above log line into a rolling on-disk buffer
+ * (`slack.commons.logger.DebugLogger`): six files `debug.log0`..`debug.log5` in the
+ * app sandbox `files/` dir, ~256KB each. `debug.log0` is the newest file; on rotation
+ * files shift up and the oldest is dropped. Within a file, the oldest line is at the top.
+ * Each line is formatted `[timestamp] TAG : message` with NO logcat column padding.
+ *
+ * This is the app's own structured log buffer, which is strictly better than scraping
+ * `adb logcat`: it survives the radar enable/disable cycle, is not subject to the device
+ * logcat ring being evicted, and carries the exact tag the app logged with. We read it the
+ * same way the DB browser reads the message store: `adb exec-out "run-as <pkg> cat ..."`,
+ * which works because debug builds are `run-as`-able. Nothing is written on the device.
+ *
+ * SECURITY: app logs can contain user/channel IDs and message fragments. This reader only
+ * returns lines to the caller (no host-side file is written), and the tag/grep filter is
+ * applied before return.
+ */
+/**
+ * Build the oldest-to-newest list of sandbox-relative log file paths. DebugLogger keeps
+ * `debug.log0` newest, so chronological order is log5, log4, ..., log0.
+ */
+export declare function debugLogFileOrder(count?: number): string[];
+/**
+ * Concatenate raw file contents (passed oldest-file-first) into a single chronological
+ * line array. Each file is already oldest-line-first, so a flat concat preserves order.
+ * Blank lines are dropped. Pure: no device access, unit-testable against fixtures.
+ */
+export declare function flattenDebugLogFiles(contentsOldestFirst: string[]): string[];
+/**
+ * A `run-as` denial does NOT fail the adb command: `adb exec-out` exits 0 and the helper's
+ * error ("run-as: unknown package: ...", "run-as: ... not debuggable", "run-as: couldn't
+ * stat ...") is written to stdout, where it would otherwise be mistaken for a log line.
+ * So failure must be detected by inspecting the output, not by catching an exception. This
+ * returns the run-as error message when the output is a denial, else null. Pure and testable.
+ */
+export declare function detectRunAsError(output: string): string | null;
+/**
+ * Read the app's DebugLogger buffer off the device via `run-as` and return its lines in
+ * chronological order (oldest first). Returns null when the buffer cannot be read so the
+ * caller can fall back to a logcat snapshot. Two distinct null cases, deliberately kept
+ * apart: a `run-as` failure (no device, the debug build is not installed, or it is not
+ * debuggable on this profile) is a condition the user likely wants to know about, so it is
+ * logged to stderr before falling back; an empty buffer (debug build present, nothing logged
+ * yet) is benign and silent. A specific `user` (Android multi-user id) is forwarded to
+ * run-as when provided.
+ */
+export declare function readDebugLogBuffer(adbPath: string, user?: string): string[] | null;

package/dist/shared/debug-log.js

@@ -0,0 +1,108 @@
+/**
+ * On-device app log buffer reader (host-side, read-only).
+ *
+ * The Slack app plants a Timber tree (`DebugMenuLoggingTree`) on debug builds that
+ * captures every DEBUG-and-above log line into a rolling on-disk buffer
+ * (`slack.commons.logger.DebugLogger`): six files `debug.log0`..`debug.log5` in the
+ * app sandbox `files/` dir, ~256KB each. `debug.log0` is the newest file; on rotation
+ * files shift up and the oldest is dropped. Within a file, the oldest line is at the top.
+ * Each line is formatted `[timestamp] TAG : message` with NO logcat column padding.
+ *
+ * This is the app's own structured log buffer, which is strictly better than scraping
+ * `adb logcat`: it survives the radar enable/disable cycle, is not subject to the device
+ * logcat ring being evicted, and carries the exact tag the app logged with. We read it the
+ * same way the DB browser reads the message store: `adb exec-out "run-as <pkg> cat ..."`,
+ * which works because debug builds are `run-as`-able. Nothing is written on the device.
+ *
+ * SECURITY: app logs can contain user/channel IDs and message fragments. This reader only
+ * returns lines to the caller (no host-side file is written), and the tag/grep filter is
+ * applied before return.
+ */
+import { execFileSync } from "child_process";
+import { SLACK_DEBUG_PKG } from "./constants.js";
+/** The debug build whose sandbox we can `run-as` into. */
+const LOG_PKG = SLACK_DEBUG_PKG;
+/** Number of rolling log files DebugLogger maintains (debug.log0..debug.log5). */
+const LOG_FILE_COUNT = 6;
+const ADB_MAX_BUFFER = 16 * 1024 * 1024; // total buffer is ~1.5MB; headroom for safety.
+/**
+ * Build the oldest-to-newest list of sandbox-relative log file paths. DebugLogger keeps
+ * `debug.log0` newest, so chronological order is log5, log4, ..., log0.
+ */
+export function debugLogFileOrder(count = LOG_FILE_COUNT) {
+    const files = [];
+    for (let i = count - 1; i >= 0; i--)
+        files.push(`files/debug.log${i}`);
+    return files;
+}
+/**
+ * Concatenate raw file contents (passed oldest-file-first) into a single chronological
+ * line array. Each file is already oldest-line-first, so a flat concat preserves order.
+ * Blank lines are dropped. Pure: no device access, unit-testable against fixtures.
+ */
+export function flattenDebugLogFiles(contentsOldestFirst) {
+    return contentsOldestFirst
+        .join("\n")
+        .split("\n")
+        .filter((line) => line.length > 0);
+}
+/**
+ * A `run-as` denial does NOT fail the adb command: `adb exec-out` exits 0 and the helper's
+ * error ("run-as: unknown package: ...", "run-as: ... not debuggable", "run-as: couldn't
+ * stat ...") is written to stdout, where it would otherwise be mistaken for a log line.
+ * So failure must be detected by inspecting the output, not by catching an exception. This
+ * returns the run-as error message when the output is a denial, else null. Pure and testable.
+ */
+export function detectRunAsError(output) {
+    const first = output.trimStart().split("\n")[0] ?? "";
+    return first.startsWith("run-as:") ? first.trim() : null;
+}
+/**
+ * Read the app's DebugLogger buffer off the device via `run-as` and return its lines in
+ * chronological order (oldest first). Returns null when the buffer cannot be read so the
+ * caller can fall back to a logcat snapshot. Two distinct null cases, deliberately kept
+ * apart: a `run-as` failure (no device, the debug build is not installed, or it is not
+ * debuggable on this profile) is a condition the user likely wants to know about, so it is
+ * logged to stderr before falling back; an empty buffer (debug build present, nothing logged
+ * yet) is benign and silent. A specific `user` (Android multi-user id) is forwarded to
+ * run-as when provided.
+ */
+export function readDebugLogBuffer(adbPath, user) {
+    const catList = debugLogFileOrder().join(" ");
+    // One run-as invocation with the given user flag; cats every file oldest-first. Missing files
+    // are tolerated (2>/dev/null) so a not-yet-rotated buffer with only debug.log0 reads cleanly.
+    // Returns the raw stdout, or an Error if adb itself failed (distinct from a run-as denial,
+    // which exits 0 with the helper error in stdout).
+    const runAs = (userFlag) => {
+        try {
+            return execFileSync(adbPath, ["exec-out", `run-as ${LOG_PKG} ${userFlag}sh -c 'cat ${catList} 2>/dev/null'`], { timeout: 10000, maxBuffer: ADB_MAX_BUFFER, encoding: "utf-8" });
+        }
+        catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+        }
+    };
+    let output = runAs(user ? `--user ${user} ` : "");
+    if (output instanceof Error) {
+        // adb itself failed (no device, adb not running). Surface and fall back.
+        console.error(`[slack-radar] app log buffer unavailable (adb error: ${output.message.split("\n")[0]}); falling back to logcat`);
+        return null;
+    }
+    // run-as denial: adb exited 0 but the helper error is in stdout. On old adb the `--user N`
+    // form can be the denial while the no-flag form works (db.ts resolves users with the same
+    // no-flag fallback). So before giving up to logcat, retry once with no user flag — but only
+    // when a flag was actually used, else we would just repeat the identical call.
+    let runAsError = detectRunAsError(output);
+    if (runAsError && user) {
+        const retry = runAs("");
+        if (!(retry instanceof Error) && !detectRunAsError(retry)) {
+            output = retry;
+            runAsError = null;
+        }
+    }
+    if (runAsError) {
+        console.error(`[slack-radar] app log buffer unavailable (${runAsError}); falling back to logcat`);
+        return null;
+    }
+    const lines = flattenDebugLogFiles([output]);
+    return lines.length > 0 ? lines : null;
+}

package/dist/shared/screen.d.ts

@@ -49,9 +49,32 @@ export declare function cleanupRecordings(): void;
 export declare function resolveFfmpeg(): string | null;
 /** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
 export declare function hasScrcpy(): boolean;
-/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+/**
+ * Re-probe ffmpeg/scrcpy ASYNCHRONOUSLY and update the cache, so the overlay can
+ * recover after a user installs ffmpeg mid-session without restarting the server.
+ *
+ * Why async (not a force flag on the sync probes): the sync `execFileSync` probes are
+ * safe only BECAUSE they are cached and run at most once (see the same rule in db.ts).
+ * Re-running them synchronously on every panel reopen would block the single event loop
+ * (the live MJPEG stream, /health, every tab) for the spawn duration. This path uses
+ * execFile (non-blocking) instead. It also ONLY re-probes a binary that is currently
+ * cached as absent: if ffmpeg was already found there is nothing to recover, so the
+ * common case does no work.
+ */
+export declare function refreshScreenCapabilities(): Promise<void>;
+/**
+ * A single runnable command to install ffmpeg on this platform. Never run
+ * automatically. This is presented as a copy-paste command, so it must be ONE
+ * runnable line: no parentheticals or alternatives, which would error if pasted
+ * into a shell. Alternative package managers belong in surrounding prose, not here.
+ */
 export declare function ffmpegInstallHint(): string;
-/** Capability summary for /health: what the screen overlay can do on this machine. */
+/**
+ * Capability summary for /health and /screen/caps: what the screen overlay can do
+ * on this machine. Reads the cached probe result. To recover after a mid-session
+ * ffmpeg install, call refreshScreenCapabilities() first (the /screen/caps?refresh=1
+ * path does this), then read here.
+ */
 export declare function screenCapabilities(): {
     screenshot: boolean;
     liveCast: boolean;

package/dist/shared/screen.js

@@ -40,6 +40,7 @@ import { spawn, execFile, execFileSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { promisify } from "util";
 import { resolveAdbPath } from "./android.js";
 const SC_TMP = path.join(os.homedir(), ".slack-radar", "screen");
 /**
@@ -76,8 +77,10 @@ function adb() {
     return resolveAdbPath() ?? "adb";
 }
 // ---- host-binary detection (for the degrade tiers) --------------------------
+const execFileP = promisify(execFile);
 let ffmpegPath; // undefined = not probed, null = absent
 let scrcpyPresent;
+const FFMPEG_CANDIDATES = ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"];
 /** Resolve an ffmpeg binary, or null if none is installed. Cached. */
 export function resolveFfmpeg() {
     // Test hook: simulate a machine with no ffmpeg so the degrade path can be exercised
@@ -86,7 +89,7 @@ export function resolveFfmpeg() {
         return null;
     if (ffmpegPath !== undefined)
         return ffmpegPath;
-    for (const c of ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"]) {
+    for (const c of FFMPEG_CANDIDATES) {
         try {
             execFileSync(c, ["-version"], { timeout: 3000, stdio: "ignore" });
             ffmpegPath = c;
@@ -112,18 +115,72 @@ export function hasScrcpy() {
     }
     return scrcpyPresent;
 }
-/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+/**
+ * Re-probe ffmpeg/scrcpy ASYNCHRONOUSLY and update the cache, so the overlay can
+ * recover after a user installs ffmpeg mid-session without restarting the server.
+ *
+ * Why async (not a force flag on the sync probes): the sync `execFileSync` probes are
+ * safe only BECAUSE they are cached and run at most once (see the same rule in db.ts).
+ * Re-running them synchronously on every panel reopen would block the single event loop
+ * (the live MJPEG stream, /health, every tab) for the spawn duration. This path uses
+ * execFile (non-blocking) instead. It also ONLY re-probes a binary that is currently
+ * cached as absent: if ffmpeg was already found there is nothing to recover, so the
+ * common case does no work.
+ */
+export async function refreshScreenCapabilities() {
+    if (process.env.SLACK_RADAR_NO_FFMPEG === "1") {
+        ffmpegPath = null;
+    }
+    else if (ffmpegPath === undefined || ffmpegPath === null) {
+        // Not yet probed, or last probe found nothing: (re-)check now. Probe into a local
+        // and assign the cache only once, at the end, so a concurrent reader (a second tab,
+        // /health) keeps seeing the prior value during the probe instead of a transient
+        // null. Recovery only moves absent -> present, never the reverse.
+        let found = null;
+        for (const c of FFMPEG_CANDIDATES) {
+            try {
+                await execFileP(c, ["-version"], { timeout: 3000 });
+                found = c;
+                break;
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        ffmpegPath = found;
+    }
+    if (scrcpyPresent === undefined || scrcpyPresent === false) {
+        try {
+            await execFileP("scrcpy", ["--version"], { timeout: 3000 });
+            scrcpyPresent = true;
+        }
+        catch {
+            scrcpyPresent = false;
+        }
+    }
+}
+/**
+ * A single runnable command to install ffmpeg on this platform. Never run
+ * automatically. This is presented as a copy-paste command, so it must be ONE
+ * runnable line: no parentheticals or alternatives, which would error if pasted
+ * into a shell. Alternative package managers belong in surrounding prose, not here.
+ */
 export function ffmpegInstallHint() {
     switch (process.platform) {
         case "darwin":
             return "brew install ffmpeg";
         case "win32":
-            return "winget install ffmpeg   (or: choco install ffmpeg)";
+            return "winget install ffmpeg";
         default:
-            return "sudo apt install ffmpeg   (or your distro's package manager)";
+            return "sudo apt install ffmpeg";
     }
 }
-/** Capability summary for /health: what the screen overlay can do on this machine. */
+/**
+ * Capability summary for /health and /screen/caps: what the screen overlay can do
+ * on this machine. Reads the cached probe result. To recover after a mid-session
+ * ffmpeg install, call refreshScreenCapabilities() first (the /screen/caps?refresh=1
+ * path does this), then read here.
+ */
 export function screenCapabilities() {
     const ffmpeg = resolveFfmpeg() !== null;
     return {

package/dist/shared/transport.d.ts

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

package/dist/web/bin.d.ts

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

package/dist/web/bin.js

@@ -1,12 +1,113 @@
 #!/usr/bin/env node
 import { execSync } from "child_process";
-import { createServer, WEB_PORT } from "./server.js";
+import { realpathSync } from "fs";
+import http from "http";
+import { fileURLToPath } from "url";
+import { cleanupOnBind, createServer, seedInitialSpec, WEB_PORT } from "./server.js";
+import { RADAR_VERSION } from "../shared/constants.js";
+/**
+ * One loopback GET against the dashboard's own port, used by the adopt path. Resolves with the
+ * status, body, and headers, or null on error/timeout. Centralizes the timeout + 127.0.0.1
+ * binding the probes share (the MCP side has its own copy in mcp/index.ts; this is the web
+ * bin's). Never throws.
+ */
+function loopbackGet(path, timeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.request({ host: "127.0.0.1", port: WEB_PORT, path, method: "GET", timeout: timeoutMs }, (res) => {
+            let body = "";
+            res.on("data", (c) => (body += c));
+            res.on("end", () => resolve({ status: res.statusCode, body, headers: res.headers }));
+        });
+        req.on("error", () => resolve(null));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.end();
+    });
+}
+/**
+ * Decide whether a /spec response body identifies a Radar dashboard. A Radar /spec
+ * is always a plain object carrying a `viz` array (even a blank spec is
+ * { title, blank, viz: [] }). Requiring both excludes a foreign service that happens
+ * to 200 with arbitrary JSON (a bare array, a string, an unrelated object). Exported
+ * for unit testing. statusCode must be 200.
+ */
+export function isRadarSpecBody(statusCode, body) {
+    if (statusCode !== 200)
+        return false;
+    let spec;
+    try {
+        spec = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    // typeof [] is "object" in JS, hence the explicit Array.isArray exclusion.
+    return (spec !== null &&
+        typeof spec === "object" &&
+        !Array.isArray(spec) &&
+        Array.isArray(spec.viz));
+}
+/** Open the dashboard in the default browser. Best-effort; never throws. */
+function openBrowser(url) {
+    try {
+        if (process.platform === "darwin") {
+            execSync(`open ${url}`, { stdio: "ignore" });
+        }
+        else if (process.platform === "linux") {
+            execSync(`xdg-open ${url}`, { stdio: "ignore" });
+        }
+    }
+    catch {
+        // Browser open is best-effort
+    }
+}
+/**
+ * The port is busy. Decide whether the thing holding it is an existing Radar
+ * dashboard (adopt it: open the browser and exit cleanly) or something else
+ * (print the manual options and exit non-zero). We do NOT kill the holder:
+ * `lsof -ti :PORT` could be a browser, a teammate's server, or any unrelated
+ * process, and killing by port from a published tool is a footgun.
+ *
+ * Detection probes GET /spec on the loopback port. /spec is instant (it returns
+ * the current dashboard spec, no device round-trip) and is unique to a Radar
+ * dashboard, so a 200 with a JSON body is a reliable fingerprint. The response's
+ * X-Radar-Version header lets us notice when the running dashboard is a DIFFERENT
+ * Radar version than this launcher and say so — we still adopt it (never kill the
+ * holder), the note just explains why a feature you expect might be missing.
+ */
+function handlePortInUse() {
+    const url = `http://localhost:${WEB_PORT}`;
+    void loopbackGet("/spec", 2000).then((r) => {
+        if (r && isRadarSpecBody(r.status, r.body)) {
+            const running = r.headers["x-radar-version"];
+            if (typeof running === "string" && running !== RADAR_VERSION) {
+                console.log(`Note: the running dashboard is Radar ${running}, this launcher is ${RADAR_VERSION}. ` +
+                    `Adopting the running one as-is (it owns the port). Restart it to pick up ${RADAR_VERSION}.`);
+            }
+            console.log(`Slack Radar is already running at ${url}. Opening it.`);
+            if (!process.env.SLACK_RADAR_NO_OPEN)
+                openBrowser(url);
+            process.exit(0);
+        }
+        reportForeignPort();
+    });
+}
+/** Port is held by something that is not a Radar dashboard. Never kill it for the user. */
+function reportForeignPort() {
+    console.error(`Port ${WEB_PORT} is already in use by another program (not a Radar dashboard).\n` +
+        `Free it, or run Radar on another port: SLACK_RADAR_WEB_PORT=8101 slack-radar web`);
+    process.exit(1);
+}
 /**
  * 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.
+ * `web` subcommand dispatcher launch the dashboard the same way. Exported so the
+ * dispatcher (mcp/index.ts) calls it explicitly rather than relying on an import
+ * side-effect, which keeps importing this module (e.g. in a test) side-effect-free.
  */
-function startWebServer() {
+export 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;
@@ -20,10 +121,10 @@ function startWebServer() {
     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);
+            // Likely our own dashboard from an earlier launch. Adopt it if so; only error
+            // if the port is held by something else. Never kill the holder for the user.
+            handlePortInUse();
+            return;
         }
         throw err;
     });
@@ -37,6 +138,12 @@ function startWebServer() {
     // 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", () => {
+        // Seed the starting spec AND wipe stale pulled DBs only now that THIS process owns the
+        // port. Doing both here (not at server.js import) means a second launcher that loses the
+        // bind never touches the running dashboard's spec file or its port-scoped pulled-DB cache,
+        // so adopting it leaves its view and open DB-browser tab intact.
+        seedInitialSpec();
+        cleanupOnBind();
         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`),
@@ -46,17 +153,7 @@ function startWebServer() {
         // /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" });
-            }
-        }
-        catch {
-            // Browser open is best-effort
-        }
+        openBrowser(url);
     });
     const shutdown = () => {
         console.log("\nShutting down…");
@@ -66,4 +163,21 @@ function startWebServer() {
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
 }
-startWebServer();
+// Only launch when run as the bin (`slack-radar-web` / `slack-radar web`), not when
+// imported (e.g. by a test that exercises isRadarSpecBody). argv[1] is the script path
+// node was invoked with; compare it to this module's own path. realpathSync resolves the
+// npm bin symlink (node_modules/.bin) to the real dist path so the comparison holds.
+function invokedDirectly() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(arg);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    startWebServer();
+}

package/dist/web/public/index.html

@@ -11,6 +11,8 @@
   .conn.waiting { color:#ffb454; }
   .reconnect { background:#3a2a10; border:1px solid #ffb454; color:#ffb454; border-radius:8px; padding:4px 12px; font:inherit; font-size:12px; font-weight:600; cursor:pointer; margin-left:8px; }
   .reconnect:hover { background:#4a360f; } .reconnect:disabled { opacity:.6; cursor:default; }
+  .profilewrap { font-size:12px; color:#7d9bd6; margin-left:8px; }
+  .profilewrap b { color:#cfe0f0; }
   .modebar { display:flex; gap:6px; margin:10px 0 6px; flex-wrap:wrap; }
   .modebtn { background:#121925; border:1px solid #243244; color:#8aa0b4; border-radius:8px; padding:6px 14px; font:inherit; font-size:12.5px; cursor:pointer; }
   .modebtn:hover { border-color:#39d98a; color:#dfe7ef; }
@@ -157,11 +159,17 @@
   .scinstall { background:#0e151e; border:1px solid #1e2a3a; border-radius:6px; padding:8px 10px; margin-top:8px; font-size:11.5px; color:#cfe3d6; }
   .scinstall code { color:#7fd6a3; }
   .scinstall .sccopy { background:#172a1f; border:1px solid #2c5a3e; color:#7fd6a3; border-radius:5px; padding:2px 8px; font:inherit; font-size:11px; cursor:pointer; margin-left:6px; }
-</style></head>
+</style>
+<!-- Import map so the vendored Preact runtime resolves the bare `preact` specifier (Preact
+     Hooks imports `from "preact"`). Inert until a UI module imports it; ships ahead of the
+     component migration (container by container) so later PRs are pure client modules. -->
+<script type="importmap">
+{ "imports": { "preact": "./vendor/preact.module.js" } }
+</script></head>
 <body>
   <div id="flash"></div>
   <div id="alertbanner"></div>
-  <h1>SLACK RADAR DASHBOARD  <span class="conn waiting" id="conn">&#9679; connecting…</span> <button id="reconnect" class="reconnect" style="display:none">⟳ Reconnect Radar</button> <button id="screenbtn" class="screenbtn" title="Mirror the live device screen">▣ Screen</button></h1>
+  <h1>SLACK RADAR DASHBOARD  <span class="conn waiting" id="conn">&#9679; connecting…</span> <span id="profilewrap" class="profilewrap" title="the device profile Radar is connected to (the first app to launch wins the socket; to watch another profile, run only that profile's Slack)">profile: <b id="profilename">detecting…</b></span> <button id="reconnect" class="reconnect" style="display:none">⟳ Reconnect Radar</button> <button id="screenbtn" class="screenbtn" title="Mirror the live device screen">▣ Screen</button></h1>
   <div id="screenpanel">
     <div class="schead">
       <span class="sctitle">Device screen</span>
@@ -354,6 +362,7 @@ async function pollHealth(){
     else if(++healthMisses>=2){ setConn('waiting','device offline, retrying…'); }
   }catch{ if(++healthMisses>=2) setConn('waiting','reconnecting…'); } }
 pollHealth(); setInterval(pollHealth,2000);
+showConnectedProfile(); setInterval(showConnectedProfile,5000); // keep the connected-profile label honest as the socket re-binds
 
 // ---- the dashboard engine: build(spec) tears down and rebuilds widgets live ----
 let es=null, tickTimer=null;
@@ -541,7 +550,47 @@ function setConn(state,msg){ const d=document.getElementById('conn'); if(!d) ret
   const rc=document.getElementById('reconnect'); if(rc && !rc._busy) rc.style.display = state==='connected' ? 'none' : 'inline-block'; }
 async function doReconnect(){ const rc=document.getElementById('reconnect'); if(!rc) return; rc._busy=true; rc.disabled=true; rc.textContent='⟳ enabling…';
   try{ await fetch('/enable',{method:'POST'}); }catch{}
-  rc._busy=false; rc.disabled=false; rc.textContent='⟳ Reconnect Radar'; pollHealth(); pollSpec(); }
+  rc._busy=false; rc.disabled=false; rc.textContent='⟳ Reconnect Radar'; showConnectedProfile(); pollHealth(); pollSpec(); }
+
+// Show which device profile Radar is connected to. Read-only: on a phone running the
+// debug build on more than one profile (personal user 0 + a work profile) only ONE
+// instance binds the single Radar socket — whichever launched first wins, and a second
+// profile cannot take it while the first holds it. So we cannot SWITCH profiles from here
+// yet (that needs per-profile sockets, a device-side change); we just report the truth.
+// The label is ALWAYS visible (operator: "profile must show even if one"): the bound
+// profile comes from /health's boundUserId/boundProfile (the real socket owner). When the
+// device drops, keep showing the last-known profile dimmed rather than vanishing.
+let lastBoundLabel=null;
+async function showConnectedProfile(){
+  const wrap=document.getElementById('profilewrap'), nameEl=document.getElementById('profilename');
+  if(!wrap||!nameEl) return;
+  try{
+    const [profilesR, healthR]=await Promise.all([
+      fetch('/_control/profiles').then(r=>r.json()).catch(()=>null),
+      fetch('/health').then(r=>r.json()).catch(()=>null),
+    ]);
+    const uid=healthR&&healthR.boundUserId;
+    if(uid==null){
+      // Device not connected right now. Do NOT hide (the label is always present), but do
+      // NOT claim a current binding either: the socket may re-bind to a DIFFERENT profile
+      // while we are down, so "<last> (disconnected)" could name the wrong one. Phrase it as
+      // the last profile we SAW, not the one bound now. Cleared so a fresh connect re-resolves.
+      nameEl.textContent = lastBoundLabel ? 'last seen '+lastBoundLabel+' — reconnecting…' : 'waiting for device…';
+      return;
+    }
+    const profiles=(profilesR&&profilesR.profiles)||[];
+    const match=profiles.find(p=>p.userId===uid);
+    // Fallback when the profile list does not name this uid (fetch failed, or ps and the
+    // live ping disagree). NEVER hard-code a user id: always print the REAL bound uid, and
+    // Title-case the profile word so it matches the matched-path label.
+    const cap=(s)=> s ? s.charAt(0).toUpperCase()+s.slice(1) : s;
+    const label = match ? match.label
+      : (healthR.boundProfile ? cap(healthR.boundProfile)+' (user '+uid+')'
+         : 'user '+uid);
+    lastBoundLabel=label;
+    nameEl.textContent=label;
+  }catch{ /* transient fetch error: leave whatever is shown */ }
+}
 // live defaults true so the SSE handler (es.onmessage=onEvent) keeps firing alerts on
 // genuine arrivals; backfill() passes live=false so replayed device HISTORY counts toward
 // widgets without triggering alerts for events that already happened.
@@ -1003,7 +1052,9 @@ async function dbRun(){ if(!DBV.db) return; const sql=document.getElementById('d
 // Consent is granted server-side (per process) and the stream/record routes enforce it.
 const SCREEN={ on:false, consent:false, recording:false, caps:null };
 function scCopy(text,btn){ navigator.clipboard?.writeText(text).then(()=>{ if(btn){ const t=btn.textContent; btn.textContent='copied'; setTimeout(()=>btn.textContent=t,1200); } }).catch(()=>{}); }
-async function scLoadCaps(){ try{ SCREEN.caps=await (await fetch('/screen/caps')).json(); SCREEN.consent=!!SCREEN.caps.consent; }catch{ SCREEN.caps=null; } }
+// refresh=1 re-probes ffmpeg/scrcpy on the server, so reopening this panel after
+// installing ffmpeg detects it without restarting the dashboard.
+async function scLoadCaps(){ try{ SCREEN.caps=await (await fetch('/screen/caps?refresh=1')).json(); SCREEN.consent=!!SCREEN.caps.consent; }catch{ SCREEN.caps=null; } }
 function scRenderConsent(){
   const body=document.getElementById('screenbody'); const hint=document.getElementById('schint');
   hint.textContent='';
@@ -1020,13 +1071,21 @@ function scRenderLive(){
     setTimeout(()=>{ if(SCREEN.on) hint.textContent='live. ▣ Screen again to close.'; },3500);
   } else {
     // No ffmpeg: live cast is unavailable. Screenshot still works (pure screencap).
-    // Show the platform install command (copy only — never auto-installed) + scrcpy hint.
-    const cmd=esc(caps.installHint||'install ffmpeg');
-    let html='<div class="scinstall">Live mirroring needs <b>ffmpeg</b>, which is not installed. Install it, then reopen this panel:<br><br><code>'+cmd+'</code><button class="sccopy" id="scffcopy">copy</button></div>';
+    // Only render a copyable command when the server returned a real platform one.
+    // The fallback used to show the literal string "install ffmpeg" with a copy
+    // button, which is not a runnable command and failed when pasted into a terminal.
+    const cmd=caps.installHint;
+    let html='<div class="scinstall">Live mirroring needs <b>ffmpeg</b>, which is not installed. ';
+    if(cmd){
+      html+='Install it with this command, then reopen this panel:<br><br><code>'+esc(cmd)+'</code><button class="sccopy" id="scffcopy">copy</button>';
+    } else {
+      html+='Install it with your system package manager (for example <code>brew install ffmpeg</code> on macOS, <code>winget install ffmpeg</code> on Windows, or <code>sudo apt install ffmpeg</code> on Debian/Ubuntu), then reopen this panel.';
+    }
+    html+='</div>';
     html+='<div class="scinstall">📷 Screenshot works without ffmpeg — use the button above.</div>';
     if(caps.scrcpy) html+='<div class="scinstall">scrcpy is installed; for a native mirror window run <code>scrcpy</code> in a terminal.</div>';
     body.innerHTML=html;
-    const c=document.getElementById('scffcopy'); if(c) c.onclick=()=>scCopy(caps.installHint||'',c);
+    const c=document.getElementById('scffcopy'); if(c) c.onclick=()=>scCopy(cmd,c);
     hint.textContent='live mirroring unavailable (no ffmpeg); screenshot still works.';
   }
 }