Terminal-billing client hardening: shared wire types, wire-layer tests, dead RPC removal

[alt-glitch]

Hardening pass over the terminal-billing client layer that #51639 built. The theme: the billing wire contract used to live in three places (a TUI-local types file, a hand-copied desktop mirror, and everyone's heads). After this PR it lives once, in @hermes/shared, together with the behavior tables that used to be duplicated switch statements.

Originally stacked on #51639; now that it merged, this targets main directly.

Where things moved

flowchart TD
    GW["tui_gateway/server.py<br/>(serializes billing/subscription RPCs)"] -->|"JSON over the gateway socket"| BT

    subgraph shared ["apps/shared (new home)"]
        BT["billing-types.ts<br/>wire shapes + Known* unions<br/>(moved from ui-tui/src/gatewayTypes.ts)"]
        BP["billing-policy.ts<br/>refusal code &rarr; recovery table"]
        CS["charge-settlement.ts<br/>settlement poll state machine"]
    end

    BT --> TUI["ui-tui<br/>(gatewayTypes.ts re-exports, zero call-site churn)"]
    BT -.-> DESK["apps/desktop billing settings<br/>(adopts in #61054)"]
    BP --> TUI
    BP -.-> DESK
    CS --> TUI
    CS -.-> DESK

Loading

Solid arrows are wired up in this PR. Dotted ones land in #61054, which swaps the desktop's hand-copied type mirror for these modules.

The changes

Wire types move to @hermes/shared/billing. The billing and subscription response shapes (plus the usage-bar types they reference) move verbatim out of ui-tui/src/gatewayTypes.ts into apps/shared/src/billing-types.ts. gatewayTypes.ts re-exports every moved name, so no ui-tui call site changes. The new ./billing subpath exists so the DOM-less TUI does not pull in the root barrel's DOM-typed WebSocket helpers.

Error codes become real types. Two literal unions describe what the wire can carry: BillingRefusalCode for typed refusals and ChargeFailureReason for terminal charge failures. Each has a closed Known* half and an open (string & {}) arm. The closed half is the useful part: an exhaustive Record<KnownBillingRefusalCode, ...> now fails to compile when someone adds a code without deciding what it means, while the open arm lets unknown future codes (new card-health states, for example) flow through to the fallback branch instead of breaking anything. The reason union includes subscription_payment_intent_requires_action, the raw Stripe code that older server builds report for an SCA-gated upgrade, so the client renders "verify your card" either way.

One policy table instead of three switches. billing-policy.ts holds a single exhaustive map from refusal code to behavior: which recovery to offer (retry, portal, step-up, reconnect, login, none), which codes make a mid-poll outcome ambiguous, and which allow reusing an idempotency key on retry. The copy stays per-surface; the decisions no longer drift. This came out of review, which found the TUI and desktop already disagreeing on two of these decisions after a week.

One settlement machine. charge-settlement.ts is the charge-status polling loop (2s cadence, 5-minute cap, bounded retry-after backoff, revocation-means-ambiguous) as a pure function over injected deps. The TUI's /topup poller is now a thin renderer over it. Its output is byte-identical; the existing poller tests pass without modification, which was the acceptance bar.

Wire-layer tests. hermes_cli/nous_billing.py's HTTP error handling had no coverage through _request. About 30 tests now pin the 401-refresh-retry machinery, the 403 family, 429/503 retry-after handling, non-JSON bodies, and URLError normalization. Writing them surfaced two real bugs, fixed here: a bare read-phase TimeoutError escaped the typed error contract (now network_error), and BillingMutationResponse.payload claimed success payloads were error-shaped.

Verification

apps/shared, ui-tui, and apps/desktop typecheck clean. ui-tui vitest: 977 passed. Wire-layer suite: 30 passed. Billing-adjacent Python suites: 119 passed. The TUI poller rewrite passed the pre-existing topupCommand tests (28) unchanged.