parallel-subagent-fanout-rate-limit-recover-from-disk

What problem does it solve? When you dispatch many parallel subagents at once, the API returns server-side rate-limit errors, and the agents' return status lies about what was actually produced — most 'failed' agents already wrote their output files before the error hit on their final summary turn. Retrying based on return status wastes tokens re-doing completed work. ## Core Features & Use Cases - Concurrency throttling diagnosis: Identifies that dispatching more than ~5-6 concurrent subagents trips a server-side throttle distinct from your usage limit, and prescribes batching at 4-5 concurrent dispatches. - Disk-based recovery: Provides a shell loop that enumerates expected output paths and re-dispatches only chunks whose files are missing or empty, treating the filesystem as ground truth rather than agent return messages. - Session-limit variant handling: Covers the user-account session limit case ('You've hit your session limit · resets HH:MM'), where retries launched inside the limit window die instantly at ~0 tokens, so re-dispatch must wait until after the stated reset time. - Use Case: A graphify-style extraction chunked 552 docs into 28 subagent tasks; 20 returned 'Rate limited' but disk checks showed 20/28 chunk files present, so only the genuinely missing chunks were re-run in batches of 4-6 with no further throttling. ## Quick Start Ask the agent to check which expected chunk output files are missing or empty on disk and re-dispatch only those subagents in batches of four.