[repo-study-hermes-codex-subscription-ui] ChatGPT subscription phase 3: add guided provider sign-in and quota UX

[atomantic]

Provenance

• Studied repository: NousResearch/hermes-agent
• License: MIT
• Study date: 2026-09-01
• Parent epic: [repo-study-hermes-chatgpt-subscription-provider] Make ChatGPT subscription a first-class PortOS AI provider (epic) #5588
• Depends on: [repo-study-hermes-codex-subscription-auth] ChatGPT subscription phase 1: add Codex app-server auth and readiness #5589 and [repo-study-hermes-codex-subscription-transport] ChatGPT subscription phase 2: make Codex a safe text-inference transport #5590
• Clean-room constraint: re-create the user workflow in PortOS's design system; do not copy Hermes source, prose, config, or assets.

Rationale

Hermes makes subscription access discoverable as a provider choice rather than requiring users to know which credential file or CLI command supplies it. PortOS's AI Providers page currently shows Codex runtime installation and a generic CLI editor, but no ChatGPT sign-in action, account/plan state, quota windows, or explanation of which PortOS features can use the subscription.

User-facing outcome

The Codex provider card offers a guided “Sign in with ChatGPT” flow, reports plan/readiness/quota without exposing identity or tokens, refreshes the model catalog, and clearly separates subscription-backed usage from OpenAI API-key billing. A user can enable it and set it as the relevant default only after the login and provider configuration are successfully saved.

Fix:

Use the account-action wrappers added in phase 1 and build the guided flow in client/src/pages/AIProviders.jsx plus client/src/components/providers/ProviderCard.jsx / ProviderReadiness.jsx. Reuse the existing Drawer/form, toast, runtime-install, status, model-picker, and URL-selection conventions. Extend client/src/utils/providers.js#credentialSource and providerCardState in parity with server/lib/providerPrerequisites.js so subscription auth is neither mislabeled as “API key missing” nor treated as ready when auth state is unknown.

Show browser login by default and a device-code fallback suitable for headless/remote installs. Display only bounded fields returned by the server: auth mode, plan label, login state, quota percentages/reset times, and last usage refresh. Keep API-key OpenAI as a separate card/path. Wire model refresh to the phase-2 app-server catalog and preserve existing user-selected model/effort pins when still valid.

Acceptance criteria

• The Codex card has explicit signed-out, login-pending, ready, quota-limited, re-auth-required, and runtime-missing states with one clear next action each.
• “Sign in with ChatGPT” opens the returned URL; device-code mode shows a copyable code and verification link; both support cancel and bounded timeout without alert/confirm.
• The page never renders an access token, refresh token, account identifier, email, credential path, or raw protocol payload.
• The API-key field is hidden for the subscription auth mode and remains available for the separate OpenAI API provider.
• Enable/default actions are gated on saved, current auth/model state. A failed or unknown readiness fetch never renders as signed out or ready.
• Plan and quota text explains that usage follows the user's ChatGPT workspace/subscription limits and that PortOS cannot promise eligibility or exact resets beyond the account data Codex reports.
• Model refresh, model-aware effort choices, fallback selection, Test, logout, and re-login update the card reactively without a full page reload.
• Browser tests cover the full successful login flow plus cancellation, expired login, revoked auth, empty model catalog, quota exhaustion, logout, and an older server that omits the new fields.

Estimated scope

Medium, about 2-4 engineering days. Provider-card state/controls, guided login UX, model/quota display, mirrored client classification, and rendered-interaction tests.