@slack/radar-mcp 1.4.0 → 1.5.0

package/README.md

@@ -49,6 +49,13 @@ Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a
 
 Each tab has a counter, rate, sparkline, graph, a filter / sort / pause feed, and a payload inspector. Switching tabs replays what you have already seen this session (the browser caches it, bounded by count and age) so the view does not reset to empty. ADB forwarding and device activation are handled for you; a reconnect control re-arms after a device sleep.
 
+### Screen overlay
+
+A **▣ Screen** button opens a side panel that mirrors the live device screen, with a full-resolution screenshot and a screen recording. It is off by default and opens to a consent notice first, because it shows whatever is on the phone (open DMs, message content, notifications).
+
+* **Screenshot** works on any machine (pure `screencap`, no extra tools).
+* **Live mirror and recording** need `ffmpeg` on your machine. If it is missing, the panel shows the install command for your platform and the screenshot still works. ffmpeg is not bundled and is never installed for you.
+
 ## Prerequisites
 
 * Node.js 18+
@@ -124,8 +131,9 @@ What gets captured depends on the in-app server implementation. The MCP server i
 * **Network calls**: OkHttp interceptor. Ring buffer: 200 calls.
 * **RTM events**: WebSocket listener. Ring buffer: 500 events.
 * **Clogs**: Analytics interceptor. Ring buffer: 500 events. Persists across radar activation cycles.
+* **SQLite database** (Database tab, web dashboard only): when you open a database, a read-only **plaintext** copy of that on-device store (message text, request/response bodies, user/channel/team IDs) is pulled to a temp directory **on your own machine** (`os.tmpdir()/slack-radar-db-<port>`, files mode 0600). Auto-deleted when the dashboard process stops.
 
-All data is in-memory only. No disk writes.
+The network, RTM, and clog captures are in-memory ring buffers. The Database tab is the exception: it writes a plaintext copy of the selected on-device database to a temp file on your host for the duration of the session. Review before sharing anything from it.
 
 ### What gets captured, in detail
 

package/dist/mcp/index.js

@@ -562,7 +562,7 @@ async function runMcpServer() {
         }
     }
     // --- MCP Server ---
-    const server = new Server({ name: "slack-radar", version: "1.4.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    const server = new Server({ name: "slack-radar", version: "1.5.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOL_DEFINITIONS,
     }));

package/dist/mcp/tools.js

@@ -61,6 +61,17 @@ export const SERVER_INSTRUCTIONS = [
     "DO NOT offer for single-query debugging or when the user is happy reading results in the",
     "transcript. Offer when visual inspection adds real value.",
     "",
+    "SCREEN OVERLAY (in the dashboard):",
+    "The dashboard has a '▣ Screen' button that mirrors the LIVE device screen in a side panel,",
+    "plus a full-resolution screenshot and screen recording. It is OFF by default and opens to a",
+    "consent notice first, because it shows real on-screen content (open DMs, messages). The live",
+    "mirror needs ffmpeg on the user's machine; the screenshot does not. If the user wants the live",
+    "screen and ffmpeg is missing, tell them plainly that live mirroring needs ffmpeg and give the",
+    "platform install command (mac: `brew install ffmpeg`; debian/ubuntu: `sudo apt install ffmpeg`;",
+    "windows: `winget install ffmpeg`), and note the screenshot works without it. NEVER run the",
+    "install for them. The dashboard's /health response reports screen.ffmpeg / screen.liveCast /",
+    "screen.installHint, so you can check before suggesting.",
+    "",
     "CUSTOM DASHBOARD (open_radar_dashboard):",
     "The pre-built tabs (Live/Network/RTM/Clogs/Logs) cover the common cases. When the user",
     "describes a live view the tabs do not show, SUGGEST building it; invoke open_radar_dashboard",

package/dist/shared/android.d.ts

@@ -32,6 +32,14 @@ export declare class AndroidTransport implements DeviceTransport {
     isForwarded(): boolean;
     getTimeoutMinutes(): number;
     getActiveUserId(): string | null;
+    /**
+     * Resolve the Android user the debug build is actually running as: the already-detected
+     * user if known, else a `ps`-based detection (which prefers the non-zero/secondary profile
+     * the work build runs under). Unlike getActiveUserId() this never returns null, so callers
+     * that need a concrete target (the DB browser) default to the profile Radar is bound to
+     * rather than blindly to user 0.
+     */
+    resolveActiveUser(): string;
     getCaptureFilePath(): string | null;
     screenshot(fullRes: boolean): string;
     recordScreen(durationS: number): string;

package/dist/shared/android.js

@@ -149,6 +149,16 @@ export class AndroidTransport {
     getActiveUserId() {
         return this.detectedUserId;
     }
+    /**
+     * Resolve the Android user the debug build is actually running as: the already-detected
+     * user if known, else a `ps`-based detection (which prefers the non-zero/secondary profile
+     * the work build runs under). Unlike getActiveUserId() this never returns null, so callers
+     * that need a concrete target (the DB browser) default to the profile Radar is bound to
+     * rather than blindly to user 0.
+     */
+    resolveActiveUser() {
+        return this.detectDebugBuildUser();
+    }
     getCaptureFilePath() {
         return getCaptureFilePath();
     }

package/dist/shared/constants.d.ts

@@ -4,6 +4,20 @@ export declare const RADAR_PORT = 8099;
 export declare const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export declare const MAX_LOCAL_BUFFER = 500;
+/**
+ * Max parsed logcat frames the web dashboard retains for the whole server
+ * session. The device does not buffer logcat host-side, so the dashboard keeps
+ * its own session ring and replays it to every newly connected stream — this is
+ * what lets a tab switch (which reopens the SSE stream) show the full history
+ * instead of only the lines that arrive after the reconnect. Bounded so a long,
+ * chatty session cannot grow without limit. logcat is captured for ALL apps (the
+ * dashboard filters by package client-side), so the depth is sized for an all-app
+ * stream: at typical line sizes this keeps the buffer well under ~10 MB (a
+ * stack-trace-heavy session runs larger per line, so treat this as a typical, not
+ * a hard, ceiling). Like Android Studio's logcat, retention is a bounded ring —
+ * the oldest lines age out once the cap is reached, not kept forever.
+ */
+export declare const MAX_LOG_SESSION_BUFFER = 20000;
 /**
  * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
  * tool POSTs its spec to the same port the web server listens on; both honor the

package/dist/shared/constants.js

@@ -4,6 +4,20 @@ export const RADAR_PORT = 8099;
 export const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export const MAX_LOCAL_BUFFER = 500;
+/**
+ * Max parsed logcat frames the web dashboard retains for the whole server
+ * session. The device does not buffer logcat host-side, so the dashboard keeps
+ * its own session ring and replays it to every newly connected stream — this is
+ * what lets a tab switch (which reopens the SSE stream) show the full history
+ * instead of only the lines that arrive after the reconnect. Bounded so a long,
+ * chatty session cannot grow without limit. logcat is captured for ALL apps (the
+ * dashboard filters by package client-side), so the depth is sized for an all-app
+ * stream: at typical line sizes this keeps the buffer well under ~10 MB (a
+ * stack-trace-heavy session runs larger per line, so treat this as a typical, not
+ * a hard, ceiling). Like Android Studio's logcat, retention is a bounded ring —
+ * the oldest lines age out once the cap is reached, not kept forever.
+ */
+export const MAX_LOG_SESSION_BUFFER = 20000;
 /**
  * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
  * tool POSTs its spec to the same port the web server listens on; both honor the

package/dist/shared/db.d.ts

@@ -0,0 +1,75 @@
+/**
+ * On-device SQLite browser (host-side, read-only).
+ *
+ * Slack's on-device databases are plaintext SQLite (not SQLCipher) on a debug build,
+ * which is what makes host-side reading possible at all: `adb exec-out "run-as <pkg>
+ * cat databases/<db>"` streams the file to the host, where the platform-tools `sqlite3`
+ * binary runs read-only SELECT/PRAGMA against a local copy. Nothing is written on the
+ * device; no app rebuild is needed. If a future build encrypts these DBs, the magic-header
+ * check in `pullDatabase` fails fast with a clear message rather than producing garbage.
+ *
+ * SECURITY: a pulled DB is the full message store in plaintext (request bodies, message
+ * text, user/channel IDs). Pulled copies are written 0600 under a dedicated tmp dir and
+ * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
+ * live from the device (`listDatabases`); none are baked into this file.
+ */
+/** Initialize DB_TMP with a port-scoped path. Call from the web server on startup. */
+export declare function initializeDatabasePath(port: number): void;
+export declare function availableUsers(): string[];
+/**
+ * Reset cached device state. Clears the sqlite-binary path so a device swap
+ * re-detects it. The targeted Android user is passed explicitly to every call
+ * (sourced from the dashboard's bound profile) rather than guessed, so list / pull /
+ * query can never silently disagree on which profile's store they touch.
+ */
+export declare function resetDbState(): void;
+/**
+ * List the on-device databases for the given Android user (the dashboard's bound
+ * profile). Filters out WAL/SHM/journal sidecar files. Returns the resolved user and
+ * the full set of profiles that have the build, so the UI can show which profile this
+ * store belongs to and offer a switch when more than one exists.
+ */
+export declare function listDatabases(user?: string | null): {
+    user: string;
+    availableUsers: string[];
+    names: string[];
+};
+/**
+ * Stream a database off the device to a local 0600 copy (scoped to the target user) and
+ * return its path. `run-as ... cp` into shared storage fails silently (sandbox), so the
+ * working path is `exec-out cat` piped to a host file. Validates the SQLite magic header
+ * so a missing DB (whose `cat` emits an error string, not file bytes) fails with a clear
+ * message instead of being written as a junk file that later trips an opaque parse error.
+ *
+ * WAL: Slack's on-device DBs are WAL-mode and the live app holds write connections open,
+ * so recently-committed rows live in the `-wal` sidecar, NOT yet in the main file. Pulling
+ * the main file alone (and reading it `immutable`) silently drops those recent rows — the
+ * exact data a debugger wants. So we also pull the `-wal` and `-shm` sidecars next to the
+ * main copy (best-effort; absent if the DB was checkpointed), and queryDatabase opens the
+ * copy NORMALLY (not immutable) so SQLite replays the WAL into the view.
+ */
+export declare function pullDatabase(name: string, user?: string | null, force?: boolean): Promise<string>;
+/**
+ * Run a read-only query against a (lazily pulled) local copy.
+ *
+ * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
+ * opened DB, but a single SELECT can still READ any host file the process can open, via
+ * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
+ * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
+ * or a pushed db-spec's `sql`. Three layers close this:
+ *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ *      control; a keyword denylist alone is whack-a-mole.
+ *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
+ *      explicit reject of attach/readfile/writefile names as defense in depth.
+ *   3. `-readonly` still blocks writes to the opened DB.
+ * Surfaces sqlite's own error message on failure.
+ */
+export declare function queryDatabase(name: string, sql: string, user?: string | null): Promise<unknown[]>;
+/** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */
+export declare function pulledSize(name: string, user?: string | null): number;
+/**
+ * Remove all pulled database copies. Pulled DBs are plaintext message stores, so they
+ * must not linger; call on server start and stop. Best-effort.
+ */
+export declare function cleanupPulledDatabases(): void;

package/dist/shared/db.js

@@ -0,0 +1,403 @@
+/**
+ * On-device SQLite browser (host-side, read-only).
+ *
+ * Slack's on-device databases are plaintext SQLite (not SQLCipher) on a debug build,
+ * which is what makes host-side reading possible at all: `adb exec-out "run-as <pkg>
+ * cat databases/<db>"` streams the file to the host, where the platform-tools `sqlite3`
+ * binary runs read-only SELECT/PRAGMA against a local copy. Nothing is written on the
+ * device; no app rebuild is needed. If a future build encrypts these DBs, the magic-header
+ * check in `pullDatabase` fails fast with a clear message rather than producing garbage.
+ *
+ * SECURITY: a pulled DB is the full message store in plaintext (request bodies, message
+ * text, user/channel IDs). Pulled copies are written 0600 under a dedicated tmp dir and
+ * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
+ * live from the device (`listDatabases`); none are baked into this file.
+ */
+import { execFile, execFileSync } from "child_process";
+import { promisify } from "util";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { resolveAdbPath } from "./android.js";
+/** The debug build whose sandbox we can `run-as` into. */
+const DB_PKG = "com.Slack.internal.debug";
+/** Dedicated tmp dir for pulled DB copies. Cleaned on start/stop; files written 0600. Port-scoped so concurrent dashboards do not collide. */
+let DB_TMP = path.join(os.tmpdir(), "slack-radar-db");
+/** Initialize DB_TMP with a port-scoped path. Call from the web server on startup. */
+export function initializeDatabasePath(port) {
+    DB_TMP = path.join(os.tmpdir(), `slack-radar-db-${port}`);
+}
+/** Every valid SQLite file begins with these 16 bytes. */
+const SQLITE_MAGIC = Buffer.from("SQLite format 3\0", "binary");
+const ADB_MAX_BUFFER = 256 * 1024 * 1024; // an org message DB can be several MB
+const SQLITE_MAX_BUFFER = 64 * 1024 * 1024;
+// No cached user preference: the target user is passed explicitly to every call (sourced
+// from the dashboard's bound profile / the operator's profile switcher), never guessed.
+// Caching the sqlite binary path is safe because the binary does not change during a session.
+let cachedSqlite = null;
+function adbBin() {
+    const p = resolveAdbPath();
+    if (!p)
+        throw new Error("adb not found. Ensure platform-tools is installed and on PATH.");
+    return p;
+}
+function runAdb(args, opts = {}) {
+    return execFileSync(adbBin(), args, {
+        timeout: 15000,
+        maxBuffer: ADB_MAX_BUFFER,
+        ...opts,
+    });
+}
+const execFileP = promisify(execFile);
+// Async adb/exec — used for the HEAVY operations (the multi-MB device pull and the sqlite
+// query over it). These must NOT use execFileSync: Node is single-threaded, so a blocking
+// 62MB exec-out or a sqlite read freezes the whole event loop (every tab, the stream, and
+// /health hang until it returns). The light, cached probes (ls, pm list users) stay sync.
+function runAdbAsync(args) {
+    // buffer encoding: the pull streams raw SQLite bytes, not text.
+    return execFileP(adbBin(), args, {
+        timeout: 30000,
+        maxBuffer: ADB_MAX_BUFFER,
+        encoding: "buffer",
+    }).then((r) => r.stdout);
+}
+/**
+ * Locate a host `sqlite3`. The Slack on-device DBs use FTS5 virtual tables (search index),
+ * so a binary WITHOUT the fts5 module fails with "no such module: fts5" on those tables —
+ * including the per-table COUNT the browser runs. Android platform-tools' bundled sqlite3 is
+ * built without fts5; the macOS system /usr/bin/sqlite3 has it. So prefer an fts5-capable
+ * binary, and only fall back to a working-but-fts5-less one if none has it (non-FTS DBs still
+ * work there). Cached after first success.
+ */
+function hasSqlite(bin) {
+    try {
+        execFileSync(bin, ["--version"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasFts5(bin) {
+    try {
+        // throws "no such module: fts5" on a binary built without it
+        execFileSync(bin, [":memory:", "CREATE VIRTUAL TABLE t USING fts5(x);"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sqliteBin() {
+    if (cachedSqlite)
+        return cachedSqlite;
+    const candidates = [
+        "/usr/bin/sqlite3", // macOS system build: has fts5
+        "/opt/homebrew/bin/sqlite3",
+        "/usr/local/bin/sqlite3",
+        path.join(process.env.HOME ?? "", "Library/Android/sdk/platform-tools/sqlite3"),
+        "sqlite3",
+    ];
+    const working = candidates.filter(hasSqlite);
+    // Prefer one with fts5; else any working sqlite3 (non-FTS DBs still query fine).
+    cachedSqlite = working.find(hasFts5) ?? working[0] ?? "sqlite3";
+    return cachedSqlite;
+}
+/**
+ * Enumerate the Android user IDs present on the device from `pm list users`, whose lines
+ * read `UserInfo{<id>:<name>:<flags>} ...`. Returns the numeric ids as strings, in device
+ * order (personal 0 first, then profiles 10/11/12/... — NOT a hardcoded guess, so a second
+ * work profile or a cloned profile is covered). Empty on parse/adb failure.
+ */
+function deviceUserIds() {
+    try {
+        const out = runAdb(["shell", "pm list users"]).toString();
+        const ids = [];
+        for (const m of out.matchAll(/UserInfo\{(\d+):/g))
+            ids.push(m[1]);
+        return ids;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Probe whether the debug build is runnable for an Android user. Used to filter the
+ * device's users down to the profiles that actually have the build (a multi-profile device
+ * may have it on personal=0 and a work profile=10/11/..., each holding a DIFFERENT org's store).
+ */
+function userHasBuild(user) {
+    try {
+        runAdb([
+            "shell",
+            `run-as ${DB_PKG} ${user ? "--user " + user : ""} ls databases >/dev/null 2>&1 && echo ok`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Android users that actually have the debug build, enumerated from the device (not a
+ * fixed list). "" means a single-user device (no --user flag). Empty array => build not
+ * installed/debuggable anywhere.
+ *
+ * CACHED: this runs `pm list users` + a `run-as` probe per user — several blocking adb
+ * round-trips. The set of profiles does not change during a session, so probing it on every
+ * /dbs request froze the (single-threaded) event loop and hung the whole dashboard. Resolve
+ * it once and reuse; resetDbState() clears it for a device/profile change.
+ */
+let cachedUsers = null;
+export function availableUsers() {
+    if (cachedUsers)
+        return cachedUsers;
+    const ids = deviceUserIds();
+    const found = ids.filter(userHasBuild);
+    // Fallback for an older adb / odd `pm` output: try the no-flag form.
+    const resolved = found.length ? found : userHasBuild("") ? [""] : [];
+    if (resolved.length)
+        cachedUsers = resolved; // only cache a successful probe
+    return resolved;
+}
+/** `--user N` flag for a resolved user, or "" for the single-user case. */
+function userFlag(user) {
+    return user ? `--user ${user}` : "";
+}
+/**
+ * Reset cached device state. Clears the sqlite-binary path so a device swap
+ * re-detects it. The targeted Android user is passed explicitly to every call
+ * (sourced from the dashboard's bound profile) rather than guessed, so list / pull /
+ * query can never silently disagree on which profile's store they touch.
+ */
+export function resetDbState() {
+    cachedSqlite = null;
+    cachedUsers = null;
+}
+/** A DB name from the device. Reject anything that is not a bare filename. */
+function assertSafeName(name) {
+    if (!name || !/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new Error("invalid database name");
+    }
+}
+/**
+ * Local copy path, scoped by Android user. A work + personal profile can each hold a
+ * databases/<same-name> with DIFFERENT contents; without the user in the path, pulling
+ * one would overwrite the other's copy and queries would read the wrong profile's store.
+ */
+function localPath(name, user) {
+    const safeName = name.replace(/[^A-Za-z0-9._-]/g, "_");
+    const safeUser = (user || "single").replace(/[^A-Za-z0-9._-]/g, "_");
+    return path.join(DB_TMP, `u${safeUser}-${safeName}.sqlite`);
+}
+/**
+ * Resolve the Android user to target. The dashboard passes the profile it is bound to
+ * (transport.getActiveUserId()); if that user does not have the build (or none was
+ * passed), fall back to the first available profile. Throws if none is available.
+ */
+function resolveUser(user) {
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    if (user != null && available.includes(user))
+        return user;
+    return available[0];
+}
+/**
+ * List the on-device databases for the given Android user (the dashboard's bound
+ * profile). Filters out WAL/SHM/journal sidecar files. Returns the resolved user and
+ * the full set of profiles that have the build, so the UI can show which profile this
+ * store belongs to and offer a switch when more than one exists.
+ */
+export function listDatabases(user) {
+    // NOTE: do not resetDbState() here — that would re-run the multi-call user probe on every
+    // /dbs and freeze the event loop. The profile set is cached for the session; a device or
+    // profile change clears it via resetDbState() (wired to /enable / reconnect).
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    const u = user != null && available.includes(user) ? user : available[0];
+    const out = runAdb([
+        "shell",
+        `run-as ${DB_PKG} ${userFlag(u)} ls -1 databases`,
+    ]).toString();
+    const names = out
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .filter((n) => !/-(wal|shm|journal)$/.test(n));
+    return { user: u, availableUsers: available, names };
+}
+/**
+ * Stream a database off the device to a local 0600 copy (scoped to the target user) and
+ * return its path. `run-as ... cp` into shared storage fails silently (sandbox), so the
+ * working path is `exec-out cat` piped to a host file. Validates the SQLite magic header
+ * so a missing DB (whose `cat` emits an error string, not file bytes) fails with a clear
+ * message instead of being written as a junk file that later trips an opaque parse error.
+ *
+ * WAL: Slack's on-device DBs are WAL-mode and the live app holds write connections open,
+ * so recently-committed rows live in the `-wal` sidecar, NOT yet in the main file. Pulling
+ * the main file alone (and reading it `immutable`) silently drops those recent rows — the
+ * exact data a debugger wants. So we also pull the `-wal` and `-shm` sidecars next to the
+ * main copy (best-effort; absent if the DB was checkpointed), and queryDatabase opens the
+ * copy NORMALLY (not immutable) so SQLite replays the WAL into the view.
+ */
+export async function pullDatabase(name, user, force = false) {
+    assertSafeName(name);
+    const u = resolveUser(user);
+    // DB_TMP lives under os.tmpdir(), which the OS (or a manual cleanup) can wipe
+    // mid-session; recreate it every pull so writeFileSync cannot ENOENT on a gone dir.
+    // mode 0700: the pulled copies are the plaintext message store; even though each file is
+    // 0600, a world-traversable dir would leak the DB filenames to other local users.
+    fs.mkdirSync(DB_TMP, { recursive: true, mode: 0o700 });
+    const local = localPath(name, u);
+    // Pull-once: an on-device DB can be several MB and writes a plaintext copy to disk, so
+    // reuse the existing local copy across db-switches. The UI's Refresh control passes
+    // force=true to re-stream when the user wants the current device state.
+    if (!force && fs.existsSync(local))
+        return local;
+    let bytes;
+    try {
+        // Async exec-out so a multi-MB pull does not block the event loop (which would hang
+        // every other tab, the stream, and /health for the duration of the pull).
+        bytes = await runAdbAsync([
+            "exec-out",
+            `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}`,
+        ]);
+    }
+    catch {
+        throw new Error(`"${name}" is not readable on the device (not present for this profile, or run-as failed). List databases to see what is there.`);
+    }
+    if (!bytes ||
+        bytes.length < SQLITE_MAGIC.length ||
+        !bytes.subarray(0, SQLITE_MAGIC.length).equals(SQLITE_MAGIC)) {
+        throw new Error(`"${name}" did not come back as a valid SQLite file (${bytes ? bytes.length : 0} bytes). It may not exist on the device, the org may not be loaded on this profile, or the database may be encrypted.`);
+    }
+    fs.writeFileSync(local, bytes, { mode: 0o600 });
+    // Pull the WAL sidecars alongside the main file so the normal (non-immutable) open below
+    // replays recently-committed rows. Best-effort: a checkpointed DB has none; a `cat` of a
+    // missing sidecar returns empty, which we simply skip. Stale local sidecars from a prior
+    // pull are removed first so they cannot be mis-applied to a freshly-pulled main file.
+    // The main file and the sidecars are separate `cat` round-trips against a DB the app may
+    // be writing, so the snapshot is best-effort, not atomic: if the app checkpoints between
+    // the cats, SQLite finds a mismatched -wal salt and ignores it (a partial, not corrupt,
+    // view). Unavoidable without a device-side read lock; the normal-open choice still stands.
+    for (const ext of ["-wal", "-shm"]) {
+        const sidecar = local + ext;
+        try {
+            fs.rmSync(sidecar, { force: true });
+            const sb = await runAdbAsync([
+                "exec-out",
+                `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}${ext}`,
+            ]);
+            if (sb && sb.length > 0)
+                fs.writeFileSync(sidecar, sb, { mode: 0o600 });
+        }
+        catch {
+            // sidecar absent or unreadable — fine, the main file stands alone
+        }
+    }
+    return local;
+}
+/**
+ * Run a read-only query against a (lazily pulled) local copy.
+ *
+ * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
+ * opened DB, but a single SELECT can still READ any host file the process can open, via
+ * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
+ * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
+ * or a pushed db-spec's `sql`. Three layers close this:
+ *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ *      control; a keyword denylist alone is whack-a-mole.
+ *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
+ *      explicit reject of attach/readfile/writefile names as defense in depth.
+ *   3. `-readonly` still blocks writes to the opened DB.
+ * Surfaces sqlite's own error message on failure.
+ */
+export async function queryDatabase(name, sql, user) {
+    assertSafeName(name);
+    // Leading-keyword gate over the common read-query entry forms: SELECT, WITH
+    // (CTEs, common against the message store), EXPLAIN, VALUES, PRAGMA. This shapes
+    // UX; it is NOT the security boundary. A `WITH ... DELETE` would slip the gate,
+    // but the device-safety property does not rest here — it rests on the copy-based
+    // design (the device file is `cat`'d to a throwaway and never written back), plus
+    // `-safe` (blocks file access), the single-statement gate, the write-PRAGMA
+    // reject, and the file-primitive denylist below. Worst case a smuggled write
+    // mutates the disposable copy; the device store is untouched.
+    if (!/^\s*(select|pragma|with|explain|values)\b/i.test(sql)) {
+        throw new Error("only read-only statements are allowed (SELECT, WITH, EXPLAIN, VALUES, PRAGMA)");
+    }
+    // Single statement only: a trailing `;` is fine, but no statement chaining (which is how
+    // `select 1; ATTACH ...; select * from s.t` smuggles a read past the leading-keyword check).
+    if (/;\s*\S/.test(sql)) {
+        throw new Error("only a single statement is allowed (no ';'-separated statements)");
+    }
+    // Reject the common write PRAGMAs: an assigning form (`PRAGMA user_version=5`,
+    // `PRAGMA journal_mode=DELETE`) or a checkpoint (`PRAGMA wal_checkpoint(...)`).
+    // This is not exhaustive — a few argless mutating PRAGMAs (`incremental_vacuum`,
+    // `optimize`, `shrink_memory`) still pass. That is acceptable: the device-safety
+    // guarantee comes from the copy-based design (we only ever read the device file
+    // and write a throwaway local copy), not from this gate. Worst case such a PRAGMA
+    // mutates the disposable copy; the device store is never written back.
+    if (/^\s*pragma\b/i.test(sql) && (/=/.test(sql) || /\bwal_checkpoint\b/i.test(sql))) {
+        throw new Error("that PRAGMA writes; only read-only PRAGMAs are allowed");
+    }
+    // Belt-and-suspenders over -safe: reject the file-access primitives by name too.
+    if (/\b(attach|readfile|writefile|edit|load_extension|fts3_tokenizer)\b/i.test(sql)) {
+        throw new Error("that function/statement is not allowed (read-only, no file access)");
+    }
+    const u = resolveUser(user);
+    const local = localPath(name, u);
+    if (!fs.existsSync(local))
+        await pullDatabase(name, u);
+    let out;
+    try {
+        // Open the pulled copy NORMALLY (not `immutable`, not `-readonly`): pullDatabase brought
+        // the -wal/-shm sidecars along, and only a normal open replays the WAL so recently-
+        // committed rows (which live in -wal until the app checkpoints) are visible. immutable=1
+        // / -readonly would read the main file alone and silently drop those rows. The copy is in
+        // our own writable temp dir, so SQLite can do its WAL replay there; nothing on the device
+        // is touched. `-safe` is the load-bearing read-only/exfil control (blocks ATTACH/readfile/
+        // writefile/load_extension at the engine level) and holds in normal mode too. The path is
+        // URI-encoded so spaces/specials are safe. Async exec so a large query does not block the
+        // event loop.
+        const uri = `file:${encodeURI(local)}`;
+        const r = await execFileP(sqliteBin(), ["-safe", "-json", uri, sql], {
+            timeout: 15000,
+            maxBuffer: SQLITE_MAX_BUFFER,
+            encoding: "utf8",
+        });
+        out = String(r.stdout) || "[]";
+    }
+    catch (e) {
+        const err = e;
+        const stderr = (err.stderr && err.stderr.toString().trim()) || "";
+        const m = stderr.match(/(no such table:.*|no such column:.*|near ".*|syntax error.*|.*error.*)/i);
+        throw new Error(m ? m[0].trim() : stderr.split("\n")[0] || "query failed");
+    }
+    return JSON.parse(out);
+}
+/** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */
+export function pulledSize(name, user) {
+    try {
+        return fs.statSync(localPath(name, resolveUser(user))).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Remove all pulled database copies. Pulled DBs are plaintext message stores, so they
+ * must not linger; call on server start and stop. Best-effort.
+ */
+export function cleanupPulledDatabases() {
+    try {
+        fs.rmSync(DB_TMP, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort
+    }
+}