Usage-limit gating is invisible to unattended sessions — agent-team orchestrator froze 5h with zero signal in transcript or terminal

Summary

When an account hits a usage-limit window, a session that is unattended (no pending interactive prompt — e.g., an agent-team lead waiting on teammate messages) is gated silently: no banner in the terminal scrollback, no transcript event, no log entry. Queued teammate messages are simply held until the window reopens. For multi-hour autonomous orchestration (experimental agent teams), this looks identical to a hang and is undiagnosable without forensics.

Environment

• Claude Code 2.1.175, macOS (darwin 26.x)
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — hub-and-spoke team: 1 lead + 5 teammates

What happened

During an overnight autonomous run (lead + 5 teammates, heavy first hour incl. an Opus teammate):

1. 05:25:45 UTC — lead's turn ends normally (last transcript event: stop_hook_summary). 9 seconds later a teammate sends the lead a report via SendMessage.
2. 05:25:45 → 10:27:23 UTC (5h01m) — the lead session writes zero transcript events of any kind. No API attempts, no retry/backoff events, no error, no banner. The teammate's message sits queued. All teammates idle (hub-and-spoke: they wait on lead dispatches), so the whole pipeline freezes.
3. 10:27:23 UTC — the queued message delivers spontaneously (no user attach — verified: a later phone-app message carries queue-operation enqueue/dequeue markers; this resume event carries none) and the run completes normally at full speed.

Diagnostics that ruled everything else out

• Host never slept: kern.sleeptime = 0 since boot
• Lead process healthy throughout: MCP client token-refresh heartbeat every ~4 min in ~/Library/Caches/claude-cli-nodejs/.../mcp-logs-*, zero gaps across the window — timers firing, outbound HTTPS succeeding
• Machine-wide: zero assistant turns in ANY session transcript during the window (53 recently-active transcripts scanned)
• Duration ≈ 5h01m and spontaneous resume → consistent with a usage-limit window reopening

Expected

When turn-starts are gated by a usage limit, the session should surface it observably, e.g.:

• a transcript/system event at gate-engage: usage limit reached — turn scheduling paused, resumes ~HH:MM (and ideally one at resume)
• the same line printed to the terminal scrollback so it survives for someone checking hours later
• bonus: expose limit state to hooks or the status line so orchestration tooling can react (notify, re-plan, park teammates)

Actual

Nothing. The only way to distinguish "usage-gated" from "hung" after the fact was transcript-gap analysis + MCP-log heartbeat forensics + kernel sleep counters. The current-window UI shows live state only — there is no history, so post-hoc confirmation is impossible user-side.

Why it matters

Agent teams make multi-hour unattended sessions a first-class workflow. A silent, unbounded pause that resumes on its own (or whenever a human attaches) reads as a hang, burns the unattended window, and invites users to kill/respawn healthy teams. One visible event would make it a non-issue.

🤖 Generated with Claude Code