@iislee/opencodex 2.11.0

package/src/oauth/google-antigravity.ts

@@ -0,0 +1,230 @@
+/**
+ * Google Antigravity (Cloud Code Assist) OAuth + project discovery.
+ *
+ * Mirrors CLIProxyAPI `internal/auth/antigravity/*`. Flow: standard Google OAuth (PKCE) → discover
+ * the Cloud Code Assist project via `loadCodeAssist`, onboarding via `onboardUser` when the account
+ * has no project yet. The discovered `projectId` is stored on the credential and injected into the
+ * CCA request envelope by the google adapter.
+ *
+ * The client id/secret below are the public OAuth client identifiers embedded in the Antigravity
+ * desktop client (overridable via env), not user secrets. Tokens/refresh are never logged.
+ */
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { OAuthController, OAuthCredentials } from "./types";
+import { antigravityUserAgent, ANTIGRAVITY_GOOG_API_CLIENT_UA } from "../adapters/client-fingerprint";
+
+const CLIENT_ID = process.env.GOOGLE_ANTIGRAVITY_CLIENT_ID
+  || "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com";
+const CLIENT_SECRET = process.env.GOOGLE_ANTIGRAVITY_CLIENT_SECRET
+  || "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";
+const AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const PROD_API = "https://cloudcode-pa.googleapis.com";
+const DAILY_API = "https://daily-cloudcode-pa.googleapis.com";
+const API_VERSION = "v1internal";
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+const CALLBACK_PORT = 51121;
+const CALLBACK_PATH = "/callback";
+// Keep provider-side margins small: the shared OAuth freshness gate applies an additional minute.
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const ONBOARD_ATTEMPTS = 5;
+const ONBOARD_POLL_MS = 2_000;
+
+function requestSignal(signal: AbortSignal | undefined): AbortSignal {
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+interface GoogleTokenPayload {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  id_token?: unknown;
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const part = token.split(".")[1];
+  if (!part) return undefined;
+  try {
+    return JSON.parse(Buffer.from(part, "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function emailFromToken(accessToken: string, idToken: string | undefined): string | undefined {
+  const payload = (idToken ? decodeJwtPayload(idToken) : undefined) ?? decodeJwtPayload(accessToken);
+  const email = payload?.email;
+  return typeof email === "string" && email.length > 0 ? email.toLowerCase() : undefined;
+}
+
+async function postToken(body: Record<string, string>, signal?: AbortSignal): Promise<GoogleTokenPayload> {
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+    signal: requestSignal(signal),
+  });
+  if (!response.ok) {
+    // Status only — the body can carry grant/account details.
+    throw new Error(`Antigravity token request failed: ${response.status}`);
+  }
+  return (await response.json()) as GoogleTokenPayload;
+}
+
+/** Pull a Cloud Code Assist project id out of a loadCodeAssist/onboardUser response shape. */
+function extractProjectId(data: Record<string, unknown> | undefined): string | undefined {
+  if (!data) return undefined;
+  for (const key of ["cloudaicompanionProject", "projectId", "project"]) {
+    const value = data[key];
+    if (typeof value === "string" && value.length > 0) return value;
+    if (value && typeof value === "object" && typeof (value as { id?: unknown }).id === "string") {
+      return (value as { id: string }).id;
+    }
+  }
+  return undefined;
+}
+
+async function loadCodeAssistProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
+  const response = await fetch(`${PROD_API}/${API_VERSION}:loadCodeAssist`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${accessToken}`, Accept: "*/*", "Content-Type": "application/json", "User-Agent": antigravityUserAgent() },
+    body: JSON.stringify({ metadata: { ideType: "ANTIGRAVITY" } }),
+    signal: requestSignal(signal),
+  });
+  if (!response.ok) return undefined;
+  return extractProjectId((await response.json().catch(() => undefined)) as Record<string, unknown> | undefined);
+}
+
+async function onboardProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
+  for (let attempt = 0; attempt < ONBOARD_ATTEMPTS; attempt++) {
+    if (signal?.aborted) throw signal.reason ?? new Error("Antigravity onboarding aborted");
+    const response = await fetch(`${DAILY_API}/${API_VERSION}:onboardUser`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}`, Accept: "*/*", "Content-Type": "application/json", "User-Agent": antigravityUserAgent(), "x-goog-api-client": ANTIGRAVITY_GOOG_API_CLIENT_UA },
+      body: JSON.stringify({ tier_id: "free-tier", metadata: { ide_type: "ANTIGRAVITY", ide_name: "antigravity", ide_version: antigravityUserAgent() } }),
+      signal: requestSignal(signal),
+    });
+    if (!response.ok) {
+      // Transient (429/5xx): keep polling within the attempt budget. Hard 4xx: give up now.
+      if (response.status === 429 || response.status >= 500) {
+        await new Promise(resolve => setTimeout(resolve, ONBOARD_POLL_MS));
+        continue;
+      }
+      return undefined;
+    }
+    const data = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    if (data.done === true) {
+      return extractProjectId(data.response as Record<string, unknown> | undefined);
+    }
+    await new Promise(resolve => setTimeout(resolve, ONBOARD_POLL_MS));
+  }
+  return undefined;
+}
+
+/** Discover the CCA project for an access token (loadCodeAssist → onboardUser fallback). */
+export async function discoverAntigravityProject(accessToken: string, signal?: AbortSignal): Promise<string | undefined> {
+  return (await loadCodeAssistProject(accessToken, signal)) ?? (await onboardProject(accessToken, signal));
+}
+
+function credentialsFromPayload(payload: GoogleTokenPayload, refreshFallback = ""): OAuthCredentials {
+  if (typeof payload.access_token !== "string" || payload.access_token.length === 0) {
+    throw new Error("Antigravity token response did not include an access token");
+  }
+  const refresh = typeof payload.refresh_token === "string" && payload.refresh_token.length > 0
+    ? payload.refresh_token
+    : refreshFallback;
+  if (!refresh) throw new Error("Antigravity token response did not include a refresh token");
+  const expiresIn = typeof payload.expires_in === "number" && Number.isFinite(payload.expires_in) ? payload.expires_in : 3600;
+  const idToken = typeof payload.id_token === "string" ? payload.id_token : undefined;
+  return {
+    refresh,
+    access: payload.access_token,
+    expires: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS,
+    email: emailFromToken(payload.access_token, idToken),
+  };
+}
+
+class AntigravityOAuthFlow extends OAuthCallbackFlow {
+  #verifier = "";
+  #forceAccountSelect: boolean;
+
+  constructor(ctrl: OAuthController, opts?: { forceAccountSelect?: boolean }) {
+    super(ctrl, {
+      preferredPort: CALLBACK_PORT,
+      callbackPath: CALLBACK_PATH,
+      callbackHostname: "127.0.0.1",
+      callbackBindHostname: "127.0.0.1",
+      redirectUri: `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`,
+    } satisfies OAuthCallbackFlowOptions);
+    this.#forceAccountSelect = opts?.forceAccountSelect === true;
+  }
+
+  async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+    const pkce = await generatePKCE();
+    this.#verifier = pkce.verifier;
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: CLIENT_ID,
+      redirect_uri: redirectUri,
+      scope: SCOPES.join(" "),
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      access_type: "offline",
+      // select_account lets the user pick a DIFFERENT Google account when adding a second one.
+      prompt: this.#forceAccountSelect ? "consent select_account" : "consent",
+      state,
+    });
+    return {
+      url: `${AUTH_ENDPOINT}?${params.toString()}`,
+      instructions: "Complete Google (Antigravity) login in your browser, then paste the redirect URL or code if prompted.",
+    };
+  }
+
+  async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+    if (!this.#verifier) throw new Error("Antigravity OAuth PKCE verifier was not initialized");
+    const payload = await postToken({
+      grant_type: "authorization_code",
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: this.#verifier,
+    }, this.ctrl.signal);
+    const creds = credentialsFromPayload(payload);
+    this.ctrl.onProgress?.("Discovering Cloud Code Assist project");
+    const projectId = await discoverAntigravityProject(creds.access, this.ctrl.signal);
+    if (!projectId) {
+      // Fail the login rather than persisting a credential that every request would reject for a
+      // missing CCA project — otherwise status shows "logged in" while all calls fail closed.
+      throw new Error("Antigravity login could not discover a Cloud Code Assist project for this account. Ensure the account has Antigravity/Cloud Code Assist access and try again.");
+    }
+    return { ...creds, projectId };
+  }
+}
+
+export async function loginAntigravity(ctrl: OAuthController, opts?: { forceAccountSelect?: boolean }): Promise<OAuthCredentials> {
+  return new AntigravityOAuthFlow(ctrl, opts).login();
+}
+
+export async function refreshAntigravityToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+  if (!refreshToken) throw new Error("Antigravity credentials are expired and do not include a refresh token");
+  const payload = await postToken({
+    grant_type: "refresh_token",
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+    refresh_token: refreshToken,
+  }, signal);
+  const creds = credentialsFromPayload(payload, refreshToken);
+  // Re-discover the project on refresh so a newly-onboarded account fills in projectId.
+  const projectId = await discoverAntigravityProject(creds.access, signal).catch(() => undefined);
+  return projectId ? { ...creds, projectId } : creds;
+}

package/src/oauth/health.ts

@@ -0,0 +1,399 @@
+import { getCodexAccountHealthSnapshot, type CodexCooldownSource } from "../codex/routing";
+import { getAnthropicAccountHealthSnapshot } from "./anthropic-routing";
+import { isAccountNeedsReauth } from "../codex/account-runtime-state";
+import { getCodexAccountCredential, listCodexAccountIds } from "../codex/account-store";
+import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { maskAccountId } from "../lib/privacy";
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { loadAuthStore, peekAuthStore, peekOAuthRefreshIntent, readOAuthRefreshIntent } from "./store";
+import type { ProviderAccount } from "./types";
+
+export type OAuthAccountHealth =
+  | { status: "healthy" }
+  | { status: "cooldown"; until: string; reason: "rate_limit" | "quota" }
+  | { status: "reauth_required"; reason: "unauthorized" | "forbidden" | "refresh_failed" }
+  | { status: "warning"; reason: "refresh_conflict" | "metadata_mismatch" | "stale_credentials" };
+
+export type OAuthHealthLabel =
+  | "Healthy"
+  | "Rate limited"
+  | "Quota limited"
+  | "Reauthentication required"
+  | "Refresh failed"
+  | "Metadata mismatch"
+  | "Credential conflict";
+
+/** Shared masked-id fallback when `maskAccountId` returns nullish. */
+export const MASKED_ACCOUNT_FALLBACK = "account-…????";
+
+export type OAuthHealthEntry = {
+  provider: string;
+  accountId: string;
+  health: OAuthAccountHealth;
+  action?: string;
+};
+
+export type OAuthAccountHealthFields = {
+  health: OAuthAccountHealth;
+  healthLabel: OAuthHealthLabel;
+  healthSummary: string;
+  healthAction?: string;
+};
+
+export type CollectOAuthHealthOptions = {
+  /** Skip chmod/backup side effects when reading credential files (doctor/status). */
+  observeOnly?: boolean;
+  /**
+   * When true (default), include Codex entries from this process's in-memory maps.
+   * CLI surfaces should prefer {@link collectOAuthHealthEntriesForCli} which queries the live proxy.
+   */
+  includeLocalCodex?: boolean;
+};
+
+type OAuthWarningReason = "refresh_conflict" | "metadata_mismatch" | "stale_credentials";
+
+export function projectOAuthAccountHealth(input: {
+  needsReauth?: boolean;
+  reauthReason?: "unauthorized" | "forbidden" | "refresh_failed";
+  cooldownUntilMs?: number;
+  cooldownReason?: "rate_limit" | "quota";
+  warningReason?: OAuthWarningReason;
+  now?: number;
+}): OAuthAccountHealth {
+  const now = input.now ?? Date.now();
+  if (input.needsReauth) {
+    return { status: "reauth_required", reason: input.reauthReason ?? "refresh_failed" };
+  }
+  if (
+    typeof input.cooldownUntilMs === "number"
+    && Number.isFinite(input.cooldownUntilMs)
+    && input.cooldownUntilMs > now
+  ) {
+    return {
+      status: "cooldown",
+      until: new Date(input.cooldownUntilMs).toISOString(),
+      reason: input.cooldownReason ?? "quota",
+    };
+  }
+  if (input.warningReason) {
+    return { status: "warning", reason: input.warningReason };
+  }
+  return { status: "healthy" };
+}
+
+/** Codex pool accounts are not a public `ocx login` provider; reauth is dashboard-driven. */
+export const CODEX_REAUTH_ACTION = "reauthenticate via the dashboard Codex account pool";
+
+function actionFor(provider: string, health: OAuthAccountHealth): string | undefined {
+  if (health.status === "reauth_required") {
+    if (provider === "codex") return CODEX_REAUTH_ACTION;
+    return `run \`ocx login ${provider}\``;
+  }
+  if (health.status === "cooldown") {
+    // Keep the transported deadline machine-readable (ISO); presentation layers localize/format.
+    return `wait until ${health.until} or start a new session with another eligible account`;
+  }
+  if (health.status === "warning" && health.reason === "refresh_conflict") {
+    return "re-run `ocx doctor` after ensuring only one proxy process writes the credential store";
+  }
+  return undefined;
+}
+
+export function oauthHealthLabel(health: OAuthAccountHealth): OAuthHealthLabel {
+  switch (health.status) {
+    case "healthy":
+      return "Healthy";
+    case "cooldown":
+      return health.reason === "rate_limit" ? "Rate limited" : "Quota limited";
+    case "reauth_required":
+      return health.reason === "refresh_failed" ? "Refresh failed" : "Reauthentication required";
+    case "warning":
+      switch (health.reason) {
+        case "refresh_conflict":
+          return "Credential conflict";
+        case "metadata_mismatch":
+          return "Metadata mismatch";
+        case "stale_credentials":
+          return "Refresh failed";
+      }
+  }
+}
+
+function displayAccountForHealth(accountId: string): string {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return "main account";
+  return maskAccountId(accountId) ?? MASKED_ACCOUNT_FALLBACK;
+}
+
+export function oauthHealthSummary(
+  provider: string,
+  accountId: string,
+  health: OAuthAccountHealth,
+  action?: string,
+): string {
+  const masked = displayAccountForHealth(accountId);
+  let summary: string;
+  switch (health.status) {
+    case "healthy":
+      summary = `${provider} ${masked}: healthy`;
+      break;
+    case "cooldown": {
+      const why = health.reason === "rate_limit" ? "rate limited" : "quota limited";
+      summary = `${provider} ${masked}: ${why} until ${health.until}. Routing for this account is paused until then.`;
+      break;
+    }
+    case "reauth_required":
+      summary = `${provider} ${masked}: reauthentication required (${health.reason.replaceAll("_", " ")}).`;
+      break;
+    case "warning":
+      summary = `${provider} ${masked}: ${health.reason.replaceAll("_", " ")}.`;
+      break;
+  }
+  if (action && health.status !== "healthy") {
+    return `${summary} Next: ${action}`;
+  }
+  return summary;
+}
+
+export function oauthAccountHealthFields(
+  provider: string,
+  accountId: string,
+  health: OAuthAccountHealth,
+): OAuthAccountHealthFields {
+  const action = actionFor(provider, health);
+  return {
+    health,
+    healthLabel: oauthHealthLabel(health),
+    healthSummary: oauthHealthSummary(provider, accountId, health, action),
+    ...(action ? { healthAction: action } : {}),
+  };
+}
+
+export function projectStoredOAuthAccountHealth(
+  provider: string,
+  account: ProviderAccount,
+  now = Date.now(),
+  opts: { observeOnly?: boolean } = {},
+): OAuthAccountHealth {
+  const anthropicSnap = provider === "anthropic"
+    ? getAnthropicAccountHealthSnapshot(account.id, now)
+    : null;
+  return projectOAuthAccountHealth({
+    needsReauth: account.needsReauth === true,
+    reauthReason: account.needsReauth === true ? "refresh_failed" : undefined,
+    cooldownUntilMs: anthropicSnap?.cooldownUntil,
+    cooldownReason: anthropicSnap?.cooldownSource === "retry-after" ? "rate_limit" : anthropicSnap ? "quota" : undefined,
+    warningReason: detectOAuthWarning(provider, account, opts.observeOnly === true, now),
+    now,
+  });
+}
+
+export function projectCodexAccountHealth(input: {
+  accountId: string;
+  needsReauth: boolean;
+  now?: number;
+}): OAuthAccountHealth {
+  const now = input.now ?? Date.now();
+  const snap = getCodexAccountHealthSnapshot(input.accountId, now);
+  return projectOAuthAccountHealth({
+    needsReauth: input.needsReauth,
+    reauthReason: input.needsReauth ? "refresh_failed" : undefined,
+    cooldownUntilMs: snap?.cooldownUntil,
+    cooldownReason: cooldownReasonFromSource(snap?.cooldownSource),
+    now,
+  });
+}
+
+/**
+ * Incomplete credentials warning. Kiro may intentionally store an empty refresh
+ * when authenticated via KIRO_ACCESS_TOKEN or a pasted access-only token, as long
+ * as the access token is still unexpired.
+ */
+export function detectOAuthWarning(
+  provider: string,
+  account: ProviderAccount,
+  observeOnly = false,
+  now = Date.now(),
+): OAuthWarningReason | undefined {
+  const intent = observeOnly
+    ? peekOAuthRefreshIntent(provider, account.id)
+    : readOAuthRefreshIntent(provider, account.id);
+  if (intent?.uncertain) return "refresh_conflict";
+  const cred = account.credential;
+  if (!cred?.access) return "stale_credentials";
+  if (!cred.refresh) {
+    if (
+      provider === "kiro"
+      && typeof cred.expires === "number"
+      && Number.isFinite(cred.expires)
+      && cred.expires > now
+    ) {
+      return undefined;
+    }
+    return "stale_credentials";
+  }
+  return undefined;
+}
+
+function cooldownReasonFromSource(
+  source: CodexCooldownSource | undefined,
+): "rate_limit" | "quota" | undefined {
+  if (!source) return undefined;
+  return source === "retry-after" ? "rate_limit" : "quota";
+}
+
+function pushEntry(
+  entries: OAuthHealthEntry[],
+  provider: string,
+  accountId: string,
+  health: OAuthAccountHealth,
+): void {
+  const action = actionFor(provider, health);
+  entries.push({
+    provider,
+    accountId,
+    health,
+    ...(action ? { action } : {}),
+  });
+}
+
+function collectLocalCodexEntries(now: number): OAuthHealthEntry[] {
+  const entries: OAuthHealthEntry[] = [];
+  const codexIds = new Set(listCodexAccountIds());
+  codexIds.add(MAIN_CODEX_ACCOUNT_ID);
+  for (const accountId of codexIds) {
+    const snap = getCodexAccountHealthSnapshot(accountId, now);
+    const needsReauth = isAccountNeedsReauth(accountId);
+    const hasPoolCredential = accountId !== MAIN_CODEX_ACCOUNT_ID && getCodexAccountCredential(accountId) !== null;
+    if (!hasPoolCredential && !needsReauth && !snap) continue;
+
+    const health = projectOAuthAccountHealth({
+      needsReauth,
+      reauthReason: needsReauth ? "refresh_failed" : undefined,
+      cooldownUntilMs: snap?.cooldownUntil,
+      cooldownReason: cooldownReasonFromSource(snap?.cooldownSource),
+      now,
+    });
+    pushEntry(entries, "codex", accountId, health);
+  }
+  return entries;
+}
+
+export function collectOAuthHealthEntries(
+  now = Date.now(),
+  opts: CollectOAuthHealthOptions = {},
+): OAuthHealthEntry[] {
+  const observeOnly = opts.observeOnly === true;
+  const includeLocalCodex = opts.includeLocalCodex !== false;
+  const entries: OAuthHealthEntry[] = [];
+  const store = observeOnly ? peekAuthStore() : loadAuthStore();
+
+  for (const [provider, set] of Object.entries(store)) {
+    for (const account of set.accounts) {
+      const health = projectStoredOAuthAccountHealth(provider, account, now, { observeOnly });
+      pushEntry(entries, provider, account.id, health);
+    }
+  }
+
+  if (includeLocalCodex) {
+    for (const entry of collectLocalCodexEntries(now)) entries.push(entry);
+  }
+
+  return entries;
+}
+
+type ProxyCodexAccountHealth = {
+  id: string;
+  health?: OAuthAccountHealth;
+  needsReauth?: boolean;
+};
+
+const KNOWN_HEALTH_STATUSES = new Set(["healthy", "cooldown", "reauth_required", "warning"]);
+
+function coerceRemoteAccountHealth(
+  account: ProxyCodexAccountHealth,
+): OAuthAccountHealth {
+  const raw = account.health;
+  if (raw && typeof raw === "object" && KNOWN_HEALTH_STATUSES.has((raw as { status?: string }).status ?? "")) {
+    return raw;
+  }
+  return projectOAuthAccountHealth({ needsReauth: account.needsReauth === true });
+}
+
+type LiveProxyCodexHealthResult = {
+  source: CodexHealthSource;
+  entries: OAuthHealthEntry[] | null;
+};
+
+async function fetchCodexHealthFromLiveProxy(
+  fetchImpl: typeof fetch = fetch,
+  findLiveProxyImpl: typeof findLiveProxy = findLiveProxy,
+): Promise<LiveProxyCodexHealthResult> {
+  const live = await findLiveProxyImpl();
+  if (!live) return { source: "unavailable", entries: null };
+  // This is a management-plane endpoint. A data-plane service token is intentionally not
+  // interchangeable with the admin credential even on loopback.
+  const token = configuredAdminToken();
+  const headers: Record<string, string> = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  try {
+    const res = await fetchImpl(
+      `http://${probeHostname(live.hostname)}:${live.port}/api/codex-auth/accounts`,
+      { headers, signal: AbortSignal.timeout(4000) },
+    );
+    if (res.status === 401 || res.status === 403) {
+      return { source: "management-auth-failed", entries: null };
+    }
+    if (!res.ok) return { source: "management-api-unavailable", entries: null };
+    const json = await res.json() as { accounts?: ProxyCodexAccountHealth[] };
+    if (!Array.isArray(json.accounts)) return { source: "management-api-unavailable", entries: null };
+    const entries: OAuthHealthEntry[] = [];
+    for (const account of json.accounts) {
+      if (!account?.id || typeof account.id !== "string") continue;
+      pushEntry(entries, "codex", account.id, coerceRemoteAccountHealth(account));
+    }
+    return { source: "management-api", entries };
+  } catch {
+    return { source: "management-api-unavailable", entries: null };
+  }
+}
+
+/** How CLI/doctor obtained Codex cooldown/reauth (proxy memory only lives in the proxy). */
+export type CodexHealthSource =
+  | "management-api"
+  | "unavailable"
+  | "management-auth-failed"
+  | "management-api-unavailable";
+
+export type OAuthCliHealthReport = {
+  entries: OAuthHealthEntry[];
+  codexHealthSource: CodexHealthSource;
+};
+
+/** Shown by `ocx status` / `ocx doctor` when the proxy management API is unreachable. */
+export const CODEX_HEALTH_UNAVAILABLE_NOTE =
+  "Codex health: unavailable (proxy not running; live cooldown/reauth requires the management API)";
+export const CODEX_HEALTH_AUTH_FAILED_NOTE =
+  "Codex health: unavailable (proxy running; management authentication failed)";
+export const CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE =
+  "Codex health: unavailable (proxy running; management API did not return account health)";
+
+/**
+ * CLI/doctor collector: observe-only OAuth store reads, and Codex health only from the
+ * running proxy management API. Never reads proxy process-local maps from the CLI process.
+ */
+export async function collectOAuthHealthEntriesForCli(
+  now = Date.now(),
+  deps: {
+    fetchImpl?: typeof fetch;
+    findLiveProxyImpl?: typeof findLiveProxy;
+  } = {},
+): Promise<OAuthCliHealthReport> {
+  const entries = collectOAuthHealthEntries(now, { observeOnly: true, includeLocalCodex: false });
+  const remote = await fetchCodexHealthFromLiveProxy(deps.fetchImpl, deps.findLiveProxyImpl);
+  if (remote.entries) {
+    for (const entry of remote.entries) entries.push(entry);
+    return { entries, codexHealthSource: "management-api" };
+  }
+  return { entries, codexHealthSource: remote.source };
+}