botmux 3.7.1 → 3.8.0

package/dist/im/lark/event-dispatcher.js

@@ -10,13 +10,13 @@ import { atomicWriteFileSync } from '../../utils/atomic-write.js';
 import { join } from 'node:path';
 import { getBot, getAllBots, findOncallChat, getOwnerOpenId } from '../../bot-registry.js';
 import { config, isVcMeetingAgentGloballyEnabled, vcMeetingAgentGlobalListenerBotAppId } from '../../config.js';
-import { getChatInfo, getChatMode, getCachedChatMode, resolveSiblingBotBySenderOpenId, replyMessage, sendMessage, sendUserMessage, isHumanOpenId, updateMessage } from './client.js';
+import { getChatInfo, getChatMode, getCachedChatMode, getUserProfile, listChatMessagesUntil, resolveSiblingBotBySenderOpenId, replyMessage, sendMessage, sendUserMessage, isHumanOpenId, updateMessage } from './client.js';
 import { logger } from '../../utils/logger.js';
 import { BoundedMap } from '../../utils/bounded-map.js';
 import { serializeByAnchor } from '../../utils/anchor-serializer.js';
 import { parseForceTopicInvocation } from '../../core/command-handler.js';
 import { shouldAutoStartOnNewTopic } from '../../core/auto-start.js';
-import { stripLeadingMentions, mentionOpenId, extractMentionIdentities } from './message-parser.js';
+import { stripLeadingMentions, mentionOpenId, mentionAppId, extractMentionIdentities, messageMentionsBot } from './message-parser.js';
 import { recordObservedBots, listObservedBots } from '../../services/observed-bots-store.js';
 import { isTeamBot, recordTeamBot } from '../../services/team-bots-store.js';
 import { isTeamGroupChat } from '../../services/team-groups-store.js';
@@ -28,12 +28,13 @@ import { BOTMUX_REQUIRED_SCOPES, DOC_FEATURE_SCOPES, DOC_WATCH_SCOPES, DOC_COMME
 import { automateOpenPlatformSetup } from '../../setup/open-platform-automation.js';
 import { larkHosts, normalizeBrand, sdkDomain } from './lark-hosts.js';
 import { tryHandleGrantCommand } from './grant-command.js';
+import { tryHandleInviteCommand } from './invite-command.js';
 import { tryHandleReplyModeCommand } from './reply-mode-command.js';
 import { tryHandleSubstituteCommand } from './substitute-command.js';
 import { buildGrantCard } from './card-builder.js';
 import { openPending, isThrottled, clearPending } from './grant-pending.js';
 import { localeForBot, t } from '../../i18n/index.js';
-import { chatQuotaKey, globalQuotaKey } from '../../services/grant-store.js';
+import { chatQuotaKey, getGrantExpiresAt, globalQuotaKey, removeExpiredGrant, } from '../../services/grant-store.js';
 import { ForwardFollowupBuffer } from './forward-followup-buffer.js';
 import { listForwardFollowups, putForwardFollowup, removeForwardFollowup } from './forward-followup-store.js';
 import { claimMessageOnce, _resetCacheForTest as _resetSeenMessagesForTest } from '../../services/seen-message-store.js';
@@ -42,7 +43,9 @@ import { resolveRegularGroupMode, resolveGroupMentionMode } from '../../services
 import { buildSummaryCommandPrompt } from './summary-command.js';
 import { DEFAULT_SUMMARY_PROMPT, summaryRangeFromBotConfig } from '../../services/summary-range-store.js';
 import { isSubstituteEnabledForChat } from '../../services/substitute-chat-toggle-store.js';
+import { evaluateMessageListener, resolveListenerSenderIdentity, buildListenerBotAppIdToOpenId, collectListenerBotAppIds } from '../../services/message-listener.js';
 import { parseVcMeetingPushEvent, VC_BOT_MEETING_ACTIVITY_EVENT, VC_BOT_MEETING_ENDED_EVENT, VC_BOT_MEETING_INVITED_EVENT, VC_PARTICIPANT_MEETING_JOINED_EVENT, } from '../../vc-agent/push-source.js';
+import { DEFAULT_GRANT_DURATION_MS, DEFAULT_GRANT_QUOTA } from '../../services/grant-policy.js';
 // 大厅回执互教的防环闸：每进程对同一打卡者只回一次（见 hall swallow 分支）。
 const hallEchoReplied = new Set();
 function vcMeetingEventPayloadForLog(data) {
@@ -674,6 +677,24 @@ export async function getGroupStats(larkAppId, chatId) {
         return { userCount: 999, botCount: 999 };
     }
 }
+/**
+ * Drop the cached group stats for one chat — called when a membership-change
+ * event that is VISIBLE to this app arrives (user add/delete broadcast, or our
+ * own bot being added/removed), so the 1v1 relax gate sees fresh counts on the
+ * very next message instead of coasting on stale numbers for up to
+ * CHAT_CACHE_TTL. TTL 继续保留,作为事件未订阅（老应用）时的兜底。
+ * 注意跨进程边界:「别的 bot 进群/离群」事件只推给当事 bot 自己的 app,
+ * 一 bot 一 daemon 部署下此函数够不到兄弟进程的缓存(见 handler 处注释)。
+ */
+export function invalidateChatStats(larkAppId, chatId) {
+    if (chatStatsCache.delete(`${larkAppId}:${chatId}`)) {
+        logger.debug(`[group-stats] invalidated cached stats for ${chatId} (${larkAppId}): membership changed`);
+    }
+}
+/** Test-only: clear the group-stats cache between cases. */
+export function __resetChatStatsForTest() {
+    chatStatsCache.clear();
+}
 // ─── Cross-bot open_id mapping ──────────────────────────────────────────
 //
 // Lark open_id is per-app scoped: Bot A sees a different open_id for Bot B
@@ -730,6 +751,10 @@ export function isKnownPeerBot(dataDir, larkAppId, senderOpenId) {
  * union_id roster）与 isTeamBot（团队群里学来的 union_id）都是 union_id 锚定的
  * bot 专属信任；平台拉的团队群则经 platform: 前缀镜像进 team-groups，走同一个
  * isTeamGroupChat。两条路都算团队模式，都不需要 /grant。
+ *
+ * 调用方只剩 {@link evaluateBotTalk} 一个（bot 闸门的唯一入口）；(1) 的两条腿与
+ * evaluateTalk 的 teamBot 腿重合，真正额外放行的是 (2)。保留本谓词是因为它是
+ * 「bot 团队信任」的定义所在，且有专属单测（team-peer-trust / platform-team-trust）。
  */
 export function isTrustedTeamBotSender(dataDir, chatId, senderUnionId) {
     return isTeamBot(dataDir, senderUnionId)
@@ -889,40 +914,17 @@ export function isBotMentioned(larkAppId, message, _senderOpenId) {
         logger.debug(`[${larkAppId}] Bot open_id not yet known, skipping @mention check`);
         return false;
     }
-    // 1. Check message.mentions array (populated for user-sent text messages).
-    //    mentionOpenId() tolerates both the WS event object shape and the REST
-    //    string shape, so a Lark mention-shape change can't silently break
-    //    @-detection (which would make the bot ignore every @ with no error).
-    const mentions = message.mentions ?? [];
     // Early-warning: today's WS events carry mention.id as an object; the REST
     // API carries a bare string. A string-form id on the event path means Lark
     // has converged the event onto the REST shape — surface it (once) so a silent
-    // @-routing regression announces itself even though mentionOpenId absorbs it.
+    // @-routing regression announces itself even though the shared gate absorbs it.
+    const mentions = message?.mentions ?? [];
     if (!warnedStringMentionShape && mentions.some((m) => typeof m?.id === 'string')) {
         warnedStringMentionShape = true;
         logger.warn(`[${larkAppId}] mention.id arrived in string form on the event path — Lark may have converged the WS event onto the REST shape. mentionOpenId() absorbs it, but verify group @-routing. (logged once per process)`);
     }
-    if (mentions.some((m) => mentionMatchesBot(m, larkAppId, botOpenId))) {
-        return true;
-    }
-    // 2. Check post content for inline at tags (bot-sent post messages may not
-    //    populate message.mentions — the @mention is embedded in the content structure)
-    try {
-        const content = JSON.parse(message.content ?? '{}');
-        const inner = content.zh_cn ?? content.en_us ?? content;
-        if (Array.isArray(inner?.content)) {
-            for (const paragraph of inner.content) {
-                if (!Array.isArray(paragraph))
-                    continue;
-                for (const node of paragraph) {
-                    if (node.tag === 'at' && node.user_id === botOpenId)
-                        return true;
-                }
-            }
-        }
-    }
-    catch { /* ignore parse errors */ }
-    return false;
+    // Single source of truth shared with the poll + dashboard-preview legs.
+    return messageMentionsBot(message, larkAppId, botOpenId);
 }
 /** Does this message @mention a *specific other member* (a person or bot that
  *  is NOT this bot)? Used by the 'ambient' mention policy to decide whether to
@@ -1011,7 +1013,15 @@ export function resolveSubstituteTrigger(larkAppId, message) {
     }
     return undefined;
 }
+function isSubstituteExcludedChat(cfg, chatId) {
+    return cfg?.excludedChats?.includes(chatId) ?? false;
+}
 function isSubstituteAllowedChat(cfg, chatId) {
+    // 黑名单先判且 deny-wins：命中即整段替身触发块短路（连带跳过其后的运行态
+    // 开关 isSubstituteEnabledForChat），因此配置黑名单 = 硬关闭，/substitute on
+    // 也翻不回来。对普通群与话题群一视同仁，与白名单同层。
+    if (isSubstituteExcludedChat(cfg, chatId))
+        return false;
     if (!cfg?.chats?.length)
         return true;
     return cfg.chats.includes(chatId);
@@ -1027,29 +1037,29 @@ function mentionMatchesBot(m, larkAppId, botOpenId) {
     const appId = mentionAppId(m);
     return Boolean(larkAppId && appId === larkAppId);
 }
-function mentionIdType(m) {
-    if (!m || typeof m !== 'object')
-        return undefined;
-    if (typeof m.id_type === 'string')
-        return m.id_type;
-    if (typeof m.idType === 'string')
-        return m.idType;
-    return undefined;
-}
-function mentionAppId(m) {
-    if (!m || typeof m !== 'object')
-        return undefined;
-    if (typeof m.appId === 'string')
-        return m.appId;
-    if (typeof m.app_id === 'string')
-        return m.app_id;
-    const idType = mentionIdType(m);
-    if (idType === 'app_id' && typeof m.id === 'string')
-        return m.id;
-    if (m.id && typeof m.id === 'object' && typeof m.id.app_id === 'string')
-        return m.id.app_id;
-    return undefined;
-}
+/**
+ * 全部 talk 放行源的**运行时**枚举（TalkReason 由它派生）。
+ *
+ * 之所以是数组而不是纯 type：`test/bot-talk-parity.test.ts` 按它逐条核对
+ * 「这条腿对人和对 bot 分别是什么行为」，少一格就红。tsconfig 的 include 只有
+ * `src/**`，测试不过 tsc——纯类型层的穷尽约束在这里执行不了，必须落到运行时。
+ *
+ * 新增一条 talk 源时：改 evaluateTalk（人/bot 同时生效）+ 在那张表补一格说明，
+ * **不要**去 bot 路由闸里加 OR 腿（那正是 allowedChatGroups 漏掉的老路）。
+ */
+export const TALK_REASONS = [
+    'allowedUser',
+    'oncall',
+    'peer',
+    'teamBot',
+    'teamMember',
+    'allowedChatGroup',
+    'open',
+    'chatGrant',
+    'globalGrant',
+    'p2pOpen',
+    'none',
+];
 export function grantCommandRestriction(larkAppId, chatId, senderOpenId) {
     const bot = getBot(larkAppId);
     if (bot.config.restrictGrantCommands !== true)
@@ -1062,11 +1072,42 @@ export function grantCommandRestriction(larkAppId, chatId, senderOpenId) {
 }
 /** per-chat per-user 授权命中判断（仅用于 canTalk —— 不给管理命令权）。 */
 function hasChatGrant(larkAppId, chatId, openId) {
-    return !!chatId && !!openId && !!getBot(larkAppId).config.chatGrants?.[chatId]?.includes(openId);
+    if (!chatId || !openId || !getBot(larkAppId).config.chatGrants?.[chatId]?.includes(openId))
+        return false;
+    return grantNotExpired(larkAppId, 'chat', chatId, openId, chatQuotaKey(chatId, openId));
 }
 /** 全局对话授权命中判断（人/bot 通用，仅用于 canTalk / bot 路由闸 —— 不给管理命令权）。 */
 function hasGlobalGrant(larkAppId, openId) {
-    return !!openId && !!getBot(larkAppId).config.globalGrants?.includes(openId);
+    if (!openId || !getBot(larkAppId).config.globalGrants?.includes(openId))
+        return false;
+    return grantNotExpired(larkAppId, 'global', undefined, openId, globalQuotaKey(openId));
+}
+const expiryCleanupInFlight = new Set();
+/**
+ * 到期判断是同步安全边界：过期后本条消息立即拒绝；持久化清理由带 observedExpiresAt
+ * 条件的原子 RMW 异步完成，避免误删刚续期的授权。
+ */
+function grantNotExpired(larkAppId, scope, chatId, openId, grantKey) {
+    const expiresAt = getGrantExpiresAt(larkAppId, grantKey);
+    if (expiresAt === undefined || Date.now() < expiresAt)
+        return true;
+    const cleanupKey = `${larkAppId}:${grantKey}:${expiresAt}`;
+    if (!expiryCleanupInFlight.has(cleanupKey)) {
+        expiryCleanupInFlight.add(cleanupKey);
+        void removeExpiredGrant(larkAppId, scope, chatId, openId, expiresAt)
+            .then(result => {
+            if (!result.ok)
+                logger.warn(`[grant:${larkAppId}] expiry cleanup failed key=${grantKey} reason=${result.reason}`);
+        })
+            .catch(err => logger.warn(`[grant:${larkAppId}] expiry cleanup failed key=${grantKey}: ${err}`))
+            .finally(() => expiryCleanupInFlight.delete(cleanupKey));
+    }
+    return false;
+}
+/** 整群 talk 授权命中判断（裸 `/grant` 写入的 allowedChatGroups）。chat 维度、sender 无关，
+ *  与 oncall 同一个安全模型：只放行 canTalk / bot 路由闸，canOperate 绝不读它。 */
+function hasAllowedChatGroup(larkAppId, chatId) {
+    return !!chatId && !!getBot(larkAppId).config.allowedChatGroups?.includes(chatId);
 }
 /**
  * 是否配置了任何白名单（限制态）。判定用 **原始** config.allowedUsers, 不用
@@ -1110,7 +1151,20 @@ export function evaluateTalk(larkAppId, chatId, senderOpenId, senderUnionId, mem
     if (chatId && findOncallChat(larkAppId, chatId)) {
         const def = bot.config.messageQuota?.defaultLimit;
         if (typeof def === 'number' && Number.isInteger(def) && def > 0 && senderOpenId) {
-            return { allowed: true, reason: 'oncall', quotaKey: chatQuotaKey(chatId, senderOpenId) };
+            // 交集处理：同群若还持有显式 chatGrant，额度由授权决定而非 oncall default。
+            // 三态：live 显式授权 → explicitGrantOverride（不兜 default）；已过期 → expiredGrantCleanup
+            //（透传给 consumeQuota，锁内以当前 expiry 为准原子清成员+quota+expiry 并回落 default）；
+            // 非成员 → 无覆盖，正常走 oncall default 懒初始化。
+            const gk = chatQuotaKey(chatId, senderOpenId);
+            const isMember = !!bot.config.chatGrants?.[chatId]?.includes(senderOpenId);
+            const exp = isMember ? getGrantExpiresAt(larkAppId, gk) : undefined;
+            if (isMember && exp !== undefined && Date.now() >= exp) {
+                return {
+                    allowed: true, reason: 'oncall', quotaKey: gk,
+                    expiredGrantCleanup: { scope: 'chat', chatId, openId: senderOpenId },
+                };
+            }
+            return { allowed: true, reason: 'oncall', quotaKey: gk, explicitGrantOverride: isMember };
         }
         return { allowed: true, reason: 'oncall' };
     }
@@ -1130,7 +1184,7 @@ export function evaluateTalk(larkAppId, chatId, senderOpenId, senderUnionId, mem
     if (memberUnionId && isPlatformTeamMemberChat(config.session.dataDir, chatId, memberUnionId)) {
         return { allowed: true, reason: 'teamMember' };
     }
-    if (chatId && bot.config.allowedChatGroups?.includes(chatId))
+    if (hasAllowedChatGroup(larkAppId, chatId))
         return { allowed: true, reason: 'allowedChatGroup' };
     // p2pOpen：私聊维度的 talk-open，与 oncall（群维度）同一个安全模型——放行 canTalk，
     // canOperate 一行不读它（管理仍限 allowedUsers）。谁能私聊由飞书应用「可用范围」控制。
@@ -1151,6 +1205,63 @@ export function evaluateTalk(larkAppId, chatId, senderOpenId, senderUnionId, mem
     }
     return { allowed: false, reason: 'none' };
 }
+/**
+ * BOT 发送方的 talk 判定 —— bot 路由闸（外部 bot @ 本 bot）的**唯一**入口。
+ *
+ * = 人侧 evaluateTalk 的完整模型 ＋ 一条 bot 专属腿。历史上 bot 侧手抄了一份
+ * talk 源子集（oncall / peer / teamBot / chatGrant / globalGrant 的 OR 链），
+ * 于是每加一条新 talk 源就漏一次、复发一次同类 bug：oncall 漏过一次、开放模式
+ * 漏过一次、allowedChatGroups 又漏一次（owner 整群 `/grant` 后真人能说话、外部 bot
+ * 一 @ 仍弹授权卡）。收敛成单一谓词后，**新增 talk 源只需改 evaluateTalk**；
+ * test/bot-talk-parity.test.ts 按 TALK_REASONS 逐条盯着这条约束。
+ *
+ * 与人侧仅有的两条差异，都是刻意的，改动前先读：
+ *
+ *  1. `isTrustedTeamBotSender`（+，bot 才有）：其中真正额外放行的是**团队拉群**那条腿
+ *     ——本群是团队拉群（团队掌控成员）→ 说话的 botmux bot 即视为背书队友，首次接触
+ *     也放行，与 oncall 群豁免同构。chat 维度、不看 union，覆盖 sender 事件没带
+ *     `union_id` 的情况（此时 gate 前那次 `recordTeamBot` 被 `senderUnionId &&` 短路，
+ *     evaluateTalk 的 teamBot 腿必然落空）。**这条不能下沉进 evaluateTalk**：那是人/bot
+ *     共用的，加进去等于团队群里任何真人都自动过 canTalk，绕开 teamMember 腿的成员校验
+ *     （isPlatformTeamMemberChat 要求 union 在该团队成员名单里）。它另外两条 union 锚定
+ *     的腿与 evaluateTalk 的 teamBot 腿重合，留着是为了让「bot 团队信任」只有一处定义。
+ *
+ *  2. `p2pOpen`（−）：不传 chatType → 该腿 fail-closed 不生效。飞书里 bot 之间不存在
+ *     私聊，开着只是白扩边界。
+ *
+ * @param senderUnionId 必须是飞书盖章的 bot 发送方 union（`sender_type ∈ app|bot`），
+ *   与 evaluateTalk 的 bot-trust 腿同一契约。真人 union 走 memberUnionId，本函数恒不传。
+ */
+export function evaluateBotTalk(larkAppId, chatId, senderOpenId, senderUnionId) {
+    const ev = evaluateTalk(larkAppId, chatId, senderOpenId, senderUnionId);
+    if (ev.allowed)
+        return ev;
+    return isTrustedTeamBotSender(config.session.dataDir, chatId, senderUnionId)
+        ? { allowed: true, reason: 'teamBot' }
+        : ev;
+}
+/**
+ * `botmux ask` 答复者是否可作答（= 该 chat 的 canTalk 门）——ask-broker 注入的
+ * canTalkChecker 的**唯一生产实现**，daemon bootstrap 一行转调它。
+ *
+ * 抽成独立导出函数（而非把分派内联进 daemon setter 闭包）的意义：让**分派谓词本身**
+ * 能被回归测试直接咬住——测试对本函数喂真实 team store 状态断言三组行为，改坏这里的
+ * 分派逻辑（如退回旧 evaluateTalk / 不认 actor.botSender）会立刻红。注意测试只覆盖到
+ * 本函数；daemon setter 的一行转调与 submitCustomReply 的 actor 构造仍靠人工核对
+ * （setter 只有一行，不经测试机械覆盖）。
+ *
+ *  - bot 发送方（actor.botSender）→ evaluateBotTalk（含团队拉群那条 chat 维度腿，
+ *    覆盖 sender 事件没带 union_id 的场景），与 dispatcher 外层闸 / quota 复查同源。
+ *  - 人 / 无 actor（卡片点击路径）→ evaluateTalk 全模型：actor.senderUnionId 走
+ *    teamBot 腿（人路径恒 undefined）、actor.memberUnionId 走 teamMember 腿。
+ *    actor 省略时两者都是 undefined → 退化为纯 evaluateTalk(openId, chatType)，
+ *    与本次改动前的卡片点击语义完全一致。
+ */
+export function evaluateAskAnswerTalk(larkAppId, chatId, senderOpenId, chatType, actor) {
+    return actor?.botSender
+        ? evaluateBotTalk(larkAppId, chatId, senderOpenId, actor.senderUnionId).allowed
+        : evaluateTalk(larkAppId, chatId, senderOpenId, actor?.senderUnionId, actor?.memberUnionId, chatType).allowed;
+}
 export function canOperate(larkAppId, _chatId, senderOpenId, senderUnionId) {
     const bot = getBot(larkAppId);
     // 同部署 cross-ref / isKnownPeerBot 只证明「这是一个可路由的 bot 身份」，仅供
@@ -1181,19 +1292,27 @@ export function canOperate(larkAppId, _chatId, senderOpenId, senderUnionId) {
  * 对话放行腿命中即可）。名单外或未配置 → 与 canOperate 完全等价（现状不变）。
  *
  * 只作用于 daemon.ts 两条路由的 DAEMON_COMMANDS 统一闸；在统一闸之前特判的命令
- * （/vc-auth /term）与 handler 内部自带 owner 闸的命令（/card /insight /land）
+ * （/vc-auth /term）与 handler 内部自带 owner 闸的命令（/card /insight）
  * 不受影响——内部闸仍是最终权威（fail-closed）。
  *
  * chatType 省略时 p2pOpen 腿不生效（fail-closed），与 canTalk 语义一致——
  * 私聊路径的调用点必须把 chatType 传进来。
+ *
+ * botSender：降权到 talk 判定这一段，必须与 dispatcher 外层闸 / quota 复查用**同一个**
+ * 谓词。bot 发送方走 evaluateBotTalk（含团队拉群那条 chat 维度腿，覆盖 sender 事件没带
+ * union_id 的情况）；否则「团队拉群里外部 bot 能 talk 却执行不了降权到 canTalk 的命令
+ * （如 /status）」——单一 talk 谓词在这道 daemon 命令闸继续分叉。不传（人的路径）→
+ * 原样走 canTalk / evaluateTalk，语义不变。canOperate 那段人/bot 通用，不受影响。
  */
-export function canRunDaemonCommand(larkAppId, chatId, senderOpenId, senderUnionId, cmd, memberUnionId, chatType) {
+export function canRunDaemonCommand(larkAppId, chatId, senderOpenId, senderUnionId, cmd, memberUnionId, chatType, botSender) {
     if (canOperate(larkAppId, chatId, senderOpenId, senderUnionId))
         return true;
     const list = getBot(larkAppId).config.canTalkDaemonCommands;
     if (!list?.includes(cmd))
         return false;
-    return canTalk(larkAppId, chatId, senderOpenId, senderUnionId, memberUnionId, chatType);
+    return botSender
+        ? evaluateBotTalk(larkAppId, chatId, senderOpenId, senderUnionId).allowed
+        : canTalk(larkAppId, chatId, senderOpenId, senderUnionId, memberUnionId, chatType);
 }
 /**
  * 入口 A：无权限者 @bot 时弹授权申请卡（正文 @owner，由 owner 处置）。
@@ -1214,10 +1333,23 @@ async function maybeSendGrantRequestCard(larkAppId, message, chatId, requesterOp
     const observedName = mentionName
         ? undefined
         : listObservedBots(config.session.dataDir, larkAppId, chatId).find(b => b.openId === requesterOpenId)?.name;
-    const name = mentionName ?? observedName ?? requesterOpenId;
+    const profileName = mentionName || observedName
+        ? undefined
+        : (await getUserProfile(larkAppId, requesterOpenId).catch(() => null))?.name;
+    const shortRequester = `${requesterOpenId.slice(0, 10)}…${requesterOpenId.slice(-4)}`;
+    const name = mentionName ?? observedName ?? profileName ?? shortRequester;
     // 把原始消息事件挂在 pending 上：授权成功后可重放，用户无需再 @ 一遍。
-    const nonce = openPending(larkAppId, chatId, requesterOpenId, getBot(larkAppId).config.messageQuota?.defaultLimit, messageData);
-    const card = buildGrantCard({ ownerOpenId: owner, targets: [{ openId: requesterOpenId, name: String(name) }], chatId, nonce, mode: 'request' }, localeForBot(larkAppId));
+    const quota = getBot(larkAppId).config.messageQuota?.defaultLimit ?? DEFAULT_GRANT_QUOTA;
+    const nonce = openPending(larkAppId, chatId, requesterOpenId, quota, messageData, DEFAULT_GRANT_DURATION_MS);
+    const card = buildGrantCard({
+        ownerOpenId: owner,
+        targets: [{ openId: requesterOpenId, name: String(name) }],
+        chatId,
+        nonce,
+        mode: 'request',
+        quota,
+        durationMs: DEFAULT_GRANT_DURATION_MS,
+    }, localeForBot(larkAppId));
     await replyMessage(larkAppId, message.message_id, card, 'interactive')
         .catch(err => {
         // 发卡失败必须撤掉刚开的 pending，否则该发送方被节流压死、owner 永远看不到卡片，
@@ -1244,7 +1376,13 @@ export async function checkGroupMessageAccess(larkAppId, message, chatId, sender
     // No @mention — only allow if sender is the sole human in the group
     // AND this is the only bot in the chat. With multiple bots, require @mention
     // to disambiguate.
-    if (isAllowed) {
+    //
+    // 若消息 @ 了别的具体成员（mentionsAnotherMember），群必然不是 1人1bot——
+    // 只有群成员能被 @，多出的那个 @ 本身就是人数变化的证据。上游可能还抱着
+    // 陈旧缓存 {1,1}（刚拉了新 bot 的 TTL 窗口），这会直接跳过人数查询落到
+    // 'ignore'，挡住「用户 @ 新 bot、老 bot 跟着回复」。群聊 @ 策略 never/ambient
+    // 在调用方（relax 条款）已先行结算，这里不受影响。
+    if (isAllowed && !mentionsAnotherMember(larkAppId, message)) {
         const { userCount, botCount } = await getGroupStats(larkAppId, chatId);
         logger.debug(`Group user count: ${userCount}, bot count: ${botCount}`);
         if (userCount <= 1 && botCount <= 1) {
@@ -1253,6 +1391,154 @@ export async function checkGroupMessageAccess(larkAppId, message, chatId, sender
     }
     return 'ignore';
 }
+function listenerRoutingContext(input) {
+    return {
+        data: input.data,
+        ctx: {
+            chatId: input.chatId,
+            messageId: input.messageId,
+            chatType: input.chatType,
+            larkAppId: input.larkAppId,
+            scope: 'thread',
+            anchor: input.messageId,
+            messageListener: input.match,
+        },
+        ownsSession: false,
+    };
+}
+const MESSAGE_LISTENER_POLL_INTERVAL_MS = Math.max(5_000, Number(process.env.BOTMUX_MESSAGE_LISTENER_POLL_INTERVAL_MS) || 30_000);
+const MESSAGE_LISTENER_BACKFILL_WINDOW_MS = Math.max(60_000, Number(process.env.BOTMUX_MESSAGE_LISTENER_BACKFILL_WINDOW_MS) || 30 * 60_000);
+const MESSAGE_LISTENER_BACKFILL_SCAN_LIMIT = Math.max(1, Number(process.env.BOTMUX_MESSAGE_LISTENER_BACKFILL_SCAN_LIMIT) || 100);
+const MESSAGE_LISTENER_BACKFILL_PAGE_SIZE = Math.min(50, Math.max(1, Number(process.env.BOTMUX_MESSAGE_LISTENER_BACKFILL_PAGE_SIZE) || 50));
+function enabledMessageListenerChatIds(bot) {
+    return Object.entries(bot.config.messageListeners ?? {})
+        .filter(([, listener]) => listener?.enabled === true && !!listener.prompt?.trim())
+        .map(([chatId]) => chatId);
+}
+function messageCreateTimeMs(message) {
+    const raw = message?.create_time ?? message?.createTime;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+function historyMessageSender(message) {
+    const sender = message?.sender ?? {};
+    const senderId = sender.id ?? sender.open_id ?? sender.user_id ?? sender.app_id
+        ?? message?.sender_id?.open_id ?? message?.sender_id?.user_id ?? message?.sender_id?.app_id;
+    const senderIdType = sender.id_type ?? sender.sender_id_type;
+    const inferredType = sender.sender_type
+        ?? message?.sender_type
+        ?? (senderIdType === 'app_id' ? 'app' : undefined);
+    return {
+        senderOpenId: typeof senderId === 'string' ? senderId : undefined,
+        senderTypeRaw: typeof inferredType === 'string' ? inferredType : undefined,
+        senderIdType: typeof senderIdType === 'string' ? senderIdType : undefined,
+    };
+}
+function larkReceiveEventFromHistoryMessage(message, chatId) {
+    const { senderOpenId, senderTypeRaw, senderIdType } = historyMessageSender(message);
+    const isAppId = senderIdType === 'app_id' || senderTypeRaw === 'app' || senderTypeRaw === 'bot';
+    return {
+        message: {
+            ...message,
+            message_type: message?.message_type ?? message?.msg_type,
+            chat_id: message?.chat_id ?? chatId,
+            chat_type: message?.chat_type ?? 'group',
+        },
+        sender: {
+            sender_type: senderTypeRaw ?? (isAppId ? 'app' : 'user'),
+            sender_id: isAppId
+                ? { app_id: senderOpenId }
+                : { open_id: senderOpenId },
+        },
+    };
+}
+async function dispatchHumanMessageViaHandlers(larkAppId, handlers, payload) {
+    await serializeByAnchor(payload.ctx.anchor, () => {
+        const ownsSession = handlers.isSessionOwner?.(payload.ctx.anchor, larkAppId) ?? payload.ownsSession;
+        return ownsSession
+            ? handlers.handleThreadReply(payload.data, payload.ctx)
+            : handlers.handleNewTopic(payload.data, payload.ctx);
+    });
+}
+async function dispatchPolledMessageListenerMatch(input) {
+    if (!claimMessageOnce(input.larkAppId, input.messageId)) {
+        logger.debug(`[message-listener:${input.larkAppId}] polled duplicate ignored msg=${input.messageId.substring(0, 12)}`);
+        return;
+    }
+    logger.info(`[message-listener:${input.larkAppId}] matched polled chat=${input.chatId.substring(0, 12)} ` +
+        `msg=${input.messageId.substring(0, 12)} sender=${input.match.senderOpenId?.substring(0, 12) ?? '-'}`);
+    await dispatchHumanMessageViaHandlers(input.larkAppId, input.handlers, listenerRoutingContext({
+        data: input.data,
+        match: input.match,
+        chatId: input.chatId,
+        messageId: input.messageId,
+        chatType: 'group',
+        larkAppId: input.larkAppId,
+    }));
+}
+async function pollMessageListenersOnce(larkAppId, handlers, now = Date.now()) {
+    const bot = getBot(larkAppId);
+    const chatIds = enabledMessageListenerChatIds(bot);
+    if (chatIds.length === 0)
+        return;
+    const cutoff = now - MESSAGE_LISTENER_BACKFILL_WINDOW_MS;
+    await ensureBotOpenId(larkAppId).catch(() => { });
+    for (const chatId of chatIds) {
+        let messages;
+        try {
+            messages = await listChatMessagesUntil(larkAppId, chatId, {
+                pageSize: MESSAGE_LISTENER_BACKFILL_PAGE_SIZE,
+                stopAfter: (message, seenCount) => {
+                    const createdAt = messageCreateTimeMs(message);
+                    return seenCount >= MESSAGE_LISTENER_BACKFILL_SCAN_LIMIT ||
+                        (Number.isFinite(createdAt) && createdAt < cutoff);
+                },
+            });
+        }
+        catch (err) {
+            logger.warn(`[message-listener:${larkAppId}] failed to poll chat=${chatId.substring(0, 12)}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        // Build the app_id→open_id map once per chat (shared with the dashboard
+        // preview leg) so bot senders (reported by app_id in history) match sender
+        // filters keyed on open_id, and unprovable bots fail closed on exclusion.
+        const candidateBotAppIds = collectListenerBotAppIds(messages, historyMessageSender);
+        const appIdToOpenId = await buildListenerBotAppIdToOpenId(larkAppId, chatId, candidateBotAppIds);
+        for (const message of messages) {
+            const messageId = String(message?.message_id ?? '');
+            if (!messageId)
+                continue;
+            const createdAt = messageCreateTimeMs(message);
+            if (Number.isFinite(createdAt) && createdAt < cutoff)
+                continue;
+            const data = larkReceiveEventFromHistoryMessage(message, chatId);
+            const rawSender = historyMessageSender(message);
+            const resolved = resolveListenerSenderIdentity(rawSender, appIdToOpenId);
+            const match = evaluateMessageListener({
+                bot,
+                chatId,
+                message: data.message,
+                senderOpenId: resolved.senderOpenId,
+                senderTypeRaw: rawSender.senderTypeRaw,
+                senderIdentityUnverified: resolved.identityUnverified,
+                explicitlyMentionedThisBot: isBotMentioned(larkAppId, data.message, resolved.senderOpenId),
+            });
+            if (!match)
+                continue;
+            await dispatchPolledMessageListenerMatch({
+                larkAppId,
+                handlers,
+                data,
+                match,
+                chatId,
+                messageId,
+            }).catch(err => logger.error(`Error handling polled message listener event: ${err}`));
+        }
+    }
+}
+export async function __pollMessageListenersOnceForTest(larkAppId, handlers, now = Date.now()) {
+    await pollMessageListenersOnce(larkAppId, handlers, now);
+}
 function usesForwardFollowupDelay(mentionMode) {
     return mentionMode === 'never' || mentionMode === 'ambient';
 }
@@ -1756,12 +2042,7 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
         resolveSessionsReady();
     sessionsReadyBarriers.set(larkAppId, { promise: sessionsReady, resolve: resolveSessionsReady });
     const dispatchHumanMessage = async (payload) => {
-        await serializeByAnchor(payload.ctx.anchor, () => {
-            const ownsSession = handlers.isSessionOwner?.(payload.ctx.anchor, larkAppId) ?? payload.ownsSession;
-            return ownsSession
-                ? handlers.handleThreadReply(payload.data, payload.ctx)
-                : handlers.handleNewTopic(payload.data, payload.ctx);
-        });
+        await dispatchHumanMessageViaHandlers(larkAppId, handlers, payload);
     };
     const dispatchPersistedForwardFollowup = async (seedMessageId, payload) => {
         // Wait for activeSessions to be rehydrated before checking ownership, so a
@@ -1860,7 +2141,12 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
             const senderType = sender?.sender_type;
             const isBotSenderType = senderType === 'app' || senderType === 'bot';
             if (isBotSenderType) {
-                const senderOpenId = sender.sender_id?.open_id;
+                const senderOpenId = sender.sender_id?.open_id ?? sender.sender_id?.app_id;
+                // When Feishu gave us only an app_id (no open_id), this bot sender's
+                // identity is not in the open_id domain the listener filters use, so
+                // the matcher must fail closed on open_id-based exclusion. Realtime
+                // events normally carry open_id; the app_id fallback is the rare case.
+                const senderIdentityUnverified = !sender.sender_id?.open_id && !!sender.sender_id?.app_id;
                 const isSelfMessage = senderOpenId === getBot(larkAppId).botOpenId;
                 // Self messages: learn our OWN union_id from the echo first (the only
                 // reliable source — see bot-union-ids-store; reported to the platform
@@ -1919,6 +2205,30 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                     logger.debug(`[${larkAppId}] hall bot message swallowed after learning (chat=${chatId.substring(0, 12)})`);
                     return;
                 }
+                const botMessageListener = chatType === 'group'
+                    ? evaluateMessageListener({
+                        bot: getBot(larkAppId),
+                        chatId,
+                        message,
+                        senderOpenId,
+                        senderTypeRaw: sender?.sender_type,
+                        senderIdentityUnverified,
+                        explicitlyMentionedThisBot: isBotMentioned(larkAppId, message, senderOpenId),
+                    })
+                    : undefined;
+                if (botMessageListener) {
+                    logger.info(`[message-listener:${larkAppId}] matched bot-sender chat=${chatId.substring(0, 12)} ` +
+                        `msg=${messageId.substring(0, 12)} sender=${senderOpenId?.substring(0, 12) ?? '-'}`);
+                    await dispatchHumanMessage(listenerRoutingContext({
+                        data,
+                        match: botMessageListener,
+                        chatId,
+                        messageId,
+                        chatType,
+                        larkAppId,
+                    })).catch(err => logger.error(`Error handling bot message listener event: ${err}`));
+                    return;
+                }
                 // Foreign bot: only route on @mention of us.
                 if (!isBotMentioned(larkAppId, message, undefined))
                     return;
@@ -1938,13 +2248,13 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 const ownsThreadSession = ctx.scope === 'thread'
                     ? (handlers.isSessionOwner?.(ctx.anchor, larkAppId) ?? false)
                     : false;
-                const canFoldForeignBotThread = findOncallChat(larkAppId, chatId)
-                    || isKnownPeerBot(config.session.dataDir, larkAppId, senderOpenId)
-                    || isTrustedTeamBotSender(config.session.dataDir, chatId, senderUnionId)
-                    || hasChatGrant(larkAppId, chatId, senderOpenId)
-                    || hasGlobalGrant(larkAppId, senderOpenId);
+                // 这个 bot 能不能在本群跟我们说话 —— 判定一次，fold 与下面的 gate 共用同一个
+                // 结论（二者之间只有 fold / shared-seed 的路由计算，不改任何授权状态）。
+                // 曾经这里是两条手抄的 OR 链，靠人肉保持同步；漏一处就是「能路由但不能 fold」
+                // 或「fold 了却弹卡」的二次分裂。
+                const botTalk = evaluateBotTalk(larkAppId, chatId, senderOpenId, senderUnionId);
                 let replyRootId = await maybeFoldMentionedRegularGroupThreadToChat({
-                    larkAppId, chatId, chatType, message, routing: ctx, forceTopicApplied: forcedTopic, mentionedThisBot: !!canFoldForeignBotThread, ownsThreadSession,
+                    larkAppId, chatId, chatType, message, routing: ctx, forceTopicApplied: forcedTopic, mentionedThisBot: botTalk.allowed, ownsThreadSession,
                 });
                 if (!replyRootId) {
                     replyRootId = await maybeApplySharedTopicSeed({
@@ -1956,71 +2266,44 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 // threads. Previously native topic replies skipped this outer gate and
                 // were silently dropped by daemon's second evaluateTalk check, so the
                 // owner never saw a grant card. Owning an existing session is not an
-                // authorization source; a revoked/unknown bot must still pass one of
-                // the explicit trust or grant legs below.
+                // authorization source; a revoked/unknown bot must still pass
+                // evaluateBotTalk (the single talk predicate — see its doc for the two
+                // deliberate human/bot deltas) or prove itself a sibling below.
                 //
-                // 注意 isKnownPeerBot 查的是 cross-ref（bot-openids-<appId>.json），它只
-                // 收录 bots-info.json 里有名字的 bot，即本机 daemon 自己配置的 bot
-                // （getAllBots）。"别人的 bot" 永远进不了这个 cross-ref，所以 isKnownPeerBot
-                // 对外部 bot 恒为 false——这跟 /introduce 是两套独立存储：/introduce 写的是
-                // observed-bots-store，只负责让发送方"发现并能 @ 到"对方，过不了这道接收闸。
+                // 这里**只判 evaluateBotTalk**。以前是手抄的 OR 链，每加一条 talk 源就漏一次：
+                // oncall 漏过、开放模式漏过、allowedChatGroups 又漏过（整群 /grant 后人通 bot 卡）。
+                // 要加新的 talk 放行源，改 evaluateTalk（人/bot 同时生效），不要在这里加腿；
+                // test/bot-talk-parity.test.ts 会盯着这条约束。
                 //
-                // Oncall 群是当前接收 bot 显式部署的协作工作区，canTalk 已对任何成员
-                // （含真人）放行；这里对 bot 同等放行，跳过 cross-ref vetting。否则本
-                // bot 已绑定的 oncall 群里外部 bot 互相 @ 会被静默丢弃、只有真人能拉起会话。
-                // 注意 oncall talk access 是 bot-scoped：一个 bot 的 /oncall bind 不会放开
-                // sibling bot 的 talk 权限；如果 sibling bot 也要开放，需要自己绑定同一个 chat。
-                //
-                // owner 还可用 `/grant @bot` 把外部 bot 加进本群 chatGrants（与真人 /grant
-                // 同一存储、同一 per-chat 语义）。命中 chatGrants 的 bot 即便不在 cross-ref，
-                // 也与已注册 peer 同等放行——这是「授权外部 bot 在本群协作」的入口。
-                // 全局授权（globalGrants）同理：命中即在任意群放行，是上面的全局版。
-                //
-                // 团队 bot 免 /grant：isTrustedTeamBotSender 命中（sender 的租户稳定
-                // union_id 已学进 team-bots，或本群就是团队拉群组建的协作群）即放行——
-                // 与「同部署兄弟 bot」(isKnownPeerBot) 对等，但覆盖跨部署的团队 peer。
-                // 这正是「加入团队即免 introduce/grant」的接收闸：身份只认 union_id /
-                // 团队群成员，绝不认自报名字（防同名 bot 冒名蹭权）。
-                //
-                // 开放模式（未配任何 allowlist：allowedUsers / allowedChatGroups /
-                // globalGrants 全空）与人侧 evaluateTalk 的 `reason:'open'`（1011 行）对齐：
-                // 「谁都能触发」本应人、bot 同权。过去这道 gate 漏了这一腿，导致开放模式下
-                // 外部 bot @ 仍被丢弃，必须真人先 @ 一次建 session 才救活。
-                // 补上 hasConfiguredAllowlist 短路后两条路径统一：一旦配了任一 allowlist，
-                // 立刻恢复「限制态」设闸，安全边界不变。
-                if (!findOncallChat(larkAppId, chatId)
-                    && hasConfiguredAllowlist(getBot(larkAppId))) {
-                    if (!isKnownPeerBot(config.session.dataDir, larkAppId, senderOpenId)
-                        && !isTrustedTeamBotSender(config.session.dataDir, chatId, senderUnionId)
-                        && !hasChatGrant(larkAppId, chatId, senderOpenId)
-                        && !hasGlobalGrant(larkAppId, senderOpenId)) {
-                        // Cold-start self-heal: the cross-ref (bot-openids-<appId>.json) is
-                        // learned lazily from observed mentions[], so the FIRST bot→bot
-                        // direct @ from a same-deployment sibling can arrive before the
-                        // receiver has learned that sibling's receiver-scoped open_id
-                        // (Lark open_id is per-app). That raced a real sibling into this
-                        // "unknown external bot" branch and mis-fired a /grant card
-                        // (regression from ec146a49). Before deciding unknown, confirm the
-                        // sender against the group's LIVE `/members/bots` roster: accept
-                        // only when it binds to exactly one locally-configured sibling of
-                        // the same unique name that independently confirms is_in_chat.
-                        // Fails closed to the grant card on any API error / ambiguity /
-                        // genuine external bot — never a name-only shortcut.
-                        const sibling = await resolveSiblingBotBySenderOpenId(larkAppId, chatId, senderOpenId)
-                            .catch((err) => ({ ok: false, reason: `resolve_threw: ${err?.message ?? String(err)}` }));
-                        if (sibling.ok) {
-                            // Persist the newly-proven mapping so subsequent @s from this
-                            // sibling hit isKnownPeerBot directly (no live API roundtrip).
-                            updateBotOpenIdCrossRef(config.session.dataDir, larkAppId, [
-                                { name: sibling.botName, id: { open_id: sibling.senderOpenId } },
-                            ]);
-                            logger.info(`Lazy sibling cross-ref backfill: ${sibling.botName} → ${senderOpenId?.substring(0, 12)} (was cold; skipping /grant)`);
-                        }
-                        else {
-                            logger.info(`Foreign bot @mention not a known sibling (${sibling.reason}); sending grant request card`);
-                            await maybeSendGrantRequestCard(larkAppId, message, chatId, senderOpenId, data);
-                            return;
-                        }
+                // 唯一留在闸门里的 bot 专属逻辑是下面的 cross-ref 冷启动自愈：它不是一条
+                // 授权来源，而是「同部署兄弟 bot 的身份还没学到」这个**识别**问题的补救。
+                if (!botTalk.allowed) {
+                    // Cold-start self-heal: the cross-ref (bot-openids-<appId>.json) is
+                    // learned lazily from observed mentions[], so the FIRST bot→bot
+                    // direct @ from a same-deployment sibling can arrive before the
+                    // receiver has learned that sibling's receiver-scoped open_id
+                    // (Lark open_id is per-app). That raced a real sibling into this
+                    // "unknown external bot" branch and mis-fired a /grant card
+                    // (regression from ec146a49). Before deciding unknown, confirm the
+                    // sender against the group's LIVE `/members/bots` roster: accept
+                    // only when it binds to exactly one locally-configured sibling of
+                    // the same unique name that independently confirms is_in_chat.
+                    // Fails closed to the grant card on any API error / ambiguity /
+                    // genuine external bot — never a name-only shortcut.
+                    const sibling = await resolveSiblingBotBySenderOpenId(larkAppId, chatId, senderOpenId)
+                        .catch((err) => ({ ok: false, reason: `resolve_threw: ${err?.message ?? String(err)}` }));
+                    if (sibling.ok) {
+                        // Persist the newly-proven mapping so subsequent @s from this
+                        // sibling hit isKnownPeerBot directly (no live API roundtrip).
+                        updateBotOpenIdCrossRef(config.session.dataDir, larkAppId, [
+                            { name: sibling.botName, id: { open_id: sibling.senderOpenId } },
+                        ]);
+                        logger.info(`Lazy sibling cross-ref backfill: ${sibling.botName} → ${senderOpenId?.substring(0, 12)} (was cold; skipping /grant)`);
+                    }
+                    else {
+                        logger.info(`Foreign bot @mention not a known sibling (${sibling.reason}); sending grant request card`);
+                        await maybeSendGrantRequestCard(larkAppId, message, chatId, senderOpenId, data);
+                        return;
                     }
                 }
                 logger.info(`Bot-to-bot @mention detected (scope=${ctx.scope}): routing to handleThreadReply`);
@@ -2058,6 +2341,11 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
             if (await tryHandleGrantCommand(larkAppId, message, senderOpenId)) {
                 return;
             }
+            // /invite — 把群外 bot 拉进本群的元命令。与 /grant 同款拦截模型（仅 owner，
+            // 需明确 @ 本 bot），防止进路由/spawn，也防多 bot 重复执行拉人。
+            if (await tryHandleInviteCommand(larkAppId, message, senderOpenId)) {
+                return;
+            }
             logger.debug('Received message:', message);
             // Diagnostic: record the Lark quote-bubble UI quirk where root_id
             // appears without thread_id. decideRouting now treats this as
@@ -2087,6 +2375,24 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 replyRootId = message.root_id;
             }
             const explicitlyMentionedThisBot = isBotMentioned(larkAppId, message, senderOpenId);
+            const messageListener = chatType === 'group'
+                ? evaluateMessageListener({
+                    bot: getBot(larkAppId),
+                    chatId,
+                    message,
+                    senderOpenId,
+                    senderTypeRaw: sender?.sender_type,
+                    explicitlyMentionedThisBot,
+                })
+                : undefined;
+            if (messageListener) {
+                routing.scope = 'thread';
+                routing.anchor = messageId;
+                routingSource = 'topic-chat';
+                replyRootId = undefined;
+                logger.info(`[message-listener:${larkAppId}] matched chat=${chatId.substring(0, 12)} ` +
+                    `msg=${messageId.substring(0, 12)} sender=${senderOpenId?.substring(0, 12) ?? '-'}`);
+            }
             // Cheap in-memory gate FIRST: skip the getChatMode roundtrip and the
             // per-chat toggle disk read entirely for bots that never configured a
             // substitute target (the overwhelming majority on the hot path).
@@ -2103,6 +2409,21 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                     substituteChatMode = chatMode;
                 }
             }
+            // 黑名单硬静默：命中黑名单的群里，一条「本该触发替身」的消息（@ 到了配置的
+            // 替身对象、但没有直接 @ 本 bot）必须当作没读到——直接 return，不只是清 trigger。
+            // 只清 trigger 不够：消息会继续 fall-through 到通用群消息门，若 bot 在该群有活跃
+            // 会话 / 是 solo 群 / mentionMode 放开，仍会被喂进去并弹卡片（用户实测现象）。
+            // 直接 @ 本 bot（explicitlyMentionedThisBot）不受影响：黑名单只静音替身代答，
+            // 不静音「直接找 bot 问问题」。/substitute 命令已在上方 command 处理器拦截。
+            if (substituteCfg?.enabled === true
+                && chatType === 'group'
+                && !explicitlyMentionedThisBot
+                && isSubstituteExcludedChat(substituteCfg, chatId)
+                && resolveSubstituteTrigger(larkAppId, message)) {
+                logger.info(`[substitute:${larkAppId}] excluded chat — dropping @target message ` +
+                    `msg=${messageId.substring(0, 12)} chat=${chatId.substring(0, 12)}`);
+                return;
+            }
             let substituteTrigger = substituteChatMode
                 ? resolveSubstituteTrigger(larkAppId, message)
                 : undefined;
@@ -2187,7 +2508,8 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
             // can't be cache-stale) or when chatType is p2p (DMs always thread).
             // Runs BEFORE /t override so a `@bot /t …` in a now-flat 普通群 still
             // gets the explicit topic seed it asked for.
-            if (routing.scope === 'thread' &&
+            if (!messageListener &&
+                routing.scope === 'thread' &&
                 routing.anchor === messageId &&
                 !message.thread_id &&
                 chatType === 'group') {
@@ -2360,9 +2682,16 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
             //   !ownsSession (group)    → require @mention + allowlist
             //   p2p                     → allowlist only
             if (chatType === 'group') {
+                const mentionMode = resolveGroupMentionMode(larkAppId);
+                // 消息里 @ 了别的具体成员,就已经证明群不是 1人1bot（只有群成员能被 @）——
+                // 此刻末条 solo 放行必然不成立,而 stats 只被末条消费,直接跳过这次（可能
+                // 昂贵的）人数查询。这在「刚拉了新 bot、用户 @ 新 bot」窗口里尤为重要：
+                // 拦截老 bot 的同时不再为它反复刷新陈旧缓存。
+                const mentionsOther = mentionsAnotherMember(larkAppId, message);
                 let stats = null;
-                if (ownsSession && !replyRootId)
+                if (ownsSession && !replyRootId && !mentionsOther && mentionMode !== 'never') {
                     stats = await getGroupStats(larkAppId, chatId);
+                }
                 // replyRootId means this turn has already been explicitly addressed
                 // to the bot by shared-topic logic (possibly from inside an existing
                 // Lark thread). Do not re-run the generic group @ gate, which would
@@ -2387,8 +2716,8 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 //     treat it as a hand-off and stay quiet.
                 // Both gated on isAllowed so restricted groups still only react to
                 // permitted senders. (The shared fold-back's replyRootId is already
-                // handled by the first clause.)
-                const mentionMode = resolveGroupMentionMode(larkAppId);
+                // handled by the first clause. `mentionMode` 已在块首解析,用于 stats
+                // 惰性获取。)
                 // 话题群 owned-topic 免@续话不再无条件放行（#336 引入的默认行为回归：
                 // 多人群里旁人不 @ 也会触发 bot）。现在与普通群共用同一套「群聊 @ 策略」:
                 // 默认 'always' 在多人群里必须 @，想要话题内免@续话就把 mentionMode 配成
@@ -2397,12 +2726,17 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 // 注：pairedForwardSeed 仅在 never/ambient 模式下产生，且 ambient redirect
                 // 已在配对前排除，故 isAllowed=true 时下方 never/ambient 条款必然放行；
                 // 不在此单独加 clause，以免 isAllowed=false 时绕过权限检查。
+                // 末条 solo 放行另有 `!mentionsOther` 守卫：消息 @ 了别的具体成员时,
+                // 群必然不是 1人1bot（只有群成员能被 @），且是指给别人的——拦住「刚拉新 bot、
+                // 缓存仍是陈旧 {1,1} 时老 bot 跟着回复」的误放行。never 条款在前已短路,
+                // 故该守卫不影响「群聊 @ 策略」配置的 never 语义。
                 const relax = (!!replyRootId && isAllowed)
                     || (!!substituteTrigger && isAllowed)
+                    || !!messageListener
                     || (isAllowed && mentionMode === 'never')
-                    || (isAllowed && mentionMode === 'ambient' && !mentionsAnotherMember(larkAppId, message))
-                    || (isAllowed && mentionMode === 'topic' && ownsSession && !!message.thread_id && !mentionsAnotherMember(larkAppId, message))
-                    || (ownsSession && isAllowed && !!stats && stats.userCount <= 1 && stats.botCount <= 1);
+                    || (isAllowed && mentionMode === 'ambient' && !mentionsOther)
+                    || (isAllowed && mentionMode === 'topic' && ownsSession && !!message.thread_id && !mentionsOther)
+                    || (ownsSession && isAllowed && !!stats && !mentionsOther && stats.userCount <= 1 && stats.botCount <= 1);
                 if (!relax) {
                     const access = await checkGroupMessageAccess(larkAppId, message, chatId, senderOpenId, humanSenderUnionId);
                     if (access === 'not_allowed') {
@@ -2459,6 +2793,7 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                     ? { name: 'summary-command', chatKind: summaryCommandMatch.chatKind }
                     : undefined,
                 substituteTrigger,
+                messageListener,
                 forwardSeedData: pairedForwardSeed?.payload.data,
             };
             if (explicitlyMentionedThisBot) {
@@ -2552,6 +2887,15 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
             const chatIdForKey = data?.chat_id;
             const operatorForKey = data?.operator_id?.open_id;
             const eventKey = `im.chat.member.bot.added_v1:${larkAppId}:${eventIdForKey(data) ?? `${chatIdForKey ?? 'unknown'}:${operatorForKey ?? 'unknown'}`}`;
+            // 飞书只把 bot.added 推给「进群的那个 bot 自己的 app」(官方文档语義,
+            // codex 复审证实),且生产是 PM2「一 bot 一 daemon 进程」(daemon.ts
+            // "Load the assigned bot (one daemon per bot)")——同群其他 bot 的缓存在
+            // 别的进程,这里够不到,只能清自己的 key。覆盖增量其实很小:新添进群
+            // 时本 bot 此前若恰有该群条目（曾被移出又拉回),避免带着上轮陈旧数放行。
+            // 「拉了别的 bot 进群→存量 bot 陈旧」方向无事件信号,靠 relax 末条款的
+            // mentionsAnotherMember 守卫 + TTL 兜底。
+            if (chatIdForKey)
+                invalidateChatStats(larkAppId, chatIdForKey);
             scheduleAckSafeEvent(eventKey, async () => {
                 try {
                     const chatId = data?.chat_id;
@@ -2566,6 +2910,26 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
                 }
             }, 'bot-added event');
         },
+        // bot.deleted 同样只推给被移出的 bot 自己的 app——清自己的 key 即可(语义
+        // 同 bot.added:进程边界上够不到兄弟 daemon;「别的 bot 离群→存量 bot
+        // 陈旧」靠①守卫+TTL)。user.added/deleted_v1 推给群内已订阅的所有 bot
+        // app,每个 bot 自己的 WS 都收到,各自清自己那条。纯本地 map 删除,同步
+        // 处理、即时 ACK,不进 work 队列;去重也不必要——失效是幂等的。
+        'im.chat.member.bot.deleted_v1': (data) => {
+            const chatId = data?.chat_id;
+            if (chatId)
+                invalidateChatStats(larkAppId, chatId);
+        },
+        'im.chat.member.user.added_v1': (data) => {
+            const chatId = data?.chat_id;
+            if (chatId)
+                invalidateChatStats(larkAppId, chatId);
+        },
+        'im.chat.member.user.deleted_v1': (data) => {
+            const chatId = data?.chat_id;
+            if (chatId)
+                invalidateChatStats(larkAppId, chatId);
+        },
         // 文档评论入口（/watch-comment / /subscribe-lark-doc）。notice 事件主要覆盖 @Bot
         // 通知；普通评论由 daemon 应用身份轮询补齐，不依赖逐文件 subscribe API。
         'drive.notice.comment_add_v1': (data) => handleCommentEventAckSafe(data, larkAppId, handlers),
@@ -2677,6 +3041,29 @@ export function startLarkEventDispatcher(larkAppId, larkAppSecret, handlers, bra
     });
     wsClient.start({ eventDispatcher });
     logger.info('Daemon WSClient started');
+    let listenerPollInFlight = false;
+    const listenerPollTimer = setInterval(() => {
+        if (listenerPollInFlight)
+            return;
+        listenerPollInFlight = true;
+        void pollMessageListenersOnce(larkAppId, handlers)
+            .catch(err => logger.error(`[message-listener:${larkAppId}] poll failed: ${err instanceof Error ? err.message : String(err)}`))
+            .finally(() => { listenerPollInFlight = false; });
+    }, MESSAGE_LISTENER_POLL_INTERVAL_MS);
+    listenerPollTimer.unref();
+    const hasListenerBackfill = enabledMessageListenerChatIds(getBot(larkAppId)).length > 0;
+    if (hasListenerBackfill) {
+        setTimeout(() => {
+            if (listenerPollInFlight)
+                return;
+            listenerPollInFlight = true;
+            void pollMessageListenersOnce(larkAppId, handlers)
+                .catch(err => logger.error(`[message-listener:${larkAppId}] initial poll failed: ${err instanceof Error ? err.message : String(err)}`))
+                .finally(() => { listenerPollInFlight = false; });
+        }, 2_000).unref();
+        logger.info(`[message-listener:${larkAppId}] polling backfill enabled interval=${MESSAGE_LISTENER_POLL_INTERVAL_MS}ms ` +
+            `window=${MESSAGE_LISTENER_BACKFILL_WINDOW_MS}ms chats=${enabledMessageListenerChatIds(getBot(larkAppId)).length}`);
+    }
     // ② SDK 重连耗尽后停在 terminalError（getConnectionStatus().state === 'failed'）并
     //    永久放弃。每分钟探测一次，发现已放弃就 start() 重新发起一轮全新握手 —— start()
     //    会清掉 terminalError 并重新 pullConnectConfig + connect，无需手动重启 daemon。