alvin-bot 4.13.0 → 4.13.2

package/CHANGELOG.md

@@ -2,6 +2,89 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.13.2] — 2026-04-16
+
+### ✨ Slack: `/alvin` slash commands + rewritten setup guide
+
+**Bug (carried over from v4.13.1):** Slash commands didn't work on Slack. When a user typed `/status` in a DM with the bot, Slack either hit its built-in `/status` (user status setter) or showed "Not a valid command" — nothing reached the bot. The Slack adapter only registered `message` + `app_mention` event handlers, no `command` handler; the manifest declared no slash commands.
+
+**Why it was a gotcha**: Slack treats slash commands as a separate event type (`command`), not as message text. Apps must explicitly register each command in their manifest AND add a `app.command(...)` handler to receive the events. None of this had been set up.
+
+**Fix**: v4.13.2 introduces a single namespaced command `/alvin` that takes a subcommand argument. Users type `/alvin status`, `/alvin new`, `/alvin effort high`, `/alvin help` — the Slack adapter parses the subcommand from `command.text` and forwards it as a `/status`/`/new`/etc. message through the existing `handlePlatformCommand` pipeline. Unknown subcommands fall through to normal LLM handling so `/alvin what's the weather` also works as a free-form query.
+
+### Technical details
+
+**New parser** `src/platforms/slack-slash-parser.ts`: pure `parseSlackSlashCommand(text)` helper. Empty text → `/help`. Single word → `/<word>`. Word + args → `/<word> <args>`. Lowercases subcommand, preserves arg capitalization, strips defensive leading slash, collapses extra whitespace. 8 unit tests.
+
+**Adapter change** `src/platforms/slack.ts`: new `app.command("/alvin", ...)` registration in `start()` (guarded with `typeof app.command === "function"` for test-mock compat). `ack()` fires immediately to meet Slack's 3-second requirement. New `handleSlashCommand(command)` method synthesizes an `IncomingMessage` with the translated `text` and the command's `channel_id`/`user_id` and forwards to the same `this.handler(...)` path as regular DMs. Response goes back via `chat.postMessage` (persistent, visible in channel history) rather than slash-command-native `respond()` (ephemeral) — matches DM behavior.
+
+**Slack app manifest**: requires a new `features.slash_commands` entry declaring `/alvin` and a new `commands` OAuth scope. Both are in the manifest JSON the setup guide pastes in — no manual per-field config. Existing installations need a one-time re-install to pick up the new `commands` scope (Slack shows a yellow banner after manifest save).
+
+**Setup guide rewrite** `src/web/setup-api.ts` Slack `setupSteps[]`: replaces the old 7-step "click-through every section" sequence with a 9-step manifest-paste flow that actually matches how the bot is currently set up (Messages Tab, Events, Socket Mode, slash commands — all covered in one JSON paste). Includes the full manifest JSON inline. New users get a working Slack app in ~2 minutes instead of hunting through the Slack API UI.
+
+### Testing
+
+- **Baseline**: 475 tests (v4.13.1)
+- **New**: `test/slack-slash-command.test.ts` — 8 tests (empty → /help, single word, args preservation, whitespace collapse, case insensitivity on subcommand, case preservation on args, defensive leading slash handling)
+- **Total**: 483 tests, all green, TSC clean
+- **Live smoke verification**: manifest pushed via Chrome browser automation, reinstall completed, Slack adapter re-registered with `app.command("/alvin")`. Live test of `/alvin status` pending user confirmation.
+
+### Files changed
+
+- **NEW**: `src/platforms/slack-slash-parser.ts`, `test/slack-slash-command.test.ts`
+- **Modified**: `src/platforms/slack.ts` (command registration + handler), `src/web/setup-api.ts` (slack setupSteps rewrite), `package.json` (4.13.1 → 4.13.2)
+
+### Known limitations
+
+- **One command namespace only**: we register `/alvin` not individual `/status`/`/new` etc. because `/status` conflicts with Slack's built-in command. Side effect: slightly more typing for users (`/alvin status` vs `/status`). Alternative namespaces considered (`/alvin-status` as multiple commands each) would work too but require more manifest boilerplate; deferred unless users complain.
+- **Channel responses are public**: when `/alvin status` is invoked in a channel, the bot's response is a normal `chat.postMessage` visible to the whole channel. If you want private responses there, use DM or switch the sendText call to use Slack's `response_url` (ephemeral). Deferred as enhancement — DM is the primary use case.
+
+---
+
+## [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/platforms/slack-slash-parser.js

@@ -0,0 +1,32 @@
+/**
+ * v4.13.2 — Parse Slack `/alvin <subcommand> [args...]` slash command
+ * text into the platform-agnostic `/<subcommand> [args]` format that
+ * handlePlatformCommand already knows.
+ *
+ * Pure function — tested in isolation. Called from the Slack adapter's
+ * `app.command('/alvin')` handler.
+ *
+ * Rules:
+ *   - Empty text → `/help` (useful default, shows the commands list)
+ *   - Subcommand is lowercased for case-insensitive matching
+ *   - Args are kept verbatim (preserve user capitalization)
+ *   - A literal leading `/` on the subcommand is stripped defensively
+ *     (handles `/alvin /status` which becomes just `/status`, not `//status`)
+ */
+export function parseSlackSlashCommand(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "/help";
+    // Split on first whitespace run — head is the subcommand, tail is args
+    const match = trimmed.match(/^(\S+)(?:\s+(.*))?$/);
+    if (!match)
+        return "/help";
+    let sub = (match[1] || "").toLowerCase();
+    // Strip a literal leading slash the user might have typed
+    if (sub.startsWith("/"))
+        sub = sub.slice(1);
+    if (sub.length === 0)
+        return "/help";
+    const args = (match[2] || "").trim();
+    return args ? `/${sub} ${args}` : `/${sub}`;
+}

package/dist/platforms/slack.js

@@ -17,6 +17,7 @@
  *   7. Set env vars and restart bot
  */
 import fs from "fs";
+import { parseSlackSlashCommand } from "./slack-slash-parser.js";
 let _slackState = {
     status: "disconnected",
     botName: null,
@@ -80,6 +81,31 @@ export class SlackAdapter {
             this.app.event("app_mention", async ({ event, say, client }) => {
                 await this.handleMention(event, say, client);
             });
+            // v4.13.2 — Handle the /alvin slash command.
+            //
+            // Slack sends slash commands as their own "command" event type
+            // (not as regular messages), so without this handler users who
+            // type /status see "Not a valid command" from Slack's built-in
+            // /status (which sets their user status). We register /alvin as
+            // a namespaced parent and parse the subcommand from command.text.
+            //
+            // CRITICAL: Slack requires ack() within 3 seconds or the user
+            // sees "/alvin didn't respond". We ack FIRST, then do the work
+            // asynchronously via the normal handler pipeline.
+            //
+            // Defensive: older/mocked Bolt versions might not expose .command().
+            // Skip registration silently rather than crashing start().
+            if (typeof this.app.command === "function") {
+                this.app.command("/alvin", async ({ command, ack }) => {
+                    await ack();
+                    try {
+                        await this.handleSlashCommand(command);
+                    }
+                    catch (err) {
+                        console.error("[slack] /alvin command failed:", err);
+                    }
+                });
+            }
             await this.app.start();
             _slackState.status = "connected";
             _slackState.connectedAt = Date.now();
@@ -160,6 +186,43 @@ export class SlackAdapter {
         };
         await this.handler(incoming);
     }
+    /**
+     * v4.13.2 — Handle /alvin slash command.
+     *
+     * Slack delivers these with command.text containing the part after
+     * "/alvin " (so "/alvin status" arrives with text="status"). We
+     * translate into a platform-agnostic "/<sub>[ args]" string and
+     * forward through the normal message handler — handlePlatformCommand
+     * picks it up since it starts with "/".
+     *
+     * The response goes back via the same sendText path as regular
+     * messages (chat.postMessage in command.channel_id). Slack allows
+     * this in addition to the slash-command-native respond() mechanism,
+     * and it keeps the codepath identical to message.im responses.
+     */
+    async handleSlashCommand(command) {
+        if (!this.handler)
+            return;
+        const translated = parseSlackSlashCommand(command.text || "");
+        const channelId = command.channel_id || "";
+        const userId = command.user_id || "";
+        const userName = command.user_name || userId;
+        const incoming = {
+            platform: "slack",
+            messageId: `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            chatId: channelId,
+            userId,
+            userName,
+            text: translated,
+            // Slack slash commands are always issued 1:1 in the sense of
+            // "one user invoking". isGroup reflects the CHANNEL context
+            // (channel_name=directmessage is a DM, otherwise channel/group).
+            isGroup: command.channel_name && command.channel_name !== "directmessage",
+            isMention: false,
+            isReplyToBot: false,
+        };
+        await this.handler(incoming);
+    }
     async handleMention(event, _say, client) {
         if (!this.handler)
             return;

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

@@ -118,7 +118,7 @@ const PLATFORMS = [
         id: "slack",
         name: "Slack",
         icon: "💼",
-        description: "Slack workspace integration via Socket Mode (no public URL needed). DMs and @mentions in channels.",
+        description: "Slack workspace integration via Socket Mode (no public URL needed). DMs, @mentions in channels, and the `/alvin` slash command for /status, /new, /effort, /help (v4.13.2+).",
         envVars: [
             { key: "SLACK_BOT_TOKEN", label: "Bot Token (xoxb-...)", placeholder: "xoxb-...", secret: true },
             { key: "SLACK_APP_TOKEN", label: "App Token (xapp-...)", placeholder: "xapp-...", secret: true },
@@ -126,13 +126,15 @@ const PLATFORMS = [
         npmPackages: ["@slack/bolt"],
         setupUrl: "https://api.slack.com/apps",
         setupSteps: [
-            "Create a new App at api.slack.com/apps (From scratch)",
-            "Enable Socket Mode (Settings → Socket Mode → Enable)",
-            "Generate App-Level Token with 'connections:write' scope → copy as SLACK_APP_TOKEN",
-            "Go to OAuth & Permissions → add Bot Token Scopes: chat:write, channels:history, groups:history, im:history, mpim:history, app_mentions:read, files:write, reactions:write",
-            "Install App to Workspace → copy Bot User OAuth Token as SLACK_BOT_TOKEN",
-            "Subscribe to Events: message.im, message.groups, message.channels, app_mention",
-            "Invite the bot to channels with /invite @botname",
+            "Go to https://api.slack.com/apps and click 'Create New App' → 'From an app manifest'. Choose your workspace.",
+            "Paste the full manifest JSON below into the JSON tab (replaces the template). This sets scopes, events, Messages Tab, Socket Mode, and the /alvin slash command in one go:\n\n{\n  \"display_information\": { \"name\": \"Alvin\" },\n  \"features\": {\n    \"app_home\": {\n      \"home_tab_enabled\": false,\n      \"messages_tab_enabled\": true,\n      \"messages_tab_read_only_enabled\": false\n    },\n    \"bot_user\": { \"display_name\": \"Alvin\", \"always_online\": false },\n    \"slash_commands\": [\n      {\n        \"command\": \"/alvin\",\n        \"description\": \"Alvin bot commands\",\n        \"usage_hint\": \"new | status | effort low|medium|high|max | help\",\n        \"should_escape\": false\n      }\n    ]\n  },\n  \"oauth_config\": {\n    \"scopes\": {\n      \"bot\": [\n        \"app_mentions:read\", \"mpim:read\", \"chat:write\",\n        \"channels:history\", \"groups:history\", \"im:history\", \"mpim:history\",\n        \"files:write\", \"reactions:write\", \"files:read\",\n        \"commands\"\n      ]\n    },\n    \"pkce_enabled\": true\n  },\n  \"settings\": {\n    \"event_subscriptions\": {\n      \"bot_events\": [\n        \"app_mention\", \"message.channels\", \"message.groups\",\n        \"message.im\", \"message.mpim\"\n      ]\n    },\n    \"interactivity\": { \"is_enabled\": true },\n    \"org_deploy_enabled\": false,\n    \"socket_mode_enabled\": true,\n    \"token_rotation_enabled\": false\n  }\n}",
+            "Click Create. Slack creates the App with all the correct config pre-wired.",
+            "Go to Settings → Basic Information → App-Level Tokens → 'Generate Token and Scopes'. Name it 'socket', pick scope 'connections:write', click Generate. Copy the xapp-... token into SLACK_APP_TOKEN below.",
+            "Go to Settings → Install App → Install to Workspace → Allow. Copy the 'Bot User OAuth Token' (xoxb-...) into SLACK_BOT_TOKEN below.",
+            "Save both tokens here (click 'Save') and then click 'Test Connection' — you should see '@alvin on <Workspace>'.",
+            "Click 'Restart bot' in Maintenance → the Slack adapter connects automatically (look for '💬 Slack connected' in the logs).",
+            "In Slack: open the app in the sidebar, click 'Messages' tab, send a DM. Or use the slash command: /alvin status, /alvin new, /alvin effort high, /alvin help.",
+            "To use in channels: invite the bot with /invite @alvin and then @mention it (e.g. '@alvin what's the weather in Berlin?').",
         ],
     },
     {
@@ -874,6 +876,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.2",
   "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-slash-command.test.ts

@@ -0,0 +1,61 @@
+/**
+ * v4.13.2 — Slack slash command parser tests.
+ *
+ * Users on Slack type `/alvin <subcommand> [args...]` which Bolt
+ * delivers via app.command('/alvin') with `command.text` containing
+ * the part after `/alvin `. We parse it into a platform-agnostic
+ * "/subcommand [args]" text that handlePlatformCommand already knows
+ * how to route (/new, /status, /effort, /help).
+ *
+ * Empty text → `/help` (most helpful default).
+ * Pass-through for everything else — unknown subcommand falls through
+ * to normal LLM prompt handling.
+ */
+import { describe, it, expect } from "vitest";
+import { parseSlackSlashCommand } from "../src/platforms/slack-slash-parser.js";
+
+describe("parseSlackSlashCommand (v4.13.2)", () => {
+  it("empty text maps to /help", () => {
+    expect(parseSlackSlashCommand("")).toBe("/help");
+    expect(parseSlackSlashCommand("   ")).toBe("/help");
+  });
+
+  it("single-word subcommand becomes /<subcommand>", () => {
+    expect(parseSlackSlashCommand("status")).toBe("/status");
+    expect(parseSlackSlashCommand("new")).toBe("/new");
+    expect(parseSlackSlashCommand("help")).toBe("/help");
+  });
+
+  it("subcommand with args preserves the args", () => {
+    expect(parseSlackSlashCommand("effort high")).toBe("/effort high");
+    expect(parseSlackSlashCommand("effort low")).toBe("/effort low");
+  });
+
+  it("multi-word args are preserved verbatim", () => {
+    expect(parseSlackSlashCommand("ask what is the weather in berlin")).toBe(
+      "/ask what is the weather in berlin",
+    );
+  });
+
+  it("collapses extra whitespace around subcommand", () => {
+    expect(parseSlackSlashCommand("   status   ")).toBe("/status");
+    expect(parseSlackSlashCommand("  effort    max   ")).toBe("/effort max");
+  });
+
+  it("lowercases the subcommand for case-insensitive matching", () => {
+    expect(parseSlackSlashCommand("Status")).toBe("/status");
+    expect(parseSlackSlashCommand("HELP")).toBe("/help");
+  });
+
+  it("does NOT lowercase the args (preserve user intent)", () => {
+    expect(parseSlackSlashCommand("ask What is THIS")).toBe(
+      "/ask What is THIS",
+    );
+  });
+
+  it("handles leading slash defensively — strips duplicate", () => {
+    // If a user literally types `/alvin /status`, Slack delivers text="/status"
+    expect(parseSlackSlashCommand("/status")).toBe("/status");
+    expect(parseSlackSlashCommand("/effort max")).toBe("/effort max");
+  });
+});

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/);
+  });
+});