@slack/radar-mcp 1.1.1 → 1.2.0

package/dist/mcp/index.js

@@ -101,8 +101,10 @@ async function handleSessionEnable(args) {
     const forwarded = device.ensureForward();
     if (!forwarded) {
         sessionEnabled = false;
+        const reason = device.getLastForwardError?.() ?? null;
         return textResult({
-            error: "Port forwarding failed. Ensure a device is connected.",
+            error: reason ??
+                "Port forwarding failed. Ensure a device is connected.",
             enabled: false,
             platform: device.platform,
         }, true);
@@ -169,10 +171,69 @@ function handleGetAppState() {
         return textResult({ error: `App state query failed: ${e.message}` }, true);
     }
 }
+function handleListProfiles() {
+    try {
+        // Narrow to implementations that expose listProfiles; the base
+        // DeviceTransport interface leaves it platform-specific.
+        const maybe = device;
+        if (typeof maybe.listProfiles !== "function") {
+            return textResult({ error: `Profile listing not supported on platform ${device.platform}` }, true);
+        }
+        const profiles = maybe.listProfiles();
+        const activeUserId = typeof device.getActiveUserId === "function"
+            ? device.getActiveUserId()
+            : null;
+        return textResult({ profiles, active_user_id: activeUserId });
+    }
+    catch (e) {
+        return textResult({ error: `Profile list failed: ${e.message}` }, true);
+    }
+}
+async function handleActivateForUser(args) {
+    const maybe = device;
+    if (typeof maybe.activateForUser !== "function") {
+        return textResult({ error: `Profile switching not supported on platform ${device.platform}` }, true);
+    }
+    try {
+        const timeout = args?.timeout_minutes || device.getTimeoutMinutes() || 5;
+        maybe.activateForUser(args.user_id, timeout);
+        // Restart the SSE stream so network/RTM/clog events from the newly
+        // activated profile start flowing again.
+        destroyStream();
+        connectStream();
+        // Give the newly spawned adb logcat child a moment to emit its first
+        // lines to the capture file. Matches the warmup delay used by
+        // handleSessionEnable so an immediate get_recent_logs call does not
+        // read an empty file.
+        await new Promise((r) => setTimeout(r, 500));
+        const sourceFile = typeof device.getCaptureFilePath === "function"
+            ? device.getCaptureFilePath()
+            : null;
+        return textResult({
+            user_id: args.user_id,
+            timeout_minutes: timeout,
+            capture_file: sourceFile,
+            note: "Profile activated. Log capture restarted on a new file; old capture preserved for 7 days.",
+        });
+    }
+    catch (e) {
+        return textResult({ error: `Profile activation failed: ${e.message}` }, true);
+    }
+}
 function handleGetRecentLogs(args) {
     try {
         const lines = device.getRecentLogs(args.tag, args.limit || 50, args.grep);
-        return textResult({ tag: args.tag, lines, count: lines.length });
+        // Surface the capture file path so the model knows which on-disk file
+        // produced these lines. Helps avoid cross-session staleness (e.g. the
+        // model remembering an earlier profile's logs after a profile switch).
+        const sourceFile = device.getCaptureFilePath?.() ?? null;
+        return textResult({
+            tag: args.tag,
+            lines,
+            count: lines.length,
+            source_file: sourceFile,
+            source: sourceFile ? "capture" : "adb_logcat_d",
+        });
     }
     catch (e) {
         return textResult({ error: `Log query failed: ${e.message}`, lines: [] }, true);
@@ -291,7 +352,7 @@ function buildApiPath(name, args) {
     }
 }
 // --- MCP Server ---
-const server = new Server({ name: "slack-radar", version: "1.1.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+const server = new Server({ name: "slack-radar", version: "1.2.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFINITIONS,
 }));
@@ -315,6 +376,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
     if (name === "get_app_state") {
         return handleGetAppState();
     }
+    if (name === "list_profiles") {
+        return handleListProfiles();
+    }
+    if (name === "activate_for_user") {
+        return handleActivateForUser(toolArgs);
+    }
     if (name === "get_recent_logs") {
         return handleGetRecentLogs(toolArgs);
     }

package/dist/mcp/tools.js

@@ -32,6 +32,22 @@ export const SERVER_INSTRUCTIONS = [
     "- Use ping(timeout_minutes=N) to extend sessions. Monitor remaining_minutes proactively.",
     "- Screenshots default to 720px. Use full_res=true only when detail matters.",
     "- Setup: /slack-radar-setup",
+    "- Manual enable (no skill): adb shell am broadcast -a slack.debug.ENABLE_RADAR --ei timeout_minutes 5 -p com.Slack.internal.debug",
+    "  Then: adb forward tcp:8099 localabstract:slack-radar",
+    "",
+    "WEB DASHBOARD (/radar-ui):",
+    "A browser-based dashboard (http://localhost:8100) shows the same live device data in a",
+    "visual UI. Launched via the /radar-ui skill, which wraps `npx -p @slack/radar-mcp slack-radar-web`.",
+    "",
+    "When to suggest /radar-ui (mention it ONCE per thread, do not auto-invoke):",
+    '- User says "watch", "monitor", "let me see", "show me live" about device traffic',
+    "- User wants to share traffic with a colleague, pair, or teammate",
+    "- User is doing a multi-minute investigation and the transcript is getting noisy",
+    '- User explicitly asks about a GUI, UI, browser view, or dashboard',
+    "",
+    "DO NOT invoke /radar-ui yourself. Opening a browser window is a user-visible action.",
+    "DO NOT suggest /radar-ui for single-query debugging or when the user is happy reading",
+    "results in the transcript. Suggest it when visual inspection adds real value.",
 ].join("\n");
 export const TOOL_DEFINITIONS = [
     {
@@ -171,6 +187,31 @@ export const TOOL_DEFINITIONS = [
         },
         annotations: { readOnlyHint: true },
     },
+    {
+        name: "list_profiles",
+        description: "List Android user profiles that have the Slack debug build running. Use this before activate_for_user when the user asks to switch profiles (personal vs work) or when logs/app state seem to point at the wrong profile. Returns each profile's userId (e.g. '0' for personal, '10' for work) and a human label.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "activate_for_user",
+        description: "Activate Slack Radar on a specific Android user profile. Use after list_profiles to switch between personal and work profile targets. Switching profiles restarts log capture with a new session-scoped file and reconnects the SSE event stream so events come from the newly activated profile; old captures remain on disk for up to 7 days. Call this when already connected and only the target profile needs to change.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                user_id: {
+                    type: "string",
+                    description: "Android user ID from list_profiles (e.g. '0' for personal, '10' for work).",
+                },
+                timeout_minutes: {
+                    type: "number",
+                    description: "Auto-shutdown timeout in minutes (default: 5).",
+                },
+            },
+            required: ["user_id"],
+        },
+        annotations: {},
+    },
     {
         name: "screenshot",
         description: "Capture a screenshot from the connected Android device.",

package/dist/shared/android.d.ts

@@ -1,4 +1,15 @@
 import type { DeviceTransport } from "./transport.js";
+/**
+ * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
+ * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
+ * fails with ENOENT even when adb works fine in the user's terminal. We look
+ * in PATH first, then fall back to common Android SDK install locations.
+ *
+ * Returns either an absolute path to the adb binary or the string "adb"
+ * (PATH-relative). When all fallbacks miss, returns null so callers can
+ * surface a clear error instead of a misleading "device not connected".
+ */
+export declare function resolveAdbPath(): string | null;
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
@@ -12,11 +23,15 @@ export declare class AndroidTransport implements DeviceTransport {
     private detectedUserId;
     private currentTimeoutMinutes;
     private radarEnabled;
+    private lastForwardError;
     ensureForward(): boolean;
+    getLastForwardError(): string | null;
     activate(timeoutMinutes: number): void;
     resetState(): void;
     isForwarded(): boolean;
     getTimeoutMinutes(): number;
+    getActiveUserId(): string | null;
+    getCaptureFilePath(): string | null;
     screenshot(fullRes: boolean): string;
     recordScreen(durationS: number): string;
     getAppState(): string;

package/dist/shared/android.js

@@ -1,9 +1,63 @@
 import { execSync } from "child_process";
+import fs from "fs";
 import os from "os";
 import path from "path";
+import { getCaptureFilePath, isCapturing, readRecentLogs, registerCleanup, rotateCaptureIfNeeded, startCapture, stopCapture, } from "./logcat-capture.js";
 const RADAR_PORT = 8099;
 const SOCKET_NAME = "slack-radar";
 const ENABLE_ACTION = "slack.debug.ENABLE_RADAR";
+/**
+ * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
+ * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
+ * fails with ENOENT even when adb works fine in the user's terminal. We look
+ * in PATH first, then fall back to common Android SDK install locations.
+ *
+ * Returns either an absolute path to the adb binary or the string "adb"
+ * (PATH-relative). When all fallbacks miss, returns null so callers can
+ * surface a clear error instead of a misleading "device not connected".
+ */
+export function resolveAdbPath() {
+    // 1. PATH-relative: if `adb` resolves, use it as-is (fast path).
+    try {
+        const which = execSync("command -v adb", {
+            timeout: 2000,
+            encoding: "utf-8",
+            shell: "/bin/sh",
+        }).trim();
+        if (which && fs.existsSync(which))
+            return "adb";
+    }
+    catch {
+        // `command -v adb` returns non-zero when not found; fall through
+    }
+    // 2. Common install locations, in order of likelihood on macOS and Linux.
+    const home = os.homedir();
+    const candidates = [
+        process.env.ANDROID_HOME
+            ? path.join(process.env.ANDROID_HOME, "platform-tools", "adb")
+            : null,
+        process.env.ANDROID_SDK_ROOT
+            ? path.join(process.env.ANDROID_SDK_ROOT, "platform-tools", "adb")
+            : null,
+        path.join(home, "Library", "Android", "sdk", "platform-tools", "adb"),
+        path.join(home, "Android", "Sdk", "platform-tools", "adb"),
+        "/usr/local/bin/adb",
+        "/opt/homebrew/bin/adb",
+    ].filter((p) => p !== null);
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            // Permission denied on some directory; skip
+        }
+    }
+    return null;
+}
+// Module-level resolution, done once at import time. The MCP process lifetime
+// is short enough (session-scoped) that we do not need to re-resolve.
+const ADB = resolveAdbPath();
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
@@ -33,29 +87,46 @@ export class AndroidTransport {
     detectedUserId = null;
     currentTimeoutMinutes = 5;
     radarEnabled = false;
+    lastForwardError = null;
     ensureForward() {
         if (this.portForwarded)
             return true;
+        if (!ADB) {
+            this.lastForwardError =
+                "adb binary not found. Set ANDROID_HOME or install Android SDK platform-tools. Searched: PATH, $ANDROID_HOME/platform-tools/adb, ~/Library/Android/sdk/platform-tools/adb, ~/Android/Sdk/platform-tools/adb, /usr/local/bin/adb, /opt/homebrew/bin/adb.";
+            return false;
+        }
         try {
-            execSync(`adb forward tcp:${RADAR_PORT} localabstract:${SOCKET_NAME}`, {
+            execSync(`${ADB} forward tcp:${RADAR_PORT} localabstract:${SOCKET_NAME}`, {
                 timeout: 5000,
             });
             this.portForwarded = true;
+            this.lastForwardError = null;
             return true;
         }
-        catch {
+        catch (e) {
+            this.lastForwardError = e.message;
             return false;
         }
     }
+    getLastForwardError() {
+        return this.lastForwardError;
+    }
     activate(timeoutMinutes) {
+        if (!ADB)
+            return;
         const timeout = timeoutMinutes || this.currentTimeoutMinutes;
         if (this.radarEnabled && timeout === this.currentTimeoutMinutes)
             return;
         try {
             const userId = this.detectDebugBuildUser();
-            execSync(`adb shell am broadcast --user ${userId} -a ${ENABLE_ACTION} --ei timeout_minutes ${timeout}`, { timeout: 5000 });
+            execSync(`${ADB} shell am broadcast --user ${userId} -a ${ENABLE_ACTION} --ei timeout_minutes ${timeout}`, { timeout: 5000 });
             this.currentTimeoutMinutes = timeout;
             this.radarEnabled = true;
+            // Start streaming logcat to a session-scoped file so reads are not
+            // subject to the device ring buffer rotating under load.
+            registerCleanup();
+            startCapture(ADB);
         }
         catch {
             // Broadcast failed — device may not be connected
@@ -65,6 +136,8 @@ export class AndroidTransport {
         this.portForwarded = false;
         this.detectedUserId = null;
         this.radarEnabled = false;
+        this.lastForwardError = null;
+        stopCapture();
     }
     isForwarded() {
         return this.portForwarded;
@@ -72,12 +145,20 @@ export class AndroidTransport {
     getTimeoutMinutes() {
         return this.currentTimeoutMinutes;
     }
+    getActiveUserId() {
+        return this.detectedUserId;
+    }
+    getCaptureFilePath() {
+        return getCaptureFilePath();
+    }
     screenshot(fullRes) {
+        if (!ADB)
+            throw new Error("adb not found on PATH or common SDK locations");
         const tmpFile = path.join(os.tmpdir(), `slack-radar-screenshot-${Date.now()}.png`);
         const devicePath = "/data/local/tmp/slack-radar-screenshot.png";
-        execSync(`adb shell screencap -p ${devicePath}`, { timeout: 10000 });
-        execSync(`adb pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
-        execSync(`adb shell rm ${devicePath}`, { timeout: 5000 });
+        execSync(`${ADB} shell screencap -p ${devicePath}`, { timeout: 10000 });
+        execSync(`${ADB} pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
+        execSync(`${ADB} shell rm ${devicePath}`, { timeout: 5000 });
         if (!fullRes) {
             try {
                 execSync(`sips -Z 720 "${tmpFile}" 2>/dev/null`, { timeout: 5000 });
@@ -89,21 +170,40 @@ export class AndroidTransport {
         return tmpFile;
     }
     recordScreen(durationS) {
+        if (!ADB)
+            throw new Error("adb not found on PATH or common SDK locations");
         const duration = Math.min(Math.max(durationS, 1), 30);
         const tmpFile = path.join(os.tmpdir(), `slack-radar-recording-${Date.now()}.mp4`);
         const devicePath = "/data/local/tmp/slack-radar-recording.mp4";
-        execSync(`adb shell screenrecord --time-limit ${duration} --size 720x1280 ${devicePath}`, { timeout: (duration + 5) * 1000 });
-        execSync(`adb pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
-        execSync(`adb shell rm ${devicePath}`, { timeout: 5000 });
+        execSync(`${ADB} shell screenrecord --time-limit ${duration} --size 720x1280 ${devicePath}`, { timeout: (duration + 5) * 1000 });
+        execSync(`${ADB} pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
+        execSync(`${ADB} shell rm ${devicePath}`, { timeout: 5000 });
         return tmpFile;
     }
     getAppState() {
-        return execSync(`adb shell "dumpsys activity activities | grep -A 5 'com.Slack.internal'"`, { timeout: 10000, encoding: "utf-8" }).trim();
+        if (!ADB)
+            throw new Error("adb not found on PATH or common SDK locations");
+        return execSync(`${ADB} shell "dumpsys activity activities | grep -A 5 'com.Slack.internal'"`, { timeout: 10000, encoding: "utf-8" }).trim();
     }
     getRecentLogs(tag, limit, grep) {
-        let cmd = `adb logcat -d | grep -F "${tag}" | tail -${limit}`;
+        if (!ADB)
+            throw new Error("adb not found on PATH or common SDK locations");
+        // Preferred path: read from the session capture file so lines cannot
+        // have been evicted from the device ring buffer between enable and now.
+        if (isCapturing()) {
+            // Opportunistic rotation. Stop+rename+restart when the file grows
+            // past the threshold so the child never writes past a truncated EOF.
+            // Bounded to the read cadence; no extra timer.
+            rotateCaptureIfNeeded(ADB);
+            const lines = readRecentLogs(tag, limit, grep);
+            if (lines !== null)
+                return lines;
+        }
+        // Fallback: device ring buffer snapshot. Used when capture is not running
+        // (activate() was skipped, child died, or the file was deleted).
+        let cmd = `${ADB} logcat -d | grep -F "${tag}" | tail -${limit}`;
         if (grep) {
-            cmd = `adb logcat -d | grep -F "${tag}" | grep -i "${grep.replace(/"/g, '\\"')}" | tail -${limit}`;
+            cmd = `${ADB} logcat -d | grep -F "${tag}" | grep -i "${grep.replace(/"/g, '\\"')}" | tail -${limit}`;
         }
         const output = execSync(cmd, {
             timeout: 10000,
@@ -113,8 +213,10 @@ export class AndroidTransport {
         return output.trim().split("\n").filter(Boolean);
     }
     listProfiles() {
+        if (!ADB)
+            return [{ userId: "0", label: "Personal (user 0)" }];
         try {
-            const ps = execSync(`adb shell "ps -A -o USER,NAME 2>/dev/null | grep Slack | grep debug"`, { timeout: 5000, encoding: "utf-8" }).trim();
+            const ps = execSync(`${ADB} shell "ps -A -o USER,NAME 2>/dev/null | grep Slack | grep debug"`, { timeout: 5000, encoding: "utf-8" }).trim();
             if (!ps)
                 return [{ userId: "0", label: "Personal (user 0)" }];
             const seen = new Set();
@@ -139,17 +241,31 @@ export class AndroidTransport {
         }
     }
     activateForUser(userId, timeoutMinutes) {
+        if (!ADB)
+            throw new Error("adb not found on PATH or common SDK locations");
         const timeout = timeoutMinutes || this.currentTimeoutMinutes;
-        execSync(`adb shell am broadcast --user ${userId} -a ${ENABLE_ACTION} --ei timeout_minutes ${timeout}`, { timeout: 5000 });
+        const profileChanged = this.detectedUserId !== null && this.detectedUserId !== userId;
+        execSync(`${ADB} shell am broadcast --user ${userId} -a ${ENABLE_ACTION} --ei timeout_minutes ${timeout}`, { timeout: 5000 });
         this.detectedUserId = userId;
         this.currentTimeoutMinutes = timeout;
         this.radarEnabled = true;
+        // Profile switch means the interesting scope changed; drop the old
+        // capture so the new session starts from a fresh file scoped to this
+        // profile's debug run.
+        if (profileChanged)
+            stopCapture();
+        registerCleanup();
+        startCapture(ADB);
     }
     detectDebugBuildUser() {
         if (this.detectedUserId !== null)
             return this.detectedUserId;
+        if (!ADB) {
+            this.detectedUserId = "0";
+            return this.detectedUserId;
+        }
         try {
-            const ps = execSync(`adb shell "ps -A -o USER,NAME 2>/dev/null | grep Slack | grep debug"`, { timeout: 5000, encoding: "utf-8" }).trim();
+            const ps = execSync(`${ADB} shell "ps -A -o USER,NAME 2>/dev/null | grep Slack | grep debug"`, { timeout: 5000, encoding: "utf-8" }).trim();
             this.detectedUserId = parseUserFromPsOutput(ps);
         }
         catch {

package/dist/shared/logcat-capture.d.ts

@@ -0,0 +1,73 @@
+import { ChildProcess } from "child_process";
+export interface CaptureState {
+    child: ChildProcess | null;
+    filePath: string | null;
+    startedAt: number | null;
+}
+/**
+ * Delete capture files older than GC_TTL_MS. Runs at session enable. Bounded
+ * disk usage without losing recent forensic history. Extracted for test.
+ */
+export declare function gcOldCaptures(dir?: string, now?: number): number;
+export declare function buildCaptureFilePath(now?: number): string;
+export declare function isCapturing(): boolean;
+export declare function getCaptureFilePath(): string | null;
+/**
+ * Start streaming logcat to a session-scoped file. Idempotent: a second call
+ * while the first capture is live is a no-op. If a prior capture's child is
+ * dead (crashed, killed), it is cleared first so this call starts fresh.
+ */
+export declare function startCapture(adbPath: string): string | null;
+export declare function stopCapture(): void;
+/**
+ * Check whether the file at `filePath` exceeds ROTATION_BYTES.
+ *
+ * The caller is responsible for performing rotation — the old approach of
+ * truncating in-place was unsafe because the child `adb logcat` process
+ * still holds an open fd at its previous write offset; after a truncate
+ * the next write lands past the new EOF and produces a sparse file with a
+ * null-byte hole. See `rotateCaptureIfNeeded` for the safe rotation path:
+ * stop the child, rename the old file, start a new child with a fresh fd.
+ *
+ * Extracted so the size check is testable without running adb.
+ */
+export declare function needsRotation(filePath: string): boolean;
+/**
+ * If the active capture has grown past the rotation threshold, cleanly
+ * rotate it: stop the child (closing its fd), rename the old file with a
+ * `.rotated-<ts>` suffix so it remains readable by consumers for a while
+ * (GC reclaims it after the 7-day TTL), and start a fresh child writing
+ * to a new file.
+ *
+ * Only has effect if a capture is currently active. Returns the new file
+ * path (or null if no rotation happened or rotation failed).
+ */
+export declare function rotateCaptureIfNeeded(adbPath: string): string | null;
+/**
+ * Filter captured log lines by tag substring (logcat threadtime format puts
+ * the tag after the PID/TID columns), optional grep (case-insensitive), and
+ * tail to `limit` most-recent matches.
+ *
+ * Extracted so the pure logic can be tested without a running adb.
+ */
+export declare function filterLogLines(lines: string[], tag: string, limit: number, grep?: string): string[];
+/**
+ * Read the last `maxBytes` of a file without loading the whole thing. Returns
+ * the tail as a UTF-8 string, dropping any partial first line so the result
+ * starts at a line boundary. Keeps memory bounded regardless of file size,
+ * which matters once the capture file grows (and once the web dashboard
+ * starts polling for logs in a later PR).
+ *
+ * Extracted for testability.
+ */
+export declare function readTailBytes(filePath: string, maxBytes: number): string;
+/**
+ * Read recent captured lines matching tag/grep, tailed to `limit`. Returns
+ * null when no capture is active (caller falls back to `adb logcat -d`).
+ *
+ * Reads only the last DEFAULT_TAIL_BYTES of the capture file so cost stays
+ * bounded as the file grows. For typical logcat traffic this window covers
+ * several thousand lines, which safely exceeds practical `limit` values.
+ */
+export declare function readRecentLogs(tag: string, limit: number, grep?: string): string[] | null;
+export declare function registerCleanup(): void;

package/dist/shared/logcat-capture.js

@@ -0,0 +1,296 @@
+import { spawn } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+/**
+ * Streams `adb logcat` to a per-session file so log queries read from a
+ * local, non-rotating store instead of the device's ring buffer at query time.
+ *
+ * The device-side logcat buffer is ~256KB-1MB per buffer and rotates under
+ * load; a chatty session can overwrite lines a user wanted to inspect hours
+ * later. Capturing to a local file from session-enable onward preserves
+ * everything from the enable moment forward.
+ *
+ * Lifecycle: startCapture on activate, stopCapture on resetState/disable.
+ */
+const LOG_DIR = path.join(os.homedir(), ".slack-radar", "logs");
+const ROTATION_BYTES = 100 * 1024 * 1024;
+const ROTATION_KEEP_BYTES = 50 * 1024 * 1024;
+const GC_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const state = {
+    child: null,
+    filePath: null,
+    startedAt: null,
+};
+function ensureLogDir() {
+    if (!fs.existsSync(LOG_DIR)) {
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+    }
+}
+/**
+ * Delete capture files older than GC_TTL_MS. Runs at session enable. Bounded
+ * disk usage without losing recent forensic history. Extracted for test.
+ */
+export function gcOldCaptures(dir = LOG_DIR, now = Date.now()) {
+    if (!fs.existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.startsWith("radar-") || !name.endsWith(".log"))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const stat = fs.statSync(full);
+            if (now - stat.mtimeMs > GC_TTL_MS) {
+                fs.unlinkSync(full);
+                removed += 1;
+            }
+        }
+        catch {
+            // ignore; file may have vanished between readdir and stat
+        }
+    }
+    return removed;
+}
+export function buildCaptureFilePath(now = Date.now()) {
+    return path.join(LOG_DIR, `radar-${now}.log`);
+}
+export function isCapturing() {
+    return state.child !== null && state.child.exitCode === null;
+}
+export function getCaptureFilePath() {
+    return state.filePath;
+}
+/**
+ * Start streaming logcat to a session-scoped file. Idempotent: a second call
+ * while the first capture is live is a no-op. If a prior capture's child is
+ * dead (crashed, killed), it is cleared first so this call starts fresh.
+ */
+export function startCapture(adbPath) {
+    if (isCapturing())
+        return state.filePath;
+    // Stale child: clear before restarting.
+    if (state.child !== null)
+        stopCapture();
+    ensureLogDir();
+    gcOldCaptures();
+    const filePath = buildCaptureFilePath();
+    const out = fs.openSync(filePath, "a");
+    try {
+        const child = spawn(adbPath, ["logcat", "-v", "threadtime"], {
+            stdio: ["ignore", out, out],
+            detached: false,
+        });
+        child.on("exit", () => {
+            try {
+                fs.closeSync(out);
+            }
+            catch {
+                // already closed
+            }
+            if (state.child === child) {
+                state.child = null;
+            }
+        });
+        child.on("error", () => {
+            try {
+                fs.closeSync(out);
+            }
+            catch {
+                // already closed
+            }
+            if (state.child === child) {
+                state.child = null;
+                state.filePath = null;
+                state.startedAt = null;
+            }
+        });
+        state.child = child;
+        state.filePath = filePath;
+        state.startedAt = Date.now();
+        // Child bring-up warmup is handled at the MCP handler boundary
+        // (handleSessionEnable / handleActivateForUser add a small async delay
+        // before returning). Doing it here would require either blocking the
+        // single-threaded MCP event loop with a busy-wait or making startCapture
+        // async, neither of which earns the complexity.
+        return filePath;
+    }
+    catch {
+        try {
+            fs.closeSync(out);
+        }
+        catch {
+            // ignore
+        }
+        return null;
+    }
+}
+export function stopCapture() {
+    const child = state.child;
+    state.child = null;
+    state.filePath = null;
+    state.startedAt = null;
+    if (child && child.exitCode === null) {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // already dead
+        }
+    }
+}
+/**
+ * Check whether the file at `filePath` exceeds ROTATION_BYTES.
+ *
+ * The caller is responsible for performing rotation — the old approach of
+ * truncating in-place was unsafe because the child `adb logcat` process
+ * still holds an open fd at its previous write offset; after a truncate
+ * the next write lands past the new EOF and produces a sparse file with a
+ * null-byte hole. See `rotateCaptureIfNeeded` for the safe rotation path:
+ * stop the child, rename the old file, start a new child with a fresh fd.
+ *
+ * Extracted so the size check is testable without running adb.
+ */
+export function needsRotation(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        return stat.size > ROTATION_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * If the active capture has grown past the rotation threshold, cleanly
+ * rotate it: stop the child (closing its fd), rename the old file with a
+ * `.rotated-<ts>` suffix so it remains readable by consumers for a while
+ * (GC reclaims it after the 7-day TTL), and start a fresh child writing
+ * to a new file.
+ *
+ * Only has effect if a capture is currently active. Returns the new file
+ * path (or null if no rotation happened or rotation failed).
+ */
+export function rotateCaptureIfNeeded(adbPath) {
+    const current = state.filePath;
+    if (!current || !isCapturing())
+        return null;
+    if (!needsRotation(current))
+        return null;
+    stopCapture();
+    try {
+        const archived = `${current}.rotated-${Date.now()}`;
+        fs.renameSync(current, archived);
+    }
+    catch {
+        // Rename failure is non-fatal: the file may have vanished. We still
+        // want to start a fresh capture, so fall through to startCapture.
+    }
+    return startCapture(adbPath);
+}
+/**
+ * Filter captured log lines by tag substring (logcat threadtime format puts
+ * the tag after the PID/TID columns), optional grep (case-insensitive), and
+ * tail to `limit` most-recent matches.
+ *
+ * Extracted so the pure logic can be tested without a running adb.
+ */
+export function filterLogLines(lines, tag, limit, grep) {
+    const tagMatches = lines.filter((line) => line.includes(tag));
+    const grepMatches = grep
+        ? tagMatches.filter((line) => line.toLowerCase().includes(grep.toLowerCase()))
+        : tagMatches;
+    if (grepMatches.length <= limit)
+        return grepMatches;
+    return grepMatches.slice(grepMatches.length - limit);
+}
+/**
+ * Read the last `maxBytes` of a file without loading the whole thing. Returns
+ * the tail as a UTF-8 string, dropping any partial first line so the result
+ * starts at a line boundary. Keeps memory bounded regardless of file size,
+ * which matters once the capture file grows (and once the web dashboard
+ * starts polling for logs in a later PR).
+ *
+ * Extracted for testability.
+ */
+export function readTailBytes(filePath, maxBytes) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return "";
+    }
+    if (stat.size === 0)
+        return "";
+    const readSize = Math.min(stat.size, maxBytes);
+    const start = stat.size - readSize;
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const buf = Buffer.alloc(readSize);
+        fs.readSync(fd, buf, 0, readSize, start);
+        const text = buf.toString("utf-8");
+        // If we read from mid-file, drop the partial first line so the caller
+        // does not see half-parsed content.
+        if (start > 0) {
+            const firstNewline = text.indexOf("\n");
+            if (firstNewline !== -1)
+                return text.slice(firstNewline + 1);
+        }
+        return text;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+// Bounded tail size for tool reads. Large enough to cover most `limit <= 500`
+// queries on chatty traffic; small enough to keep per-read memory predictable.
+// Tuned for the radar-ui polling case (later PR) where many reads per second
+// are plausible.
+const DEFAULT_TAIL_BYTES = 4 * 1024 * 1024;
+/**
+ * Read recent captured lines matching tag/grep, tailed to `limit`. Returns
+ * null when no capture is active (caller falls back to `adb logcat -d`).
+ *
+ * Reads only the last DEFAULT_TAIL_BYTES of the capture file so cost stays
+ * bounded as the file grows. For typical logcat traffic this window covers
+ * several thousand lines, which safely exceeds practical `limit` values.
+ */
+export function readRecentLogs(tag, limit, grep) {
+    const filePath = state.filePath;
+    if (!filePath)
+        return null;
+    // Note: rotation is not triggered here. Rotating requires an adb path to
+    // start the replacement child, and the read path is intentionally sync +
+    // adb-free. Callers that have adb (AndroidTransport.getRecentLogs) can
+    // invoke rotateCaptureIfNeeded before reading.
+    let tail;
+    try {
+        tail = readTailBytes(filePath, DEFAULT_TAIL_BYTES);
+    }
+    catch {
+        return null;
+    }
+    const lines = tail.split("\n").filter(Boolean);
+    return filterLogLines(lines, tag, limit, grep);
+}
+/**
+ * Install once at process start so the child adb logcat is killed when the
+ * MCP server exits. Prevents orphaned adb streams that would hold the
+ * device and accumulate across restarts.
+ */
+let cleanupRegistered = false;
+export function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    const cleanup = () => stopCapture();
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+        cleanup();
+        process.exit(143);
+    });
+}

package/dist/shared/transport.d.ts

@@ -55,4 +55,43 @@ export interface DeviceTransport {
      * @returns Array of matching log lines
      */
     getRecentLogs(tag: string, limit: number, grep?: string): string[];
+    /**
+     * Returns the last error message from an `ensureForward()` failure, or null
+     * if the last attempt succeeded or has not happened. Lets callers surface
+     * concrete causes (missing adb, unauthorized device) instead of a generic
+     * "device not connected" message. Optional; implementations may omit it.
+     */
+    getLastForwardError?(): string | null;
+    /**
+     * Returns the path of the session-scoped log capture file, or null if no
+     * capture is running. Surfaced in tool responses so the model can reason
+     * about which file's contents it just saw and detect staleness across
+     * profile switches or session restarts. Optional; platforms without
+     * file-backed capture may omit it.
+     */
+    getCaptureFilePath?(): string | null;
+    /**
+     * List profiles the debug build is running under. Android uses this to
+     * expose personal vs work profile; iOS will be a no-op or single entry.
+     * Optional; platforms without multi-user models may omit it.
+     */
+    listProfiles?(): {
+        userId: string;
+        label: string;
+    }[];
+    /**
+     * Activate the on-device radar server for a specific user profile.
+     * Optional; only implementations that implement listProfiles should
+     * implement this.
+     *
+     * @param userId The user ID from listProfiles
+     * @param timeoutMinutes Auto-shutdown timeout in minutes
+     */
+    activateForUser?(userId: string, timeoutMinutes: number): void;
+    /**
+     * Returns the currently active user ID, or null if not set. Surfaced in
+     * list_profiles output so callers can tell which profile the current
+     * session is targeting without making a second call. Optional.
+     */
+    getActiveUserId?(): string | null;
 }

package/dist/web/public/index.html

@@ -223,8 +223,9 @@
 
   <div class="toolbar">
     <input type="text" id="filter" placeholder="Filter by URL, channel, event name, payload..." />
-    <select id="profile-select" style="display: none; margin-right: 4px; font-size: 12px; padding: 2px 4px; background: #2a2a2a; color: #ccc; border: 1px solid #444; border-radius: 3px;"></select>
+    <span id="profile-label" style="display: none; font-size: 12px; color: #616061; margin-right: 4px;"></span>
     <button id="enable-btn" style="display: none;">Enable Radar</button>
+    <button id="disconnect-btn" style="display: none;">Disconnect</button>
     <button id="pause-btn">Pause</button>
     <button id="clear-btn">Clear</button>
   </div>
@@ -256,7 +257,8 @@
     const detailEl = document.getElementById("detail");
     const filterEl = document.getElementById("filter");
     const enableBtn = document.getElementById("enable-btn");
-    const profileSelect = document.getElementById("profile-select");
+    const profileLabel = document.getElementById("profile-label");
+    const disconnectBtn = document.getElementById("disconnect-btn");
     const pauseBtn = document.getElementById("pause-btn");
     const clearBtn = document.getElementById("clear-btn");
     const statusDot = document.getElementById("status-dot");
@@ -307,22 +309,25 @@
       enableBtn.disabled = true;
       enableBtn.textContent = "Enabling…";
       try {
-        const selectedUser = profileSelect.value;
-        const qs = selectedUser ? `?user_id=${selectedUser}` : "";
-        const res = await fetch(`/_control/activate${qs}`, { method: "POST" });
+        const res = await fetch("/_control/activate", { method: "POST" });
         const data = await res.json();
         if (!data.ok) {
           statusText.textContent = "enable failed";
           alert(data.error || "Failed to enable radar");
         } else {
           statusText.textContent = "connecting";
+          // Device-side server needs a moment to start after the broadcast.
+          // Without this delay, the SSE connect races the server startup and
+          // gets connection-refused, snapping back to disconnected instantly.
+          await new Promise((r) => setTimeout(r, 1500));
+          connectStream();
+          return; // skip the finally reset — stay in "connecting" state
         }
       } catch (e) {
         alert("Failed to reach server: " + e.message);
-      } finally {
-        enableBtn.disabled = false;
-        enableBtn.textContent = "Enable Radar";
       }
+      enableBtn.disabled = false;
+      enableBtn.textContent = "Enable Radar";
     });
 
     async function fetchProfiles() {
@@ -330,32 +335,47 @@
         const res = await fetch("/_control/profiles");
         const data = await res.json();
         const profiles = data.profiles || [];
-        profileSelect.innerHTML = "";
-        if (profiles.length > 1) {
-          for (const p of profiles) {
-            const opt = document.createElement("option");
-            opt.value = p.userId;
-            opt.textContent = p.label;
-            profileSelect.appendChild(opt);
-          }
-          profileSelect.style.display = "";
+        const activeId = data.active_user_id;
+
+        if (activeId && profiles.length >= 1) {
+          const active = profiles.find((p) => p.userId === activeId) ?? profiles[0];
+          profileLabel.textContent = active.label;
+          profileLabel.style.display = "";
+        } else if (profiles.length >= 1) {
+          profileLabel.textContent = profiles[0].label;
+          profileLabel.style.display = "";
         } else {
-          profileSelect.style.display = "none";
+          profileLabel.style.display = "none";
         }
       } catch {
-        profileSelect.style.display = "none";
+        profileLabel.style.display = "none";
       }
     }
 
     function setDisconnectedUi(disconnected) {
       enableBtn.style.display = disconnected ? "" : "none";
+      disconnectBtn.style.display = disconnected ? "none" : "";
       if (disconnected) {
-        fetchProfiles();
-      } else {
-        profileSelect.style.display = "none";
+        uptimeBadge.textContent = "";
+        extendBtn.style.display = "none";
       }
+      fetchProfiles();
     }
 
+    disconnectBtn.addEventListener("click", () => {
+      if (activeStream) {
+        activeStream.close();
+        activeStream = null;
+      }
+      state.connected = false;
+      statusDot.classList.remove("connected");
+      statusText.textContent = "disconnected";
+      enableBtn.disabled = false;
+      enableBtn.textContent = "Enable Radar";
+      setDisconnectedUi(true);
+      renderList();
+    });
+
     // --- SSE ---
     function insertReconnectMarker() {
       const marker = {
@@ -363,14 +383,18 @@
         timestamp: Date.now(),
         label: `reconnected @ ${new Date().toLocaleTimeString("en-US", { hour12: false })}`,
       };
+      const buffers = state.buffers;
       for (const type of ["network", "rtm", "clog"]) {
-        const buf = state.buffers[type];
+        const buf = buffers[type];
         if (buf.length > 0) buf.push({ ...marker }); // avoid empty-list markers
       }
     }
 
+    let activeStream = null;
+
     function connectStream() {
       const es = new EventSource("/api/stream");
+      activeStream = es;
       es.onopen = () => {
         const wasDisconnected = !state.connected && state.hadConnection;
         state.connected = true;
@@ -394,15 +418,21 @@
         state.connected = false;
         statusDot.classList.remove("connected");
         statusText.textContent = "disconnected";
+        enableBtn.disabled = false;
+        enableBtn.textContent = "Enable Radar";
         setDisconnectedUi(true);
         renderList();
         es.close();
-        setTimeout(connectStream, 2000);
       };
     }
 
     function ingest(type, event) {
-      const buf = state.buffers[type];
+      // Attribute incoming events to whichever profile is currently active.
+      // There is a small misattribution window right at a switch boundary
+      // (a few events in flight may land in the wrong bucket), which is an
+      // acceptable cost relative to server-side event tagging.
+      const buffers = state.buffers;
+      const buf = buffers[type];
       if (!buf) return;
       buf.push(event);
       if (buf.length > state.MAX_BUFFER) buf.shift();
@@ -411,9 +441,10 @@
     }
 
     function updateCounts() {
-      document.getElementById("network-count").textContent = state.buffers.network.length;
-      document.getElementById("rtm-count").textContent = state.buffers.rtm.length;
-      document.getElementById("clog-count").textContent = state.buffers.clog.length;
+      const buffers = state.buffers;
+      document.getElementById("network-count").textContent = buffers.network.length;
+      document.getElementById("rtm-count").textContent = buffers.rtm.length;
+      document.getElementById("clog-count").textContent = buffers.clog.length;
     }
 
     // --- Rendering ---
@@ -665,6 +696,7 @@ ${escapeHtml(tryPretty(data.data))}
     });
 
     async function pollPing() {
+      if (!state.connected) return;
       try {
         const res = await fetch("/api/ping");
         const data = await res.json();
@@ -683,11 +715,13 @@ ${escapeHtml(tryPretty(data.data))}
         extendBtn.style.display = "none";
       }
     }
-    pollPing();
+    // pollPing runs on interval; skips when not connected.
     setInterval(pollPing, 5000);
 
     // --- Go ---
-    connectStream();
+    // Start in disconnected state. User picks a profile and clicks Enable.
+    // connectStream() is called after Enable succeeds.
+    setDisconnectedUi(true);
     updateCounts();
     renderList();
   </script>

package/dist/web/server.js

@@ -43,10 +43,14 @@ export function createServer() {
 }
 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 }));
+    res.end(JSON.stringify({ profiles, active_user_id: activeUserId }));
 }
 function activateRadar(res, userId) {
+    // Reset cached state so ensureForward() re-runs adb forward. This handles
+    // stale forwards after device-side idle timeout or profile switching.
+    transport.resetState();
     const forwarded = transport.ensureForward();
     if (!forwarded) {
         res.writeHead(502, { "Content-Type": "application/json; charset=utf-8" });
@@ -73,7 +77,7 @@ function activateRadar(res, userId) {
         return;
     }
     res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify({ ok: true, user_id: userId ?? "auto" }));
+    res.end(JSON.stringify({ ok: true, user_id: userId ?? transport.getActiveUserId() ?? "auto" }));
 }
 function proxyToRadar(req, res) {
     const upstream = http.request({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slack/radar-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
   "type": "module",
   "main": "dist/mcp/index.js",