feat(models): add oauth auth health

src/agents/auth-health.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildAuthHealthSummary,
+  DEFAULT_OAUTH_WARN_MS,
+} from "./auth-health.js";
+
+describe("buildAuthHealthSummary", () => {
+  const now = 1_700_000_000_000;
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("classifies OAuth and API key profiles", () => {
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    const store = {
+      version: 1,
+      profiles: {
+        "anthropic:ok": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now + DEFAULT_OAUTH_WARN_MS + 60_000,
+        },
+        "anthropic:expiring": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now + 10_000,
+        },
+        "anthropic:expired": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now - 10_000,
+        },
+        "anthropic:api": {
+          type: "api_key" as const,
+          provider: "anthropic",
+          key: "sk-ant-api",
+        },
+      },
+    };
+
+    const summary = buildAuthHealthSummary({
+      store,
+      warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+    });
+
+    const statuses = Object.fromEntries(
+      summary.profiles.map((profile) => [profile.profileId, profile.status]),
+    );
+
+    expect(statuses["anthropic:ok"]).toBe("ok");
+    expect(statuses["anthropic:expiring"]).toBe("expiring");
+    expect(statuses["anthropic:expired"]).toBe("expired");
+    expect(statuses["anthropic:api"]).toBe("static");
+
+    const provider = summary.providers.find(
+      (entry) => entry.provider === "anthropic",
+    );
+    expect(provider?.status).toBe("expired");
+  });
+});

src/agents/auth-health.ts

@@ -0,0 +1,227 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import {
+  type AuthProfileCredential,
+  type AuthProfileStore,
+  CLAUDE_CLI_PROFILE_ID,
+  CODEX_CLI_PROFILE_ID,
+  resolveAuthProfileDisplayLabel,
+} from "./auth-profiles.js";
+
+export type AuthProfileSource = "claude-cli" | "codex-cli" | "store";
+
+export type AuthProfileHealthStatus =
+  | "ok"
+  | "expiring"
+  | "expired"
+  | "missing"
+  | "static";
+
+export type AuthProfileHealth = {
+  profileId: string;
+  provider: string;
+  type: "oauth" | "api_key";
+  status: AuthProfileHealthStatus;
+  expiresAt?: number;
+  remainingMs?: number;
+  source: AuthProfileSource;
+  label: string;
+};
+
+export type AuthProviderHealthStatus =
+  | "ok"
+  | "expiring"
+  | "expired"
+  | "missing"
+  | "static";
+
+export type AuthProviderHealth = {
+  provider: string;
+  status: AuthProviderHealthStatus;
+  expiresAt?: number;
+  remainingMs?: number;
+  profiles: AuthProfileHealth[];
+};
+
+export type AuthHealthSummary = {
+  now: number;
+  warnAfterMs: number;
+  profiles: AuthProfileHealth[];
+  providers: AuthProviderHealth[];
+};
+
+export const DEFAULT_OAUTH_WARN_MS = 24 * 60 * 60 * 1000;
+
+export function resolveAuthProfileSource(profileId: string): AuthProfileSource {
+  if (profileId === CLAUDE_CLI_PROFILE_ID) return "claude-cli";
+  if (profileId === CODEX_CLI_PROFILE_ID) return "codex-cli";
+  return "store";
+}
+
+export function formatRemainingShort(remainingMs?: number): string {
+  if (remainingMs === undefined || Number.isNaN(remainingMs)) return "unknown";
+  if (remainingMs <= 0) return "0m";
+  const minutes = Math.max(1, Math.round(remainingMs / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours}h`;
+  const days = Math.round(hours / 24);
+  return `${days}d`;
+}
+
+function resolveOAuthStatus(
+  expiresAt: number | undefined,
+  now: number,
+  warnAfterMs: number,
+): { status: AuthProfileHealthStatus; remainingMs?: number } {
+  if (!expiresAt || !Number.isFinite(expiresAt) || expiresAt <= 0) {
+    return { status: "missing" };
+  }
+  const remainingMs = expiresAt - now;
+  if (remainingMs <= 0) {
+    return { status: "expired", remainingMs };
+  }
+  if (remainingMs <= warnAfterMs) {
+    return { status: "expiring", remainingMs };
+  }
+  return { status: "ok", remainingMs };
+}
+
+function buildProfileHealth(params: {
+  profileId: string;
+  credential: AuthProfileCredential;
+  store: AuthProfileStore;
+  cfg?: ClawdbotConfig;
+  now: number;
+  warnAfterMs: number;
+}): AuthProfileHealth {
+  const { profileId, credential, store, cfg, now, warnAfterMs } = params;
+  const label = resolveAuthProfileDisplayLabel({ cfg, store, profileId });
+  const source = resolveAuthProfileSource(profileId);
+
+  if (credential.type === "api_key") {
+    return {
+      profileId,
+      provider: credential.provider,
+      type: "api_key",
+      status: "static",
+      source,
+      label,
+    };
+  }
+
+  const { status, remainingMs } = resolveOAuthStatus(
+    credential.expires,
+    now,
+    warnAfterMs,
+  );
+  return {
+    profileId,
+    provider: credential.provider,
+    type: "oauth",
+    status,
+    expiresAt: credential.expires,
+    remainingMs,
+    source,
+    label,
+  };
+}
+
+export function buildAuthHealthSummary(params: {
+  store: AuthProfileStore;
+  cfg?: ClawdbotConfig;
+  warnAfterMs?: number;
+  providers?: string[];
+}): AuthHealthSummary {
+  const now = Date.now();
+  const warnAfterMs = params.warnAfterMs ?? DEFAULT_OAUTH_WARN_MS;
+  const providerFilter = params.providers
+    ? new Set(params.providers.map((p) => p.trim()).filter(Boolean))
+    : null;
+
+  const profiles = Object.entries(params.store.profiles)
+    .filter(([_, cred]) =>
+      providerFilter ? providerFilter.has(cred.provider) : true,
+    )
+    .map(([profileId, credential]) =>
+      buildProfileHealth({
+        profileId,
+        credential,
+        store: params.store,
+        cfg: params.cfg,
+        now,
+        warnAfterMs,
+      }),
+    )
+    .sort((a, b) => {
+      if (a.provider !== b.provider) {
+        return a.provider.localeCompare(b.provider);
+      }
+      return a.profileId.localeCompare(b.profileId);
+    });
+
+  const providersMap = new Map<string, AuthProviderHealth>();
+  for (const profile of profiles) {
+    const existing = providersMap.get(profile.provider);
+    if (!existing) {
+      providersMap.set(profile.provider, {
+        provider: profile.provider,
+        status: "missing",
+        profiles: [profile],
+      });
+    } else {
+      existing.profiles.push(profile);
+    }
+  }
+
+  if (providerFilter) {
+    for (const provider of providerFilter) {
+      if (!providersMap.has(provider)) {
+        providersMap.set(provider, {
+          provider,
+          status: "missing",
+          profiles: [],
+        });
+      }
+    }
+  }
+
+  for (const provider of providersMap.values()) {
+    if (provider.profiles.length === 0) {
+      provider.status = "missing";
+      continue;
+    }
+
+    const oauthProfiles = provider.profiles.filter((p) => p.type === "oauth");
+    const apiKeyProfiles = provider.profiles.filter(
+      (p) => p.type === "api_key",
+    );
+
+    if (oauthProfiles.length === 0) {
+      provider.status = apiKeyProfiles.length > 0 ? "static" : "missing";
+      continue;
+    }
+
+    const expiryCandidates = oauthProfiles
+      .map((p) => p.expiresAt)
+      .filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+    if (expiryCandidates.length > 0) {
+      provider.expiresAt = Math.min(...expiryCandidates);
+      provider.remainingMs = provider.expiresAt - now;
+    }
+
+    const statuses = oauthProfiles.map((p) => p.status);
+    if (statuses.includes("expired") || statuses.includes("missing")) {
+      provider.status = "expired";
+    } else if (statuses.includes("expiring")) {
+      provider.status = "expiring";
+    } else {
+      provider.status = "ok";
+    }
+  }
+
+  const providers = Array.from(providersMap.values()).sort((a, b) =>
+    a.provider.localeCompare(b.provider),
+  );
+
+  return { now, warnAfterMs, profiles, providers };
+}

src/cli/models-cli.ts

@@ -57,6 +57,11 @@ export function registerModelsCli(program: Command) {
     .description("Show configured model state")
     .option("--json", "Output JSON", false)
     .option("--plain", "Plain output", false)
+    .option(
+      "--check",
+      "Exit non-zero if auth is expiring/expired (1=expired/missing, 2=expiring)",
+      false,
+    )
     .action(async (opts) => {
       try {
         await modelsStatusCommand(opts, defaultRuntime);

src/commands/doctor-auth.ts

@@ -1,8 +1,16 @@
 import { note } from "@clack/prompts";
 
 import {
+  buildAuthHealthSummary,
+  DEFAULT_OAUTH_WARN_MS,
+  formatRemainingShort,
+} from "../agents/auth-health.js";
+import {
+  CLAUDE_CLI_PROFILE_ID,
+  CODEX_CLI_PROFILE_ID,
   ensureAuthProfileStore,
   repairOAuthProfileIdMismatch,
+  resolveApiKeyForProfile,
 } from "../agents/auth-profiles.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import type { DoctorPrompter } from "./doctor-prompter.js";
@@ -28,3 +36,114 @@ export async function maybeRepairAnthropicOAuthProfileId(
   if (!apply) return cfg;
   return repair.config;
 }
+
+type AuthIssue = {
+  profileId: string;
+  provider: string;
+  status: string;
+  remainingMs?: number;
+};
+
+function formatAuthIssueHint(issue: AuthIssue): string | null {
+  if (
+    issue.provider === "anthropic" &&
+    issue.profileId === CLAUDE_CLI_PROFILE_ID
+  ) {
+    return "Run `claude setup-token` on the gateway host.";
+  }
+  if (
+    issue.provider === "openai-codex" &&
+    issue.profileId === CODEX_CLI_PROFILE_ID
+  ) {
+    return "Run `codex login` (or `clawdbot configure` → OpenAI Codex OAuth).";
+  }
+  return "Re-auth via `clawdbot configure` or `clawdbot onboard`.";
+}
+
+function formatAuthIssueLine(issue: AuthIssue): string {
+  const remaining =
+    issue.remainingMs !== undefined
+      ? ` (${formatRemainingShort(issue.remainingMs)})`
+      : "";
+  const hint = formatAuthIssueHint(issue);
+  return `- ${issue.profileId}: ${issue.status}${remaining}${hint ? ` — ${hint}` : ""}`;
+}
+
+export async function noteAuthProfileHealth(params: {
+  cfg: ClawdbotConfig;
+  prompter: DoctorPrompter;
+  allowKeychainPrompt: boolean;
+}): Promise<void> {
+  const store = ensureAuthProfileStore(undefined, {
+    allowKeychainPrompt: params.allowKeychainPrompt,
+  });
+  let summary = buildAuthHealthSummary({
+    store,
+    cfg: params.cfg,
+    warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+  });
+
+  const findIssues = () =>
+    summary.profiles.filter(
+      (profile) =>
+        profile.type === "oauth" &&
+        (profile.status === "expired" ||
+          profile.status === "expiring" ||
+          profile.status === "missing"),
+    );
+
+  let issues = findIssues();
+  if (issues.length === 0) return;
+
+  const shouldRefresh = await params.prompter.confirmRepair({
+    message: "Refresh expiring OAuth tokens now?",
+    initialValue: true,
+  });
+
+  if (shouldRefresh) {
+    const refreshTargets = issues.filter((issue) =>
+      ["expired", "expiring", "missing"].includes(issue.status),
+    );
+    const errors: string[] = [];
+    for (const profile of refreshTargets) {
+      try {
+        await resolveApiKeyForProfile({
+          cfg: params.cfg,
+          store,
+          profileId: profile.profileId,
+        });
+      } catch (err) {
+        errors.push(
+          `- ${profile.profileId}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    if (errors.length > 0) {
+      note(errors.join("\n"), "OAuth refresh errors");
+    }
+    summary = buildAuthHealthSummary({
+      store: ensureAuthProfileStore(undefined, {
+        allowKeychainPrompt: false,
+      }),
+      cfg: params.cfg,
+      warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+    });
+    issues = findIssues();
+  }
+
+  if (issues.length > 0) {
+    note(
+      issues
+        .map((issue) =>
+          formatAuthIssueLine({
+            profileId: issue.profileId,
+            provider: issue.provider,
+            status: issue.status,
+            remainingMs: issue.remainingMs,
+          }),
+        )
+        .join("\n"),
+      "Model auth",
+    );
+  }
+}

src/commands/doctor.ts

@@ -26,7 +26,10 @@ import {
   GATEWAY_DAEMON_RUNTIME_OPTIONS,
   type GatewayDaemonRuntime,
 } from "./daemon-runtime.js";
-import { maybeRepairAnthropicOAuthProfileId } from "./doctor-auth.js";
+import {
+  maybeRepairAnthropicOAuthProfileId,
+  noteAuthProfileHealth,
+} from "./doctor-auth.js";
 import {
   buildGatewayRuntimeHints,
   formatGatewayRuntimeSummary,
@@ -124,6 +127,12 @@ export async function doctorCommand(
   }
 
   cfg = await maybeRepairAnthropicOAuthProfileId(cfg, prompter);
+  await noteAuthProfileHealth({
+    cfg,
+    prompter,
+    allowKeychainPrompt:
+      options.nonInteractive !== true && Boolean(process.stdin.isTTY),
+  });
   const gatewayDetails = buildGatewayConnectionDetails({ config: cfg });
   if (gatewayDetails.remoteFallbackNote) {
     note(gatewayDetails.remoteFallbackNote, "Gateway");

src/commands/models/list.status.test.ts

@@ -77,12 +77,17 @@ vi.mock("../../agents/agent-paths.js", () => ({
   resolveClawdbotAgentDir: mocks.resolveClawdbotAgentDir,
 }));
 
-vi.mock("../../agents/auth-profiles.js", () => ({
-  ensureAuthProfileStore: mocks.ensureAuthProfileStore,
-  listProfilesForProvider: mocks.listProfilesForProvider,
-  resolveAuthProfileDisplayLabel: mocks.resolveAuthProfileDisplayLabel,
-  resolveAuthStorePathForDisplay: mocks.resolveAuthStorePathForDisplay,
-}));
+vi.mock("../../agents/auth-profiles.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../../agents/auth-profiles.js")>();
+  return {
+    ...actual,
+    ensureAuthProfileStore: mocks.ensureAuthProfileStore,
+    listProfilesForProvider: mocks.listProfilesForProvider,
+    resolveAuthProfileDisplayLabel: mocks.resolveAuthProfileDisplayLabel,
+    resolveAuthStorePathForDisplay: mocks.resolveAuthStorePathForDisplay,
+  };
+});
 
 vi.mock("../../agents/model-auth.js", () => ({
   resolveEnvApiKey: mocks.resolveEnvApiKey,
@@ -126,6 +131,9 @@ describe("modelsStatusCommand auth overview", () => {
     expect(payload.auth.shellEnvFallback.appliedKeys).toContain(
       "OPENAI_API_KEY",
     );
+    expect(payload.auth.missingProvidersInUse).toEqual([]);
+    expect(payload.auth.oauth.warnAfterMs).toBeGreaterThan(0);
+    expect(payload.auth.oauth.profiles.length).toBeGreaterThan(0);
 
     const providers = payload.auth.providers as Array<{
       provider: string;
@@ -152,4 +160,27 @@ describe("modelsStatusCommand auth overview", () => {
       ),
     ).toBe(true);
   });
+
+  it("exits non-zero when auth is missing", async () => {
+    const originalProfiles = { ...mocks.store.profiles };
+    mocks.store.profiles = {};
+    const localRuntime = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: vi.fn(),
+    };
+    const originalEnvImpl = mocks.resolveEnvApiKey.getMockImplementation();
+    mocks.resolveEnvApiKey.mockImplementation(() => null);
+
+    try {
+      await modelsStatusCommand(
+        { check: true, plain: true },
+        localRuntime as never,
+      );
+      expect(localRuntime.exit).toHaveBeenCalledWith(1);
+    } finally {
+      mocks.store.profiles = originalProfiles;
+      mocks.resolveEnvApiKey.mockImplementation(originalEnvImpl);
+    }
+  });
 });

src/commands/models/list.ts

@@ -7,6 +7,11 @@ import {
 } from "@mariozechner/pi-coding-agent";
 
 import { resolveClawdbotAgentDir } from "../../agents/agent-paths.js";
+import {
+  buildAuthHealthSummary,
+  DEFAULT_OAUTH_WARN_MS,
+  formatRemainingShort,
+} from "../../agents/auth-health.js";
 import {
   type AuthProfileStore,
   ensureAuthProfileStore,
@@ -599,7 +604,7 @@ export async function modelsListCommand(
 }
 
 export async function modelsStatusCommand(
-  opts: { json?: boolean; plain?: boolean },
+  opts: { json?: boolean; plain?: boolean; check?: boolean },
   runtime: RuntimeEnv,
 ) {
   ensureFlagCompatibility(opts);
@@ -656,6 +661,7 @@ export async function modelsStatusCommand(
       .filter(Boolean),
   );
   const providersFromModels = new Set<string>();
+  const providersInUse = new Set<string>();
   for (const raw of [
     defaultLabel,
     ...fallbacks,
@@ -666,6 +672,15 @@ export async function modelsStatusCommand(
     const parsed = parseModelRef(String(raw ?? ""), DEFAULT_PROVIDER);
     if (parsed?.provider) providersFromModels.add(parsed.provider);
   }
+  for (const raw of [
+    defaultLabel,
+    ...fallbacks,
+    imageModel,
+    ...imageFallbacks,
+  ]) {
+    const parsed = parseModelRef(String(raw ?? ""), DEFAULT_PROVIDER);
+    if (parsed?.provider) providersInUse.add(parsed.provider);
+  }
 
   const providersFromEnv = new Set<string>();
   // Keep in sync with resolveEnvApiKey() mappings (we want visibility even when
@@ -715,6 +730,12 @@ export async function modelsStatusCommand(
         Boolean(entry.modelsJson);
       return hasAny;
     });
+  const providerAuthMap = new Map(
+    providerAuth.map((entry) => [entry.provider, entry]),
+  );
+  const missingProvidersInUse = Array.from(providersInUse)
+    .filter((provider) => !providerAuthMap.has(provider))
+    .sort((a, b) => a.localeCompare(b));
 
   const providersWithOauth = providerAuth
     .filter(
@@ -726,6 +747,29 @@ export async function modelsStatusCommand(
       return `${entry.provider} (${count})`;
     });
 
+  const authHealth = buildAuthHealthSummary({
+    store,
+    cfg,
+    warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+    providers,
+  });
+  const oauthProfiles = authHealth.profiles.filter(
+    (profile) => profile.type === "oauth",
+  );
+
+  const checkStatus = (() => {
+    const hasExpiredOrMissing =
+      oauthProfiles.some((profile) =>
+        ["expired", "missing"].includes(profile.status),
+      ) || missingProvidersInUse.length > 0;
+    const hasExpiring = oauthProfiles.some(
+      (profile) => profile.status === "expiring",
+    );
+    if (hasExpiredOrMissing) return 1;
+    if (hasExpiring) return 2;
+    return 0;
+  })();
+
   if (opts.json) {
     runtime.log(
       JSON.stringify(
@@ -746,18 +790,30 @@ export async function modelsStatusCommand(
               appliedKeys: applied,
             },
             providersWithOAuth: providersWithOauth,
+            missingProvidersInUse,
             providers: providerAuth,
+            oauth: {
+              warnAfterMs: authHealth.warnAfterMs,
+              profiles: authHealth.profiles,
+              providers: authHealth.providers,
+            },
           },
         },
         null,
         2,
       ),
     );
+    if (opts.check) {
+      runtime.exit(checkStatus);
+    }
     return;
   }
 
   if (opts.plain) {
     runtime.log(resolvedLabel);
+    if (opts.check) {
+      runtime.exit(checkStatus);
+    }
     return;
   }
 
@@ -933,4 +989,48 @@ export async function modelsStatusCommand(
     }
     runtime.log(`- ${theme.heading(entry.provider)} ${bits.join(separator)}`);
   }
+
+  if (missingProvidersInUse.length > 0) {
+    runtime.log("");
+    runtime.log(colorize(rich, theme.heading, "Missing auth"));
+    for (const provider of missingProvidersInUse) {
+      const hint =
+        provider === "anthropic"
+          ? "Run `claude setup-token` or `clawdbot configure`."
+          : "Run `clawdbot configure` or set an API key env var.";
+      runtime.log(`- ${theme.heading(provider)} ${hint}`);
+    }
+  }
+
+  runtime.log("");
+  runtime.log(colorize(rich, theme.heading, "OAuth status"));
+  if (oauthProfiles.length === 0) {
+    runtime.log(colorize(rich, theme.muted, "- none"));
+    return;
+  }
+
+  const formatStatus = (status: string) => {
+    if (status === "ok") return colorize(rich, theme.success, "ok");
+    if (status === "expiring") return colorize(rich, theme.warn, "expiring");
+    if (status === "missing") return colorize(rich, theme.warn, "unknown");
+    return colorize(rich, theme.error, "expired");
+  };
+
+  for (const profile of oauthProfiles) {
+    const labelText = profile.label || profile.profileId;
+    const label = colorize(rich, theme.accent, labelText);
+    const status = formatStatus(profile.status);
+    const expiry = profile.expiresAt
+      ? ` expires in ${formatRemainingShort(profile.remainingMs)}`
+      : " expires unknown";
+    const source =
+      profile.source !== "store"
+        ? colorize(rich, theme.muted, ` (${profile.source})`)
+        : "";
+    runtime.log(`- ${label} ${status}${expiry}${source}`);
+  }
+
+  if (opts.check) {
+    runtime.exit(checkStatus);
+  }
 }