test: harden the provider special-case gatekeeper and derive its findings (#2693)

* test: harden provider architecture gatekeeper

* refactor: derive provider presentation policies

* test: pin provider dispatch constructs

* test: document gatekeeper catalog lint scope

---------

Co-authored-by: Peter Steinberger <steipete@clawstudio.local>

Author: steipete

Sources/CodexBar/CostHistoryChartMenuView.swift

@@ -300,7 +300,14 @@ struct CostHistoryChartMenuView: View {
     }
 
     static func estimateDisclaimer(provider: UsageProvider) -> String? {
-        provider == .codex ? L("codex_api_estimate_hint") : nil
+        guard let hint = ProviderDescriptorRegistry.descriptor(for: provider).tokenCost.chartEstimateDisclaimer else {
+            return nil
+        }
+        return switch hint {
+        case let .localized(key): L(key)
+        case .estimate: UsageFormatter.costEstimateHint(provider: provider)
+        case let .literal(text): L(text)
+        }
     }
 
     private struct Model {

Sources/CodexBar/InlineUsageDashboardContent.swift

@@ -164,7 +164,8 @@ extension UsageMenuCardView.Model {
                 : historyDays == 30
                 ? "30d"
                 : String(format: L("Last %d days"), historyDays))
-        let historyTitle = provider == .codex ? codexHistoryPeriod : defaultHistoryTitle
+        let tokenCost = ProviderDescriptorRegistry.descriptor(for: provider).tokenCost
+        let historyTitle = tokenCost.historyTitleStyle == .compact ? codexHistoryPeriod : defaultHistoryTitle
         let tokenHistoryTitle = snapshot.historyLabel.map { "\($0) \(L("tokens"))" }
             ?? (historyDays == 1
                 ? L("Today tokens")
@@ -193,7 +194,7 @@ extension UsageMenuCardView.Model {
                 accessibilityValue: "\(entry.date): \(convertedString(cost))")
         }
         let latest = CostUsageTokenSnapshot.latestEntry(in: snapshot.daily)
-        let usesLatestPrimary = provider == .bedrock || provider == .mistral
+        let usesLatestPrimary = tokenCost.primaryValue == .latestDaily
         let primaryCostUSD = usesLatestPrimary ? latest?.costUSD : snapshot.sessionCostUSD
         var details: [String] = []
         if comparisonPeriodsEnabled {
@@ -211,16 +212,16 @@ extension UsageMenuCardView.Model {
         if let topModel = Self.topCostModel(from: snapshot.daily) {
             details.append("\(L("Top model")): \(Self.shortModelName(topModel))")
         }
-        if provider == .codex {
-            details.append(L("codex_api_estimate_hint"))
+        let hintLines = Self.tokenUsageHintLines(provider: provider)
+        if tokenCost.hintPlacement == .beforeRequestHistory {
+            details.append(contentsOf: hintLines)
         }
-        if provider != .groq {
+        if tokenCost.showsRequestHistory {
             if let requestCount = snapshot.last30DaysRequests {
                 details
                     .append("\(requestHistoryTitle): \(UsageFormatter.tokenCountString(requestCount)) \(L("requests"))")
             }
-            if provider != .codex {
-                let hintLines = Self.tokenUsageHintLines(provider: provider)
+            if tokenCost.hintPlacement == .afterRequestHistory {
                 if hintLines.isEmpty == false {
                     details.append(contentsOf: hintLines)
                 } else {

Sources/CodexBar/MenuCardView+Costs.swift

@@ -376,16 +376,13 @@ extension UsageMenuCardView.Model {
     }
 
     static func providerCostSection(
-        provider: UsageProvider,
         cost: ProviderCostSnapshot?,
+        style: ProviderCostMenuCardStyle,
         isClaudeAdminAPI: Bool = false,
         preferredCurrencyCode: String = "auto") -> ProviderCostSection?
     {
-        if provider == .manus {
-            return nil
-        }
+        guard style != .hidden else { return nil }
         guard let cost else { return nil }
-        guard provider != .synthetic else { return nil }
 
         /// Formats a cost value using the user's currency preference.
         func formatCost(_ value: Double, providerCurrency: String? = nil) -> String {
@@ -395,7 +392,7 @@ extension UsageMenuCardView.Model {
                 providerCurrency: providerCurrency ?? cost.currencyCode)
         }
 
-        if provider == .factory || provider == .devin, cost.period == "Extra usage balance" {
+        if style == .extraUsageBalance {
             let balance = formatCost(cost.used)
             return ProviderCostSection(
                 title: L("Extra usage"),
@@ -404,7 +401,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .opencodego, cost.period == "Zen balance" {
+        if style == .zenBalance {
             let balance = formatCost(cost.used)
             return ProviderCostSection(
                 title: L("Zen balance"),
@@ -413,7 +410,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .minimax, cost.period == "MiniMax points balance" {
+        if style == .pointsBalance {
             let balance = String(format: "%.0f", cost.used)
             return ProviderCostSection(
                 title: L("Credits"),
@@ -422,7 +419,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .xai, cost.period == "Prepaid credits" {
+        if style == .prepaidCredits {
             let balance = UsageFormatter.currencyString(cost.used, currencyCode: cost.currencyCode)
             return ProviderCostSection(
                 title: L("Credits"),
@@ -431,7 +428,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .zenmux || provider == .neuralwatt {
+        if style == .payAsYouGoBalance {
             let balance = formatCost(cost.used)
             return ProviderCostSection(
                 title: L("metric_mistral_payg"),
@@ -440,7 +437,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .claude {
+        if style == .claude {
             if isClaudeAdminAPI {
                 let spend = formatCost(cost.used)
                 let periodLabel = Self.localizedPeriodLabel(cost.period ?? "Last 30 days")
@@ -479,9 +476,7 @@ extension UsageMenuCardView.Model {
                 showsInProviderDetails: false)
         }
 
-        if provider == .openai || provider == .litellm || provider == .aiand,
-           cost.limit <= 0
-        {
+        if style == .apiSpend {
             let spend = formatCost(cost.used)
             let periodLabel = Self.localizedPeriodLabel(cost.period ?? "Last 30 days")
             return ProviderCostSection(
@@ -491,11 +486,7 @@ extension UsageMenuCardView.Model {
                 percentLine: nil)
         }
 
-        if provider == .litellm {
-            return nil
-        }
-
-        if provider == .clawrouter, cost.limit <= 0 {
+        if style == .clawRouter, cost.limit <= 0 {
             let spend = formatCost(cost.used)
             return ProviderCostSection(
                 title: "ClawRouter spend",
@@ -510,7 +501,7 @@ extension UsageMenuCardView.Model {
         let limit: String
         let title: String
 
-        if provider == .clawrouter {
+        if style == .clawRouter {
             title = "Monthly budget"
             used = formatCost(cost.used)
             limit = formatCost(cost.limit)

Sources/CodexBar/MenuCardView+ModelHelpers.swift

@@ -428,11 +428,12 @@ extension UsageMenuCardView.Model {
     }
 
     static func progressColor(for provider: UsageProvider) -> Color {
-        if provider == .elevenlabs {
+        let branding = ProviderDescriptorRegistry.descriptor(for: provider).branding
+        if branding.progressColorStyle == .label {
             return Color(nsColor: .labelColor)
         }
 
-        let color = ProviderDescriptorRegistry.descriptor(for: provider).branding.color
+        let color = branding.color
         return Color(red: color.red, green: color.green, blue: color.blue)
     }
 

Sources/CodexBar/MenuCardView.swift

@@ -911,7 +911,8 @@ extension UsageMenuCardView.Model {
         let openAIAPIUsage = input.snapshot?.openAIAPIUsage
         let inlineUsageDashboard = Self.inlineUsageDashboard(input: input)
         let usageNotes = Self.usageNotes(input: input)
-        let menuCard = ProviderDescriptorRegistry.descriptor(for: input.provider).presentation.menuCard
+        let presentation = ProviderDescriptorRegistry.descriptor(for: input.provider).presentation
+        let menuCard = presentation.menuCard
         let rawCreditsText: String? = if !menuCard.showsCreditsSection ||
             !input.showOptionalCreditsAndExtraUsage
         {
@@ -932,12 +933,15 @@ extension UsageMenuCardView.Model {
         let showsProviderCost = menuCard.showsProviderCost(context: ProviderCostVisibilityContext(
             snapshot: input.snapshot,
             showOptionalUsage: input.showOptionalCreditsAndExtraUsage))
+        let providerCostStyle = input.snapshot.map {
+            presentation.cost(snapshot: $0).menuCardStyle
+        } ?? .generic
         let providerCost: ProviderCostSection? = if !showsProviderCost {
             nil
         } else {
             Self.providerCostSection(
-                provider: input.provider,
                 cost: input.snapshot?.providerCost,
+                style: providerCostStyle,
                 isClaudeAdminAPI: isClaudeAdminAPI,
                 preferredCurrencyCode: input.preferredCurrencyCode)
         }
@@ -989,10 +993,13 @@ extension UsageMenuCardView.Model {
     private static func visibleProviderDetails(input: Input) -> [ProviderDetailSection] {
         var details = input.snapshot?.details ?? []
         if !input.showOptionalCreditsAndExtraUsage {
-            if input.provider == .sakana {
+            let policy = ProviderDescriptorRegistry.descriptor(for: input.provider).presentation.optionalDetails
+            if policy.hidesAllWithoutOptionalUsage {
                 details = []
-            } else if input.provider == .minimax {
-                details.removeAll { $0.title == "Billing history" }
+            } else if !policy.hiddenTitlesWithoutOptionalUsage.isEmpty {
+                details.removeAll { section in
+                    section.title.map(policy.hiddenTitlesWithoutOptionalUsage.contains) == true
+                }
             }
         }
         guard input.hidePersonalInfo else { return details }

Sources/CodexBar/MenuDescriptor.swift

@@ -390,10 +390,13 @@ struct MenuDescriptor {
                 usage: mistralUsage,
                 preferredCurrencyCode: preferredCurrencyCode)
         }
-        if provider != .sakana || showOptionalUsage {
-            let details = provider == .minimax && !showOptionalUsage
-                ? snapshot.details.filter { $0.title != "Billing history" }
-                : snapshot.details
+        let policy = ProviderDescriptorRegistry.descriptor(for: provider).presentation.optionalDetails
+        if !policy.hidesAllWithoutOptionalUsage || showOptionalUsage {
+            let details = showOptionalUsage || policy.hiddenTitlesWithoutOptionalUsage.isEmpty
+                ? snapshot.details
+                : snapshot.details.filter { section in
+                    section.title.map(policy.hiddenTitlesWithoutOptionalUsage.contains) != true
+                }
             for section in details {
                 for row in section.rows {
                     let value = [row.value, row.secondaryValue].compactMap(\.self).joined(separator: " · ")

Sources/CodexBar/PreferencesDebugPane.swift

@@ -7,6 +7,7 @@ struct DebugPane: View {
     @Bindable var settings: SettingsStore
     @Bindable var store: UsageStore
     @AppStorage("debugFileLoggingEnabled") private var debugFileLoggingEnabled = false
+    // Provider-specific by design: debug probe, fetch, and error pickers historically start on Codex.
     @State private var currentLogProvider: UsageProvider = .codex
     @State private var currentFetchProvider: UsageProvider = .codex
     @State private var isLoadingLog = false
@@ -126,6 +127,7 @@ struct DebugPane: View {
                         }
                         .disabled(self.isLoadingLog && self.logText.isEmpty)
 
+                        // Provider-specific by design: only Claude exposes the raw parser dump diagnostic.
                         if self.currentLogProvider == .claude {
                             Button { self.loadClaudeDump() } label: {
                                 Label(L("load_parse_dump"), systemImage: "doc.text.magnifyingglass")

Sources/CodexBar/ProviderRegistry.swift

@@ -79,6 +79,7 @@ struct ProviderRegistry {
                         },
                         providerManualTokenUpdater: { provider, token in
                             await MainActor.run {
+                                // Provider-specific by design: StepFun rotates its legacy app-owned session token.
                                 if provider == .stepfun {
                                     settings.stepfunToken = token
                                 }
@@ -155,6 +156,7 @@ struct ProviderRegistry {
         // quotas, and dashboard data. Token-cost/session history is intentionally handled
         // separately because it is provider-level local telemetry from this Mac's Codex sessions,
         // not account-owned remote state.
+        // Provider-specific by design: managed Codex account selection scopes the fetcher's CODEX_HOME.
         if provider == .codex {
             let codexActiveSource = codexActiveSourceOverride ?? settings.codexResolvedActiveSource
             if let managedHomePath = settings.managedCodexRemoteHomePath(forActiveSource: codexActiveSource) {
@@ -169,6 +171,7 @@ struct ProviderRegistry {
     }
 
     static func makeFetcher(base: UsageFetcher, provider: UsageProvider, env: [String: String]) -> UsageFetcher {
+        // Provider-specific by design: a Codex account scope needs a fetcher rebuilt with its selected CODEX_HOME.
         guard provider == .codex else { return base }
         return UsageFetcher(environment: env)
     }

Sources/CodexBar/SettingsStore.swift

@@ -410,6 +410,7 @@ extension SettingsStore {
         config: CodexBarConfig,
         hadExistingConfig: Bool) -> Bool
     {
+        // Provider-specific by design: the legacy OpenAI web-access flag was inferred from Codex's cookie config.
         guard let codex = config.providerConfig(for: .codex) else { return false }
         if let cookieSource = codex.cookieSource {
             return cookieSource.isEnabled
@@ -732,6 +733,7 @@ extension SettingsStore {
 
         // Tagged builds through v0.35 used primary=Claude, secondary=Gemini Pro,
         // and tertiary=Gemini Flash. Remap those meanings once to the two-pool schema.
+        // Provider-specific by design: this one-time migration rewrites Antigravity's historical persisted lanes.
         var migrated = preferences
         switch MenuBarMetricPreference(rawValue: migrated[UsageProvider.antigravity.rawValue] ?? "") {
         case .primary:

Sources/CodexBar/StatusItemController+Actions.swift

@@ -468,6 +468,7 @@ extension StatusItemController: StatusItemMenuPersistentActionDelegate {
     }
 
     @objc func openTerminalCommand(_ sender: NSMenuItem) {
+        // Provider-specific by design: legacy terminal menu items without a command payload open Claude.
         let command = sender.representedObject as? String ?? "claude"
         self.openTerminal(command: command)
     }