fix(auth): distinguish revoked API keys from transient auth errors (#25754)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 8f9c07a200
Co-authored-by: rrenamed <87486610+rrenamed@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/commands/doctor-auth.hints.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { resolveUnusableProfileHint } from "./doctor-auth.js";
+
+describe("resolveUnusableProfileHint", () => {
+  it("returns billing guidance for disabled billing profiles", () => {
+    expect(resolveUnusableProfileHint({ kind: "disabled", reason: "billing" })).toBe(
+      "Top up credits (provider billing) or switch provider.",
+    );
+  });
+
+  it("returns credential guidance for permanent auth disables", () => {
+    expect(resolveUnusableProfileHint({ kind: "disabled", reason: "auth_permanent" })).toBe(
+      "Refresh or replace credentials, then retry.",
+    );
+  });
+
+  it("falls back to cooldown guidance for non-billing disable reasons", () => {
+    expect(resolveUnusableProfileHint({ kind: "disabled", reason: "unknown" })).toBe(
+      "Wait for cooldown or switch provider.",
+    );
+  });
+
+  it("returns cooldown guidance for cooldown windows", () => {
+    expect(resolveUnusableProfileHint({ kind: "cooldown" })).toBe(
+      "Wait for cooldown or switch provider.",
+    );
+  });
+});

src/commands/doctor-auth.ts

@@ -206,6 +206,21 @@ type AuthIssue = {
   remainingMs?: number;
 };
 
+export function resolveUnusableProfileHint(params: {
+  kind: "cooldown" | "disabled";
+  reason?: string;
+}): string {
+  if (params.kind === "disabled") {
+    if (params.reason === "billing") {
+      return "Top up credits (provider billing) or switch provider.";
+    }
+    if (params.reason === "auth_permanent" || params.reason === "auth") {
+      return "Refresh or replace credentials, then retry.";
+    }
+  }
+  return "Wait for cooldown or switch provider.";
+}
+
 function formatAuthIssueHint(issue: AuthIssue): string | null {
   if (issue.provider === "anthropic" && issue.profileId === CLAUDE_CLI_PROFILE_ID) {
     return `Deprecated profile. Use ${formatCliCommand("openclaw models auth setup-token")} or ${formatCliCommand(
@@ -245,13 +260,14 @@ export async function noteAuthProfileHealth(params: {
       }
       const stats = store.usageStats?.[profileId];
       const remaining = formatRemainingShort(until - now);
-      const kind =
-        typeof stats?.disabledUntil === "number" && now < stats.disabledUntil
-          ? `disabled${stats.disabledReason ? `:${stats.disabledReason}` : ""}`
-          : "cooldown";
-      const hint = kind.startsWith("disabled:billing")
-        ? "Top up credits (provider billing) or switch provider."
-        : "Wait for cooldown or switch provider.";
+      const disabledActive = typeof stats?.disabledUntil === "number" && now < stats.disabledUntil;
+      const kind = disabledActive
+        ? `disabled${stats.disabledReason ? `:${stats.disabledReason}` : ""}`
+        : "cooldown";
+      const hint = resolveUnusableProfileHint({
+        kind: disabledActive ? "disabled" : "cooldown",
+        reason: stats?.disabledReason,
+      });
       out.push(`- ${profileId}: ${kind} (${remaining})${hint ? ` — ${hint}` : ""}`);
     }
     return out;

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { mapFailoverReasonToProbeStatus } from "./list.probe.js";
+
+describe("mapFailoverReasonToProbeStatus", () => {
+  it("maps auth_permanent to auth", () => {
+    expect(mapFailoverReasonToProbeStatus("auth_permanent")).toBe("auth");
+  });
+
+  it("keeps existing failover reason mappings", () => {
+    expect(mapFailoverReasonToProbeStatus("auth")).toBe("auth");
+    expect(mapFailoverReasonToProbeStatus("rate_limit")).toBe("rate_limit");
+    expect(mapFailoverReasonToProbeStatus("billing")).toBe("billing");
+    expect(mapFailoverReasonToProbeStatus("timeout")).toBe("timeout");
+    expect(mapFailoverReasonToProbeStatus("format")).toBe("format");
+  });
+
+  it("falls back to unknown for unrecognized values", () => {
+    expect(mapFailoverReasonToProbeStatus(undefined)).toBe("unknown");
+    expect(mapFailoverReasonToProbeStatus(null)).toBe("unknown");
+    expect(mapFailoverReasonToProbeStatus("model_not_found")).toBe("unknown");
+  });
+});

src/commands/models/list.probe.ts

@@ -82,11 +82,13 @@ export type AuthProbeOptions = {
   maxTokens: number;
 };
 
-const toStatus = (reason?: string | null): AuthProbeStatus => {
+export function mapFailoverReasonToProbeStatus(reason?: string | null): AuthProbeStatus {
   if (!reason) {
     return "unknown";
   }
-  if (reason === "auth") {
+  if (reason === "auth" || reason === "auth_permanent") {
+    // Keep probe output backward-compatible: permanent auth failures still
+    // surface in the auth bucket instead of showing as unknown.
     return "auth";
   }
   if (reason === "rate_limit") {
@@ -102,7 +104,7 @@ const toStatus = (reason?: string | null): AuthProbeStatus => {
     return "format";
   }
   return "unknown";
-};
+}
 
 function buildCandidateMap(modelCandidates: string[]): Map<string, string[]> {
   const map = new Map<string, string[]>();
@@ -346,7 +348,7 @@ async function probeTarget(params: {
       label: target.label,
       source: target.source,
       mode: target.mode,
-      status: toStatus(described.reason),
+      status: mapFailoverReasonToProbeStatus(described.reason),
       error: redactSecrets(described.message),
       latencyMs: Date.now() - start,
     };