fix(monitor): cross-session rate-limit retry coordination (#3931)

[OneStepAt4time]

Fix: Parallel sessions competing for CC rate limit

Closes #3931

Problem

When 3+ parallel ag run sessions hit the CC rate limit, each retries independently with its own exponential backoff. The concurrent retries amplify rate-limit pressure instead of reducing it.

Solution

RateLimitCoordinator — a lightweight semaphore that serializes rate-limit retries across sessions:

• Concurrency cap (default: 1): only one session retries at a time
• Stagger delay (default: 2s): minimum gap between consecutive retry starts
• Queue: sessions hitting rate limits acquire a slot; if full, they queue FIFO
• Cleanup: sessions killed while queued are dequeued via removeSession()

Changes

New files:

• src/rate-limit-coordinator.ts — coordinator (124 lines)
• src/__tests__/rate-limit-coordinator.test.ts — 8 tests

Modified:

• src/monitor.ts — handleRateLimitSignal() uses coordinator.acquire() before delay + restart, coordinator.release() on completion/failure. removeSession() calls coordinator.dequeue() for cleanup.

Tests (8 passing)

• Acquire when under limit
• Queue when at limit, proceed on release
• FIFO ordering
• Dequeue removes specific session
• Stagger delay between releases
• Active count tracking
• Default config (maxConcurrent=1, staggerMs=2000)
• Safe release when nothing active

Verification

tsc --noEmit → 0 errors
npm run build → OK

[aegis-gh-agent]

Review: PR #4059 — Rate-Limit Retry Coordination (#3931)

Verdict: ✅ Approved

Clean semaphore implementation. The coordinator correctly serializes rate-limit retries across sessions with concurrency cap and stagger delay. Integration into monitor is well-structured — acquire→delay→restart→release chain with proper cleanup on session kill.

Key Points

• Semaphore pattern: maxConcurrent=1 default means only one session retries at a time
• Stagger delay: 2s minimum between consecutive retry starts — prevents retry storms
• Cleanup: dequeue on session kill, release on both success and error paths
• Observability: structured logging at acquire/release/dequeue with session context
• Tests: 8 unit tests covering concurrency, FIFO, dequeue, stagger, defaults, edge cases

Minor Nits (non-blocking)

1. lastReleaseAt is set then immediately read in release() — elapsed is always ~0, so stagger is effectively a fixed delay. Behavior is correct, but the variable name is misleading.
2. No integration test for the monitor.ts acquire→restart→release chain. Acceptable given mocking complexity.

9 Merge Gates — All Pass

1. ✅ Review completed
2. ✅ No conflicts — MERGEABLE
3. ✅ CI green — all checks pass
4. ✅ No regressions
5. ✅ Unit tests (+8 new)
6. ✅ E2E pass
7. ✅ Documented
8. ✅ Security clean
9. ✅ Targets develop