alvin-bot 4.13.0 → 4.13.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.13.1] — 2026-04-16
+
+### 🐛 Patch: Slack Test Connection + PM2 → launchd migration for Maintenance UI
+
+Two latent UI bugs surfaced during live Slack setup:
+
+**Bug 1 — `/api/platforms/test-connection` returned "Unknown platform" for Slack.** The handler in `setup-api.ts` only knew about telegram/discord/signal/whatsapp. Users who entered a valid Bot Token (`xoxb-…`) + App Token (`xapp-…`) and clicked Test Connection got a confusing "Unknown platform" error — couldn't tell if their tokens were wrong or the feature was broken.
+
+**Fix:** New `slack` case in the handler. Validates Bot Token via `https://slack.com/api/auth.test` (cheap, ~100ms). For App Token, checks the `xapp-` prefix as the quickest sanity check (Socket Mode can't actually be "pinged" without opening a persistent WebSocket). Returns the authenticated bot user + team name on success, or Slack's own `auth.test` error (e.g. `invalid_auth`, `token_expired`) on failure. Warns if App Token is missing or has wrong prefix even when Bot Token is valid — helps users notice they only configured half the pair.
+
+**Bug 2 — Maintenance section's buttons were broken on macOS launchd installs.** Since v4.8 the macOS install runs under `launchd` (`com.alvinbot.app.plist`), not PM2. But `doctor-api.ts` kept calling `pm2 jlist`/`pm2 restart`/`pm2 stop`/`pm2 logs`. Results: status endpoint returned stale data from ghost PM2 entries (uptime/memory/cpu/restarts all wrong), Stop/Start buttons silently failed, log viewer was empty. The Restart button accidentally worked because it used `scheduleGracefulRestart` (launchd's `KeepAlive` auto-brings-back on exit).
+
+**Fix:** New `src/services/process-manager.ts` abstraction that auto-detects the active supervisor per request:
+- **launchd** (macOS) if `launchctl print gui/$UID/com.alvinbot.app` succeeds
+- **pm2** (VPS / legacy installs) if `pm2 jlist` lists our process
+- **standalone** if neither (fallback — only Restart works, since there's no supervisor to bring the process back)
+
+Each manager implements `getStatus()`, `stop()`, `start()`, `getLogs()` with the right tooling:
+- launchd: `launchctl print` + `ps -p <pid> -o %cpu=,%mem=,rss=,etime=` for resource stats, `launchctl bootout` / `bootstrap` for stop/start, `tail` on the known log paths for logs
+- pm2: unchanged — `pm2 jlist` / `pm2 stop` / `pm2 start` / `pm2 logs`
+- standalone: `process.uptime()` / `process.memoryUsage()` / manual log tailing
+
+The WebUI routes (`/api/pm2/status`, `/api/pm2/action`, `/api/pm2/logs`) keep their names for compat but now dispatch via `detectProcessManager()`. Real-world verified against the running bot: detection returned `launchd`, PID/uptime/memory all correct from the actual launchd-managed process (not a stale PM2 ghost).
+
+### Testing
+
+- **Baseline**: 460 tests (v4.13.0)
+- **New**:
+  - `test/slack-test-connection.test.ts` — 5 tests (no tokens set, auth.test accepts, auth.test rejects, App Token format warning, unknown platform regression)
+  - `test/process-manager.test.ts` — 10 tests (detection order, each manager's status parsing, stop/start command dispatch)
+- **Total**: 475 tests, all green, TSC clean
+- **Live verification**: ran `detectProcessManager().getStatus()` against the actual running bot → returned `launchd`, PID 4767 (matches `launchctl print pid = 4767`), uptime 655s, memory 76MB — all real data, not stale PM2 cache
+
+### Files changed
+
+- **NEW**: `src/services/process-manager.ts`, `test/slack-test-connection.test.ts`, `test/process-manager.test.ts`
+- **Modified**: `src/web/setup-api.ts` (+slack case in test-connection), `src/web/doctor-api.ts` (routes use process-manager abstraction), `package.json` (4.13.0 → 4.13.1)
+
+### Known limitations (deferred to v4.14)
+
+- **Slack subagent support**: v4.13.0's `mcp__alvin__dispatch_agent` tool only activates on the Telegram handler (passes `alvinDispatchContext`). Slack users can receive normal replies but can't trigger background sub-agents yet. Requires extending `PendingAsyncAgent.chatId` to `number | string`, adding `platform` to the watcher's pending record, and making `subagent-delivery.ts` platform-aware. Tracked for v4.14.
+
+---
+
 ## [4.13.0] — 2026-04-16
 
 ### ✨ Major: truly detached sub-agent dispatch via `alvin_dispatch_agent` MCP tool

package/dist/services/process-manager.js

@@ -0,0 +1,291 @@
+/**
+ * v4.13.1 — Process manager abstraction for the Maintenance Web UI.
+ *
+ * History: the bot was originally PM2-managed. Since v4.8 the macOS
+ * install uses launchd (`com.alvinbot.app.plist`). The WebUI
+ * Maintenance section kept calling `pm2 jlist`/`pm2 restart`/...
+ * which returned "PM2 not available" for launchd users — all status,
+ * stop, start, and logs buttons were broken.
+ *
+ * This module auto-detects the active manager per request and
+ * routes commands accordingly:
+ *
+ *   - launchd (macOS) — via `launchctl print` / `bootout` / `bootstrap`
+ *   - pm2 (VPS / Linux) — via `pm2 jlist` / `pm2 stop` / `pm2 start`
+ *   - standalone — no supervisor; only `scheduleGracefulRestart` works
+ *
+ * Restart is NOT on this interface — it always uses
+ * `scheduleGracefulRestart` (Grammy-safe) and relies on whichever
+ * supervisor is present to bring the process back. For "standalone",
+ * a restart effectively kills the process and the user has to run it
+ * again manually (we warn in the UI).
+ */
+import { execSync } from "node:child_process";
+import os from "node:os";
+import { resolve } from "node:path";
+const LAUNCHD_LABEL = "com.alvinbot.app";
+const LAUNCHD_PLIST = resolve(os.homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+const PM2_NAME = "alvin-bot";
+// ── Detection ───────────────────────────────────────────────────
+export function detectProcessManager(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const uid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+    // Only try launchd on macOS
+    if (platform === "darwin") {
+        try {
+            const out = execSync(`launchctl print gui/${uid}/${LAUNCHD_LABEL}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" });
+            if (out && out.length > 0) {
+                return createLaunchdManager(uid);
+            }
+        }
+        catch {
+            // Not loaded in launchd — fall through
+        }
+    }
+    // PM2 fallback (Linux VPS, or Mac installs that stayed on PM2)
+    try {
+        const out = execSync("pm2 jlist", {
+            encoding: "utf-8",
+            timeout: 3000,
+            stdio: "pipe",
+        });
+        const parsed = JSON.parse(out);
+        if (Array.isArray(parsed) &&
+            parsed.some((p) => p?.name === PM2_NAME)) {
+            return createPm2Manager();
+        }
+    }
+    catch {
+        // pm2 not installed or didn't report our process
+    }
+    return createStandaloneManager();
+}
+function parseLaunchdPrint(text) {
+    const out = {};
+    // state = running
+    const stateMatch = text.match(/\bstate\s*=\s*(\S+)/);
+    if (stateMatch)
+        out.state = stateMatch[1];
+    // pid = 12345
+    const pidMatch = text.match(/\bpid\s*=\s*(\d+)/);
+    if (pidMatch)
+        out.pid = Number(pidMatch[1]);
+    // program = /path/to/node
+    const programMatch = text.match(/\bprogram\s*=\s*(\S+)/);
+    if (programMatch)
+        out.program = programMatch[1];
+    // working directory = /path
+    const cwdMatch = text.match(/\bworking directory\s*=\s*(\S+)/);
+    if (cwdMatch)
+        out.cwd = cwdMatch[1];
+    return out;
+}
+export function createLaunchdManager(uid) {
+    const service = `gui/${uid}/${LAUNCHD_LABEL}`;
+    return {
+        kind: "launchd",
+        async getStatus() {
+            try {
+                const out = execSync(`launchctl print ${service}`, {
+                    encoding: "utf-8",
+                    timeout: 3000,
+                    stdio: "pipe",
+                });
+                const parsed = parseLaunchdPrint(out);
+                const pid = parsed.pid;
+                // Enrich with ps info if we have a PID
+                let memory;
+                let cpu;
+                let uptime;
+                if (pid) {
+                    try {
+                        // ps output: %cpu %mem rss etime
+                        const psOut = execSync(`ps -p ${pid} -o %cpu=,%mem=,rss=,etime=`, { encoding: "utf-8", timeout: 2000, stdio: "pipe" }).trim();
+                        const [cpuStr, , rssStr, etime] = psOut.split(/\s+/);
+                        cpu = parseFloat(cpuStr) || 0;
+                        memory = (parseInt(rssStr, 10) || 0) * 1024; // rss is kB
+                        uptime = parseEtimeToMs(etime);
+                    }
+                    catch {
+                        /* ps may fail if pid vanished — ignore */
+                    }
+                }
+                return {
+                    kind: "launchd",
+                    status: parsed.state === "running" ? "running" : parsed.state || "unknown",
+                    pid,
+                    uptime,
+                    memory,
+                    cpu,
+                    execPath: parsed.program,
+                    cwd: parsed.cwd,
+                    nodeVersion: process.version,
+                };
+            }
+            catch {
+                return { kind: "launchd", status: "not-loaded" };
+            }
+        },
+        async stop() {
+            // bootout removes the service from the domain, which stops it
+            // and disables KeepAlive until bootstrap is run again.
+            execSync(`launchctl bootout ${service}`, {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: "pipe",
+            });
+        },
+        async start() {
+            // bootstrap re-registers the plist with the domain.
+            execSync(`launchctl bootstrap gui/${uid} ${JSON.stringify(LAUNCHD_PLIST).slice(1, -1)}`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+        },
+        async getLogs(lines = 30) {
+            // launchd redirects stdout/stderr to files — just tail them.
+            const logDir = resolve(process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot"), "logs");
+            const outLog = resolve(logDir, "alvin-bot.out.log");
+            const errLog = resolve(logDir, "alvin-bot.err.log");
+            try {
+                return execSync(`tail -n ${lines} ${outLog} ${errLog} 2>/dev/null`, {
+                    encoding: "utf-8",
+                    timeout: 3000,
+                    stdio: "pipe",
+                });
+            }
+            catch {
+                return "No logs available.";
+            }
+        },
+    };
+}
+function parseEtimeToMs(etime) {
+    // ps etime format: "MM:SS", "HH:MM:SS", "D-HH:MM:SS"
+    if (!etime)
+        return undefined;
+    const parts = etime.split("-");
+    let days = 0;
+    let hms;
+    if (parts.length === 2) {
+        days = parseInt(parts[0], 10) || 0;
+        hms = parts[1];
+    }
+    else {
+        hms = parts[0];
+    }
+    const bits = hms.split(":").map((x) => parseInt(x, 10) || 0);
+    let h = 0, m = 0, s = 0;
+    if (bits.length === 3)
+        [h, m, s] = bits;
+    else if (bits.length === 2)
+        [m, s] = bits;
+    else
+        return undefined;
+    return (((days * 24 + h) * 60 + m) * 60 + s) * 1000;
+}
+export function createPm2Manager() {
+    return {
+        kind: "pm2",
+        async getStatus() {
+            try {
+                const out = execSync("pm2 jlist", {
+                    encoding: "utf-8",
+                    timeout: 3000,
+                    stdio: "pipe",
+                });
+                const procs = JSON.parse(out);
+                const me = procs.find((p) => p.name === PM2_NAME);
+                if (!me) {
+                    return { kind: "pm2", status: "unknown" };
+                }
+                const env = me.pm2_env ?? {};
+                return {
+                    kind: "pm2",
+                    status: env.status || "unknown",
+                    pid: me.pid,
+                    uptime: env.pm_uptime ? Date.now() - env.pm_uptime : undefined,
+                    memory: me.monit?.memory,
+                    cpu: me.monit?.cpu,
+                    restarts: env.restart_time ?? 0,
+                    version: env.version,
+                    nodeVersion: env.node_version || process.version,
+                    execPath: env.pm_exec_path,
+                    cwd: env.pm_cwd,
+                };
+            }
+            catch {
+                return { kind: "pm2", status: "unknown" };
+            }
+        },
+        async stop() {
+            execSync(`pm2 stop ${PM2_NAME}`, {
+                encoding: "utf-8",
+                timeout: 10_000,
+                stdio: "pipe",
+            });
+        },
+        async start() {
+            execSync(`pm2 start ${PM2_NAME}`, {
+                encoding: "utf-8",
+                timeout: 10_000,
+                stdio: "pipe",
+            });
+        },
+        async getLogs(lines = 30) {
+            try {
+                const raw = execSync(`pm2 logs ${PM2_NAME} --nostream --lines ${lines} 2>&1`, {
+                    encoding: "utf-8",
+                    timeout: 5000,
+                    stdio: "pipe",
+                    env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+                });
+                // eslint-disable-next-line no-control-regex
+                return raw.replace(/\x1b\[[0-9;]*m/g, "");
+            }
+            catch {
+                return "No logs available.";
+            }
+        },
+    };
+}
+// ── standalone ──────────────────────────────────────────────────
+export function createStandaloneManager() {
+    return {
+        kind: "standalone",
+        async getStatus() {
+            return {
+                kind: "standalone",
+                status: "running",
+                pid: process.pid,
+                uptime: process.uptime() * 1000,
+                memory: process.memoryUsage().rss,
+                nodeVersion: process.version,
+                execPath: process.execPath,
+                cwd: process.cwd(),
+            };
+        },
+        async stop() {
+            // No supervisor — just exit. User must restart manually.
+            setTimeout(() => process.exit(0), 300);
+        },
+        async start() {
+            // Cannot start ourselves if we're already running (nonsensical).
+            // Callers should not hit this path when status is "running".
+            throw new Error("standalone: cannot 'start' — no supervisor. Run the bot manually.");
+        },
+        async getLogs(lines = 30) {
+            // Standalone mode may or may not redirect stdout. Try the
+            // default ~/.alvin-bot/logs path first.
+            const logDir = resolve(process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot"), "logs");
+            const outLog = resolve(logDir, "alvin-bot.out.log");
+            try {
+                return execSync(`tail -n ${lines} ${outLog} 2>/dev/null`, {
+                    encoding: "utf-8",
+                    timeout: 3000,
+                    stdio: "pipe",
+                });
+            }
+            catch {
+                return "No logs available (standalone mode — stdout not captured).";
+            }
+        },
+    };
+}

package/dist/web/doctor-api.js

@@ -491,42 +491,42 @@ export async function handleDoctorAPI(req, res, urlPath, body) {
         scheduleGracefulRestart(500);
         return true;
     }
-    // ── PM2 Process Control ────────────────────────────────
-    // GET /api/pm2/status — Get PM2 process info
+    // ── Process Control (v4.13.1: launchd/pm2/standalone auto-detect) ──
+    //
+    // Routes kept under `/api/pm2/*` for UI compat — the UI still calls
+    // those paths. Under the hood we now use the process-manager
+    // abstraction which auto-detects launchd (macOS native installs)
+    // or pm2 (VPS / legacy Mac installs) or standalone (neither).
+    // GET /api/pm2/status — Get process info via detected manager
     if (urlPath === "/api/pm2/status") {
         try {
-            const output = execSync("pm2 jlist", { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-            const processes = JSON.parse(output);
-            // Find our process (by name or script)
-            const botProcess = processes.find((p) => p.name === "alvin-bot" ||
-                p.pm2_env?.pm_exec_path?.includes("alvin-bot")) || processes[0]; // fallback to first process
-            if (!botProcess) {
-                res.end(JSON.stringify({ error: "No PM2 process found" }));
-                return true;
-            }
-            const env = botProcess.pm2_env || {};
+            const { detectProcessManager } = await import("../services/process-manager.js");
+            const pm = detectProcessManager();
+            const status = await pm.getStatus();
             res.end(JSON.stringify({
                 process: {
-                    name: botProcess.name,
-                    pid: botProcess.pid,
-                    status: env.status || "unknown",
-                    uptime: env.pm_uptime ? Date.now() - env.pm_uptime : 0,
-                    memory: botProcess.monit?.memory || 0,
-                    cpu: botProcess.monit?.cpu || 0,
-                    restarts: env.restart_time || 0,
-                    version: env.version || "?",
-                    nodeVersion: env.node_version || process.version,
-                    execPath: env.pm_exec_path || "?",
-                    cwd: env.pm_cwd || "?",
+                    name: "alvin-bot",
+                    kind: status.kind,
+                    pid: status.pid ?? 0,
+                    status: status.status,
+                    uptime: status.uptime ?? 0,
+                    memory: status.memory ?? 0,
+                    cpu: status.cpu ?? 0,
+                    restarts: status.restarts ?? 0,
+                    version: status.version || "?",
+                    nodeVersion: status.nodeVersion || process.version,
+                    execPath: status.execPath || "?",
+                    cwd: status.cwd || "?",
                 },
             }));
         }
         catch (err) {
-            res.end(JSON.stringify({ error: "PM2 not available" }));
+            const msg = err instanceof Error ? err.message : String(err);
+            res.end(JSON.stringify({ error: `Process manager detection failed: ${msg}` }));
         }
         return true;
     }
-    // POST /api/pm2/action — Execute PM2 action (restart, stop, start, reload, flush)
+    // POST /api/pm2/action — Execute action via detected manager
     if (urlPath === "/api/pm2/action" && req.method === "POST") {
         try {
             const { action } = JSON.parse(body);
@@ -536,41 +536,44 @@ export async function handleDoctorAPI(req, res, urlPath, body) {
                 res.end(JSON.stringify({ ok: false, error: `Invalid action: ${action}` }));
                 return true;
             }
-            // Find our process name
-            let processName = "alvin-bot";
-            try {
-                const jlist = execSync("pm2 jlist", { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-                const procs = JSON.parse(jlist);
-                const found = procs.find((p) => p.name === "alvin-bot" || p.name === "alvin-bot");
-                if (found)
-                    processName = found.name;
-            }
-            catch { /* use default */ }
+            const { detectProcessManager } = await import("../services/process-manager.js");
+            const pm = detectProcessManager();
             if (action === "flush") {
-                execSync(`pm2 flush ${processName}`, { encoding: "utf-8", timeout: 10000, stdio: "pipe" });
+                // Truncate our own log files directly — works on both launchd
+                // and standalone. PM2's flush is also just truncation.
+                const logDir = resolve(DATA_DIR, "logs");
+                for (const f of ["alvin-bot.out.log", "alvin-bot.err.log"]) {
+                    try {
+                        fs.truncateSync(resolve(logDir, f), 0);
+                    }
+                    catch {
+                        /* file may not exist — ignore */
+                    }
+                }
                 res.end(JSON.stringify({ ok: true, message: "Logs flushed" }));
                 return true;
             }
             if (action === "stop") {
-                // Stop is special — we can't respond after stopping ourselves
-                res.end(JSON.stringify({ ok: true, message: "Bot is stopping..." }));
+                // Stop is special — can't respond after we've killed ourselves.
+                res.end(JSON.stringify({ ok: true, message: `Bot is stopping (${pm.kind})...` }));
                 setTimeout(() => {
-                    try {
-                        execSync(`pm2 stop ${processName}`, { timeout: 10000, stdio: "pipe" });
-                    }
-                    catch { /* process might already be dead */ }
+                    pm.stop().catch(() => {
+                        /* process might already be dead */
+                    });
                 }, 300);
                 return true;
             }
             if (action === "start") {
-                // Start the process if stopped
-                execSync(`pm2 start ${processName}`, { encoding: "utf-8", timeout: 10000, stdio: "pipe" });
-                res.end(JSON.stringify({ ok: true, message: "Bot started" }));
+                await pm.start();
+                res.end(JSON.stringify({ ok: true, message: `Bot started via ${pm.kind}` }));
                 return true;
             }
             if (action === "restart" || action === "reload") {
                 const { scheduleGracefulRestart } = await import("../services/restart.js");
-                res.end(JSON.stringify({ ok: true, message: `Bot is ${action === "restart" ? "restarting" : "reloading"}...` }));
+                res.end(JSON.stringify({
+                    ok: true,
+                    message: `Bot is ${action === "restart" ? "restarting" : "reloading"} (${pm.kind})...`,
+                }));
                 scheduleGracefulRestart(500);
                 return true;
             }
@@ -580,31 +583,20 @@ export async function handleDoctorAPI(req, res, urlPath, body) {
         }
         return true;
     }
-    // GET /api/pm2/logs — Get recent PM2 logs
+    // GET /api/pm2/logs — Get recent logs via detected manager
     if (urlPath === "/api/pm2/logs") {
         try {
-            // Find process name
-            let processName = "alvin-bot";
-            try {
-                const jlist = execSync("pm2 jlist", { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-                const procs = JSON.parse(jlist);
-                const found = procs.find((p) => p.name === "alvin-bot" || p.name === "alvin-bot");
-                if (found)
-                    processName = found.name;
-            }
-            catch { /* use default */ }
-            let logs = execSync(`pm2 logs ${processName} --nostream --lines 30 2>&1`, {
-                encoding: "utf-8",
-                timeout: 5000,
-                stdio: "pipe",
-                env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
-            });
-            // Strip ANSI escape codes
-            logs = logs.replace(/\x1b\[[0-9;]*m/g, "");
-            res.end(JSON.stringify({ logs }));
+            const { detectProcessManager } = await import("../services/process-manager.js");
+            const pm = detectProcessManager();
+            const logs = await pm.getLogs(30);
+            res.end(JSON.stringify({ logs, kind: pm.kind }));
         }
         catch (err) {
-            res.end(JSON.stringify({ error: "Logs not available", logs: "" }));
+            res.end(JSON.stringify({
+                error: "Logs not available",
+                logs: "",
+                detail: err instanceof Error ? err.message : String(err),
+            }));
         }
         return true;
     }

package/dist/web/setup-api.js

@@ -874,6 +874,58 @@ export async function handleSetupAPI(req, res, urlPath, body) {
                 }
                 return true;
             }
+            if (platformId === "slack") {
+                // v4.13.1 — Validate Slack config via auth.test (Bot Token) +
+                // format check on App Token (xapp-). We can't actually "ping"
+                // Socket Mode without opening a WebSocket, so we rely on the
+                // App Token prefix as the cheapest sanity check.
+                const botToken = process.env.SLACK_BOT_TOKEN;
+                const appToken = process.env.SLACK_APP_TOKEN;
+                if (!botToken) {
+                    res.end(JSON.stringify({ ok: false, error: "SLACK_BOT_TOKEN not set" }));
+                    return true;
+                }
+                try {
+                    const apiRes = await fetch("https://slack.com/api/auth.test", {
+                        method: "POST",
+                        headers: {
+                            "Authorization": `Bearer ${botToken}`,
+                            "Content-Type": "application/x-www-form-urlencoded",
+                        },
+                    });
+                    const data = await apiRes.json();
+                    if (!data.ok) {
+                        res.end(JSON.stringify({
+                            ok: false,
+                            error: `Slack rejected Bot Token: ${data.error || "unknown error"}`,
+                        }));
+                        return true;
+                    }
+                    // Bot Token valid. Now check App Token format — Socket Mode
+                    // requires it and the xapp- prefix is the quickest sanity check.
+                    let warning = "";
+                    if (!appToken) {
+                        warning = " ⚠️ SLACK_APP_TOKEN not set — Socket Mode will fail.";
+                    }
+                    else if (!appToken.startsWith("xapp-")) {
+                        warning =
+                            " ⚠️ SLACK_APP_TOKEN has wrong prefix (expected xapp-) — Socket Mode will fail.";
+                    }
+                    res.end(JSON.stringify({
+                        ok: true,
+                        info: `@${data.user} on ${data.team} (team_id: ${data.team_id}, bot_id: ${data.bot_id})` +
+                            warning,
+                    }));
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    res.end(JSON.stringify({
+                        ok: false,
+                        error: `Failed to reach slack.com/api/auth.test: ${msg}`,
+                    }));
+                }
+                return true;
+            }
             res.end(JSON.stringify({ ok: false, error: "Unknown platform" }));
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "description": "Alvin Bot \u2014 Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/process-manager.test.ts

@@ -0,0 +1,186 @@
+/**
+ * v4.13.1 — process-manager abstraction tests.
+ *
+ * The maintenance section in the Web UI used to hard-wire PM2 commands
+ * (`pm2 jlist`, `pm2 restart`, `pm2 stop`, `pm2 logs ...`). Since v4.8
+ * the Mac install uses launchd (`com.alvinbot.app.plist`) — PM2 isn't
+ * running, so those calls returned "PM2 not available" and the buttons
+ * did nothing.
+ *
+ * This module abstracts the process manager and auto-detects which one
+ * is actually managing the bot. Detection order:
+ *
+ *   1. launchd (macOS) — if `launchctl print gui/$UID/com.alvinbot.app`
+ *      succeeds AND the bot's actual running pid matches
+ *   2. PM2 — if `pm2 jlist` returns our process
+ *   3. standalone — neither detected; only the in-process graceful
+ *      restart works (scheduleGracefulRestart — since there's no
+ *      supervisor to bring it back, "stop" is effectively "kill")
+ *
+ * Each manager implements: getStatus(), stop(), start(), getLogs().
+ * Restart is intentionally NOT on the manager — it always routes through
+ * scheduleGracefulRestart() (Grammy-safe) and the supervisor auto-brings-
+ * back behaviour.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+interface ExecCall {
+  cmd: string;
+  opts?: unknown;
+}
+
+let execLog: ExecCall[] = [];
+let execReturn: Record<string, string | Error> = {};
+
+function stubExec() {
+  vi.doMock("node:child_process", () => ({
+    execSync: (cmd: string, opts?: unknown) => {
+      execLog.push({ cmd, opts });
+      // Find match by pattern — longest matching prefix wins
+      const matches = Object.keys(execReturn).filter((k) => cmd.includes(k));
+      matches.sort((a, b) => b.length - a.length);
+      const key = matches[0];
+      if (key) {
+        const v = execReturn[key];
+        if (v instanceof Error) throw v;
+        return v;
+      }
+      throw new Error(`execSync: no stub for ${cmd}`);
+    },
+  }));
+}
+
+beforeEach(() => {
+  execLog = [];
+  execReturn = {};
+  vi.resetModules();
+  stubExec();
+});
+
+afterEach(() => {
+  vi.doUnmock("node:child_process");
+});
+
+describe("detectProcessManager (v4.13.1)", () => {
+  it("detects 'launchd' when launchctl print succeeds on darwin", async () => {
+    execReturn["launchctl print"] = `gui/502/com.alvinbot.app = {
+      state = running
+      program = /opt/homebrew/bin/node
+    }`;
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.detectProcessManager({ platform: "darwin" });
+    expect(pm.kind).toBe("launchd");
+  });
+
+  it("falls through to 'pm2' when launchd is not detected", async () => {
+    execReturn["launchctl print"] = new Error("Could not find service");
+    execReturn["pm2 jlist"] = JSON.stringify([
+      { name: "alvin-bot", pid: 1234, pm2_env: { status: "online" } },
+    ]);
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.detectProcessManager({ platform: "linux" });
+    expect(pm.kind).toBe("pm2");
+  });
+
+  it("falls through to 'standalone' when neither is detected", async () => {
+    execReturn["launchctl print"] = new Error("not found");
+    execReturn["pm2 jlist"] = new Error("command not found");
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.detectProcessManager({ platform: "linux" });
+    expect(pm.kind).toBe("standalone");
+  });
+
+  it("skips launchd detection on non-darwin platforms", async () => {
+    // No launchctl command should be issued on Linux
+    execReturn["pm2 jlist"] = JSON.stringify([
+      { name: "alvin-bot", pid: 1234, pm2_env: { status: "online" } },
+    ]);
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.detectProcessManager({ platform: "linux" });
+    expect(pm.kind).toBe("pm2");
+    // Verify launchctl was NOT called
+    expect(execLog.some((e) => e.cmd.includes("launchctl"))).toBe(false);
+  });
+});
+
+describe("launchd process manager (v4.13.1)", () => {
+  it("getStatus parses launchctl print output for state + PID", async () => {
+    execReturn["launchctl print"] = `gui/502/com.alvinbot.app = {
+      active count = 1
+      state = running
+      program = /opt/homebrew/Cellar/node/25.9.0_1/bin/node
+      pid = 65432
+      program path = /usr/bin/node
+      working directory = /Users/alvin_de/Projects/alvin-bot
+      stdout path = /Users/alvin_de/.alvin-bot/logs/alvin-bot.out.log
+    }`;
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createLaunchdManager(502);
+    const status = await pm.getStatus();
+    expect(status.status).toBe("running");
+    expect(status.pid).toBe(65432);
+    expect(status.kind).toBe("launchd");
+  });
+
+  it("getStatus returns 'not-loaded' when service is not registered", async () => {
+    execReturn["launchctl print"] = new Error("Could not find service");
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createLaunchdManager(502);
+    const status = await pm.getStatus();
+    expect(status.status).toBe("not-loaded");
+  });
+
+  it("stop uses launchctl bootout", async () => {
+    execReturn["launchctl bootout"] = "";
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createLaunchdManager(502);
+    await pm.stop();
+    const stopCall = execLog.find((e) => e.cmd.includes("bootout"));
+    expect(stopCall).toBeDefined();
+    expect(stopCall!.cmd).toContain("gui/502/com.alvinbot.app");
+  });
+
+  it("start uses launchctl bootstrap", async () => {
+    execReturn["launchctl bootstrap"] = "";
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createLaunchdManager(502);
+    await pm.start();
+    const startCall = execLog.find((e) => e.cmd.includes("bootstrap"));
+    expect(startCall).toBeDefined();
+    expect(startCall!.cmd).toMatch(/com\.alvinbot\.app\.plist/);
+  });
+});
+
+describe("pm2 process manager (v4.13.1)", () => {
+  it("getStatus parses pm2 jlist for our process", async () => {
+    execReturn["pm2 jlist"] = JSON.stringify([
+      {
+        name: "alvin-bot",
+        pid: 9999,
+        pm2_env: {
+          status: "online",
+          pm_uptime: Date.now() - 60_000,
+          restart_time: 2,
+        },
+        monit: { memory: 123456, cpu: 1.5 },
+      },
+    ]);
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createPm2Manager();
+    const status = await pm.getStatus();
+    expect(status.status).toBe("online");
+    expect(status.pid).toBe(9999);
+    expect(status.kind).toBe("pm2");
+    expect(status.restarts).toBe(2);
+  });
+
+  it("getStatus returns 'unknown' if pm2 jlist does not include our process", async () => {
+    execReturn["pm2 jlist"] = JSON.stringify([
+      { name: "other-service", pid: 1111, pm2_env: { status: "online" } },
+    ]);
+    const mod = await import("../src/services/process-manager.js");
+    const pm = mod.createPm2Manager();
+    const status = await pm.getStatus();
+    expect(status.status).toBe("unknown");
+  });
+});

package/test/slack-test-connection.test.ts

@@ -0,0 +1,176 @@
+/**
+ * v4.13.1 — `/api/platforms/test-connection` must accept `slack` as a
+ * platformId and validate the Bot Token via Slack's auth.test endpoint.
+ *
+ * Before v4.13.1, the handler only knew about telegram/discord/signal/
+ * whatsapp, so slack fell through to "Unknown platform" even when a
+ * valid xoxb- Bot Token was set.
+ *
+ * These tests hit the handler directly (no HTTP server spin-up) and stub
+ * global fetch so the Slack API is never actually contacted.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { Writable } from "node:stream";
+
+/**
+ * Minimal request/response pair that the setup-api handler expects.
+ * We capture the body written via res.end(body) so the test can assert
+ * on the JSON payload.
+ */
+interface FakeIO {
+  req: EventEmitter & { method: string; url: string; headers: Record<string, string> };
+  res: Writable & { statusCode: number; headers: Record<string, string>; body: string };
+}
+
+function makeIO(method: string, url: string, body: string): FakeIO {
+  const req = new EventEmitter() as FakeIO["req"];
+  req.method = method;
+  req.url = url;
+  req.headers = {};
+
+  let captured = "";
+  const res = new Writable({
+    write(chunk, _enc, cb) {
+      captured += chunk.toString();
+      cb();
+    },
+  }) as FakeIO["res"];
+  res.statusCode = 200;
+  res.headers = {};
+  res.setHeader = (k: string, v: string) => {
+    res.headers[k.toLowerCase()] = v;
+    return res as any;
+  };
+  res.end = (b?: unknown) => {
+    if (b != null) captured += String(b);
+    res.body = captured;
+    return res as any;
+  };
+
+  return { req, res };
+}
+
+beforeEach(() => {
+  vi.resetModules();
+  // Prevent the setup-api module from crashing on BOT_ROOT etc.
+  process.env.BOT_TOKEN = "";
+  process.env.SLACK_BOT_TOKEN = "";
+  process.env.SLACK_APP_TOKEN = "";
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  delete process.env.BOT_TOKEN;
+  delete process.env.SLACK_BOT_TOKEN;
+  delete process.env.SLACK_APP_TOKEN;
+});
+
+describe("POST /api/platforms/test-connection — slack (v4.13.1)", () => {
+  it("returns {ok:false, error: 'SLACK_BOT_TOKEN not set'} when no tokens configured", async () => {
+    const { handleSetupAPI } = await import("../src/web/setup-api.js");
+    const { req, res } = makeIO("POST", "/api/platforms/test-connection", "");
+    const body = JSON.stringify({ platformId: "slack" });
+
+    const handled = await handleSetupAPI(req as any, res as any, "/api/platforms/test-connection", body);
+    expect(handled).toBe(true);
+    const parsed = JSON.parse(res.body);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toMatch(/SLACK_BOT_TOKEN/);
+  });
+
+  it("returns {ok:true, info: '...'} when Slack's auth.test accepts the token", async () => {
+    process.env.SLACK_BOT_TOKEN = "xoxb-fake-valid";
+    process.env.SLACK_APP_TOKEN = "xapp-fake-valid";
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string) => {
+        expect(url).toContain("slack.com/api/auth.test");
+        return {
+          ok: true,
+          json: async () => ({
+            ok: true,
+            url: "https://alev-b.slack.com/",
+            team: "Alev-B Workspace",
+            user: "alvinbot",
+            team_id: "T123",
+            user_id: "U456",
+            bot_id: "B789",
+          }),
+        };
+      }),
+    );
+
+    const { handleSetupAPI } = await import("../src/web/setup-api.js");
+    const { req, res } = makeIO("POST", "/api/platforms/test-connection", "");
+    const body = JSON.stringify({ platformId: "slack" });
+    await handleSetupAPI(req as any, res as any, "/api/platforms/test-connection", body);
+
+    const parsed = JSON.parse(res.body);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.info).toMatch(/alvinbot|Alev-B/i);
+  });
+
+  it("returns {ok:false} when Slack's auth.test rejects the token", async () => {
+    process.env.SLACK_BOT_TOKEN = "xoxb-fake-invalid";
+    process.env.SLACK_APP_TOKEN = "xapp-fake-invalid";
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({ ok: false, error: "invalid_auth" }),
+      })),
+    );
+
+    const { handleSetupAPI } = await import("../src/web/setup-api.js");
+    const { req, res } = makeIO("POST", "/api/platforms/test-connection", "");
+    const body = JSON.stringify({ platformId: "slack" });
+    await handleSetupAPI(req as any, res as any, "/api/platforms/test-connection", body);
+
+    const parsed = JSON.parse(res.body);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toMatch(/invalid_auth/);
+  });
+
+  it("warns about missing/invalid App Token format when Bot Token is OK", async () => {
+    process.env.SLACK_BOT_TOKEN = "xoxb-fake-valid";
+    process.env.SLACK_APP_TOKEN = "xoxb-not-an-app-token"; // wrong prefix
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({
+          ok: true,
+          user: "alvinbot",
+          team: "x",
+          team_id: "T1",
+          user_id: "U1",
+          bot_id: "B1",
+        }),
+      })),
+    );
+
+    const { handleSetupAPI } = await import("../src/web/setup-api.js");
+    const { req, res } = makeIO("POST", "/api/platforms/test-connection", "");
+    const body = JSON.stringify({ platformId: "slack" });
+    await handleSetupAPI(req as any, res as any, "/api/platforms/test-connection", body);
+
+    const parsed = JSON.parse(res.body);
+    // Bot Token was valid, but we should still note the App Token format issue
+    expect(parsed.ok).toBe(true);
+    expect(parsed.info).toMatch(/App.?Token|xapp-/i);
+  });
+
+  it("still rejects 'slack-workspace' or other typos as unknown (regression guard)", async () => {
+    const { handleSetupAPI } = await import("../src/web/setup-api.js");
+    const { req, res } = makeIO("POST", "/api/platforms/test-connection", "");
+    const body = JSON.stringify({ platformId: "slack-workspace" });
+    await handleSetupAPI(req as any, res as any, "/api/platforms/test-connection", body);
+    const parsed = JSON.parse(res.body);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toMatch(/Unknown platform/);
+  });
+});