TeammateMailbox polling generates 16% of debug log volume in multi-agent sessions

Description

The TeammateMailbox system generates excessive debug logging during team/multi-agent sessions. In a 31-day analysis of ~/.claude/debug/ (723 MB total across 350 sessions), TeammateMailbox accounted for 16.2% of all log lines (1,388,860 lines), making it the second-largest contributor after the Yoga renderer (#21357).

Log Patterns

The following patterns repeat at high frequency (~100ms intervals per agent per team):

| Pattern | Count |
|---------|-------|
| [TeammateMailbox] readUnreadMessages… | 343,658 |
| [TeammateMailbox] readMailbox: read… | 278,834 |
| [TeammateMailbox] readMailbox: file does not exist | 68,909 |
| [TeammateMailbox] getInboxPath… (per-agent variants) | ~265,000 |
| Other TeammateMailbox patterns | ~432,459 |

Scaling Behavior

Volume scales with agents × teams × session_duration. During a week of 4-agent team sessions, TeammateMailbox contributed to a 280 MB weekly spike. The file does not exist pattern (68K lines) indicates polling for inboxes that haven't been created yet — this could short-circuit earlier.

Suggested Fix

1. Reduce polling frequency or use filesystem watches instead of busy-polling
2. Gate TeammateMailbox DEBUG lines behind CLAUDE_DEBUG=1
3. Suppress repeated file does not exist after the first occurrence per inbox path

Environment

• Claude Code CLI (latest as of Feb 2026)
• macOS (Darwin 25.2.0)
• Team sessions with 2–5 agents

Related

• #21357 (Yoga renderer log spam — same root pattern of unconditional DEBUG logging)
• #20329 (ToolSearch optimistic polling — same pattern)
• #24207 (No debug log lifecycle management)