feat(desktop): billing settings tab

[alt-glitch]

A Billing tab in the desktop settings UI: the core of the portal billing page (balance, plan, payment method, buy credits, auto-refill, per-type usage), fed entirely by the terminal-billing gateway RPCs. No new Electron surface; everything rides the existing gateway socket, and anything sensitive (card entry, plan changes) deep-links out to the portal in the system browser.

Stacked on #61067 and consumes its shared modules. Layout is a summary bar (Balance / Plan / Auto-refill) over settings-list rows, plus a Usage section where each row carries a real denominator (subscription credits remaining of the monthly allotment; top-up credits as a plain amount since nothing bounds them; monthly spend cap when one exists).

How the pieces connect

flowchart LR
    subgraph desktop ["apps/desktop · settings › Billing"]
        UI["summary bar + rows<br/>(index.tsx)"] --> HOOKS["use-billing-state<br/>use-charge-poller &middot; use-step-up"]
        HOOKS --> API["api.ts<br/>(normalizes results + throws<br/>into one refusal union)"]
    end

    API -->|"gateway socket RPCs"| GW["tui_gateway"]
    GW --> SRV["billing API"]

    subgraph shared ["@hermes/shared (from #61067)"]
        BT["billing-types<br/>(wire shapes, types.ts is a re-export shim)"]
        BP["billing-policy<br/>(refusal &rarr; recovery)"]
        CS["charge-settlement<br/>(poll state machine)"]
    end

    BT --> API
    BP --> HOOKS
    CS --> HOOKS

Loading

The TUI consumes the same three shared modules, so the two surfaces classify errors and poll settlements identically by construction. Copy stays per-surface (this page says "Settings → Gateway" where the TUI says /portal).

Surface	RPC	Notes
Summary, payment method, usage	billing.state	TanStack Query, 30s stale, refetch on focus
Subscription row	subscription.state	fail-open when the endpoint is absent
Buy credits	billing.charge + billing.charge_status	client idempotency key; settlement runs on the shared charge-settlement driver (2s cadence, 5-min cap, backoff on retryable codes, revocation mid-poll reads as an ambiguous outcome, never a failure)
Auto-refill edit/disable	billing.auto_reload	edits enforce the server's real min_usd/max_usd; enabling from scratch is portal-only because it needs a card-setup step the terminal can't perform
Scope step-up	billing.step_up + verification event	code + URL rendered, RPC resolution = completion

If auto-refill is charging a different card than the one on file, the row says so by brand and last4 (or "a different card" when those are null) and offers a Reconcile deep-link to the portal.

When things are missing

The tab fails open like the TUI. Logged out gets a calm connect state. An unavailable endpoint or a refusal gets an inline notice while the page shell stays intact. can_charge:false or billing disabled hides the buy controls and says why. Card provenance chips render only when the server sends those fields, so older deployments just show less. "Adjust plan" is a portal deep-link with org_id (in-app subscription writes are a later cut), and the invoices section is feature-gated off because no endpoint exists yet.

Every known refusal code has specific copy and a working recovery action (step-up, portal link, retry with the server's retry-after, reconnect, or sign-in), and the mapping test is Record-exhaustive over the known-code union, so adding a code without deciding its copy fails to compile. Unknown codes still degrade to a generic notice that shows the server's message.

Tests

54 vitest cases across the module: wire-payload pins (including a captured real payload with can_charge:false), envelope normalization ({ok:false} results and transport throws collapse into one refusal union), the settlement flow under fake timers (settle / fail / backoff / cap-timeout / ambiguous revocation / idempotency-key reuse, plus a case pinning that a temporary payment-provider outage backs off instead of failing hard), the degradation render matrix, step-up event wiring, the auto-refill bounds rejection, and the overdrawn-credits clamp ("$0 of $220 left · $0.79 over").

Also exercised live in the dev app against a real account over the gateway (real balance, card, divergent auto-refill state, and the dev fixture simulator for the states that are awkward to reproduce on demand).

Screenshots

(attached in comments)