@manybot/manybot 5.7.0 → 5.9.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,18 +16,17 @@
  * 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";
 import { handleMessage } from "./messageHandler.js";
-import { normalizeJid } from "#drivers/jid.js";
-import { loadPlugins, setupPlugins } from "#kernel/pluginLoader.js";
+import { normalizeJid, splitLidPn } from "#drivers/jid.js";
+import { loadPlugins, setupPlugins, loadIntegrationPlugin } from "#kernel/pluginLoader.js";
+import { isIntegrationOptIn } from "#kernel/integrationMode.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 +52,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,11 +204,32 @@ 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);
                 await setupPlugins(contract, store);
+                // Opt-in: when the operator is running the integration test
+                // suite (`MANYBOT_RUN_WHATSAPP_TESTS=1`), also load the
+                // reserved integration plugin so its public API
+                // (`waitForMarker`, `testChat`, ...) is available for the
+                // test harness. Done after setupPlugins() so the integration
+                // plugin's own setup() can subscribe to events already wired
+                // up by the regular plugins. Production runs (no opt-in flag)
+                // are completely unaffected — `loadIntegrationPlugin()` itself
+                // throws on missing opt-in, so we gate it here too for an
+                // early, clean skip.
+                if (isIntegrationOptIn()) {
+                    try {
+                        await loadIntegrationPlugin();
+                    }
+                    catch (e) {
+                        logger.warn(`[baileys] integration plugin failed to load: ${e.message}`);
+                    }
+                }
             }
             startCacheAutosave(store);
             startContactRefreshSweep(contract);
@@ -227,15 +248,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 +273,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 +283,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 +414,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 +483,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,13 +588,37 @@ 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;
+    // See splitLidPn() in #drivers/jid.js — `key.participant` is only the PN
+    // form under legacy `addressingMode: "pn"`; under the modern default
+    // "lid" mode it's already the LID and `key.participantAlt` carries the
+    // PN instead. Resolve by JID suffix, not by field position.
+    const participantIds = splitLidPn(key.participant, key.participantAlt);
     return {
         id: msg.key?.id ?? "",
         chatId: normalizeJid(msg.key?.remoteJid ?? ""),
@@ -580,10 +636,10 @@ export function toBotMessage(msg) {
             fromMe: false,
             participant: contextInfo.participant ?? undefined,
         } : undefined,
-        fromLid: key.participantAlt,
-        fromPn: key.participant,
-        participantAlt: key.participantAlt,
-        remoteJidAlt: key.remoteJidAlt,
+        fromLid: participantIds.lid,
+        fromPn: participantIds.pn,
+        participantAlt: participantIds.lid,
+        remoteJidAlt: splitLidPn(key.remoteJid, key.remoteJidAlt).lid,
         _raw: {
             pollEncKeyRaw: m?.messageContextInfo?.messageSecret ?? undefined,
         },

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

@@ -10,16 +10,156 @@
  *   3. Pass context to all active plugins
  *
  * Each plugin decides whether to act or ignore.
+ *
+ * v6 loading indicators: a matched command may declare a `loading:` spec
+ * (or reference a top-level `loading_presets:` preset) which controls
+ * the user-visible "processando..." signal — `reaction`, `typing`,
+ * `recording_audio`, `spinner`, or `none`. The spec is resolved at
+ * registry build time (defaults → category → command → sub), so by the
+ * time the dispatch path reads it we only have to apply it.
  */
 import { CHATS, EXCLUDE_CHATS } from "#config";
+import { getChatPrefix, getChatLocale } from "#kernel/chatOverrides.js";
 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) : "";
+}
+/**
+ * Drive the per-command loading indicator described by the registry.
+ *
+ * - `reaction`        : drop an emoji reaction on the source message,
+ *                       update with onSuccess/onError on completion.
+ * - `typing`          : native WhatsApp "typing..." presence, refreshed
+ *                       on a 4s interval; cleared on completion.
+ * - `recording_audio` : native WhatsApp "recording audio..." presence,
+ *                       same interval/clear semantics as typing.
+ * - `spinner`         : self-sent message showing a frame sequence,
+ *                       edited every `intervalMs` (default 1500); last
+ *                       frame stays on completion.
+ * - `none`            : no-op — caller doesn't see a difference.
+ *
+ * All best-effort: any driver-level failure is logged at `warn` level
+ * and swallowed so a broken indicator never breaks a command.
+ */
+function startLoadingIndicator(spec, contract, rawJid, msgKey) {
+    const noop = async () => { };
+    if (!spec)
+        return { stop: noop };
+    if (spec.type === "reaction") {
+        const icon = spec.icon ?? "⏳";
+        if (msgKey) {
+            contract.react(rawJid, msgKey, icon).catch((e) => {
+                const err = e instanceof Error ? e : new Error(String(e));
+                logger.warn(`[messageHandler] loading.reaction send failed: ${err.message}`);
+            });
+        }
+        return {
+            stop: async (outcome) => {
+                if (!msgKey)
+                    return;
+                const next = outcome === "success" ? spec.onSuccess : spec.onError;
+                try {
+                    await contract.react(rawJid, msgKey, next ?? "");
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    logger.warn(`[messageHandler] loading.reaction clear failed: ${err.message}`);
+                }
+            },
+        };
+    }
+    if (spec.type === "typing" || spec.type === "recording_audio") {
+        const presence = spec.type === "typing" ? "composing" : "recording";
+        const interval = setInterval(() => {
+            contract.sendPresenceUpdate(presence, rawJid).catch(() => { });
+        }, 4000);
+        contract.sendPresenceUpdate(presence, rawJid).catch(() => { });
+        return {
+            stop: async () => {
+                clearInterval(interval);
+                contract.sendPresenceUpdate("paused", rawJid).catch(() => { });
+            },
+        };
+    }
+    if (spec.type === "spinner") {
+        const frames = spec.frames && spec.frames.length > 0 ? spec.frames : ["⏳"];
+        const intervalMs = Math.max(1000, spec.intervalMs ?? 1500);
+        let frameIdx = 0;
+        let sentMsgId = null;
+        const cycle = async () => {
+            try {
+                if (sentMsgId === null) {
+                    const sent = await contract.sendText(rawJid, frames[0]);
+                    sentMsgId = sent.id;
+                }
+                else {
+                    frameIdx = (frameIdx + 1) % frames.length;
+                    await contract.editMessage(rawJid, { id: sentMsgId, remoteJid: rawJid, fromMe: true }, frames[frameIdx]);
+                }
+            }
+            catch {
+                // Spinner is best-effort — leave the previous frame in place
+                // when an edit fails rather than aborting the whole indicator.
+            }
+        };
+        cycle().catch(() => { });
+        const interval = setInterval(() => { cycle().catch(() => { }); }, intervalMs);
+        return {
+            stop: async (outcome) => {
+                clearInterval(interval);
+                if (sentMsgId !== null) {
+                    const finalText = outcome === "success" ? spec.onSuccess : spec.onError;
+                    try {
+                        if (finalText !== undefined) {
+                            await contract.editMessage(rawJid, { id: sentMsgId, remoteJid: rawJid, fromMe: true }, finalText);
+                        }
+                        else {
+                            await contract.deleteMessage(rawJid, { id: sentMsgId, remoteJid: rawJid, fromMe: true }, true);
+                        }
+                    }
+                    catch (e) {
+                        const err = e instanceof Error ? e : new Error(String(e));
+                        logger.warn(`[messageHandler] loading.spinner finalize failed: ${err.message}`);
+                    }
+                }
+            },
+        };
+    }
+    // `none` or any future variant — nothing to do.
+    return { stop: noop };
+}
+/**
+ * Resolve the loading spec for the matched command/sub. Subcommands win
+ * (their own chain inheritance ran at registry build time); falls back
+ * to the parent's resolved spec.
+ */
+function resolveLoadingForDispatch(entry, resolution) {
+    if (resolution.target.kind === "sub")
+        return resolution.target.sub.loading ?? entry.loading;
+    if (resolution.target.kind === "parent")
+        return entry.loading;
+    return null;
+}
 // ── 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 +231,167 @@ 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, rawKey);
     }
     finally {
         releaseChatSlot();
     }
 }
-async function runPluginsForMessage(msg, chat, contract, store, rawJid) {
+async function runPluginsForMessage(msg, chat, msgCtx, contract, store, rawJid, rawKey) {
+    const chatPrefix = getChatPrefix(msg.chatId);
+    const chatLocale = getChatLocale(msg.chatId);
+    const command = extractCommand(msgCtx.body, chatPrefix);
+    const registry = getCommandRegistry();
+    // 0. Welcome message (first message within the configured window)
+    //
+    // Two gates before we even consider firing the welcome:
+    //
+    //   - `!msg.fromMe`: skip when the bot itself "sent" the message
+    //     that triggered this dispatch. Baileys' history-sync replays
+    //     the bot's own outgoing messages as `messages.upsert` with
+    //     `fromMe=true` on every reconnect — without this gate, the
+    //     bot would greet itself in its own DM/group on every restart
+    //     the moment history-sync completes. The welcome is for
+    //     *incoming* messages only.
+    //
+    //   - `!chat.isGroup`: skip when the message arrived in a group.
+    //     A new member joining a group shouldn't get a per-member
+    //     welcome reply inside the group's conversation — it's noise
+    //     and reads weird in front of everyone else. The welcome is
+    //     only meaningful in a 1:1 (DM) chat where the message
+    //     originates from the user being greeted, and where the reply
+    //     goes back to the same chat (`msgCtx.reply` already targets
+    //     the source chat).
+    if (registry && !msg.fromMe && !chat.isGroup) {
+        const welcomeMsg = checkAndTriggerWelcomeMessage(msgCtx.sender ?? msg.chatId, registry, { body: msgCtx.body, timestamp: msg.timestamp }, chatLocale, chatPrefix);
+        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(chatPrefix.length + command.length).trim();
+        const scope = chat.isGroup ? "group" : "dm";
+        const menuResponse = handleMenuCommand(command, rawArgs, registry, chatLocale, 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(chatPrefix.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,
+            sender: { lid: msgCtx.sender, pn: msgCtx.senderPn },
+            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, chatLocale) ?? "";
+            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;
+    // "core" (ping/status/config/...) is a synthetic pseudo-plugin: it only
+    // exists in a *local* `allPlugins` map built inside commandRegistry.ts
+    // for registry-building purposes — it is never inserted into the real
+    // `pluginRegistry` singleton that the loop below iterates. Left as-is,
+    // no "core"-sourced command could ever be dispatched (runCommand() would
+    // never be called for it, plugin count or not), so it's handled here
+    // explicitly, once, before the real-plugin loop.
+    if (matchedPlugin && matchedPlugin.pluginName === "core") {
+        const coreCtx = buildApi({
+            msg,
+            chat,
+            contract,
+            store,
+            pluginRegistry,
+            pluginName: "core",
+            guardOptions: {},
+        });
+        const coreLoading = startLoadingIndicator(resolveLoadingForDispatch(matchedPlugin, resolution), contract, rawJid, rawKey);
+        let coreOutcome = "success";
+        try {
+            await runCommand({ pluginName: "core", ctx: coreCtx, resolution, reply: msgCtx.reply, chatId: msg.chatId });
+        }
+        catch (e) {
+            coreOutcome = "error";
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.warn(`[messageHandler] runCommand crashed for core: ${err.message}`);
+        }
+        finally {
+            await coreLoading.stop(coreOutcome);
+        }
+    }
     for (const plugin of pluginRegistry.values()) {
         const ctx = buildApi({
             msg,
@@ -108,7 +402,7 @@ async function runPluginsForMessage(msg, chat, contract, store, rawJid) {
             pluginName: plugin.name,
             guardOptions: plugin.guardOptions,
         });
-        const useTyping = plugin.guardOptions?.typing !== false;
+        const useTyping = !matchedPlugin && plugin.guardOptions?.typing !== false;
         let typingInterval;
         if (useTyping) {
             // Refresh presence every 4s so WhatsApp doesn't auto-clear it
@@ -117,7 +411,40 @@ 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) {
+                // Loading indicator: the resolved spec is read once per dispatch
+                // and drives start/stop around the runCommand call.
+                const loading = startLoadingIndicator(resolveLoadingForDispatch(matchedPlugin, resolution), contract, rawJid, rawKey);
+                let outcome = "success";
+                try {
+                    // 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, chatId: msg.chatId });
+                    }
+                    catch (e) {
+                        outcome = "error";
+                        const err = e instanceof Error ? e : new Error(String(e));
+                        logger.warn(`[messageHandler] runCommand crashed for plugin "${plugin.name}": ${err.message}`);
+                    }
+                }
+                finally {
+                    await loading.stop(outcome);
+                }
+            }
+            else {
+                await runPlugin(plugin, ctx);
+            }
         }
         finally {
             if (useTyping) {
@@ -126,4 +453,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, chatLocale));
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            logger.warn(`[messageHandler] notFoundFallback reply failed: ${err.message}`);
+        }
+    }
 }