@scrylog/cli 0.1.4 → 0.3.0

package/src/usage/planner.ts

@@ -1,5 +1,17 @@
 import type { TokenResolver } from "./resolver";
-import type { ClaudePlannerDecision, ClaudeDataSource, ClaudeOAuthCredentials, ClaudeWebSession } from "./types";
+import type { ClaudePlannerDecision, ClaudeDataSource, ClaudeOAuthCredentials, ClaudePlannedRoute, ClaudeWebSession } from "./types";
+
+/**
+ * Web session resolver with planning-safe operations. Planning only observes
+ * the in-memory session cache and cheap import-source checks; browser cookie
+ * import happens exclusively when a Web route executes.
+ */
+export interface ClaudeWebSourceResolver extends TokenResolver<ClaudeWebSession> {
+  /** Cache-only session resolution; never reads browser stores. */
+  resolveCached(): Promise<ClaudeWebSession | null>;
+  /** True when an import could yield candidates (cheap existence checks). */
+  hasImportSources(): Promise<boolean>;
+}
 
 export interface ClaudeSourcePlannerConfig {
   dataSource: ClaudeDataSource;
@@ -10,45 +22,97 @@ export class ClaudeSourcePlanner {
   constructor(
     private readonly config: ClaudeSourcePlannerConfig,
     private readonly oauthResolver: TokenResolver<ClaudeOAuthCredentials>,
-    private readonly webResolver: TokenResolver<ClaudeWebSession>,
+    private readonly webResolver: ClaudeWebSourceResolver,
     private readonly cliResolver: TokenResolver<string>,
   ) {}
 
   async decide(): Promise<ClaudePlannerDecision> {
-    const [hasOAuth, hasWeb, hasCli] = await Promise.all([
-      this.oauthResolver.isAvailable(),
-      this.webResolver.isAvailable(),
-      this.cliResolver.isAvailable(),
-    ]);
-
     const selected = this.config.dataSource;
     const webExtras = this.config.webExtrasEnabled;
 
     if (selected === "oauth") {
-      return { primary: "oauth", fallback: [], webExtras };
+      const oauth = await this.oauthResolver.resolve();
+      if (!oauth) return this.decision([], webExtras);
+      const cachedWeb = await this.webResolver.resolveCached();
+      const routes: ClaudePlannedRoute[] = [{ type: "oauth", credentials: oauth }];
+      if (oauth.owner !== "environment") {
+        const cli = await this.cliResolver.resolve();
+        if (cli) routes.push({ type: "cli", credentials: cli });
+      }
+      return this.decision(routes, webExtras, cachedWeb ?? undefined);
     }
     if (selected === "web") {
-      return { primary: "web", fallback: [], webExtras };
+      const cachedWeb = await this.webResolver.resolveCached();
+      if (!cachedWeb && !(await this.webResolver.hasImportSources())) {
+        return this.decision([], webExtras);
+      }
+      const routes: ClaudePlannedRoute[] = [{ type: "web", credentials: cachedWeb ?? this.deferredWebSession() }];
+      return this.decision(routes, webExtras, cachedWeb ?? undefined);
     }
     if (selected === "cli") {
-      return { primary: "cli", fallback: [], webExtras };
+      const cli = await this.cliResolver.resolve();
+      const cachedWeb = webExtras ? await this.webResolver.resolveCached() : null;
+      const routes: ClaudePlannedRoute[] = cli ? [{ type: "cli", credentials: cli }] : [];
+      return this.decision(routes, webExtras, cachedWeb ?? undefined);
     }
 
-    // Auto mode
-    const fallback: ClaudeDataSource[] = [];
-    if (hasOAuth) {
-      if (hasWeb) fallback.push("web");
-      if (hasCli) fallback.push("cli");
-      return { primary: "oauth", fallback, webExtras };
-    }
-    if (hasWeb) {
-      if (hasCli) fallback.push("cli");
-      return { primary: "web", fallback, webExtras };
-    }
-    if (hasCli) {
-      return { primary: "cli", fallback: [], webExtras };
+    const [oauth, cli] = await Promise.all([
+      this.oauthResolver.resolve(),
+      this.cliResolver.resolve(),
+    ]);
+    const cachedWeb = await this.webResolver.resolveCached();
+    const routes: ClaudePlannedRoute[] = [];
+    const webMayBeAvailable = Boolean(cachedWeb) || (await this.webResolver.hasImportSources());
+    if (oauth) {
+      routes.push({ type: "oauth", credentials: oauth });
+      if (oauth.owner !== "environment") {
+        if (cli) routes.push({ type: "cli", credentials: cli });
+        if (webMayBeAvailable) routes.push({ type: "web", credentials: cachedWeb ?? this.deferredWebSession() });
+      }
+    } else if (webMayBeAvailable) {
+      routes.push({ type: "web", credentials: cachedWeb ?? this.deferredWebSession() });
+      if (cli) routes.push({ type: "cli", credentials: cli });
+    } else if (cli) {
+      routes.push({ type: "cli", credentials: cli });
     }
+    return this.decision(routes, webExtras, cachedWeb ?? undefined);
+  }
+
+  /**
+   * A planning-safe Web session without a cookie header. The first cursor
+   * advance resolves the session once and returns its imported header;
+   * later advances continue the same cursor so a rejected source is not
+   * re-imported within the attempt.
+   */
+  private deferredWebSession(): ClaudeWebSession {
+    let sessionPromise: Promise<ClaudeWebSession | null> | null = null;
+    let primed = false;
+    return {
+      cookieHeader: "",
+      importNext: async () => {
+        sessionPromise ??= this.webResolver.resolve();
+        const session = await sessionPromise;
+        if (!session) return null;
+        if (!primed) {
+          primed = true;
+          return session.cookieHeader || null;
+        }
+        return session.importNext ? await session.importNext() : null;
+      },
+    };
+  }
 
-    return { primary: "auto", fallback: [], webExtras };
+  private decision(
+    routes: ClaudePlannedRoute[],
+    webExtras: boolean,
+    webExtrasCredentials?: ClaudeWebSession,
+  ): ClaudePlannerDecision {
+    return {
+      primary: routes[0]?.type ?? "auto",
+      fallback: routes.slice(1).map((route) => route.type),
+      webExtras,
+      routes,
+      webExtrasCredentials: webExtras ? webExtrasCredentials : undefined,
+    };
   }
 }

package/src/usage/providers/claude.ts

@@ -1,113 +1,233 @@
 import type { UsageClient } from "../client";
-import type { ClaudeOAuthCredentials, ClaudeUsageSnapshot, ClaudeWebSession, UsageProviderEntry } from "../types";
-import { ClaudeSourcePlanner } from "../planner";
-import { AnthropicOAuthUsageClient, AuthenticationError, ScopeError } from "../clients/anthropic-oauth-usage";
-import { AnthropicWebUsageClient, InvalidCredentialsError } from "../clients/anthropic-web-usage";
+import {
+  AnthropicOAuthUsageClient,
+  fetchOAuthProfile,
+} from "../clients/anthropic-oauth-usage";
+import { InvalidCredentialsError, AnthropicWebUsageClient } from "../clients/anthropic-web-usage";
 import { ClaudeCliProbeClient } from "../clients/claude-cli-probe";
-import type { TokenResolver } from "../resolver";
+import { classifyUsageError, UsageError } from "../errors";
 import { mapClaudeToEntry } from "../mappers";
+import type { ClaudeSourcePlanner } from "../planner";
+import type { TokenResolver } from "../resolver";
+import type {
+  ClaudeOAuthCredentials,
+  ClaudePlannedRoute,
+  ClaudeUsageSnapshot,
+  ClaudeWebSession,
+  UsageProviderEntry,
+} from "../types";
+
+interface ClaudeClients {
+  oauth: UsageClient<ClaudeOAuthCredentials, ClaudeUsageSnapshot>;
+  web: UsageClient<ClaudeWebSession, ClaudeUsageSnapshot>;
+  cli: UsageClient<string, ClaudeUsageSnapshot>;
+}
+
+interface WebExtrasPrimaryIdentity {
+  email: string | null;
+  organizationId: string | null;
+  organizationName: string | null;
+}
+
+interface KeychainDiagnostics {
+  describeKeychainFailure?(): string | null;
+}
+
+const DEFAULT_PROFILE_IDENTITY_TTL_MS = 30 * 60 * 1_000;
+
+function nullIdentity(): WebExtrasPrimaryIdentity {
+  return { email: null, organizationId: null, organizationName: null };
+}
+
+function normalizedIdentity(value: string | null | undefined): string | null {
+  const trimmed = value?.trim().toLowerCase();
+  return trimmed ? trimmed : null;
+}
+
+function webExtrasIdentityMatches(primary: WebExtrasPrimaryIdentity, web: ClaudeUsageSnapshot): boolean {
+  const webEmail = normalizedIdentity(web.accountEmail);
+  if (primary.email && webEmail && normalizedIdentity(primary.email) === webEmail) return true;
+  const webOrganizationId = normalizedIdentity(web.accountOrganizationId);
+  if (primary.organizationId && webOrganizationId && normalizedIdentity(primary.organizationId) === webOrganizationId) return true;
+  const webOrganizationName = normalizedIdentity(web.accountOrganization);
+  if (primary.organizationName && webOrganizationName && normalizedIdentity(primary.organizationName) === webOrganizationName) return true;
+  return false;
+}
 
 export class ClaudeUsageProvider {
-  private readonly oauthClient: UsageClient<ClaudeOAuthCredentials, ClaudeUsageSnapshot>;
-  private readonly webClient: UsageClient<ClaudeWebSession, ClaudeUsageSnapshot>;
-  private readonly cliClient: UsageClient<string, ClaudeUsageSnapshot>;
+  private readonly clients: ClaudeClients;
+  private readonly oauthResolver: TokenResolver<ClaudeOAuthCredentials> & KeychainDiagnostics;
+  private readonly webResolver: TokenResolver<ClaudeWebSession> & KeychainDiagnostics;
+  private readonly profileIdentityTtlMs: number;
+  private profileIdentity?: { token: string; identity: WebExtrasPrimaryIdentity; fetchedAt: number };
 
   constructor(
     private readonly planner: ClaudeSourcePlanner,
-    private readonly oauthResolver: TokenResolver<ClaudeOAuthCredentials>,
-    private readonly webResolver: TokenResolver<ClaudeWebSession>,
-    private readonly cliResolver: TokenResolver<string>,
+    oauthResolver: TokenResolver<ClaudeOAuthCredentials> & KeychainDiagnostics,
+    webResolver: TokenResolver<ClaudeWebSession> & KeychainDiagnostics,
+    _cliResolver: TokenResolver<string>,
+    clients?: Partial<ClaudeClients>,
+    options?: { profileIdentityTtlMs?: number },
   ) {
-    this.oauthClient = new AnthropicOAuthUsageClient();
-    this.webClient = new AnthropicWebUsageClient();
-    this.cliClient = new ClaudeCliProbeClient();
+    this.oauthResolver = oauthResolver;
+    this.webResolver = webResolver;
+    this.profileIdentityTtlMs = options?.profileIdentityTtlMs ?? DEFAULT_PROFILE_IDENTITY_TTL_MS;
+    this.clients = {
+      oauth: clients?.oauth ?? new AnthropicOAuthUsageClient(),
+      web: clients?.web ?? new AnthropicWebUsageClient(),
+      cli: clients?.cli ?? new ClaudeCliProbeClient(),
+    };
   }
 
   async fetch(options?: { signal?: AbortSignal }): Promise<{ entry: UsageProviderEntry; snapshot: ClaudeUsageSnapshot | null }> {
     const decision = await this.planner.decide();
-    const errors: string[] = [];
-
-    if (decision.primary === "auto") {
-      // No credentials available on this machine
-      return { entry: mapClaudeToEntry(null, [], false, null), snapshot: null };
+    if (decision.routes.length === 0) {
+      // Surface actionable keychain diagnostics when a blocking failure (not
+      // merely missing credentials) explains the empty route plan.
+      const reason =
+        this.oauthResolver.describeKeychainFailure?.() ??
+        this.webResolver.describeKeychainFailure?.() ??
+        null;
+      return { entry: mapClaudeToEntry(null, reason ? [reason] : [], false, null), snapshot: null };
     }
 
-    // Resolve all credentials upfront for both fetch and accountId generation
-    const [oauthCreds, webCreds, cliCreds] = await Promise.all([
-      this.oauthResolver.resolve(),
-      this.webResolver.resolve(),
-      this.cliResolver.resolve(),
-    ]);
-
-    const sources: Array<{ type: "oauth" | "web" | "cli"; creds: unknown }> = [];
-
-    // Primary
-    if (decision.primary === "oauth" && oauthCreds) {
-      sources.push({ type: "oauth", creds: oauthCreds });
-    } else if (decision.primary === "web" && webCreds) {
-      sources.push({ type: "web", creds: webCreds });
-    } else if (decision.primary === "cli" && cliCreds) {
-      sources.push({ type: "cli", creds: cliCreds });
+    const errors: string[] = [];
+    let sawNonAuthFailure = false;
+    for (let index = 0; index < decision.routes.length; index++) {
+      const route = decision.routes[index]!;
+      try {
+        const snapshot = await this.fetchRoute(route, options);
+        const withExtras = await this.mergeWebExtras(snapshot, route, decision.webExtrasCredentials, options);
+        const winningOAuth = route.type === "oauth" ? route.credentials : null;
+        return { entry: mapClaudeToEntry(withExtras, [], true, winningOAuth), snapshot: withExtras };
+      } catch (error) {
+        const classified = error instanceof InvalidCredentialsError
+          ? new UsageError("invalid-credentials", error.message)
+          : classifyUsageError(error);
+        if (classified.kind === "cancelled") throw classified;
+        errors.push(`${route.type}: ${classified.message}`);
+        if (classified.kind !== "invalid-credentials") sawNonAuthFailure = true;
+        if (classified.kind === "invalid-credentials" && route.type === "oauth") {
+          // Invalidate the daemon-lifetime credential cache so the next poll
+          // re-resolves the OAuth source after an authentication rejection.
+          // The profile identity cache is keyed by token, so dropping it
+          // forces re-verification once the rotated token arrives.
+          (this.oauthResolver as Partial<{ invalidate?: () => void }>).invalidate?.();
+          this.profileIdentity = undefined;
+        }
+        const canRecover = classified.kind === "invalid-credentials" && index + 1 < decision.routes.length;
+        if (!canRecover) break;
+      }
     }
 
-    // Fallbacks
-    for (const fb of decision.fallback) {
-      if (fb === "oauth" && oauthCreds) {
-        sources.push({ type: "oauth", creds: oauthCreds });
-      } else if (fb === "web" && webCreds) {
-        sources.push({ type: "web", creds: webCreds });
-      } else if (fb === "cli" && cliCreds) {
-        sources.push({ type: "cli", creds: cliCreds });
+    if (errors.length > 0 && !sawNonAuthFailure) {
+      // Every attempted route failed with authentication failures: surface a
+      // single actionable state instead of raw probe errors.
+      const sessionExpired = errors.some((message) => message.includes("expired") || message.includes("re-login"));
+      if (sessionExpired) {
+        return {
+          entry: mapClaudeToEntry(null, ["Claude session expired — run \"claude\" to re-login"], false, null),
+          snapshot: null,
+        };
       }
+      return { entry: mapClaudeToEntry(null, [], false, null), snapshot: null };
     }
 
-    let snapshot: ClaudeUsageSnapshot | null = null;
+    return { entry: mapClaudeToEntry(null, errors, true, null), snapshot: null };
+  }
 
-    for (const source of sources) {
-      try {
-        if (source.type === "oauth") {
-          snapshot = await this.oauthClient.fetch(source.creds as ClaudeOAuthCredentials, options);
-        } else if (source.type === "web") {
-          snapshot = await this.webClient.fetch(source.creds as ClaudeWebSession, options);
-        } else if (source.type === "cli") {
-          snapshot = await this.cliClient.fetch(source.creds as string, options);
-        }
-        break;
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        errors.push(`${source.type}: ${message}`);
-        if (err instanceof InvalidCredentialsError || err instanceof AuthenticationError || err instanceof ScopeError) {
-          continue;
-        }
-        // Continue to fallback for other errors too
+  private fetchRoute(
+    route: ClaudePlannedRoute,
+    options?: { signal?: AbortSignal },
+  ): Promise<ClaudeUsageSnapshot> {
+    if (route.type === "oauth") {
+      if (route.credentials.isStale) {
+        return Promise.reject(new UsageError("invalid-credentials", "Claude-owned OAuth token is expired or near expiry"));
       }
+      return this.clients.oauth.fetch(route.credentials, options);
     }
+    if (route.type === "web") return this.fetchWebRoute(route.credentials, options);
+    return this.clients.cli.fetch(route.credentials, options);
+  }
 
-    // Merge OAuth credential metadata into snapshot for accountId generation
-    if (snapshot && oauthCreds) {
-      if (snapshot.subscriptionType === null && oauthCreds.subscriptionType) {
-        snapshot = { ...snapshot, subscriptionType: oauthCreds.subscriptionType };
-      }
-      if (snapshot.rateLimitTier === null && oauthCreds.rateLimitTier) {
-        snapshot = { ...snapshot, rateLimitTier: oauthCreds.rateLimitTier };
-      }
+  private async fetchWebRoute(
+    session: ClaudeWebSession,
+    options?: { signal?: AbortSignal },
+  ): Promise<ClaudeUsageSnapshot> {
+    let cookieHeader = session.cookieHeader;
+    if (!cookieHeader && session.importNext) {
+      cookieHeader = (await session.importNext()) ?? "";
+    }
+    if (!cookieHeader) {
+      // Prefer the resolver's keychain diagnostic when a blocking failure (not
+      // a transient import miss) is why no web session could be produced. It
+      // is an environment failure, not rejected credentials, so transient
+      // classification keeps the reason visible in the reported entry.
+      const reason = this.webResolver.describeKeychainFailure?.();
+      throw new UsageError(
+        reason ? "transient" : "invalid-credentials",
+        reason
+          ? `${reason} (no Claude web session available)`
+          : "No Claude web session available",
+      );
     }
+    return this.clients.web.fetch({ ...session, cookieHeader }, options);
+  }
 
-    // Web extras merge
-    if (snapshot && decision.webExtras && snapshot.source !== "web" && webCreds) {
-      try {
-        const webSnapshot = await this.webClient.fetch(webCreds, options);
-        if (snapshot.extraRateWindows.length === 0 && webSnapshot.extraRateWindows.length > 0) {
-          snapshot = { ...snapshot, extraRateWindows: webSnapshot.extraRateWindows };
-        }
-        if (!snapshot.providerCost && webSnapshot.providerCost) {
-          snapshot = { ...snapshot, providerCost: webSnapshot.providerCost };
-        }
-      } catch {
-        // Ignore web extras failures
-      }
+  private async mergeWebExtras(
+    snapshot: ClaudeUsageSnapshot,
+    route: ClaudePlannedRoute,
+    webCredentials: ClaudeWebSession | undefined,
+    options?: { signal?: AbortSignal },
+  ): Promise<ClaudeUsageSnapshot> {
+    if (!webCredentials || snapshot.source === "web") return snapshot;
+    try {
+      const web = await this.clients.web.fetch(webCredentials, options);
+      const primary = await this.primaryWebExtrasIdentity(snapshot, route, options);
+      if (!webExtrasIdentityMatches(primary, web)) return snapshot;
+      return {
+        ...snapshot,
+        extraRateWindows: snapshot.extraRateWindows.length === 0 ? web.extraRateWindows : snapshot.extraRateWindows,
+        providerCost: snapshot.providerCost ?? web.providerCost,
+      };
+    } catch (error) {
+      if (classifyUsageError(error).kind === "cancelled") throw error;
+      return snapshot;
     }
+  }
+
+  private async primaryWebExtrasIdentity(
+    snapshot: ClaudeUsageSnapshot,
+    route: ClaudePlannedRoute,
+    options?: { signal?: AbortSignal },
+  ): Promise<WebExtrasPrimaryIdentity> {
+    if (snapshot.accountEmail || snapshot.accountOrganization || snapshot.accountOrganizationId) {
+      return {
+        email: snapshot.accountEmail,
+        organizationId: snapshot.accountOrganizationId,
+        organizationName: snapshot.accountOrganization,
+      };
+    }
+    if (route.type !== "oauth") return nullIdentity();
 
-    return { entry: mapClaudeToEntry(snapshot, errors, true, oauthCreds), snapshot };
+    const token = route.credentials.accessToken;
+    const cached = this.profileIdentity;
+    if (cached && cached.token === token && Date.now() - cached.fetchedAt < this.profileIdentityTtlMs) {
+      return cached.identity;
+    }
+    try {
+      const profile = await fetchOAuthProfile(token, options);
+      const identity: WebExtrasPrimaryIdentity = {
+        email: profile.email,
+        organizationId: profile.organizationId,
+        organizationName: null,
+      };
+      this.profileIdentity = { token, identity, fetchedAt: Date.now() };
+      return identity;
+    } catch (error) {
+      if (classifyUsageError(error).kind === "cancelled") throw error;
+      // Best-effort: do not cache failures so the next poll can retry.
+      return nullIdentity();
+    }
   }
 }

package/src/usage/providers/codex.ts

@@ -1,34 +1,115 @@
 import type { UsageClient } from "../client";
-import type { CodexOAuthCredentials, CodexUsageSnapshot, UsageProviderEntry } from "../types";
+import type { CodexDataSource, CodexOAuthCredentials, CodexUsageSnapshot, UsageProviderEntry } from "../types";
 import type { TokenResolver } from "../resolver";
-import { CodexOAuthUsageClient } from "../clients/codex-oauth-usage";
+import { CodexMonthlySpendClient, CodexOAuthUsageClient } from "../clients/codex-oauth-usage";
+import { CodexAppServerClient } from "../clients/codex-app-server";
+import { classifyUsageError, isRecoverableAuthenticationError } from "../errors";
+import { isCodexCredentialFresh } from "../resolvers/codex-auth";
 import { mapCodexToEntry } from "../mappers";
 
+interface CodexAppServerUsageClient {
+  fetch(
+    identity?: Pick<CodexOAuthCredentials, "accountEmail" | "accountId">,
+    options?: { signal?: AbortSignal },
+  ): Promise<CodexUsageSnapshot>;
+}
+
+interface CodexMonthlySpendUsageClient {
+  fetch(
+    credentials: CodexOAuthCredentials,
+    accountId: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<NonNullable<CodexUsageSnapshot["individualLimit"]> | null>;
+}
+
+export interface CodexUsageProviderDependencies {
+  oauthClient?: UsageClient<CodexOAuthCredentials, CodexUsageSnapshot>;
+  appServerClient?: CodexAppServerUsageClient;
+  monthlySpendClient?: CodexMonthlySpendUsageClient;
+}
+
 export class CodexUsageProvider {
   private readonly oauthClient: UsageClient<CodexOAuthCredentials, CodexUsageSnapshot>;
+  private readonly appServerClient: CodexAppServerUsageClient;
+  private readonly monthlySpendClient: CodexMonthlySpendUsageClient;
 
   constructor(
     private readonly oauthResolver: TokenResolver<CodexOAuthCredentials>,
+    private readonly dataSource: CodexDataSource = "auto",
+    dependencies: CodexUsageProviderDependencies = {},
   ) {
-    this.oauthClient = new CodexOAuthUsageClient();
+    this.oauthClient = dependencies.oauthClient ?? new CodexOAuthUsageClient();
+    this.appServerClient = dependencies.appServerClient ?? new CodexAppServerClient();
+    this.monthlySpendClient = dependencies.monthlySpendClient ?? new CodexMonthlySpendClient();
   }
 
   async fetch(options?: { signal?: AbortSignal }): Promise<{ entry: UsageProviderEntry; snapshot: CodexUsageSnapshot | null }> {
-    const errors: string[] = [];
-    const oauthCreds = await this.oauthResolver.resolve();
+    let oauthCreds: CodexOAuthCredentials | null;
+    try {
+      oauthCreds = await this.oauthResolver.resolve();
+    } catch (error) {
+      const failure = classifyUsageError(error);
+      return { entry: mapCodexToEntry(null, [`oauth: ${failure.message}`], true, null), snapshot: null };
+    }
 
     if (!oauthCreds) {
       return { entry: mapCodexToEntry(null, [], false, null), snapshot: null };
     }
 
-    let snapshot: CodexUsageSnapshot | null = null;
+    if (!isCodexCredentialFresh(oauthCreds)) {
+      return this.fetchFromCli(oauthCreds, options);
+    }
+
     try {
-      snapshot = await this.oauthClient.fetch(oauthCreds, options);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      errors.push(`oauth: ${message}`);
+      let snapshot = await this.oauthClient.fetch(oauthCreds, options);
+      snapshot = await this.enrichMonthlySpend(snapshot, oauthCreds, options);
+      return { entry: mapCodexToEntry(snapshot, [], true, oauthCreds), snapshot };
+    } catch (error) {
+      const failure = classifyUsageError(error);
+      if (failure.kind === "cancelled") throw failure;
+      if (this.dataSource === "auto" && isRecoverableAuthenticationError(failure)) {
+        return this.fetchFromCli(oauthCreds, options);
+      }
+      return {
+        entry: mapCodexToEntry(null, [`oauth: ${failure.message}`], true, oauthCreds),
+        snapshot: null,
+      };
     }
+  }
 
-    return { entry: mapCodexToEntry(snapshot, errors, true, oauthCreds), snapshot };
+  private async enrichMonthlySpend(
+    snapshot: CodexUsageSnapshot,
+    oauthCreds: CodexOAuthCredentials,
+    options?: { signal?: AbortSignal },
+  ): Promise<CodexUsageSnapshot> {
+    const accountId = snapshot.accountId ?? oauthCreds.accountId;
+    if (snapshot.source !== "oauth" || !snapshot.spendControlPresent || snapshot.individualLimit || !accountId) {
+      return snapshot;
+    }
+    try {
+      const individualLimit = await this.monthlySpendClient.fetch(oauthCreds, accountId, options);
+      return individualLimit ? { ...snapshot, individualLimit } : snapshot;
+    } catch (error) {
+      const failure = classifyUsageError(error);
+      if (failure.kind === "cancelled") throw failure;
+      return snapshot;
+    }
+  }
+
+  private async fetchFromCli(
+    oauthCreds: CodexOAuthCredentials,
+    options?: { signal?: AbortSignal },
+  ): Promise<{ entry: UsageProviderEntry; snapshot: CodexUsageSnapshot | null }> {
+    try {
+      const snapshot = await this.appServerClient.fetch(oauthCreds, options);
+      return { entry: mapCodexToEntry(snapshot, [], true, null), snapshot };
+    } catch (error) {
+      const failure = classifyUsageError(error);
+      if (failure.kind === "cancelled") throw failure;
+      return {
+        entry: mapCodexToEntry(null, [`cli: ${failure.message}`], true, oauthCreds),
+        snapshot: null,
+      };
+    }
   }
 }