Quota tracking

DurinDoor stores two different kinds of numbers. Local usage (usageHistory) is what this install counted. Provider snapshots are what the upstream account reported. Routing reads snapshots. Invoices still come from the provider.

Open Dashboard → Quota Tracker (/dashboard/quota) for remaining capacity, cooldowns, and reset hints. The same ProviderLimits widget also sits on Dashboard → Usage. Auto-ping toggles live on Dashboard → Providers → (Claude or Codex connection) and on that limits view.

Read a quota snapshot

Connect an account, open Quota Tracker, and refresh its limits. A snapshot is bounded, unlimited, or unknown. Missing data is neither unlimited nor exhausted; zero remaining capacity is valid. Default freshness is 60 seconds, shortened by an earlier reset or cooldown. Stale information cannot block an account by itself.

Who has a provider API

These families write snapshot rows through the shared tracker (HTTPS only, 10s timeout, 1 MiB body cap, no credential-bearing URLs, redirects rejected):

Gemini CLI, Antigravity / agy, Codex, Claude, GitHub Copilot, Cursor (WorkOS dashboard JSON, not Connect/protobuf), Kiro, Kimi Coding, GLM / GLM CN / Z.AI / GLM T, MiniMax / MiniMax CN, CodeBuddy CN, Bailian Coding Plan, Qoder, Qoder CN, Vercel AI Gateway, Crof, DeepSeek.

These do not create snapshot rows: gemini API-key, qwen, iFlow, xAI, Xiaomi MiMo, Grok Web, Ollama / Ollama Cloud, Vertex billing, OpenCode variants, NanoGPT (absent from the registry). Amazon Q is represented by Kiro. Local RPM/RPD estimates and usage-history spend are not snapshots.

Successful observations cache for at most 60 seconds. Equal callers share one in-flight refresh. The cache key is provider, connection id, and connection revision.

Verify account selection

Before dispatch, fresh exhausted or cooling-down quota can skip an account for the relevant model or account window. Missing, stale, unknown, or malformed data keeps the account eligible. This check reads existing snapshots rather than fetching the provider on every request.

When multiple accounts have comparable fresh quota, remaining capacity, in-flight requests, health, and priority influence their order. Local reservations estimate capacity for concurrent dispatches; they are not provider quota reports. Unknown quota keeps the established account order.

The optional routing floor is off by default and normally uses 2% remaining when enabled. Window and connection overrides take precedence over provider and global settings. Fresh bounded request windows must still have capacity for one request.

File-backed SQLite coordinates reservations on one host. The sql.js fallback cannot coordinate multiple processes, and separate hosts need an external coordinator.

Send a request after refreshing an exhausted account alongside another eligible account. Check Usage for the account that answered. If every account and combo member is blocked, the client receives the all-rate-limited response. Retry-After is present only when every blocking account has a known deadline.

Auto-ping

Opt-in per active Claude or Codex OAuth connection. DurinDoor sends a minimal request only when the five-hour session window is ready to restart. Codex also waits when a longer blocking quota is exhausted. API-key connections and other providers are never pinged.

The scheduler uses the same snapshots and tracker. A ping counts as success only after a native Claude message_stop or a valid Codex Responses terminal. Empty or truncated 200 streams do not update ping metadata. A request already accepted upstream cannot be recalled.

Redeem a Claude reset only when intended

Claude Code OAuth connections eligible for Anthropic's free "limit reset" program (cedar_ember) show their available resets on the same limits view, read-only, as part of the normal usage poll. No extra request is made to see them.

Spending a reset is never automatic. The dashboard only calls the redeem endpoint after you press the reset button and confirm the Durin DS dialog, which states the action is irreversible and names which limits it refills (session, weekly, or a model-scoped weekly window). Redeeming clears the connection's cached quota so the next read shows the refilled limits.

Compare quota with cost

Cost estimates need catalog prices and token counts. Reasoning tokens are a subset of output, not an extra charge. Treat the number as an operational hint. The provider remains the billing authority.

Resetting local usage does not reset upstream quota. Back up DATA_DIR first if you still need the history.

Check fallback with two accounts

Two Codex OAuth connections. The first is on a five-hour window that the Quota Tracker shows as exhausted until 18:00 UTC. Send model: "codex/gpt-5" (or your combo that lists that member). Preflight skips the exhausted row and dispatches the second connection. Usage shows the second account. No provider 429 is fabricated for the skip.

If both are exhausted and no other combo member remains, the client sees the existing all-rate-limited response, with Retry-After only when every blocking account has a known deadline.

Recover missing or stale limits

Refresh the account and read the reported error. Reauthorize expired OAuth credentials, or check provider availability and proxy connectivity. A provider without a quota API cannot produce a live snapshot through this tracker. Resetting local usage does not replenish the upstream account.