#22106: fix(whatsapp): honor selfChatMode override for group mentions

## Summary - Problem: In WhatsApp personal-number setups, explicit group @mentions could be ignored because self-chat inference always treated the account as self-chat when `allowFrom` included the owner number. - Why it matters: Group bots configured with `requireMention: true` + personal-number onboarding were not reliably triggerable by explicit mentions. - What changed: Mention resolution now honors `channels.whatsapp.selfChatMode` as an explicit override; when set to `false`, explicit JID mentions are evaluated normally. - What did NOT change (scope boundary): No changes to auth, pairing, transport, or DM/group policy gates. ## Change Type (select all) - [x] Bug fix - [ ] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [ ] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [x] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes # - Related # ## User-visible / Behavior Changes - New explicit behavior: `channels.whatsapp.selfChatMode=false` allows explicit mention-JID detection in groups. - `selfChatMode=true` continues to suppress mention-JID auto-trigger behavior for personal-number self-chat safety. - Added docs note under WhatsApp self-chat behavior. ## Security Impact (required) - New permissions/capabilities? `No` - Secrets/tokens handling changed? `No` - New/changed network calls? `No` - Command/tool execution surface changed? `No` - Data access scope changed? `No` - If any `Yes`, explain risk + mitigation: `N/A` ## Repro + Verification ### Environment - OS: Ubuntu (Hetzner VPS) - Runtime/container: Docker (`openclaw:test-lid-fix-v3`) - Model/provider: OpenAI Codex OAuth (runtime env) - Integration/channel: WhatsApp - Relevant config (redacted): - `channels.whatsapp.groupPolicy="open"` - `channels.whatsapp.groups["*"].requireMention=true` - `channels.whatsapp.dmPolicy="disabled"` - `channels.whatsapp.selfChatMode=false` ### Steps 1. Configure WhatsApp with personal-number mode and mention-gated groups. 2. Send group message without mention. 3. Send group message with explicit @mention. ### Expected - Without mention: no auto-reply. - With mention: mention is detected and message is eligible for reply. ### Actual - Before fix: explicit mention could still be treated as not mentioned in self-chat inference scenarios. - After fix: explicit mention is detected when `selfChatMode=false`. ## Evidence - [x] Failing test/log before + passing after - [x] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) ## Human Verification (required) - Verified scenarios: - Unit tests: `src/web/auto-reply/web-auto-reply-utils.test.ts` pass. - Runtime smoke on VPS with WhatsApp group mention flows. - Edge cases checked: - Self-chat mode true still suppresses mention-JID triggers. - Self-chat mode false allows explicit JID mention path. - What you did **not** verify: - Full matrix `pnpm test` on all channels. ## Compatibility / Migration - Backward compatible? `Yes` - Config/env changes? `No` (behavioral clarity only) - Migration needed? `No` - If yes, exact upgrade steps: `N/A` ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: - Set `channels.whatsapp.selfChatMode=true` or revert commit. - Files/config to restore: - `src/web/auto-reply/mentions.ts` - `src/web/auto-reply/web-auto-reply-utils.test.ts` - `docs/channels/whatsapp.md` - Known bad symptoms reviewers should watch for: - Group @mentions not triggering while `selfChatMode=false`. ## Risks and Mitigations - Risk: Behavior differences for users relying on implicit self-chat inference in mixed setups. - Mitigation: Explicit opt-in via `selfChatMode=false`; default behavior preserved. <!-- greptile_comment --> <h3>Greptile Summary</h3> Adds explicit `selfChatMode` override to fix WhatsApp group mention detection in personal-number setups. When `selfChatMode: false` is explicitly set, the system now honors explicit `@mention` JIDs in groups instead of suppressing them via self-chat inference. **Key changes:** - Modified `mentions.ts:49-50` to check explicit `selfChatMode` config before falling back to inferred self-chat mode - Added `selfChatMode` field to `MentionConfig` type and `buildMentionConfig` function - Added test coverage for `selfChatMode: false` behavior with explicit JID mentions - Documented the new config option with clear usage example for mention-gated groups The implementation correctly preserves backward compatibility - when `selfChatMode` is undefined or true, behavior remains unchanged. <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The change is a focused bug fix with clear scope: adds explicit config override for self-chat mode detection in WhatsApp mention handling. The implementation is simple (2-line logic change), well-tested (new test case validates exact behavior), and backward compatible (undefined/true values preserve existing behavior). No security, auth, or data access changes. - No files require special attention _{Last reviewed commit: a685528} <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->