[repo-study-hermes-codex-subscription-auth] ChatGPT subscription phase 1: add Codex app-server auth and readiness

[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
• Clean-room constraint: use the documented Codex app-server protocol and PortOS conventions; do not copy Hermes source, prose, config, or assets.

Rationale

PortOS's existing codex and codex-tui cards prove that the CLI can be launched, but they cannot tell the user whether ChatGPT auth exists, which plan is active, whether re-authentication is needed, or whether quota is available. Hermes makes subscription auth a visible provider concern. OpenAI's app-server already owns this lifecycle, so PortOS can add the missing product experience without reading ~/.codex/auth.json or storing tokens itself.

User-facing outcome

The server can report Codex account readiness and start, cancel, or end an explicit ChatGPT browser/device-code login. Provider state distinguishes runtime missing, signed out, login pending, ready, quota exhausted, and re-authentication required; no API-key field is involved.

Fix:

Add a PortOS-owned Codex app-server lifecycle client in server/services/codexAppServer.js and expose bounded provider account actions from server/routes/providers.js. Extend server/services/providerPrerequisites.js, server/lib/providerPrerequisites.js, and provider presentation so the existing Codex provider records publish validated auth/readiness state. Keep the spawned command fixed to the supported codex app-server invocation, register shutdown cleanup, serialize JSON-RPC writes, bound startup/login timeouts, and redact all token-bearing payloads. Do not import PortOS modules into server/lib/aiToolkit/.

Add client wrappers in client/src/services/apiProviders.js for later UI use, but do not build the Providers-page UX in this phase.

Acceptance criteria

• account/read is the source of truth; PortOS never parses, copies, returns, logs, or persists Codex credential files or tokens.
• Login starts only from an explicit POST and returns only the browser URL or device verification URL/code plus a bounded login identifier.
• Cancellation, logout, app-server exit, login timeout, revoked auth, and malformed protocol frames settle once and produce typed, actionable errors.
• Provider readiness uses explicit sentinels: unavailable/unknown is not collapsed into signed out, and a legitimate empty quota/model response is not treated as a failed fetch.
• The existing Codex CLI/TUI providers remain usable through their current spawn path; users already signed in through Codex are detected without a new login.
• No Codex process or network call is started during cold boot merely to check auth; readiness is fetched lazily from the Providers page or immediately before an explicitly requested run.
• Focused route/service tests cover signed-out, pending, ready, cancellation, revoked, timeout, and process-exit paths without real OAuth or sleeps.

Estimated scope

Medium-large, about 3-5 engineering days. New lifecycle service and route contract plus readiness integration and focused tests; no final UI and no generic inference transport yet.