From 8f9c07a200644284e11adae76368adab40c5fa4e Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Wed, 25 Feb 2026 19:46:08 -0500 Subject: [PATCH] fix(doctor): show auth_permanent recovery guidance --- src/agents/auth-profiles/usage.test.ts | 45 +++++++++++++++++++++++++- src/agents/auth-profiles/usage.ts | 5 +-- src/commands/doctor-auth.hints.test.ts | 28 ++++++++++++++++ src/commands/doctor-auth.ts | 30 +++++++++++++---- 4 files changed, 98 insertions(+), 10 deletions(-) create mode 100644 src/commands/doctor-auth.hints.test.ts diff --git a/src/agents/auth-profiles/usage.test.ts b/src/agents/auth-profiles/usage.test.ts index 0025007f729..8c499654b49 100644 --- a/src/agents/auth-profiles/usage.test.ts +++ b/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; now: number; - reason: "rate_limit" | "billing"; + reason: "rate_limit" | "billing" | "auth_permanent"; }): Promise { 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) { diff --git a/src/agents/auth-profiles/usage.ts b/src/agents/auth-profiles/usage.ts index 115ea56ba2f..60c43c9c3c8 100644 --- a/src/agents/auth-profiles/usage.ts +++ b/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; diff --git a/src/commands/doctor-auth.hints.test.ts b/src/commands/doctor-auth.hints.test.ts new file mode 100644 index 00000000000..f660a4e82a2 --- /dev/null +++ b/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.", + ); + }); +}); diff --git a/src/commands/doctor-auth.ts b/src/commands/doctor-auth.ts index a12ab384a20..f408dc43f93 100644 --- a/src/commands/doctor-auth.ts +++ b/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;