feat(usage-queue): per-tab + per-runtime auto-Enter (ADR-068)

[aterrylu]

What & why

Fixes a reported bug: the "auto-Enter when limit resets" button showed on a Codex agent's pane while it was Claude usage that was capped. The usage queue was written single-account-Claude — the cap was one account-wide value read by every pane, so a Codex (or Gemini) pane lit its button on the Claude limit and would have fired on the Claude clear. With split panes it was also nominal-per-tab (every tab saw the same global cap).

How — per-tab AND per-runtime (ADR-068)

flowchart LR
  A["armed pane\n(carries its provider)"] --> T{tick: group by provider}
  T -->|claude-code| C["claude-usage cap\n(hysteresis 90/80)"]
  T -->|codex| X["codex-usage cap"]
  T -->|gemini-cli| G["no probe → can't arm"]
  C -->|clear edge| FC["fire Claude panes"]
  X -->|clear edge| FX["fire Codex panes"]

Loading

• Each armed pane carries its agent's provider (resolved server-side from the record). Block state is tracked per provider; each tick polls only the providers with armed panes and fires each on its own high→low clear edge — Claude via claude-usage, Codex via codex-usage. Gemini has no rolling-window source → can't arm, button never shows.
• The queue core is plugin-agnostic (NormalizedUsage + injected probes); normalizeClaudeUsage / normalizeCodexUsage adapt each plugin's snapshot. All original invariants kept — re-entrancy guard, hysteresis, per-pane seenBlocked latch, notify-on-drop — just keyed per provider.
• Route arms with the agent's provider and GET returns per-provider caps; SessionPane → UsageQueueButton(provider) → useUsageQueue(sessionId, provider) reads only its pane's cap. Per-tab is then correct by construction.

Testing

• make check green — server suite (20 usage-queue tests) + 362 dashboard tests, biome + tsc clean.
• Mutation-verified: forcing the queue to ignore a pane's provider turns the isolation tests red ("Claude and Codex fire independently", "Codex fires on the Codex clear"). Plus "a Claude cap does not fire a Codex pane" (the reported bug), the adapter maps, evaluateCap, and the gemini no-op.

Checklist

• make check passes locally
• Conventional-commit title (feat:)
• ADR recorded (ADR-068)
• Not a visible default-scene change — the button only appears at a live cap, so no make hero

🤖 Generated with Claude Code

[nox-0x]

Approving — the per-runtime refactor is correct and well-tested on the server side, and the four findings are follow-ups rather than blockers.

What I verified

• The core change is sound: blocked/resetsAt scalars → Map<Provider, …>, tick() groups armed panes by provider and polls only providers that have one, and each fires on its own high→low edge. Every original invariant survives — the re-entrancy guard still wraps the whole tick (so the double-Enter case stays closed across providers), hysteresis is unchanged, seenBlocked is now latched per provider, and the notify-on-drop path is intact.
• The provider is resolved server-side from the agent record, so a client cannot arm a pane against the wrong runtime's limit. Good call over trusting a client-supplied value.
• NormalizedUsage + injected probes is the right seam — the unit tests drive both runtimes with fakes and the reported bug ("a Claude cap does not fire a Codex pane") is pinned directly. The mutation evidence in the ADR checks out against what those tests assert.
• Per-tab correctness genuinely does fall out for free once the button reads s.caps[provider].

Follow-ups (none blocking)

1. 🟡 GET /api/usage-queue unconditionally probes Codex on every 15s poll. getCodexUsage()'s no-auth and expired-token branches skip the 60s cache and run an uncached recursive scan of ~/.codex/sessions/** plus up to 8 whole-file reads — 4×/min per dashboard tab, for Claude-only users too. Also awaited serially, so it lands on the Claude button's latency.
2. 🟡 A stale Codex rollout fallback carries no errorKind, so it normalizes to non-empty windows with authError: false. Frozen at ≥90% (expired token, or /wham/usage down), an armed pane never sees the clear edge and never hits the auth-warning branch — a silent multi-hour wait, which is exactly what the Claude path notifies about.
3. 🟡 useUsageQueue.dom.test.tsx was left on the old contract (one-arg call, {capped, resetsAt} body). It passes vacuously because tsconfig excludes test files from tsc and neither case asserts capped — so the client half of the fix (s.caps[provider]) is currently untested, with the button DOM tests mocking the hook wholesale.
4. 🟢 POST /:sessionId returns { armed: true } even when arm() no-ops for a probe-less provider.

Details are in the inline comments. ADR-068 is thorough and honest about the alternatives.