fix(providers): surface quota authentication failures

Author: pavelhov

app/Sources/MenuBarCore/BuildProvenance.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+/// Presentation-only source identity stamped by `build:macos`.
+///
+/// Release version and source revision answer different questions: two worktrees can
+/// build version 2.10.2 from different commits. Keep the full revision in Info.plist
+/// and use this bounded form in diagnostics/tooltips.
+public enum BuildProvenance {
+    public static func shortRevision(_ raw: Any?) -> String? {
+        guard let value = raw as? String else { return nil }
+        let dirty = value.hasSuffix("-dirty")
+        let revision = dirty ? String(value.dropLast("-dirty".count)) : value
+        guard revision.count == 40,
+              revision.unicodeScalars.allSatisfy({ scalar in
+                  (48...57).contains(scalar.value) || (65...70).contains(scalar.value)
+                      || (97...102).contains(scalar.value)
+              })
+        else { return nil }
+        return String(revision.prefix(8)) + (dirty ? "-dirty" : "")
+    }
+}

app/Sources/MenuBarCore/PollingCoordinator.swift

@@ -27,6 +27,9 @@ public actor PollingCoordinator {
     /// immediately reopening the popover dropped the reopen's refresh entirely: the old
     /// cycle exited on its generation guard and the new one had already been rejected.
     private var pendingOpenRefresh = false
+    /// Preserve a user-requested server-cache bypass when it arrives during another
+    /// cycle; reducing it to a normal pending refresh would make the button lie.
+    private var pendingQuotaForceRefresh = false
     /// A stale-while-revalidate startup-health response is intentionally conservative.
     /// Keep the neutral/last-known state while the background probe catches up, but
     /// bound retries so a genuinely broken diagnostic eventually remains visible.
@@ -87,9 +90,19 @@ public actor PollingCoordinator {
     /// while the provider quota read still respects
     /// the 60s interval so reopening the popover repeatedly does not hammer the proxy.
     public func refresh(includeHeavy: Bool = false) async {
+        await performRefresh(includeHeavy: includeHeavy, forceQuotaRefresh: false)
+    }
+
+    /// Internal pairing keeps `forceQuotaRefresh` from being requested without the
+    /// popover-heavy reads that can actually consume it.
+    private func performRefresh(
+        includeHeavy: Bool,
+        forceQuotaRefresh: Bool
+    ) async {
         // Overlapping cycles publish interleaved state and double the request rate.
         guard !refreshInFlight else {
             if includeHeavy { pendingOpenRefresh = true }
+            if forceQuotaRefresh { pendingQuotaForceRefresh = true }
             return
         }
         refreshInFlight = true
@@ -154,12 +167,12 @@ public actor PollingCoordinator {
 
             // Rate-limit on ATTEMPT, not success, so a persistently failing endpoint is
             // not retried on every two-second activity cycle.
-            let quotaDue = lastQuotaAttempt.map {
+            let quotaDue = forceQuotaRefresh || (lastQuotaAttempt.map {
                 Date().timeIntervalSince($0) >= Self.heavyInterval
-            } ?? true
+            } ?? true)
             if quotaDue, isCurrent(cycle) {
                 lastQuotaAttempt = Date()
-                await refreshQuotas(cycle: cycle)
+                await refreshQuotas(cycle: cycle, forceRefresh: forceQuotaRefresh)
             }
         }
 
@@ -169,20 +182,22 @@ public actor PollingCoordinator {
     }
 
     /// User-initiated refresh: activity is immediate and quotas bypass their normal
-    /// sixty-second cadence exactly once.
+    /// sixty-second cadence and the proxy's five-minute cache exactly once.
     public func forceRefresh() async {
-        lastQuotaAttempt = nil
-        await refresh(includeHeavy: true)
+        await performRefresh(includeHeavy: true, forceQuotaRefresh: true)
     }
 
     /// Runs a refresh that arrived while another cycle held the lock.
     private func drainPendingRefresh() async {
         guard pendingOpenRefresh, popoverOpen else {
             pendingOpenRefresh = false
+            pendingQuotaForceRefresh = false
             return
         }
+        let forceQuotaRefresh = pendingQuotaForceRefresh
         pendingOpenRefresh = false
-        await refresh(includeHeavy: true)
+        pendingQuotaForceRefresh = false
+        await performRefresh(includeHeavy: true, forceQuotaRefresh: forceQuotaRefresh)
     }
 
     /// Reads that are only meaningful while the popover is open.
@@ -219,11 +234,12 @@ public actor PollingCoordinator {
 
     /// The slower provider-quota read. A failed refresh preserves the last successful
     /// rows and their upstream freshness timestamps.
-    private func refreshQuotas(cycle: Int) async {
+    private func refreshQuotas(cycle: Int, forceRefresh: Bool) async {
         guard isCurrent(cycle) else { return }
-        if let quotas = try? await client.quotas() {
+        if let envelope = try? await client.quotas(forceRefresh: forceRefresh) {
             guard isCurrent(cycle) else { return }
-            snapshot.quotas = quotas
+            snapshot.quotas = envelope.reports ?? []
+            snapshot.quotaAvailability = envelope.availability ?? []
             snapshot.quotasLoaded = true
         }
     }

app/Sources/MenuBarCore/ProxyClient.swift

@@ -71,11 +71,6 @@ private struct HealthIdentity: Decodable {
     let port: Int
 }
 
-private struct QuotaEnvelope: Decodable {
-    let generatedAt: Double?
-    let reports: [QuotaReport]?
-}
-
 private struct EmptyBody: Encodable {}
 
 public struct RestartAccepted: Decodable, Equatable, Sendable {
@@ -169,12 +164,11 @@ public actor ProxyClient {
         try await authenticatedGet("api/agent-activity")
     }
 
-    public func quotas(forceRefresh: Bool = false) async throws -> [QuotaReport] {
-        let envelope: QuotaEnvelope = try await authenticatedGet(
+    public func quotas(forceRefresh: Bool = false) async throws -> ProviderQuotaEnvelope {
+        try await authenticatedGet(
             "api/provider-quotas",
             query: forceRefresh ? [URLQueryItem(name: "refresh", value: "1")] : []
         )
-        return envelope.reports ?? []
     }
 
     public func restart() async throws -> RestartAccepted {

app/Sources/MenuBarCore/ProxyModels.swift

@@ -143,6 +143,53 @@ public struct QuotaReport: Decodable, Equatable, Sendable {
     public let updatedAt: Double?
 }
 
+public enum ProviderQuotaAvailabilityState: Equatable, Sendable, Decodable {
+    case available
+    case stale
+    case unavailable
+    case unknown
+
+    public init(from decoder: Decoder) throws {
+        switch try decoder.singleValueContainer().decode(String.self) {
+        case "available": self = .available
+        case "stale": self = .stale
+        case "unavailable": self = .unavailable
+        default: self = .unknown
+        }
+    }
+}
+
+public enum ProviderQuotaUnavailableReason: Equatable, Sendable, Decodable {
+    case reauthRequired
+    case localCLIRefreshRequired
+    case upstreamUnavailable
+    case unknown
+
+    public init(from decoder: Decoder) throws {
+        switch try decoder.singleValueContainer().decode(String.self) {
+        case "reauth_required": self = .reauthRequired
+        case "local_cli_refresh_required": self = .localCLIRefreshRequired
+        case "upstream_unavailable": self = .upstreamUnavailable
+        default: self = .unknown
+        }
+    }
+}
+
+public struct ProviderQuotaAvailability: Decodable, Equatable, Sendable {
+    public let provider: String
+    public let status: ProviderQuotaAvailabilityState
+    public let reason: ProviderQuotaUnavailableReason?
+    public let checkedAt: Double?
+}
+
+/// Additive `/api/provider-quotas` envelope. Older proxies omit `availability`; the
+/// companion preserves its existing generic unavailable fallback in that case.
+public struct ProviderQuotaEnvelope: Decodable, Equatable, Sendable {
+    public let generatedAt: Double?
+    public let reports: [QuotaReport]?
+    public let availability: [ProviderQuotaAvailability]?
+}
+
 public enum AgentActivityRole: String, Decodable, Equatable, Sendable {
     case primary
     case subagent
@@ -308,28 +355,35 @@ public struct ProviderSummary: Decodable, Equatable, Sendable {
 /// Tray-only display state. An unavailable row is structurally incapable of carrying
 /// a fabricated percentage, reset, source, or freshness timestamp.
 public enum ProviderQuotaRow: Equatable, Sendable {
-    case available(QuotaReport)
-    case unavailable(ProviderSummary)
+    case available(QuotaReport, ProviderQuotaAvailability?)
+    case unavailable(ProviderSummary, ProviderQuotaAvailability?)
 
     public var provider: String {
         switch self {
-        case .available(let report): return report.provider
-        case .unavailable(let summary): return summary.name
+        case .available(let report, _): return report.provider
+        case .unavailable(let summary, _): return summary.name
         }
     }
 
     public var label: String? {
-        if case .available(let report) = self { return report.label }
+        if case .available(let report, _) = self { return report.label }
         return nil
     }
 
     public var report: QuotaReport? {
-        if case .available(let report) = self { return report }
+        if case .available(let report, _) = self { return report }
         return nil
     }
 
+    public var availability: ProviderQuotaAvailability? {
+        switch self {
+        case .available(_, let availability), .unavailable(_, let availability):
+            return availability
+        }
+    }
+
     public var isUnavailable: Bool {
-        if case .unavailable = self { return true }
+        if case .unavailable(_, _) = self { return true }
         return false
     }
 
@@ -340,7 +394,15 @@ public extension ProxySnapshot {
     /// Join one completed provider inventory with the latest completed quota snapshot.
     /// Enabled configured providers form the left side; actual reports always win.
     var providerQuotaRows: [ProviderQuotaRow] {
-        guard providersLoaded, quotasLoaded else { return quotas.map(ProviderQuotaRow.available) }
+        let availabilityByProvider = Dictionary(
+            quotaAvailability.map { ($0.provider.lowercased(), $0) },
+            uniquingKeysWith: { first, _ in first }
+        )
+        guard providersLoaded, quotasLoaded else {
+            return quotas.map {
+                .available($0, availabilityByProvider[$0.provider.lowercased()])
+            }
+        }
 
         var reportsByProvider: [String: QuotaReport] = [:]
         for report in quotas {
@@ -350,10 +412,11 @@ public extension ProxySnapshot {
 
         var rows: [ProviderQuotaRow] = []
         for provider in providers where provider.isEnabled {
+            let availability = availabilityByProvider[provider.name.lowercased()]
             if let report = reportsByProvider.removeValue(forKey: provider.name.lowercased()) {
-                rows.append(.available(report))
+                rows.append(.available(report, availability))
             } else if provider.supportsQuotaReporting {
-                rows.append(.unavailable(provider))
+                rows.append(.unavailable(provider, availability))
             }
         }
         return rows

app/Sources/MenuBarCore/ProxySnapshot.swift

@@ -78,6 +78,7 @@ public struct ProxySnapshot: Equatable, Sendable {
     public var state: ProxyState
     public var endpoint: ProxyEndpoint
     public var quotas: [QuotaReport]
+    public var quotaAvailability: [ProviderQuotaAvailability]
     public var activity: AgentActivitySnapshot?
     public var providers: [ProviderSummary]
     public var lastUpdated: Date?
@@ -99,6 +100,7 @@ public struct ProxySnapshot: Equatable, Sendable {
         state: ProxyState = .loading,
         endpoint: ProxyEndpoint,
         quotas: [QuotaReport] = [],
+        quotaAvailability: [ProviderQuotaAvailability] = [],
         activity: AgentActivitySnapshot? = nil,
         providers: [ProviderSummary] = [],
         lastUpdated: Date? = nil,
@@ -113,6 +115,7 @@ public struct ProxySnapshot: Equatable, Sendable {
         self.state = state
         self.endpoint = endpoint
         self.quotas = quotas
+        self.quotaAvailability = quotaAvailability
         self.activity = activity
         self.providers = providers
         self.lastUpdated = lastUpdated

app/Sources/MenuBarCoreTests/ModelDecodingSuite.swift

@@ -35,6 +35,23 @@ enum ModelDecodingSuite {
     """
 
     static func run(_ t: TestRunner) {
+        t.test("build provenance: formats only stamped git revisions") {
+            t.equal(
+                BuildProvenance.shortRevision(
+                    "d986bada3d4c7986b8d127b2d60eabfc81713d25"
+                ),
+                "d986bada"
+            )
+            t.equal(
+                BuildProvenance.shortRevision(
+                    "d986bada3d4c7986b8d127b2d60eabfc81713d25-dirty"
+                ),
+                "d986bada-dirty"
+            )
+            t.isNil(BuildProvenance.shortRevision("2.10.2"), "release version is not provenance")
+            t.isNil(BuildProvenance.shortRevision("unknown"), "unknown source")
+        }
+
         t.test("health: decodes the live startup-health payload") {
             let health = try decode(StartupHealth.self, liveHealth)
             t.equal(health.status, "at-risk")
@@ -83,6 +100,27 @@ enum ModelDecodingSuite {
             t.equal(byProvider["xai"]?.providerLabel, "xAI Grok")
         }
 
+        t.test("quotas: availability reasons are actionable and forward compatible") {
+            let envelope = try decode(ProviderQuotaEnvelope.self, """
+            {"generatedAt":1784915336899,"reports":[],"availability":[
+              {"provider":"xai","status":"unavailable",
+               "reason":"local_cli_refresh_required","checkedAt":1784915336899},
+              {"provider":"future","status":"future-state",
+               "reason":"future-reason","checkedAt":1784915336899}]}
+            """)
+            t.equal(envelope.availability?.count, 2)
+            t.equal(envelope.availability?.first?.status, .unavailable)
+            t.equal(envelope.availability?.first?.reason, .localCLIRefreshRequired)
+            t.equal(envelope.availability?.last?.status, .unknown)
+            t.equal(envelope.availability?.last?.reason, .unknown)
+
+            let oldProxy = try decode(
+                ProviderQuotaEnvelope.self,
+                #"{"generatedAt":1,"reports":[]}"#
+            )
+            t.isNil(oldProxy.availability, "older proxy fallback")
+        }
+
         t.test("providers: quota presentation eligibility mirrors supported probes") {
             let providers = try decode([ProviderSummary].self, """
             [
@@ -115,6 +153,10 @@ enum ModelDecodingSuite {
                 state: .running(StartupHealth(status: "protected")),
                 endpoint: .default,
                 quotas: reports,
+                quotaAvailability: try decode([ProviderQuotaAvailability].self, """
+                [{"provider":"openai","status":"unavailable",
+                  "reason":"reauth_required","checkedAt":1}]
+                """),
                 providers: providers,
                 providersLoaded: true,
                 quotasLoaded: true
@@ -124,6 +166,10 @@ enum ModelDecodingSuite {
             t.equal(rows.filter { $0.provider == "xai" }.count, 1, "actual report wins")
             t.equal(rows.first { $0.provider == "xai" }?.isUnavailable, false)
             t.equal(rows.first { $0.provider == "openai" }?.isUnavailable, true)
+            t.equal(
+                rows.first { $0.provider == "openai" }?.availability?.reason,
+                .reauthRequired
+            )
         }
 
         t.test("quotas: nested freshness wins and report freshness fills the gap") {