Terminal capacity handling: one decision, one button

[catomean]

Summary

Terminal capacity handling simplified to one decision: a short explanation and one button for the next available agent. Reduces cognitive load, time, and effort.

What This Is

When an agent hits a capacity limit, the operator sees:

Claude hit its limit (resets 1pm).
[Switch to Cursor]

Not: a menu of agents, a cloud/local puzzle, and a vendor error at the same time.

Design Principle

Reduce cognitive load. The operator shouldn't have to:

• Know which side (cloud/machine) has the session → We pick it (auto-switch)
• Understand what the vendor error means → We hide it (full overlay)
• Choose from several agents → We pick the next one (their configured order)
• Press the right button among many → One primary action

They confirm. We handle the rest.

What Changed

1. One Decision Only

• One sentence explaining what happened
• One button for the next available agent in their AGENT_FALLBACK_ORDER
• No menu of agents, no chip grid, no multiple choices

2. Hide Vendor Error Completely

• Full-screen overlay (bg-surface-terminal) covers the terminal
• Operator never sees Claude's "weekly limit" text
• No competing messages or visual clutter

3. Auto-Handle Everything

• Source switching: Automatically try other source when Watch lands on wrong side
• Agent selection: Pick the next available agent from their configured order
• Visual hierarchy: One obvious action (primary button)

4. Exhausted Fallback Case

When all agents are at capacity:

Claude hit its limit (resets 1pm).
All agents are at capacity. Wait for the reset time or install additional agents.

Clear, actionable, no button when there's nothing to switch to.

Implementation

Before (overcomplicated):

• Icon + header + explanation paragraph
• Grid of agent chips (all remaining agents)
• Disabled chips with availability reasons
• Micro text about unavailable agents
• Multiple primary actions competing

After (minimal):

• One sentence: current agent + reset time
• One button: next agent
• Center-aligned, simple
• Full overlay hides the error

Code:

<p>Claude hit its limit (resets 1pm).</p>
<button onClick={() => onSwitch(nextAgent.id)}>
  Switch to Cursor
</button>

Uses Existing Order

No settings tour, no new page. Uses AGENT_FALLBACK_ORDER from the registry — the order they already configured.

Verification

• npx tsc --noEmit
• npm run lint
• Manual: Capacity overlay shows one sentence + one button
• Manual: Clicking button switches to next agent
• Manual: Vendor error text is hidden by overlay
• Manual: "All exhausted" case shows no button

Production Notes

• Migrations: None
• Deployment: Standard
• Rollback: Safe
• Behavioral change: Simpler UI, same backend

What Ships

One decision per capacity event:

1. Explanation (what happened, when it resets)
2. Action (switch to the next agent)
3. Confirmation (click the button)

No menus, no puzzles, no cognitive load. They confirm; we handle the rest.