fix: cap pairing requests and suppress outbound pairing replies

docs/gateway/configuration.md

@@ -248,7 +248,7 @@ Controls how WhatsApp direct chats (DMs) are handled:
 - `"open"`: allow all inbound DMs (**requires** `whatsapp.allowFrom` to include `"*"`)
 - `"disabled"`: ignore all inbound DMs
 
-Pairing codes expire after 1 hour; the bot only sends a pairing code when a new request is created.
+Pairing codes expire after 1 hour; the bot only sends a pairing code when a new request is created. Pending DM pairing requests are capped at **3 per provider** by default.
 
 Pairing approvals:
 - `clawdbot pairing list --provider whatsapp`

docs/gateway/security.md

@@ -38,7 +38,7 @@ Clawdbot’s stance:
 
 All current DM-capable providers support a DM policy (`dmPolicy` or `*.dm.policy`) that gates inbound DMs **before** the message is processed:
 
-- `pairing` (default): unknown senders receive a short pairing code and the bot ignores their message until approved. Codes expire after 1 hour; repeated DMs won’t resend a code until a new request is created.
+- `pairing` (default): unknown senders receive a short pairing code and the bot ignores their message until approved. Codes expire after 1 hour; repeated DMs won’t resend a code until a new request is created. Pending requests are capped at **3 per provider** by default.
 - `allowlist`: unknown senders are blocked (no pairing handshake).
 - `open`: allow anyone to DM (public). **Requires** the provider allowlist to include `"*"` (explicit opt-in).
 - `disabled`: ignore inbound DMs entirely.

docs/gateway/troubleshooting.md

@@ -169,6 +169,24 @@ clawdbot logs --follow
 tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"
 ```
 
+### Pairing Code Not Arriving
+
+If `dmPolicy` is `pairing`, unknown senders should receive a code and their message is ignored until approved.
+
+**Check 1:** Is a pending request already waiting?
+```bash
+clawdbot pairing list --provider <provider>
+```
+
+Pending DM pairing requests are capped at **3 per provider** by default. If the list is full, new requests won’t generate a code until one is approved or expires.
+
+**Check 2:** Did the request get created but no reply was sent?
+```bash
+clawdbot logs --follow | grep "pairing request"
+```
+
+**Check 3:** Confirm `dmPolicy` isn’t `open`/`allowlist` for that provider.
+
 ### Image + Mention Not Working
 
 Known issue: When you send an image with ONLY a mention (no other text), WhatsApp sometimes doesn't include the mention metadata.

docs/providers/whatsapp.md

@@ -103,9 +103,9 @@ on outbound replies.
 If you run Clawdbot on your **personal WhatsApp number**, enable `whatsapp.selfChatMode` (see sample above).
 
 Behavior:
-- Suppresses pairing replies for **outbound DMs** (prevents spamming contacts).
+- Outbound DMs never trigger pairing replies (prevents spamming contacts).
 - Inbound unknown senders still follow `whatsapp.dmPolicy`.
-- Self-chat mode avoids auto read receipts and ignores mention JIDs.
+- Self-chat mode (allowFrom includes your number) avoids auto read receipts and ignores mention JIDs.
 - Read receipts sent for non-self-chat DMs.
 
 ## Message normalization (what the model sees)
@@ -186,7 +186,7 @@ Behavior:
 
 ## Config quick map
 - `whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
-- `whatsapp.selfChatMode` (same-phone setup; suppress pairing replies for outbound DMs).
+- `whatsapp.selfChatMode` (same-phone setup; bot uses your personal WhatsApp number).
 - `whatsapp.allowFrom` (DM allowlist).
 - `whatsapp.mediaMaxMb` (inbound media save cap).
 - `whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).

docs/start/faq.md

@@ -632,6 +632,7 @@ Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:
 - Default behavior on DM‑capable providers is **pairing**:
   - Unknown senders receive a pairing code; the bot does not process their message.
   - Approve with: `clawdbot pairing approve --provider <provider> <code>`
+  - Pending requests are capped at **3 per provider**; check `clawdbot pairing list --provider <provider>` if a code didn’t arrive.
 - Opening DMs publicly requires explicit opt‑in (`dmPolicy: "open"` and allowlist `"*"`).
 
 Run `clawdbot doctor` to surface risky DM policies.

docs/start/pairing.md

@@ -25,6 +25,7 @@ Default DM policies are documented in: [Security](/gateway/security)
 Pairing codes:
 - 8 characters, uppercase, no ambiguous chars (`0O1I`).
 - **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
+- Pending DM pairing requests are capped at **3 per provider** by default; additional requests are ignored until one expires or is approved.
 
 ### Approve a sender