fix(doctor): show auth_permanent recovery guidance

src/agents/auth-profiles/usage.test.ts

@@ -141,6 +141,24 @@ describe("resolveProfilesUnavailableReason", () => {
     ).toBe("billing");
   });
 
+  it("returns auth_permanent for active permanent auth disables", () => {
+    const now = Date.now();
+    const store = makeStore({
+      "anthropic:default": {
+        disabledUntil: now + 60_000,
+        disabledReason: "auth_permanent",
+      },
+    });
+
+    expect(
+      resolveProfilesUnavailableReason({
+        store,
+        profileIds: ["anthropic:default"],
+        now,
+      }),
+    ).toBe("auth_permanent");
+  });
+
   it("uses recorded non-rate-limit failure counts for active cooldown windows", () => {
     const now = Date.now();
     const store = makeStore({
@@ -490,7 +508,7 @@ describe("markAuthProfileFailure — active windows do not extend on retry", ()
   async function markFailureAt(params: {
     store: ReturnType<typeof makeStore>;
     now: number;
-    reason: "rate_limit" | "billing";
+    reason: "rate_limit" | "billing" | "auth_permanent";
   }): Promise<void> {
     vi.useFakeTimers();
     vi.setSystemTime(params.now);
@@ -528,6 +546,18 @@ describe("markAuthProfileFailure — active windows do not extend on retry", ()
       }),
       readUntil: (stats: WindowStats | undefined) => stats?.disabledUntil,
     },
+    {
+      label: "disabledUntil(auth_permanent)",
+      reason: "auth_permanent" as const,
+      buildUsageStats: (now: number): WindowStats => ({
+        disabledUntil: now + 20 * 60 * 60 * 1000,
+        disabledReason: "auth_permanent",
+        errorCount: 5,
+        failureCounts: { auth_permanent: 5 },
+        lastFailureAt: now - 60_000,
+      }),
+      readUntil: (stats: WindowStats | undefined) => stats?.disabledUntil,
+    },
   ];
 
   for (const testCase of activeWindowCases) {
@@ -573,6 +603,19 @@ describe("markAuthProfileFailure — active windows do not extend on retry", ()
       expectedUntil: (now: number) => now + 20 * 60 * 60 * 1000,
       readUntil: (stats: WindowStats | undefined) => stats?.disabledUntil,
     },
+    {
+      label: "disabledUntil(auth_permanent)",
+      reason: "auth_permanent" as const,
+      buildUsageStats: (now: number): WindowStats => ({
+        disabledUntil: now - 60_000,
+        disabledReason: "auth_permanent",
+        errorCount: 5,
+        failureCounts: { auth_permanent: 2 },
+        lastFailureAt: now - 60_000,
+      }),
+      expectedUntil: (now: number) => now + 20 * 60 * 60 * 1000,
+      readUntil: (stats: WindowStats | undefined) => stats?.disabledUntil,
+    },
   ];
 
   for (const testCase of expiredWindowCases) {

src/agents/auth-profiles/usage.ts

@@ -425,8 +425,9 @@ function computeNextProfileUsageStats(params: {
 }
 
 /**
- * Mark a profile as failed for a specific reason. Billing failures are treated
- * as "disabled" (longer backoff) vs the regular cooldown window.
+ * Mark a profile as failed for a specific reason. Billing and permanent-auth
+ * failures are treated as "disabled" (longer backoff) vs the regular cooldown
+ * window.
  */
 export async function markAuthProfileFailure(params: {
   store: AuthProfileStore;

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;