@manybot/manybot 5.7.0 → 5.8.0

package/dist/drivers/baileys/index.js

@@ -5,7 +5,7 @@
  *
  * Owns the socket state machine (connect / disconnect / reconnect /
  * circuit breaker) and exposes the live `WaContract` adapter to the
- * rest of the kernel. Plugins, sendFallbackGuard, messageHandler,
+ * rest of the kernel. Plugins, activeDriverSend, messageHandler,
  * pluginLoader, contactAutoSave and sendGuard all consume the
  * `WaContract` returned here — they never touch the raw Baileys socket.
  *
@@ -16,9 +16,8 @@
  * registration, and the reconnect circuit breaker — none of which
  * the adapter should know about.
  *
- * For the verification-required path (sendFallbackGuard), the contract
- * also exposes `getHistory?` — which the adapter populates from the
- * Baileys store.messages map on demand.
+ * The contract also exposes `getHistory?` — which the adapter
+ * populates from the Baileys store.messages map on demand.
  */
 import { createSocket, AUTH_DIR, store as sharedStore } from "./sdk/baileysSock.js";
 import { createBaileysAdapter } from "./adapter.js";
@@ -27,7 +26,6 @@ import { normalizeJid } from "#drivers/jid.js";
 import { loadPlugins, setupPlugins } from "#kernel/pluginLoader.js";
 import { runContactRefreshSweep } from "#kernel/contactAutoSave.js";
 import { registerAlertSockProvider, sendAlert } from "#kernel/alerts.js";
-import { getDriverManager } from "#kernel/driverManager.js";
 import { startUpdateCheckSchedule, stopUpdateCheckSchedule } from "#kernel/updateCheck.js";
 import { setStatus } from "#kernel/statusServer.js";
 import { logger } from "#logger";
@@ -53,6 +51,7 @@ let halted = false;
 let cacheHydrated = false;
 let cacheSaveTimer = null;
 let contactRefreshTimer = null;
+let bannerShown = false;
 registerAlertSockProvider(() => currentSock);
 // ── Per-chat message queue ──────────────────────────────────────────────────
 // Messages from the same chat are processed one at a time (in order), but
@@ -204,7 +203,10 @@ async function startBot() {
             setStatus(true);
             logger.success(t("system.connected"));
             logger.info(t("system.clientId", { id: CLIENT_ID }));
-            printBanner();
+            if (!bannerShown) {
+                bannerShown = true;
+                printBanner();
+            }
             if (!pluginsReady) {
                 pluginsReady = true;
                 await loadPlugins(PLUGINS);
@@ -227,15 +229,22 @@ async function startBot() {
             if (loggedOut || badSession) {
                 if (badSession) {
                     logger.warn("Session data corrupted (badSession=500). Clearing session dir.");
-                    getDriverManager().markDegraded("baileys", 300_000);
+                    // No longer mark degraded - halt on failure
+                    logger.error("Baileys driver failed due to bad session - bot will halt");
+                    process.exit(1);
                 }
                 else {
                     logger.warn(t("system.sessionExpired"));
+                    // No longer mark degraded - halt on failure
+                    logger.error("Baileys driver failed due to session expired - bot will halt");
+                    process.exit(1);
                 }
                 try {
                     await fs.rm(AUTH_DIR, { recursive: true, force: true });
                 }
                 catch (e) {
+                    logger.error(`Baileys driver failed due to ${badSession ? "bad session" : "session expired"} - bot will halt`);
+                    process.exit(1);
                     logger.error(`[whatsapp] Failed to remove session dir: ${e.message}`);
                 }
                 scheduleReconnect(1000);
@@ -245,13 +254,8 @@ async function startBot() {
                 if (restartRequiredCount >= MAX_RESTART_REQUIRED) {
                     halted = true;
                     logger.error(`restartRequired (515) recurring — protocol drift suspected. Halting.`);
-                    getDriverManager().markDegraded("baileys", 600_000);
-                    sendAlert({
-                        level: "critical",
-                        title: "manybot — restartRequired recurring",
-                        message: `Protocol drift suspected after ${restartRequiredCount}x restartRequired. Bot halted on Baileys. Run connect() manually.`,
-                    }).catch(() => { });
-                    return;
+                    logger.error("Baileys driver failed due to repeated restartRequired - bot will halt");
+                    process.exit(1);
                 }
                 const delay = Math.min(500, RECONNECT_BASE_MS);
                 logger.info(t("system.reconnecting", { secs: Math.round(delay / 1000) }));
@@ -260,12 +264,13 @@ async function startBot() {
             else if (!shuttingDown) {
                 if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
                     halted = true;
-                    getDriverManager().markDegraded("baileys", 600_000);
                     logger.error(t("system.reconnectHalted", { attempts: reconnectAttempts }));
+                    logger.error("Baileys driver failed due to exhausted reconnect attempts - bot will halt");
+                    process.exit(1);
                     sendAlert({
                         level: "critical",
-                        title: "manybot parou de tentar reconectar",
-                        message: `Desisti após ${reconnectAttempts} tentativas — possível restrição de conta. Rode connect() manualmente pra tentar de novo.`,
+                        title: t("alerts.reconnectHaltedTitle"),
+                        message: t("alerts.reconnectHaltedMessage", { attempts: reconnectAttempts }),
                     }).catch(() => { });
                     return;
                 }
@@ -390,10 +395,10 @@ export const baileysContract = {
     me: () => requireReady().me(),
     // ── media (download) ────────────────────────────────────────────────────
     downloadMedia: (...args) => requireReady().downloadMedia(...args),
-    // ── verification primitive ─────────────────────────────────────────────
+    // ── history ──────────────────────────────────────────────────────────
     // Delegates to the adapter, which reads from the in-memory Baileys
-    // store (store.messages). The adapter guarantees getHistory is defined
-    // (the Baileys adapter guarantees getHistory is defined), so the defensive fallback is gone.
+    // store (store.messages). The Baileys adapter always defines
+    // getHistory, so calling it unconditionally here is safe.
     getHistory: (jid, opts) => requireReady().getHistory(jid, opts),
     /**
      * Diagnostic mode: connects on its own session (separate from the
@@ -459,22 +464,30 @@ export const baileysContract = {
         const sorted = chats
             .map((c) => ({ id: c.id, name: c.name ?? "" }))
             .sort((a, b) => a.name.localeCompare(b.name));
-        const picked = await clack.select({
-            message: t("getid.pickChat"),
+        // Allow selecting multiple chats (Space to toggle, Enter to confirm).
+        const picked = await clack.multiselect({
+            message: t("getid.pickPrompt"),
             options: sorted.map((c) => ({ label: c.name || c.id, value: c.id })),
         });
-        if (clack.isCancel(picked) || typeof picked !== "string") {
+        if (clack.isCancel(picked) || !Array.isArray(picked) || picked.length === 0) {
             teardownSock(sock);
             process.exit(0);
         }
-        const resolved = await resolveLidForJid(sock, picked);
-        const finalJid = resolved ?? picked;
-        try {
-            await copyToClipboard(finalJid);
-            logger.success(`[getid] ${t("getid.copied", { id: finalJid })}`);
+        // Resolve any @lid values to their phone-based JIDs when possible.
+        const finalJids = [];
+        for (const p of picked) {
+            const resolved = await resolveLidForJid(sock, p);
+            finalJids.push(resolved ?? p);
+        }
+        const joined = finalJids.join("\n");
+        const copied = await copyToClipboard(joined);
+        if (copied) {
+            logger.success(`[getid] ${t("getid.copied", { count: finalJids.length, ids: joined })}`);
         }
-        catch {
-            logger.info(`[getid] ${finalJid}`);
+        else {
+            logger.warn(`[getid] ${t("getid.copyFailed", { count: finalJids.length, ids: joined })}`);
+            // Also print to stdout so the user can still see the IDs.
+            logger.info(`[getid] \n${joined}`);
         }
         teardownSock(sock);
     },
@@ -556,12 +569,31 @@ export function toBotMessage(msg) {
         text = "";
         mimetype = m.stickerMessage.mimetype ?? undefined;
     }
+    else if (m?.templateMessage) {
+        type = "text";
+        const tpl = m.templateMessage.hydratedTemplate ?? m.templateMessage.hydratedFourRowTemplate;
+        const buttonUrls = tpl?.hydratedButtons?.map((b) => b.urlButton?.url).filter(Boolean).join(" ") ?? "";
+        text = [tpl?.hydratedContentText ?? "", buttonUrls].filter(Boolean).join(" ");
+    }
+    else if (m?.interactiveMessage) {
+        type = "text";
+        const buttonParams = m.interactiveMessage.nativeFlowMessage?.buttons
+            ?.map((b) => b.buttonParamsJson).filter(Boolean).join(" ") ?? "";
+        text = [m.interactiveMessage.body?.text ?? "", buttonParams].filter(Boolean).join(" ");
+    }
+    else if (m?.buttonsMessage) {
+        type = "text";
+        text = [m.buttonsMessage.contentText ?? "", m.buttonsMessage.footerText ?? ""].filter(Boolean).join(" ");
+    }
     const key = msg.key;
     const contextInfo = m?.extendedTextMessage?.contextInfo ??
         m?.imageMessage?.contextInfo ??
         m?.videoMessage?.contextInfo ??
         m?.audioMessage?.contextInfo ??
         m?.documentMessage?.contextInfo ??
+        m?.templateMessage?.contextInfo ??
+        m?.interactiveMessage?.contextInfo ??
+        m?.buttonsMessage?.contextInfo ??
         undefined;
     return {
         id: msg.key?.id ?? "",

package/dist/drivers/baileys/loginPrompt.js

@@ -11,7 +11,6 @@
 import * as clack from "@clack/prompts";
 import { CONFIG, persistConfigValue } from "#config";
 import { t } from "#i18n";
-import { promptWhatsmeowInstall } from "#drivers/whatsmeow/installer.js";
 function cancelAndExit() {
     clack.cancel(t("onboarding.cancelled"));
     process.exit(1);
@@ -73,7 +72,6 @@ export async function resolveLoginMethod() {
     clack.intro(t("onboarding.intro"));
     if (needsMethod) {
         method = await promptLoginMethod();
-        await promptWhatsmeowInstall();
     }
     if (method === "phone" && !phone) {
         phone = await promptPhoneNumber();

package/dist/drivers/baileys/messageHandler.js

@@ -11,15 +11,31 @@
  *
  * Each plugin decides whether to act or ignore.
  */
-import { CHATS, EXCLUDE_CHATS } from "#config";
+import { CHATS, EXCLUDE_CHATS, CMD_PREFIX } from "#config";
 import { buildApi, buildChatFromMsg, buildMessageContext } from "./api/index.js";
 import { pluginRegistry } from "#kernel/pluginLoader.js";
+import { getCommandByInvocation, getCommandRegistry } from "#kernel/commandRegistry.js";
+import { resolveDispatch, runCommand } from "#kernel/runCommand.js";
+import { getActiveDeprecation, formatDeprecationMessage } from "#kernel/commandDeprecation.js";
+import { checkPermission } from "#kernel/commandPermissions.js";
+import { handleMenuCommand, renderNotFound, resolveLocalizedString, checkAndTriggerWelcomeMessage } from "#kernel/commandMenu.js";
 import { runPlugin } from "#kernel/pluginGuard.js";
 import { acquireChatSlot } from "#sendguard";
 import { trackIncomingForContactSave } from "#kernel/contactAutoSave.js";
 import { normalizeJid } from "#drivers/jid.js";
+import { logger } from "#logger";
 const INCOMING_DEBOUNCE_MS = 0;
 const lastProcessedAt = new Map();
+/**
+ * Extract the bare command token from a raw body string.
+ * Mirrors the prefix/parsing logic in `buildMessageContext` and `buildApi`
+ * (kept local to avoid coupling to internal helpers of api/index.ts).
+ * Returns "" when the body does not start with the configured prefix.
+ */
+function extractCommand(body, prefix) {
+    const first = body.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    return first.startsWith(prefix) ? first.slice(prefix.length) : "";
+}
 // ── Dedup of already-processed messages ────────────────────────────────────
 // WhatsApp resends messages without a delivery/read confirmation (the
 // protocol's own retry, usually up to 3 times) when the socket reconnects.
@@ -91,13 +107,115 @@ export async function handleMessage(msg, contract, store) {
     // Caps how many chats get answered at the same time — see SECURITY_LEVEL.
     const releaseChatSlot = await acquireChatSlot(jid);
     try {
-        await runPluginsForMessage(msg, chat, contract, store, rawJid);
+        await runPluginsForMessage(msg, chat, msgCtx, contract, store, rawJid);
     }
     finally {
         releaseChatSlot();
     }
 }
-async function runPluginsForMessage(msg, chat, contract, store, rawJid) {
+async function runPluginsForMessage(msg, chat, msgCtx, contract, store, rawJid) {
+    const command = extractCommand(msgCtx.body, CMD_PREFIX);
+    const registry = getCommandRegistry();
+    // 0. Welcome message (first message within the configured window)
+    if (registry) {
+        const welcomeMsg = checkAndTriggerWelcomeMessage(msgCtx.sender, registry);
+        if (welcomeMsg) {
+            try {
+                await msgCtx.reply.text(welcomeMsg);
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                logger.warn(`[messageHandler] welcome reply failed: ${err.message}`);
+            }
+        }
+    }
+    // 1. Menu aliases match (overview / category / manual / notFound)
+    if (command && registry && registry.menuAliases.has(command)) {
+        const rawArgs = msgCtx.body.trim().slice(CMD_PREFIX.length + command.length).trim();
+        const scope = chat.isGroup ? "group" : "dm";
+        const menuResponse = handleMenuCommand(command, rawArgs, registry, undefined, scope);
+        try {
+            await msgCtx.reply.text(menuResponse);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.warn(`[messageHandler] menu reply failed: ${err.message}`);
+        }
+        return;
+    }
+    const matched = command ? getCommandByInvocation(command) : null;
+    // Full v6 dispatch resolution (parent vs. subcommand) for the matched
+    // entry, if any — feeds `runCommand()` below so subcommand routing,
+    // required-argument validation, and the Phase-8 crash-alert hook are
+    // active in production. Kept separate from the `matched` top-level
+    // permission pre-check further down (unchanged, still gates the whole
+    // per-message plugin loop exactly as before `runCommand` existed).
+    const rawArgsForDispatch = command ? msgCtx.body.trim().slice(CMD_PREFIX.length + command.length).trim() : "";
+    const resolution = command ? resolveDispatch(command, rawArgsForDispatch) : { target: { kind: "none" } };
+    if (matched) {
+        const permApi = buildApi({
+            msg,
+            chat,
+            contract,
+            store,
+            pluginRegistry,
+            pluginName: matched.pluginName ?? "system",
+            guardOptions: {},
+        });
+        const permResult = await checkPermission(matched, {
+            isGroup: permApi.chat.isGroup,
+            chatId: permApi.chat.id,
+            senderId: msgCtx.sender,
+            isSenderAdmin: () => permApi.chat.isSenderAdmin(),
+            isBotAdmin: () => permApi.chat.isBotAdmin(),
+        });
+        if (!permResult.allowed) {
+            if (permResult.message) {
+                try {
+                    await msgCtx.reply.text(permResult.message);
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    logger.warn(`[messageHandler] permission reply failed: ${err.message}`);
+                }
+            }
+            return;
+        }
+    }
+    // Fixed-text command: reply with the literal text and stop — do not
+    // invoke any plugin (legacy or migrated) for this message.
+    if (matched && matched.source === "text" && matched.text !== null) {
+        try {
+            const textContent = resolveLocalizedString(matched.text) ?? "";
+            await msgCtx.reply.text(textContent);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.warn(`[messageHandler] fixed-text reply failed: ${err.message}`);
+        }
+        return;
+    }
+    // Deprecated old name: notify the user and stop. We do NOT redirect
+    // to the new command and do NOT fall through to the legacy run(ctx).
+    if (!matched && command) {
+        const defaults = registry?.defaults ?? {
+            notifyChanges: true,
+            notifyPeriodDays: 7,
+            notifyMessage: null,
+        };
+        const dep = defaults.notifyChanges ? getActiveDeprecation(command) : null;
+        if (dep) {
+            try {
+                await msgCtx.reply.text(formatDeprecationMessage(dep, defaults));
+            }
+            catch (e) {
+                const err = e instanceof Error ? e : new Error(String(e));
+                logger.warn(`[messageHandler] deprecation reply failed: ${err.message}`);
+            }
+            return;
+        }
+    }
+    const matchedPlugin = matched && matched.source === "plugin" ? matched : null;
     for (const plugin of pluginRegistry.values()) {
         const ctx = buildApi({
             msg,
@@ -117,7 +235,30 @@ async function runPluginsForMessage(msg, chat, contract, store, rawJid) {
             }, 4000);
         }
         try {
-            await runPlugin(plugin, ctx);
+            // If this plugin owns the matched registry entry, skip the legacy
+            // run(ctx) and go through the unified v6 dispatcher instead — avoids
+            // double-firing for a migrated command and activates subcommand
+            // routing, required-argument validation, and the Phase-8 crash-alert
+            // hook (`runCommand.ts`), none of which the direct `runPlugin` call
+            // below it used to provide. Other plugins (and other invocations of
+            // this same plugin that did NOT match the registry) keep their legacy
+            // run(ctx).
+            if (matchedPlugin && matchedPlugin.pluginName === plugin.name && matchedPlugin.handler) {
+                // runCommand() opts into rethrow so its Phase-8 fireAlert("plugin_crash")
+                // catch actually runs (runPlugin() swallows by default — see pluginGuard.ts).
+                // Swallow here too, at the boundary: this loop must never crash the bot,
+                // same guarantee the legacy runPlugin(plugin, ctx) branch below already has.
+                try {
+                    await runCommand({ pluginName: plugin.name, ctx, resolution, reply: msgCtx.reply });
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    logger.warn(`[messageHandler] runCommand crashed for plugin "${plugin.name}": ${err.message}`);
+                }
+            }
+            else {
+                await runPlugin(plugin, ctx);
+            }
         }
         finally {
             if (useTyping) {
@@ -126,4 +267,17 @@ async function runPluginsForMessage(msg, chat, contract, store, rawJid) {
             }
         }
     }
+    // Legacy plugins do not report whether they handled a message.  Keep the
+    // generic fallback opt-in and send it only after they have all had a
+    // chance to respond; a legacy plugin may therefore still produce a reply
+    // alongside this fallback.
+    if (!matched && command && registry?.menu.notFoundFallback) {
+        try {
+            await msgCtx.reply.text(renderNotFound(command, registry));
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.warn(`[messageHandler] notFoundFallback reply failed: ${err.message}`);
+        }
+    }
 }

package/dist/drivers/baileys/messageHandler.test.js

@@ -0,0 +1,203 @@
+import assert from "node:assert/strict";
+import { describe, test, beforeEach, afterEach } from "node:test";
+import { createStore } from "#client/store.js";
+import { handleMessage } from "#drivers/baileys/messageHandler.js";
+import { pluginRegistry } from "#kernel/pluginLoader.js";
+import { buildCommandRegistry, __setRegistryForTests } from "#kernel/commandRegistry.js";
+import { getDriverManager, _resetDriverManagerForTests } from "#kernel/driverManager.js";
+// ── Minimal spec builders (mirrors kernel/runCommand.test.ts conventions) ──
+function emptySpec(overrides) {
+    return {
+        id: overrides.id ?? "task::run",
+        cmd: overrides.cmd ?? "task",
+        aliases: overrides.aliases ?? [],
+        plugin: overrides.plugin ?? "taskPlugin",
+        function: overrides.function ?? "runFn",
+        text: overrides.text ?? null,
+        desc: overrides.desc ?? null,
+        category: overrides.category ?? null,
+        group: overrides.group ?? null,
+        manual: overrides.manual ?? null,
+        deprecatedMessage: overrides.deprecatedMessage ?? null,
+        notifyChanges: overrides.notifyChanges ?? null,
+        permissions: overrides.permissions ?? null,
+        messages: overrides.messages ?? null,
+        arguments: overrides.arguments ?? [],
+        subcommands: overrides.subcommands ?? [],
+    };
+}
+function emptySub(overrides) {
+    return {
+        id: overrides.id ?? "task::list",
+        cmd: overrides.cmd ?? "list",
+        aliases: overrides.aliases ?? [],
+        function: overrides.function ?? null,
+        desc: overrides.desc ?? null,
+        manual: overrides.manual ?? null,
+        arguments: overrides.arguments ?? [],
+        permissions: overrides.permissions ?? null,
+        messages: overrides.messages ?? null,
+    };
+}
+// ── Mock WaContract — only the surface handleMessage's pipeline touches ────
+function createMockContract() {
+    const sentTexts = [];
+    let msgSeq = 0;
+    const contract = {
+        name: "baileys",
+        connect: async () => { },
+        disconnect: async () => { },
+        isReady: () => true,
+        resolveLid: async () => null,
+        on: () => () => { },
+        sendText: async (jid, text) => {
+            sentTexts.push({ jid, text });
+            return { id: `msg-${++msgSeq}`, chatId: jid, timestamp: Date.now() };
+        },
+        sendImage: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        sendVideo: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        sendAudio: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        sendSticker: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        sendDocument: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        sendPoll: async () => ({ id: "x", chatId: "x", timestamp: Date.now() }),
+        react: async () => { },
+        deleteMessage: async () => { },
+        editMessage: async () => { },
+        sendPresenceUpdate: async () => { },
+        readMessages: async () => { },
+        onWhatsApp: async () => [{ exists: true }],
+        getBusinessProfile: async () => null,
+        profilePictureUrl: async () => null,
+        fetchStatus: async () => null,
+        updateBlockStatus: async () => { },
+        addOrEditContact: async () => { },
+        removeContact: async () => { },
+        groupMetadata: async () => ({ subject: "Group", participants: [] }),
+        groupParticipantsUpdate: async () => [],
+        groupUpdateSubject: async () => { },
+        groupUpdateDescription: async () => { },
+        groupInviteCode: async () => "",
+        groupRevokeInvite: async () => "",
+        updateProfilePicture: async () => { },
+        updateProfileName: async () => { },
+        updateProfileStatus: async () => { },
+        me: () => ({ id: "5511900000000@s.whatsapp.net" }),
+        downloadMedia: async () => null,
+        getHistory: async () => [],
+    };
+    return { contract, sentTexts };
+}
+function makeBotMessage(overrides = {}) {
+    return {
+        id: `in-${Math.random().toString(36).slice(2)}`,
+        chatId: "5511888888888@s.whatsapp.net",
+        fromMe: false,
+        contentHash: "hash",
+        timestamp: Date.now(),
+        type: "text",
+        body: "!task",
+        fromPn: "5511888888888@s.whatsapp.net",
+        ...overrides,
+    };
+}
+function buildRegistry(specs) {
+    return buildCommandRegistry(specs, pluginRegistry);
+}
+describe("drivers/baileys/messageHandler — v6 runCommand dispatch", () => {
+    let store;
+    let contract;
+    let sentTexts;
+    let runCalls;
+    let listCalls;
+    beforeEach(() => {
+        _resetDriverManagerForTests();
+        store = createStore();
+        const mock = createMockContract();
+        contract = mock.contract;
+        sentTexts = mock.sentTexts;
+        getDriverManager().register(contract, { isPrimary: true });
+        runCalls = [];
+        listCalls = [];
+        const plugin = {
+            name: "taskPlugin",
+            status: "active",
+            run: null,
+            setup: null,
+            exports: {},
+            error: null,
+            guardOptions: {},
+            commands: {
+                runFn: {
+                    cmd: "task",
+                    aliases: [],
+                    handler: async (ctx, input) => {
+                        runCalls.push(input);
+                        const c = ctx;
+                        await c.send.text("done");
+                    },
+                },
+                listFn: {
+                    cmd: "list",
+                    aliases: [],
+                    handler: async (_ctx, input) => {
+                        listCalls.push(input);
+                    },
+                },
+                crashFn: {
+                    cmd: "task",
+                    aliases: [],
+                    handler: async () => {
+                        throw new Error("plugin exploded");
+                    },
+                },
+            },
+        };
+        pluginRegistry.set("taskPlugin", plugin);
+    });
+    afterEach(() => {
+        pluginRegistry.delete("taskPlugin");
+        __setRegistryForTests(null);
+        _resetDriverManagerForTests();
+    });
+    test("routes a matched subcommand to the subcommand handler, not the parent's, and replies", async () => {
+        const spec = emptySpec({ subcommands: [emptySub({ function: "listFn" })] });
+        __setRegistryForTests(buildRegistry([spec]));
+        const msg = makeBotMessage({ body: "!task list" });
+        await handleMessage(msg, contract, store);
+        assert.equal(listCalls.length, 1, "subcommand handler was invoked");
+        assert.equal(runCalls.length, 0, "parent handler was not invoked for the subcommand token");
+    });
+    test("matched parent command dispatches through runCommand and sends its reply", async () => {
+        __setRegistryForTests(buildRegistry([emptySpec({})]));
+        const msg = makeBotMessage({ body: "!task" });
+        await handleMessage(msg, contract, store);
+        assert.equal(runCalls.length, 1, "parent handler ran");
+        assert.equal(sentTexts.length, 1);
+        assert.equal(sentTexts[0].text, "done");
+    });
+    test("a crash inside the matched command's handler is swallowed at the messageHandler boundary", async () => {
+        const spec = emptySpec({ id: "task::crash", cmd: "crashcmd", function: "crashFn" });
+        __setRegistryForTests(buildRegistry([spec]));
+        const msg = makeBotMessage({ body: "!crashcmd" });
+        // The whole point of this session's fix: runCommand() now genuinely
+        // throws (rethrow: true) so Phase-8's fireAlert runs, but
+        // messageHandler.ts wraps that call in its own try/catch so the
+        // per-message plugin loop — and handleMessage() itself — must never
+        // propagate the error to the caller.
+        await assert.doesNotReject(() => handleMessage(msg, contract, store));
+        assert.equal(sentTexts.length, 0, "no reply is sent for a crashed handler");
+    });
+    test("the message loop keeps working for the next message after a handler crash", async () => {
+        const crashSpec = emptySpec({ id: "task::crash", cmd: "crashcmd", function: "crashFn" });
+        __setRegistryForTests(buildRegistry([crashSpec]));
+        await handleMessage(makeBotMessage({ body: "!crashcmd" }), contract, store);
+        // Swap in a healthy command and confirm a later message still dispatches
+        // normally — the crash must not have left the plugin loop, the driver
+        // manager, or the registry in a broken state.
+        __setRegistryForTests(buildRegistry([emptySpec({})]));
+        await handleMessage(makeBotMessage({ body: "!task" }), contract, store);
+        assert.equal(runCalls.length, 1);
+        assert.equal(sentTexts.length, 1);
+        assert.equal(sentTexts[0].text, "done");
+    });
+});