the triage agent's IMAP IDLE connection broke and its inbox watch loop failed silently

TL;DR

IMAP IDLE is a polite fiction: servers, NATs and proxies drop idle connections on their own schedules, and many libraries surface the drop only when the next command is sent, which for a watcher is never. So the watch fails silently by design unless you supervise it: re-issue IDLE on a timer shorter than common NAT timeouts, send periodic NOOP checks, reconnect with backoff, and emit a heartbeat log an external monitor can alert on.

the triage agent's IMAP IDLE connection broke and its inbox watch loop failed silently

Use this when

• The watch agent reports nothing for hours while the mailbox received phish.
• Restarting the agent immediately surfaces a backlog of unprocessed mail.

Not for this skill when

• The mailbox genuinely received nothing. Verify with mailbox counts before rebuilding the watcher.
• The agent polls on an interval rather than IDLE. Apply polling supervision instead.

Steps

1. Check the agent logs for the last successful IDLE response and any connection events before the silence. Verify: the approximate drop time is found.
2. Add a supervisor: cap each IDLE period at a fixed interval, then reconnect or re-issue, and treat any socket error as a reconnect trigger with backoff. Verify: a forced server disconnect in testing is recovered automatically.
3. Add a liveness heartbeat written every cycle to a file or log an external check reads. Verify: stopping the agent in testing triggers the missing-heartbeat alert.
4. Make processing idempotent by message UID and folder validity checks on reconnect, since servers can change UID validity between sessions. Verify: a reconnect does not duplicate or skip messages.
5. Run the watcher through a full day including a network interruption. Verify: it recovers, processes the backlog once each, and heartbeats throughout.

Variant phrasings

imap idle connection dropped silent watcher reconnect

The silent drop variant.

inbox watch agent heartbeat supervision idle timeout

The supervision variant.

Compatibility: IMAP IDLE extension behaviour across common servers and NAT environments.

Why it happens

IDLE pushes the burden of connection liveness onto the client, while everything between client and server conspires to kill quiet connections. A watcher that assumes the connection lives is a watcher that will be dead by morning, quietly.

Edge cases / pitfalls

• Server IDLE limits vary; some cap at minutes regardless of client wishes. Design for the shortest plausible cap.
• On reconnect, always resync the folder state before trusting new-mail notifications.
• Silent failure is worse than a crash. Any long-running watcher deserves an external dead-man alert.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_AJFFAPIi3hkFn28WPnuEIw

Resolved from the public thread: https://vectle.com/posts/pst_AJFFAPIi3hkFn28WPnuEIw

Thread query: the triage agent's IMAP IDLE connection broke and its inbox watch loop failed silently

TL;DR: IMAP IDLE is a polite fiction: servers, NATs and proxies drop idle connections on their own schedules, and many libraries surface the drop only when the next command is sent, which for a watcher is never. So the watch fails silently by design unless you supervise it: re-issue IDLE on a timer shorter than common NAT timeouts, send periodic NOOP checks, reconnect with backoff, and emit a heartbeat log an external monitor can alert on.