fix(cli): authenticate Codex health with admin token

Author: Ingwannu

src/cli/doctor.ts

@@ -149,6 +149,18 @@ export async function collectOAuthDoctorChecks(
       message:
         "Codex account health unavailable (proxy not running). Action: start the proxy and re-run `ocx doctor` to inspect live cooldown/reauth",
     });
+  } else if (report.codexHealthSource === "management-auth-failed") {
+    checks.push({
+      level: "WARN",
+      message:
+        "Codex account health unavailable (proxy running; management authentication failed). Action: verify the admin token configuration, restart the proxy, and re-run `ocx doctor`",
+    });
+  } else if (report.codexHealthSource === "management-api-unavailable") {
+    checks.push({
+      level: "WARN",
+      message:
+        "Codex account health unavailable (proxy running; management API response failed). Action: inspect the proxy service log, restart the proxy if needed, and re-run `ocx doctor`",
+    });
   }
   for (const entry of report.entries) {
     if (entry.health.status === "healthy") continue;

src/cli/status-oauth.ts

@@ -1,5 +1,7 @@
 import { maskAccountId } from "../lib/privacy";
 import {
+  CODEX_HEALTH_AUTH_FAILED_NOTE,
+  CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE,
   CODEX_HEALTH_UNAVAILABLE_NOTE,
   MASKED_ACCOUNT_FALLBACK,
   type OAuthAccountHealth,
@@ -59,8 +61,16 @@ export function formatOAuthHealthForStatus(
     : input;
 
   const parts: string[] = [];
-  if (report.codexHealthSource === "unavailable") {
-    parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+  switch (report.codexHealthSource) {
+    case "unavailable":
+      parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+      break;
+    case "management-auth-failed":
+      parts.push(CODEX_HEALTH_AUTH_FAILED_NOTE);
+      break;
+    case "management-api-unavailable":
+      parts.push(CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE);
+      break;
   }
   const oauthBlock = formatEntryBlock(report.entries);
   if (oauthBlock) parts.push(oauthBlock);

src/oauth/health.ts

@@ -3,8 +3,8 @@ 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 { loadServiceTokenFromFile } from "../lib/service-secrets";
 import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import { loadAuthStore, peekAuthStore, peekOAuthRefreshIntent, readOAuthRefreshIntent } from "./store";
 import type { ProviderAccount } from "./types";
@@ -320,36 +320,50 @@ function coerceRemoteAccountHealth(
   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<OAuthHealthEntry[] | null> {
+): Promise<LiveProxyCodexHealthResult> {
   const live = await findLiveProxyImpl();
-  if (!live) return null;
-  const token = process.env.OPENCODEX_API_AUTH_TOKEN ?? loadServiceTokenFromFile(process.env);
+  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.ok) return null;
+    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 null;
+    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 entries;
+    return { source: "management-api", entries };
   } catch {
-    return null;
+    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";
+export type CodexHealthSource =
+  | "management-api"
+  | "unavailable"
+  | "management-auth-failed"
+  | "management-api-unavailable";
 
 export type OAuthCliHealthReport = {
   entries: OAuthHealthEntry[];
@@ -359,6 +373,10 @@ export type OAuthCliHealthReport = {
 /** 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
@@ -373,9 +391,9 @@ export async function collectOAuthHealthEntriesForCli(
 ): Promise<OAuthCliHealthReport> {
   const entries = collectOAuthHealthEntries(now, { observeOnly: true, includeLocalCodex: false });
   const remote = await fetchCodexHealthFromLiveProxy(deps.fetchImpl, deps.findLiveProxyImpl);
-  if (remote) {
-    for (const entry of remote) entries.push(entry);
+  if (remote.entries) {
+    for (const entry of remote.entries) entries.push(entry);
     return { entries, codexHealthSource: "management-api" };
   }
-  return { entries, codexHealthSource: "unavailable" };
+  return { entries, codexHealthSource: remote.source };
 }

src/oauth/index.ts

@@ -20,6 +20,8 @@ import { resolveProviderTransport } from "../providers/xai-transport";
 import { detectClaudeCodeToken, detectGrokCliToken, hasComparableGrokIdentity, isSameGrokIdentity, shouldAdoptGrokGeneration } from "./local-token-detect";
 import { logOAuthEvent } from "./log";
 export {
+  CODEX_HEALTH_AUTH_FAILED_NOTE,
+  CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE,
   CODEX_HEALTH_UNAVAILABLE_NOTE,
   MASKED_ACCOUNT_FALLBACK,
   collectOAuthHealthEntries,

structure/05_gui-and-management-api.md

@@ -23,6 +23,10 @@ OpenCodex uses three mutually exclusive admission credential classes:
 The service token file remains a delivery mechanism for the data-plane environment token; it is not
 a fourth credential class. A management credential that equals any configured data-plane credential
 does not enable management access. The data plane may continue to start, but `/api/*` remains closed.
+CLI health collection follows the same boundary: `ocx status` and `ocx doctor` use the configured
+management credential for `/api/codex-auth/accounts`, never the service/data-plane token. Their
+output distinguishes a missing proxy, rejected management authentication, and an unexpected
+management response so a reachable `401` cannot be reported as "proxy not running."
 
 Management authentication never has a loopback bypass. If no management credential is available, or
 management token creation, validation, or permission hardening fails, every `/api/*` request returns

tests/cli-status-oauth-health.test.ts

@@ -76,6 +76,16 @@ describe("formatOAuthHealthForStatus", () => {
     expect(text).toContain("Codex health: unavailable");
     expect(text).toContain("management API");
   });
+
+  test("does not call an authentication failure a stopped proxy", () => {
+    const text = formatOAuthHealthForStatus({
+      entries: [],
+      codexHealthSource: "management-auth-failed",
+    });
+    expect(text).toContain("proxy running");
+    expect(text).toContain("management authentication failed");
+    expect(text).not.toContain("proxy not running");
+  });
 });
 
 describe("collectOAuthHealthEntries via status formatter", () => {

tests/doctor-oauth.test.ts

@@ -75,6 +75,19 @@ describe("collectOAuthDoctorChecks", () => {
     expect(warn!.message).toContain("start the proxy");
   });
 
+  test("labels management auth failure without claiming the proxy is down", async () => {
+    const checks = await collectOAuthDoctorChecks(Date.now(), {
+      findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),
+      fetchImpl: async () => new Response("unauthorized", { status: 401 }),
+    });
+    const warn = checks.find((c) => c.level === "WARN" && c.message.includes("Codex account health unavailable"));
+    expect(warn).toBeTruthy();
+    expect(warn!.message).toContain("proxy running");
+    expect(warn!.message).toContain("management authentication failed");
+    expect(warn!.message).not.toContain("proxy not running");
+    expect(warn!.message).toContain("Action:");
+  });
+
   test("Codex needsReauth WARN comes from management API, not CLI process maps", async () => {
     const checks = await collectOAuthDoctorChecks(Date.now(), {
       findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),

tests/oauth-health.test.ts

@@ -25,6 +25,7 @@ import { formatOAuthHealthForStatus } from "../src/cli/status-oauth";
 
 const origHome = process.env.HOME;
 const origOcxHome = process.env.OPENCODEX_HOME;
+const origAdminToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
 let tmp: string;
 
 beforeEach(() => {
@@ -40,6 +41,8 @@ afterEach(() => {
   else process.env.HOME = origHome;
   if (origOcxHome === undefined) delete process.env.OPENCODEX_HOME;
   else process.env.OPENCODEX_HOME = origOcxHome;
+  if (origAdminToken === undefined) delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  else process.env.OPENCODEX_ADMIN_AUTH_TOKEN = origAdminToken;
   clearCodexUpstreamHealth();
   clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
   rmSync(tmp, { recursive: true, force: true });
@@ -170,10 +173,13 @@ describe("collectOAuthHealthEntries", () => {
 describe("collectOAuthHealthEntriesForCli", () => {
   test("uses management API Codex health and does not read CLI process maps", async () => {
     markCodexAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+    process.env.OPENCODEX_ADMIN_AUTH_TOKEN = "ocx-admin-health-test";
+    let authorization: string | null = null;
     const report = await collectOAuthHealthEntriesForCli(Date.now(), {
       findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),
-      fetchImpl: async () =>
-        new Response(JSON.stringify({
+      fetchImpl: async (_input, init) => {
+        authorization = new Headers(init?.headers).get("authorization");
+        return new Response(JSON.stringify({
           accounts: [{
             id: "proxy-codex-acct",
             health: {
@@ -182,8 +188,10 @@ describe("collectOAuthHealthEntriesForCli", () => {
               reason: "rate_limit",
             },
           }],
-        }), { status: 200 }),
+        }), { status: 200 });
+      },
     });
+    expect(authorization).toBe("Bearer ocx-admin-health-test");
     expect(report.codexHealthSource).toBe("management-api");
     expect(report.entries.some(e => e.accountId === MAIN_CODEX_ACCOUNT_ID)).toBe(false);
     const remote = report.entries.find(e => e.accountId === "proxy-codex-acct");
@@ -207,6 +215,29 @@ describe("collectOAuthHealthEntriesForCli", () => {
     expect(text).not.toContain(MAIN_CODEX_ACCOUNT_ID);
   });
 
+  test("distinguishes management authentication failure from a stopped proxy", async () => {
+    const report = await collectOAuthHealthEntriesForCli(Date.now(), {
+      findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),
+      fetchImpl: async () => new Response("unauthorized", { status: 401 }),
+    });
+    expect(report.codexHealthSource).toBe("management-auth-failed");
+    const text = formatOAuthHealthForStatus(report);
+    expect(text).toContain("proxy running");
+    expect(text).toContain("management authentication failed");
+    expect(text).not.toContain("proxy not running");
+  });
+
+  test("distinguishes an invalid management response from a stopped proxy", async () => {
+    const report = await collectOAuthHealthEntriesForCli(Date.now(), {
+      findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),
+      fetchImpl: async () => new Response("upstream error", { status: 500 }),
+    });
+    expect(report.codexHealthSource).toBe("management-api-unavailable");
+    const text = formatOAuthHealthForStatus(report);
+    expect(text).toContain("proxy running");
+    expect(text).toContain("management API did not return account health");
+  });
+
   test("malformed remote health is re-derived instead of rendering undefined", async () => {
     const report = await collectOAuthHealthEntriesForCli(Date.now(), {
       findLiveProxyImpl: async () => ({ hostname: "127.0.0.1", port: 19191, pid: null }),