Handle Grok team principal billing fallback

Sources/CodexBar/PreferencesProvidersPane.swift

@@ -325,7 +325,9 @@ struct ProvidersPane: View {
     }
 
     func providerErrorDisplay(_ provider: UsageProvider) -> ProviderErrorDisplay? {
-        guard let full = self.store.error(for: provider), !full.isEmpty else { return nil }
+        guard let full = self.store.error(for: provider) ?? self.store.diagnostic(for: provider),
+              !full.isEmpty
+        else { return nil }
         let preview = self.store.userFacingError(for: provider) ?? full
         return ProviderErrorDisplay(
             preview: self.truncated(preview, prefix: ""),

Sources/CodexBar/UsageStore+Accessors.swift

@@ -38,11 +38,18 @@ extension UsageStore {
         self.errors[provider]
     }
 
+    func diagnostic(for provider: UsageProvider) -> String? {
+        self.diagnostics[provider]
+    }
+
     func userFacingError(for provider: UsageProvider) -> String? {
         if let raw = self.errors[provider] {
             guard provider == .codex else { return raw }
             return CodexUIErrorMapper.userFacingMessage(raw)
         }
+        if let diagnostic = self.diagnostics[provider] {
+            return diagnostic
+        }
         return self.unavailableMessage(for: provider)
     }
 

Sources/CodexBar/UsageStore+BackgroundRefresh.swift

@@ -30,6 +30,7 @@ extension UsageStore {
         self.snapshots.removeValue(forKey: provider)
         self.lastKnownResetSnapshots.removeValue(forKey: provider)
         self.errors[provider] = nil
+        self.diagnostics[provider] = nil
         if provider == .gemini {
             self.clearGeminiConsumerTierDeprecationObservation()
         }

Sources/CodexBar/UsageStore+CodexResetCredits.swift

@@ -117,6 +117,7 @@ extension ProviderFetchOutcome {
                 sourceLabel: result.sourceLabel,
                 strategyID: result.strategyID,
                 strategyKind: result.strategyKind,
+                diagnostic: result.diagnostic,
                 claudeOAuthKeychainPersistentRefHash: result.claudeOAuthKeychainPersistentRefHash,
                 claudeOAuthHistoryOwnerIdentifier: result.claudeOAuthHistoryOwnerIdentifier,
                 claudeOAuthKeychainCredentialMismatch: result.claudeOAuthKeychainCredentialMismatch,

Sources/CodexBar/UsageStore+Refresh.swift

@@ -329,6 +329,7 @@ extension UsageStore {
             }
         }
 
+        self.diagnostics[provider] = nil
         let claudeAuthStateBeforeFetch = provider == .claude
             ? await Self.captureClaudeRefreshAuthState(invalidateCredentialsFile: true)
             : nil
@@ -554,6 +555,7 @@ extension UsageStore {
             }
             self.lastSourceLabels[provider] = result.sourceLabel
             self.errors[provider] = nil
+            self.diagnostics[provider] = result.diagnostic
             if let tokenAccount = currentTokenAccount {
                 self.cacheTokenAccountSnapshot(
                     provider: provider,
@@ -957,6 +959,7 @@ extension UsageStore {
         let shouldNotifyPermissionPrompt = Self.isPermissionPromptWaiting(error)
         await MainActor.run {
             guard self.isCurrentProviderRefreshGeneration(provider, generation: context.generation) else { return }
+            self.diagnostics[provider] = nil
             if provider == .gemini, Self.isGeminiConsumerTierDeprecationError(error) {
                 // This is a durable provider migration signal, not a transient fetch failure.
                 // Surface it immediately so a cached snapshot cannot hide the required handoff.

Sources/CodexBar/UsageStore.swift

@@ -11,6 +11,7 @@ extension UsageStore {
     var menuObservationToken: Int {
         _ = self.snapshots
         _ = self.errors
+        _ = self.diagnostics
         _ = self.knownLimitsAvailabilityByProvider
         _ = self.lastSourceLabels
         _ = self.lastFetchAttempts
@@ -44,6 +45,7 @@ extension UsageStore {
     var iconObservationToken: Int {
         _ = self.snapshots
         _ = self.errors
+        _ = self.diagnostics
         _ = self.knownLimitsAvailabilityByProvider
         _ = self.credits
         _ = self.lastCreditsError
@@ -153,6 +155,7 @@ final class UsageStore {
 
     var snapshots: [UsageProvider: UsageSnapshot] = [:]
     var errors: [UsageProvider: String] = [:]
+    var diagnostics: [UsageProvider: String] = [:]
     var geminiObservedConsumerTierDeprecation = false
     var knownLimitsAvailabilityByProvider: [UsageProvider: UsageLimitsAvailability] = [:]
     var lastSourceLabels: [UsageProvider: String] = [:]

Sources/CodexBarCLI/CLIPayloads.swift

@@ -15,6 +15,7 @@ struct ProviderPayload: Encodable {
     let credits: CreditsSnapshot?
     let antigravityPlanInfo: AntigravityPlanInfoSummary?
     let openaiDashboard: OpenAIDashboardSnapshot?
+    let diagnostic: String?
     let error: ProviderErrorPayload?
     let pace: ProviderPacePayload?
 
@@ -28,6 +29,7 @@ struct ProviderPayload: Encodable {
         case credits
         case antigravityPlanInfo
         case openaiDashboard
+        case diagnostic
         case error
         case pace
     }
@@ -44,6 +46,7 @@ struct ProviderPayload: Encodable {
         antigravityPlanInfo: AntigravityPlanInfoSummary?,
         openaiDashboard: OpenAIDashboardSnapshot?,
         error: ProviderErrorPayload?,
+        diagnostic: String? = nil,
         pace: ProviderPacePayload? = nil)
     {
         self.provider = provider.rawValue
@@ -56,6 +59,7 @@ struct ProviderPayload: Encodable {
         self.credits = credits
         self.antigravityPlanInfo = antigravityPlanInfo
         self.openaiDashboard = openaiDashboard
+        self.diagnostic = diagnostic
         self.error = error
         self.pace = pace
     }
@@ -72,6 +76,7 @@ struct ProviderPayload: Encodable {
         antigravityPlanInfo: AntigravityPlanInfoSummary?,
         openaiDashboard: OpenAIDashboardSnapshot?,
         error: ProviderErrorPayload?,
+        diagnostic: String? = nil,
         pace: ProviderPacePayload? = nil)
     {
         self.provider = providerID
@@ -84,6 +89,7 @@ struct ProviderPayload: Encodable {
         self.credits = credits
         self.antigravityPlanInfo = antigravityPlanInfo
         self.openaiDashboard = openaiDashboard
+        self.diagnostic = diagnostic
         self.error = error
         self.pace = pace
     }

Sources/CodexBarCLI/CLIUsageCommand.swift

@@ -48,6 +48,7 @@ private struct UsageSuccessRenderInput {
     let dashboard: OpenAIDashboardSnapshot?
     let effectiveSourceMode: ProviderSourceMode
     let command: UsageCommandContext
+    let diagnostic: String?
     let notes: [String]
 }
 
@@ -287,6 +288,7 @@ extension CodexBarCLI {
         credits: CreditsSnapshot?,
         antigravityPlanInfo: AntigravityPlanInfoSummary?,
         dashboard: OpenAIDashboardSnapshot?,
+        diagnostic: String?,
         weeklyWorkDays: Int?) -> ProviderPayload
     {
         ProviderPayload(
@@ -301,6 +303,7 @@ extension CodexBarCLI {
             antigravityPlanInfo: antigravityPlanInfo,
             openaiDashboard: dashboard,
             error: nil,
+            diagnostic: diagnostic,
             pace: CLIRenderer.providerPacePayload(provider: provider, snapshot: usage, weeklyWorkDays: weeklyWorkDays))
     }
 
@@ -354,6 +357,7 @@ extension CodexBarCLI {
                 credits: input.credits,
                 antigravityPlanInfo: input.antigravityPlanInfo,
                 dashboard: input.dashboard,
+                diagnostic: input.diagnostic,
                 weeklyWorkDays: input.command.weeklyWorkDays))
         }
     }
@@ -458,7 +462,7 @@ extension CodexBarCLI {
             let notes = Self.usageTextNotes(
                 provider: provider,
                 sourceMode: effectiveSourceMode,
-                resolvedSourceLabel: source)
+                resolvedSourceLabel: source) + (result.diagnostic.map { [$0] } ?? [])
 
             Self.appendSuccessRenderOutput(
                 UsageSuccessRenderInput(
@@ -474,6 +478,7 @@ extension CodexBarCLI {
                     dashboard: dashboard,
                     effectiveSourceMode: effectiveSourceMode,
                     command: command,
+                    diagnostic: result.diagnostic,
                     notes: notes),
                 output: &output)
         case let .failure(error):

Sources/CodexBarCore/Providers/Codex/CodexProviderDescriptor.swift

@@ -321,7 +321,8 @@ struct CodexOAuthFetchStrategy: ProviderFetchStrategy {
             dashboard: oauthResult.dashboard,
             sourceLabel: oauthResult.sourceLabel,
             strategyID: oauthResult.strategyID,
-            strategyKind: oauthResult.strategyKind)
+            strategyKind: oauthResult.strategyKind,
+            diagnostic: oauthResult.diagnostic)
     }
 
     private static func fetchResetCreditsIfRequested(

Sources/CodexBarCore/Providers/Grok/GrokAuth.swift

@@ -10,6 +10,9 @@ public struct GrokCredentials: Sendable {
     public let firstName: String?
     public let lastName: String?
     public let teamId: String?
+    /// The principal scope reported by Grok's cached OIDC credential, when available.
+    /// Keep this optional because older auth.json entries do not include it.
+    public let principalType: String?
     public let oidcIssuer: String?
     public let oidcClientId: String?
     public let expiresAt: Date?
@@ -25,6 +28,7 @@ public struct GrokCredentials: Sendable {
         firstName: String?,
         lastName: String?,
         teamId: String?,
+        principalType: String? = nil,
         oidcIssuer: String?,
         oidcClientId: String?,
         expiresAt: Date?,
@@ -39,6 +43,7 @@ public struct GrokCredentials: Sendable {
         self.firstName = firstName
         self.lastName = lastName
         self.teamId = teamId
+        self.principalType = principalType
         self.oidcIssuer = oidcIssuer
         self.oidcClientId = oidcClientId
         self.expiresAt = expiresAt
@@ -56,6 +61,11 @@ public struct GrokCredentials: Sendable {
         return Date() >= expiresAt
     }
 
+    public var isTeamPrincipal: Bool {
+        self.principalType?.trimmingCharacters(in: .whitespacesAndNewlines)
+            .caseInsensitiveCompare("team") == .orderedSame
+    }
+
     public var loginMethod: String? {
         switch self.authMode?.lowercased() {
         case "oidc": "SuperGrok"
@@ -147,6 +157,7 @@ public enum GrokCredentialsStore {
             firstName: (entry["first_name"] as? String)?.nilIfEmpty,
             lastName: (entry["last_name"] as? String)?.nilIfEmpty,
             teamId: (entry["team_id"] as? String)?.nilIfEmpty,
+            principalType: (entry["principal_type"] as? String)?.nilIfEmpty,
             oidcIssuer: (entry["oidc_issuer"] as? String)?.nilIfEmpty,
             oidcClientId: (entry["oidc_client_id"] as? String)?.nilIfEmpty,
             expiresAt: Self.parseDate(entry["expires_at"]),
@@ -175,7 +186,9 @@ public enum GrokCredentialsStore {
         guard let value = raw as? String, !value.isEmpty else { return nil }
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
-        if let date = formatter.date(from: value) { return date }
+        if let date = formatter.date(from: value) {
+            return date
+        }
         formatter.formatOptions = [.withInternetDateTime]
         return formatter.date(from: value)
     }

Sources/CodexBarCore/Providers/Grok/GrokProviderDescriptor.swift

@@ -71,8 +71,12 @@ public enum GrokProviderDescriptor {
     private static func primaryLabel(duration seconds: TimeInterval) -> String? {
         guard seconds > 3600 else { return nil }
         let days = Int((seconds / 86400).rounded(.toNearestOrAwayFromZero))
-        if (4...12).contains(days) { return "Weekly" }
-        if (20...45).contains(days) { return "Monthly" }
+        if (4...12).contains(days) {
+            return "Weekly"
+        }
+        if (20...45).contains(days) {
+            return "Monthly"
+        }
         return nil
     }
 }
@@ -90,7 +94,8 @@ struct GrokCLIFetchStrategy: ProviderFetchStrategy {
         let snap = try await probe.fetch(env: context.env)
         return self.makeResult(
             usage: snap.toUsageSnapshot(),
-            sourceLabel: "grok-cli")
+            sourceLabel: "grok-cli",
+            diagnostic: snap.diagnostic)
     }
 
     func shouldFallback(on _: Error, context: ProviderFetchContext) -> Bool {
@@ -101,6 +106,10 @@ struct GrokCLIFetchStrategy: ProviderFetchStrategy {
 struct GrokWebFetchStrategy: ProviderFetchStrategy {
     let id: String = "grok.web"
     let kind: ProviderFetchKind = .web
+    typealias WebBillingFetch = @Sendable () async throws -> (
+        snapshot: GrokWebBillingSnapshot,
+        sourceLabel: String,
+        authenticatedByAuthFile: Bool)
 
     static func canImportBrowserCookies(runtime: ProviderRuntime, env: [String: String]) -> Bool {
         runtime == .app || env["CODEXBAR_ALLOW_BROWSER_COOKIE_IMPORT"] == "1"
@@ -118,7 +127,36 @@ struct GrokWebFetchStrategy: ProviderFetchStrategy {
     }
 
     func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
-        let (webBilling, sourceLabel, authenticatedByAuthFile) = try await self.fetchWebBilling(context: context)
+        try await self.fetch(context, webBilling: { [self] in
+            try await self.fetchWebBilling(context: context)
+        })
+    }
+
+    func fetch(
+        _ context: ProviderFetchContext,
+        webBilling fetchWebBilling: @escaping WebBillingFetch) async throws -> ProviderFetchResult
+    {
+        let webBilling: GrokWebBillingSnapshot
+        let sourceLabel: String
+        let authenticatedByAuthFile: Bool
+        do {
+            (webBilling, sourceLabel, authenticatedByAuthFile) = try await fetchWebBilling()
+        } catch GrokWebBillingError.teamUsageUnsupported {
+            guard let authState = try? GrokCredentialsStore.load(env: context.env),
+                  !authState.isExpired,
+                  authState.isTeamPrincipal
+            else {
+                throw GrokWebBillingError.teamUsageUnsupported
+            }
+            let identitySnapshot = GrokStatusProbe.identityOnlySnapshot(
+                credentials: authState,
+                localSummary: GrokLocalSessionScanner.summarize(env: context.env),
+                cliVersion: GrokStatusProbe.detectVersion(env: context.env))
+            return self.makeResult(
+                usage: identitySnapshot.toUsageSnapshot(),
+                sourceLabel: "grok-web",
+                diagnostic: identitySnapshot.diagnostic)
+        }
         let credentials = Self.credentialsForWebBillingSnapshot(
             credentials: try? GrokCredentialsStore.load(env: context.env),
             authenticatedByAuthFile: authenticatedByAuthFile)
@@ -198,17 +236,21 @@ struct GrokWebFetchStrategy: ProviderFetchStrategy {
                 credentials: credentials)
         }
         var lastError: Error?
+        var teamUsageUnsupportedError: Error?
         for session in sessions {
             for authCredentials in Self.cookieAuthAttempts(credentials: credentials) {
                 do {
                     let snapshot = try await fetchSnapshot(session.cookieHeader, authCredentials)
                     return (snapshot, session.sourceLabel)
                 } catch {
+                    if case GrokWebBillingError.teamUsageUnsupported = error {
+                        teamUsageUnsupportedError = error
+                    }
                     lastError = error
                 }
             }
         }
-        throw lastError ?? GrokWebBillingError.missingCredentials
+        throw teamUsageUnsupportedError ?? lastError ?? GrokWebBillingError.missingCredentials
     }
 
     static func cookieAuthAttempts(credentials: GrokCredentials?) -> [GrokCredentials?] {