[leemour]

Task

Draft standard for two things the owner asked for after a real mail sync failed on Yandex 360: a rule for per-request timeouts and transient retries (none existed), and a longer CLI deadline for a resumable sync. Draft: not to be merged until the owner rules on the numbers.

Why

Real runs on a 253,024-message INBOX ([email protected], Yandex 360): the server answered single messages with * NO [UNAVAILABLE] UID FETCH ... failure due to backend error and then closed the connection; every later command failed with imapflow NoConnection. It was not the socket timeout (it failed at 94 s and 197 s with a 600 s limit). A header FETCH of 200 messages took from 5 s to over 130 s, minute to minute. Each CLI invents its own handling, so the owner wants one standard.

What

New WC-LIFE-17 (read it in the diff):

• Own timeout per request: the smaller of a per-request default (60 s) and the time left to the deadline; a CLI may set a longer one next to its requestMs, with the measurement (mail-cli: 90 s).
• Retry only a read that failed in transit or for a moment: closed or reset connection, request timeout, temporary DNS, 502/503/504, IMAP NO [UNAVAILABLE], 429/THROTTLED with a named wait. Never a write (stays outcome_unknown, WC-OUT-20), never a refused login or another 4xx.
• Waits 1 s, 3 s, then 10 s, times a random 0.5 to 1.5; a wait the service names wins when longer.
• Each retry takes one request from the run's budget (WC-LIFE-16) and is not made if it would end after the deadline or the run is cancelled; 8 attempts is the ceiling for a command without a budget.
• A reconnect re-checks the position identity (IMAP UIDVALIDITY) before going on; a change stops the run.
• One failing item of a batch does not fail the batch: asked for once more at the end, then left for the next run and not stored as done; the answer counts them.
• The error keeps the transport's own code as details.cause_code (plain code, at most 40 characters, never the server's text); a run records it (error.cause_code, cli-core).

WC-LIFE-5 (the numbers for the owner to rule on): a cooperative command that also declares partial (a resumable sync) gets a deadline of 15 min at a terminal instead of 5. Other cooperative commands stay at 5 min, MCP stays at 45 s. The owner chose 15 min on 2026-10-29 (option C); the trade-offs below are for the record.

	5 min (today)	15 min (proposed)
Request budget at requestMs 10 s	floor((300 - 45) / 10) = 25 requests	floor((900 - 135) / 10) = 76 requests
First sync of 16,000 mail messages	many reruns (each run reads about 1,500 messages at 3 requests per 200)	a third of the reruns
A run that looks hung	up to 5 min with no output	up to 15 min with no output
A kill or reboot	loses at most the last unsaved part (WC-LIFE-12)	same
Provider session limits and idle limits	one connection for 5 min	one connection (plus retries) for 15 min; the source reconnects, so a closed session costs one retry
Agent that runs the CLI from a shell tool with its own 2 to 10 min limit	fits at the lower end	can be cut by the agent's tool; --timeout or MCP (45 s) avoid it
Overlapping scheduled runs	shorter window	longer window: a lock is needed, as before
Who is affected	calendar sync and any cooperative command	only commands that declare partial (calendar sync and mail sync); the calendar sync's 5 min becomes 15

Also: the "Who follows" list and the WC-LIFE-16 exceptions name mail-cli's sync (request budget from the cli-core release that follows 0.472.0); mail-cli is added to the repositories Enforced by may name; index count and CHANGELOG are updated.

Testing

pnpm docs:check (docs, rule ids, "Enforced by" lines), pnpm docs:lint, pnpm docs:spell, pnpm lint. The enforcing tests are in cli-core (#2144, merged) and mail-cli.

🤖 Generated with Claude Code