[chore] Paid-API tier has no live verification (anti-key stance) — exercise it when a real key exists

[Jason-Vaughan]

What

The paid-API tier (tier: api / ApiAdapter, gate, last-resort routing — #2) is fully hermetic-tested (mocked HTTP, gated build_adapter, router last-resort fallback, GUI visibility) but has never been run against a real paid endpoint. This is by design: the project is deliberately anti-key — we don't hold raw provider keys, and we don't mint billable LiteLLM virtual keys or make billed calls just to test.

So the live paid path is wired but unproven end-to-end: the code hooks are in place, but no real request has flowed router → ApiAdapter → LiteLLM virtual key → paid provider → response.

Why this is filed (not fixed)

Minting a budget-scoped LiteLLM virtual key + loading a provider key lives on Monad (the coordinator side) and spends real money — an operator/PM action, out of scope for a builder session. Tracking it here so it's visible rather than buried.

What "done" looks like (for whoever picks this up)

When a real provider key + budget-scoped LiteLLM virtual key exist on Monad:

1. Follow the README runbook ("Runbook — enabling a paid key") to wire a tier: api entry via key_ref.
2. Flip api_billing_enabled: true, run tanglebrain --model <api-id> "..." for an explicit paid call, then exhaust the subs to confirm the router last-resort fallback reaches it.
3. Confirm spend lands LiteLLM-side under the virtual key's cap; capture any shape/parse fixes the live provider needs (the adapter reuses the openai-compat transport, so deltas would be in response parsing / error handling).
4. Add a gated live test alongside tests/test_live.py if the path needs ongoing coverage.

Until then: treat the paid tier as hermetically correct but live-unverified. No action needed unless you actually want to use a paid key.

[Jason-Vaughan]

Provider-side budget note (owed from the c12 session, for whoever mints the key):

When the real key gets minted, cap the budget provider-side as well as LiteLLM-side. The LiteLLM virtual key's monthly cap is gateway software enforcement — it bounds spend only while requests actually flow through the gateway with that key. A hard spend limit set at the provider itself (e.g. the OpenAI/Anthropic org's monthly budget cap on the underlying provider key) bounds the blast radius even if the gateway is misconfigured, the raw provider key leaks from Monad, or a routing bug bypasses the virtual key. Two independent caps, two failure domains: mint the provider key with the smallest budget the verification needs (single-digit dollars covers step 2's runbook), then layer the LiteLLM virtual-key cap under it.

One addition to the "done" checklist since c13 shipped (v0.19.0): the paid ApiAdapter now inherits run_stream, so live verification should also exercise stream: true through tanglebrain-serve pinned to the api entry — the streaming path hits the same gates but a different transport code path (SSE pass-through), and step 3's shape/parse caveat applies doubly to provider SSE dialects.