feat(oauth): reliability, credential integrity, and diagnostics

[Wibias]

Summary

This PR hardens OpenCodex OAuth reliability, credential integrity, and actionable diagnostics. It does not add client impersonation, fingerprint spoofing, or rate-limit circumvention.

Why

Concurrent requests and multi-process refresh races can corrupt rotated tokens or refresh the same grant twice. Operators also lacked a shared, redacted view of OAuth health across ocx status, ocx doctor, and the dashboard. The Codex forward path needed regression locks so genuine client metadata stays preserved and official-client identity is never fabricated when absent.

What this does

1. Refresh single-flight + CAS for generic OAuth providers
   Extends the existing xAI/Anthropic pattern: in-process join map + per-account file lock + reload-before-refresh + mergeAccountCredential generation CAS. Prevents stale refresh results from overwriting newer credentials.

2. Shared OAuthAccountHealth projection
   One read model over existing needsReauth, Codex cooldowns, and warning signals — consumed by CLI, management API, and GUI. No parallel credential store.

3. Diagnostics

   • ocx status: redacted OAuth health block
   • ocx doctor: observe-only checks with recovery Actions
   • Dashboard: health badges, summaries, reauth / copy-ocx doctor / cooldown hints

4. Privacy
   maskAccountId / displayAccountId, structured logOAuthEvent that strips token-like keys, never falls back to raw account IDs in UI.

5. Codex metadata integrity
   Regression tests: preserve genuine originator / session_id / thread-id; do not fabricate when missing; outgoing chatgpt-account-id matches the selected pool credential.

6. Docs
   Documents refresh coordination, cooldowns, process-local affinity, preserved vs non-fabricated metadata, status/doctor usage, and explicitly that this cannot guarantee protection from provider enforcement.

Explicit non-goals / policy

• Affinity Policy A kept: Codex pool still clears affinity on 401/403/429 and may rotate the active account after quota cooldown. This PR does not pin threads through 429.
• No anti-ban marketing or behaviour.
• No automatic destructive doctor repairs.
• Codex reauth Actions point at the dashboard account pool, not ocx login codex (not a public login provider).

Test plan

• bun test targeted OAuth/privacy/health/status/doctor/metadata suites
• Full bun run test (4183 pass after rebase smoke on key suites)
• bun run typecheck
• bun run lint:gui
• bun run privacy:scan
• bun run build:gui
• Re-run full suite on CI (Linux/Windows/macOS)
• Manual: ocx status / ocx doctor with a reauth-marked and cooldown account
• Manual: dashboard Providers/Codex pool shows health badge + redacted account id

Design / plan

• docs/superpowers/specs/2026-07-26-oauth-reliability-integrity-design.md
• docs/superpowers/plans/2026-07-26-oauth-reliability-integrity.md

Summary by CodeRabbit

• New Features

  • Added OAuth health visibility across the CLI, dashboard, and provider account views, including cooldowns, warnings, and reauthentication requirements.
  • Added actionable diagnostics through ocx status and ocx doctor, with convenient doctor-command copying in the dashboard.
  • Account identifiers and diagnostic output are now privacy-protected.
  • Improved OAuth refresh reliability during concurrent requests and preserved forwarded client metadata.

• Documentation

  • Expanded provider, architecture, and CLI guidance for OAuth health, recovery, cooldowns, and reauthentication.

[Wibias]

Ready for merge. @lidge-jun

[Ingwannu]

A major health-state propagation bug remains at exact head fb9b64cd47b6b314330a672de1c737f08d7f4f15. In gui/src/components/CodexAccountPool.tsx, activePoolNeedsReauth correctly combines the legacy flag with health.status === "reauth_required", but the effect still calls onActiveNeedsReauthChange(activeNeedsReauth) and depends on the legacy value. In gui/src/hooks/useProviderAccountPools.ts, activeAccountNeedsReauth likewise marks a provider only when active.needsReauth is true and ignores active.health?.status. An API response that carries only the new canonical health projection therefore shows a reauth action on the account row while the Providers overview remains healthy and omits its attention state. Pass activePoolNeedsReauth through the Codex callback, include health-only reauth in the generic provider map, and add focused aggregate-path regressions for both. This is an authentication-health UI contract and blocks merge; the current Windows job is also not green.

[Wibias]

A major health-state propagation bug remains at exact head fb9b64cd47b6b314330a672de1c737f08d7f4f15. In gui/src/components/CodexAccountPool.tsx, activePoolNeedsReauth correctly combines the legacy flag with health.status === "reauth_required", but the effect still calls onActiveNeedsReauthChange(activeNeedsReauth) and depends on the legacy value. In gui/src/hooks/useProviderAccountPools.ts, activeAccountNeedsReauth likewise marks a provider only when active.needsReauth is true and ignores active.health?.status. An API response that carries only the new canonical health projection therefore shows a reauth action on the account row while the Providers overview remains healthy and omits its attention state. Pass activePoolNeedsReauth through the Codex callback, include health-only reauth in the generic provider map, and add focused aggregate-path regressions for both. This is an authentication-health UI contract and blocks merge; the current Windows job is also not green.

On it. btw. window job cancels on many pr's right now after 8 minutes, but can only look at it after i slept, So maybe u got the time to have a look.

[Ingwannu]

Re-reviewed exact head af6bd0f. The requested aggregate-health blocker is resolved: both the shared Codex controller and generic provider map now treat health-only reauth_required as an attention state, while inactive-account reauth remains isolated. The new focused regressions pass (15 GUI + 14 workspace tests), and both GUI/root TypeScript checks are clean. The sole non-green check was a Windows job cancelled at the repository 8-minute ceiling, not a test failure; I have rerun that workflow. Approved pending a successful required-CI rerun.