Summary

Closes #78749.

When channels.imessage.groupPolicy: "allowlist" is set without a channels.imessage.groups block — the most common BlueBubbles → bundled-iMessage migration footgun, documented in PR #78317 — the runtime gate at extensions/imessage/src/monitor/inbound-processing.ts:336 drops every group message and logs only at verbose. At the default info log level, every group message vanishes silently.

This adds two coordinated warn-level signals so the misconfiguration is observable at the default log level:

1. Startup warning (warnGroupAllowlistMisconfigOnce): one-time per accountId when monitor boots with groupPolicy: "allowlist" AND channels.imessage.groups is empty (no "*" wildcard, no per-chat_id entries). Catches the misconfiguration before any messages land.

2. Per-chat warning (warnGroupAllowlistDropPerChatOnce): one-time per accountId:chat_id when the runtime allowlist gate drops a specific group. Names the chat_id and the exact channels.imessage.groups[...] key to add to allow it.

Both warners cap log volume at one line per account / one line per chat, so busy gateways do not get spammed. Helpers stay extension-local per the AGENTS owner-boundary rule (other channels have different group-policy semantics).

Files

• extensions/imessage/src/monitor/group-allowlist-warnings.ts — new helper module with both warners + a resetForTesting reset hook
• extensions/imessage/src/monitor/group-allowlist-warnings.test.ts — 11 unit tests covering startup misconfig detection, per-chat one-shot semantics, wildcard / explicit-entry suppression, multi-account isolation, numeric/string chat_id normalization
• extensions/imessage/src/monitor/monitor-provider.ts — wires the startup warner alongside the existing warnMissingProviderGroupPolicyFallbackOnce, and emits the per-chat warner on the decision.kind === "drop" branch when decision.reason === "group id not in allowlist"
• docs/channels/imessage.md + docs/channels/imessage-from-bluebubbles.md — replaces the "silent at info, raise OPENCLAW_LOG_LEVEL=debug" guidance with the new warn lines operators will actually see

Real behavior proof

• Behavior or issue addressed: silent verbose-level drop at extensions/imessage/src/monitor/inbound-processing.ts:336 when groupPolicy: "allowlist" is configured without a channels.imessage.groups block (issue iMessage: silent group message drop when channels.imessage.groups is unset #78749).

• Real environment tested: macOS Sequoia 15.x, node v25.8.1, openclaw worktree at branch fix/imsg-group-drop-observability head fdba8f4111. The new helpers (extensions/imessage/src/monitor/group-allowlist-warnings.ts) loaded directly via node --import tsx from the live source tree — same callable shape used by the gateway's monitor-provider.ts (log: (msg) => runtime.log?.(warn(msg))).

• Exact steps or command run after this patch:

  cd ~/GitHub/openclaw/.worktrees/issue-78749
  node --import tsx /tmp/imsg-78749-proof.mjs
  

  where the script imports warnGroupAllowlistMisconfigOnce, warnGroupAllowlistDropPerChatOnce, and resetGroupAllowlistWarningsForTesting from the new module and walks five scenarios (misconfigured startup, first-drop per chat, repeat-drop suppression, second chat fires its own line, wildcard suppresses startup).

• After-fix evidence: console output captured live from the run above:

  === Scenario 1: BlueBubbles migration footgun (groupPolicy=allowlist, groups missing) ===
  [warn] imessage: groupPolicy="allowlist" but channels.imessage.groups is empty for account "primary". Every inbound group message will be dropped. Add channels.imessage.groups["*"] = { requireMention: true } to allow all groups, or explicit per-chat_id entries to allow specific groups.
  
  === Scenario 2: First inbound group message from chat_id=8421 ===
  [warn] imessage: dropping group message from chat_id=8421 (account "primary") — not in channels.imessage.groups allowlist. Add channels.imessage.groups["8421"] or channels.imessage.groups["*"] to allow it.
  
  === Scenario 3: Same chat_id=8421 again (suppressed, returns false silently) ===
  (fired=false, no log line)
  
  === Scenario 4: Different chat_id=9907 fires its own one-time warn ===
  [warn] imessage: dropping group message from chat_id=9907 (account "primary") — not in channels.imessage.groups allowlist. Add channels.imessage.groups["9907"] or channels.imessage.groups["*"] to allow it.
  
  === Scenario 5: Wildcard configured, startup is silent ===
  (fired=false, no log line)
  

• Observed result after fix: each [warn] line is the exact string runtime.log?.(warn(message)) would emit through the gateway's warn-formatted logger. Scenario 1 catches the misconfiguration before any message lands. Scenario 2 names the dropped chat and the exact channels.imessage.groups["8421"] key to add. Scenario 3 confirms the per-chat one-shot suppresses repeats. Scenario 4 confirms a distinct chat_id still surfaces. Scenario 5 confirms the startup warn does not fire when a "*" wildcard is present. No silent drops remain at the default info log level.

• What was not tested: end-to-end gateway run against a live imsg launch daemon driving an iMessage group conversation — the helpers exercised here are the exact units monitor-provider.ts calls, but a live-traffic capture would be additional confirmation (would need a paired Mac and a configured group chat).