design(aggregator): quota + throughput view — pooled quotas, resets, burn rates, model-choice support #851

Design issue — aggregator quota + throughput view

Parent context: the project-management stack design record
(doc/2026-10-24T11-05-38Z_design_project-management-stack/) and the
aggregator UI phase (session K, branch pm/aggregator-ui). Reference
design (concept only — FSL-1.1-MIT licensed, do NOT vendor its code):
https://github.com/amirfish1/claude-command-center (throughput page +
share card).

What Drew asked for (2026-10-25)

A view into all pooled quotas and their resets plus throughput,
so that Muse can quickly answer "what's the quota status" for every
provider and effectively choose the best model/pool for the next piece
of work. A nice GUI should exist, but the priority is machine
analyzability: this view is primarily a data surface for Muse, with
the GUI as a presentation of the same data.

Required content

Per provider/pool:

• Plan name and pool identity (e.g. OpenCode Go Personal vs Lab are
  separate pools; Antigravity has TWO independent pools — Gemini models
  and the Claude models it supports; Meta Model API is a token quota
  under the Muse Code High Usage subscription).
• Current usage for each window the provider exposes (5-hour, weekly,
  monthly as applicable), % used, and reset timestamps.
• State flag: healthy / near limit / walled, with the wall/reset time
  when walled.

Throughput:

• Sessions currently burning, attributed per provider + model.
• Rough token rate per provider (tokens/min over recent windows) and
  cumulative tokens per session — enough to answer "which providers
  are you using at roughly what rate".
• Historical burn per pool between resets, so headroom can be
  projected, not just observed.

Model-choice support:

• Given the fleet burn order (Anthropic pools first, then other plan
  providers, OpenAI last), surface which pool has headroom for a new
  session and which pools are about to reset with unused headroom
  (burn-it-before-reset rule) or are close enough to their limit that
  no second session should start on them.

Data sources (routes established 2026-10-25)

• Codex/ChatGPT: GET chatgpt.com/backend-api/codex/usage (OAuth).
• OpenCode Go: opencode.ai/zen/go/v1/usage per org.
• CommandCode: api.commandcode.ai/alpha/usage/summary.
• Cline: api.cline.bot/api/v1/users/me/plan/usage-limits.
• DeepSeek: API /user/balance.
• Cloudflare: GraphQL workersInvocationsAdaptive.
• Turso: turso plan show.
• Meta Model API: dev.meta.ai Usage page (team quota; key must be the
  team-attached meta.api-key-funded — the orphaned key 402s).
• Claude (Anthropic): console only, claude.ai/settings/usage.
• Antigravity: agy /usage panel (both pools).
• Open Design: open-design.ai/cloud/dashboard.
• GitHub: REST /users/{user}/settings/billing/usage/summary
  (needs user scope; comped minutes net to $0 and do not consume
  the plan).

Acceptance shape

• One joined, queryable model (projector output / API) that Muse can
  read in one call and answer a full quota question from.
• GUI page rendering the same data (pools, windows, resets,
  throughput) — the CCC-style share card is a nice-to-have on top.
• No estimator for pools already shown in the OpenChamber quota
  picker; log picker values instead (standing rule, 2026-10-24).

Design first: this issue wants a written design (data model, refresh
cadence per source, wall detection) in the stack design record before
implementation.

Acceptance criteria

• A written design lands in the project-management stack design record: the joined quota/throughput data model, a refresh cadence per data source, and the wall-detection rule per pool.
• The machine-first model answers a full quota question in one call: per pool — plan/pool identity, usage and % used for each exposed window, reset timestamps, and a healthy / near-limit / walled flag with the wall/reset time when walled.
• Throughput is attributed per provider + model: sessions currently burning, rough token rate per provider, cumulative tokens per session, and historical burn per pool between resets.
• Model-choice support is explicit in the output: which pool has headroom for a new session (fleet burn order respected, OpenAI last), which pools are about to reset with unused headroom, and which are too close to their limit for a second session.
• The GUI page renders the same data (pools, windows, resets, throughput); no estimator is built for pools already shown in the OpenChamber quota picker — picker values are logged instead.
• A linked implementation issue (or a tracked item with a named next action) is filed when the design lands, so the design does not sit as finished work.