feat(tui+cli): change your Nous plan from the terminal (/subscription, /topup, terminal-billing UX)

[alt-glitch]

Change your Nous plan from the terminal

Why this change

Until now, if you wanted to change your subscription while working in the Hermes terminal, we sent you to the billing website. This PR handles the whole thing in the terminal instead: see your plan, preview what a change would cost, and apply it — in both the visual terminal UI (the TUI) and the classic command-line interface.

The server side of this (the API the terminal calls) ships separately; this PR is the client.

What /subscription does now

Running /subscription opens a small flow with four screens:

1. Overview — your plan, how much of this month's allowance is left, and the renewal date. If you've already scheduled a change, it's front and center: a banner like ⏳ Scheduled change · Ultra ──▶ Plus · Jul 28, 2026, and the first menu option becomes "Keep Ultra (undo this change)".
2. Pick a plan — the other available plans, each marked upgrade or downgrade.
3. Confirm — before anything happens, the terminal asks the server "what would this change actually do?" and shows you the answer: an upgrade says exactly what you'd pay right now ("Pay $46.30 & upgrade now"); a downgrade says when it takes effect and "No charge now; you keep your current plan until then".
4. Result — what happened, with a link to the website if the card needs extra verification or was declined.

Downgrades and cancellations are free and take effect at renewal; undoing a scheduled change is free and immediate. An upgrade is the only thing that charges — it uses the card already on your subscription, immediately. Starting a brand-new subscription still goes to the website (it needs a card we don't have yet).

The classic CLI gets the same flow with the same wording, so it doesn't matter which interface you're in.

The one-time permission step

Changing a plan from a terminal requires a one-time "terminal billing" permission. Previously, hitting this wall meant an error and a trip to a different command. Now the flow handles it in place: it opens your browser to approve, waits, and — once you approve — finishes the change you were making (the visual UI asks you to press Continue first; the classic CLI picks it back up automatically). You never re-run the command.

Being careful with the paying step

An upgrade moves real money, so this flow got three adversarial review passes, which found and fixed 10 real issues. The important behaviors, in plain terms:

• Pressing the button twice can't charge twice. Every upgrade carries a one-time key the server uses to recognize a duplicate.
• Cancelling really cancels. If you back out while the browser approval is pending, a late approval won't fire the charge you abandoned. And even after approval, the visual UI charges nothing until you explicitly press Continue.
• If the connection drops mid-charge, we tell the truth: "Couldn't confirm the upgrade — your card may or may not have been charged. Re-run /subscription to check your plan before trying again." — instead of a false "failed" that would tempt you to retry into a double charge.
• A stray Enter can't pay. In the CLI, the default option on the payment confirmation is "Go back", not "Pay".

Which card? (pairs with the server's card-resolver work)

Paying screens now tell you exactly which card is involved, and why:

• Named, with provenance. The /topup payment lines and the /subscription upgrade confirmation show the card and where it came from — "Visa ····4242 — the card on your subscription" (or "your default card saved on the portal" / "your auto-reload card"). The upgrade confirm only names a card when it resolved the same way Stripe itself picks the charge card, so what's shown is what's charged.
• Presence at a glance. The /topup overview shows Card: … or "No saved card on file". If the server flags the card as failing automatic top-ups, the screens warn before you try to charge it.
• A guided add-card path. With no card on file, "Add funds" no longer walks you into an amount that would fail — it opens the portal's billing page to add the card (cards are never typed into the terminal), and "I've added it — check again" re-checks and continues the purchase right where you were.

This reads the new card fields from the server's card-resolver work and degrades cleanly until it deploys: older servers just get the previous wording, and a subscriber's card doesn't show until the resolver lands.

Also in this PR

• /topup (renamed from /billing, with /credits folded in; the old names are retired) — buy credits in-terminal against the card saved on the website, with the same browser-approval step.
• Dollar amounts everywhere instead of "credits": a plan-allowance bar and a top-up bar, on both interfaces.
• Clearer errors when spending is turned off: if this terminal's spending was revoked, the spending screen closes immediately with a message that says who turned it off (you, or an admin) and how to reconnect — instead of a stale button that fails on click.

Testing

• The TUI overlay has tests for every screen — the scheduled-change banner, the picker, the pay/scheduled/cancel/blocked confirmations, the result, and the permission step.
• The CLI tests drive the whole flow through the real menus (scripted keypresses, stubbed server): schedule a downgrade, upgrade (charges once), cancel, undo, the permission step and its replay, a declined approval — plus regression tests for the money-safety behaviors above (the ambiguous-charge message, the "rate limited ≠ maybe charged" distinction, and that the flow replays once after approval and never loops).
• The card work is covered on both surfaces: the provenance and failing-card warnings render, a Link payment method shows its brand alone (it has no card number), the add-card path continues after "check again" finds the card (and abandons cleanly), and the upgrade confirmation names the subscription's card only when the server says that's the one being charged.
• Driven live against a preview deployment of the server PR: log in, preview, schedule a downgrade, undo it — the real round trip.

Rollout note

The server API should deploy before this is released. If the terminal ships first, viewing your plan still works (the read half of the API shipped earlier and is already on the server's main branch), and a plan change fails safely at the first step: the "what would this change do?" call returns an error, so the confirm and pay screens are never reached and nothing can be charged.

---

Update 2026-07-17 — reconciled against the live server contract

The server's card-on-file and subscription-change APIs are both live now, so this PR was reconciled against the real contract instead of the preview it was built on. The full client-side table of states, refusal codes, copy, and recovery actions is in docs/billing-lifecycle.md, added here.

• Dropped the chargeability / needs_repair card fields everywhere (parse, gateway serialization, the three TUI repair warnings, the dev fixture). The server removed them; a richer card-health signal is planned on the server side later. The "failing-card warning" testing note above is superseded.
• The client now consumes the server's canChangePlan capability verbatim, with a fallback to the old role check only when the server omits it. This fixes finance admins being locked out of plan changes, and the refusal copy is capability-neutral ("owner, admin, or finance admin").
• Auto-refill divergence is visible from the terminal: when auto-refill is charging a different card than the one on file, the Auto-reload screen says so and offers the portal reconcile link.
• Distinct refusal codes survive to the UI. A payment-provider outage (503, transient, honors Retry-After) and the daily plan-change cap (429) no longer collapse into generic rate-limit copy, and consent_required, org_access_denied, and auto_top_up_disabled_failures each get their own message. Unknown codes still fall through to the default that shows the server's message.
• SCA-on-upgrade branches on the failure reason rather than the status, because older server builds report a verification-needed upgrade as a payment failure. Either shape now routes to "verify your card in the portal". Upgrades also poll until the new tier is visible ("Applying…") instead of assuming immediacy, and a dropped connection during a charge reads as an unconfirmed outcome, never a false failure.
• The rollout note above is obsolete: the server API is deployed.

Verified live against a test account in the payment provider's test mode: the state parse (including a genuinely divergent auto-refill card), the free preview → schedule-downgrade → resume cycle through the real client wrappers, a live consent_required refusal rendered in the real TUI, the portal card-confirm flow, and the divergence-to-reconciled transition end to end. A live settled charge was also verified once the account's hourly charge limiter allowed it.

Update 2026-07-18 — code-quality review response

Structural pass after a five-way review. The broken credits.view handler is deleted. The ~1,400-line billing/subscription CLI family moved out of cli.py into hermes_cli/cli_billing_mixin.py (cli.py 17.2k → 15.8k lines). Charge gates follow the server capability (can_change_plan) instead of the deprecated three-role is_admin. The transient-error taxonomy is an explicit BillingTransient trait, so a payment-provider outage is no longer modeled as a kind of rate limiting. useMenu is a shared overlay primitive, pendingTierId is typed end to end (shadow interface and cast deleted), and the CLI stops poking the billing client's private token cache (invalidate_cached_token() is the public API). All scoped suites green: 176 Python, 977 TS.

[tonydwb]

Code Review Summary

Verdict: Comment (high surface area: 19 files, 1422 additions)

This PR adds a terminal /subscription view and cleans up billing command handling. The surface area is significant (19 files, 1422 additions), so a full human review is recommended before merge.

Quick observations from the diff:

• New subscription_view.py module with clean dataclass-based parsing (SubscriptionTier, CurrentSubscription, SubscriptionState)
• Fail-open philosophy documented and implemented (logged_in=False when portal unreachable)
• TUI overlay integration for the subscription screen
• Billing command cleanup

The code quality looks good from the portion reviewed, but the scope spans multiple concerns (new core module, TUI integration, billing cleanup) that warrant a more thorough human review of the full 19-file diff.

---

Reviewed by Hermes Agent