fix: cap session row by binding quotas (#2841)

Yuxin-Qiao · web-flow · commit 4f0ac0680cd2 · 2026-08-10T07:32:55.000-07:00
Co-authored-by: Yuxin Qiao &lt;104957188+Yuxin-Qiao@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## 0.49.2 — 2026-08-10
 
 ### Fixed
+- Menu cards: show session quota as exhausted until the final reset of every binding weekly/monthly plan lane, while preserving session-specific details and independent purchased credits (#2840). Thanks @Yuxin-Qiao!
 - Plugins: honor the “Usage bars fill” remaining/used setting in user-installed provider cards, keeping percentage labels and bar direction aligned (#2749). Thanks @RyloRiz!
 - Sub2API: localize and group menu-card quota labels and request, token, and cost totals into a compact usage summary (#2835). Thanks @weirdo-adam!
 - Codex: avoid repeatedly converting historical token snapshots during cost-cache refreshes, preventing sustained CPU usage on large session histories.
diff --git a/Sources/CodexBar/MenuCardView+ModelHelpers.swift b/Sources/CodexBar/MenuCardView+ModelHelpers.swift
@@ -2,6 +2,29 @@ import CodexBarCore
 import SwiftUI
 
 extension UsageMenuCardView.Model {
+    /// Resolves the displayed primary percentage/reset through the provider's binding quotas.
+    /// Primary-owned detail text remains sourced from the raw primary window.
+    static func bindingQuotaProjection(
+        input: Input,
+        primary: RateWindow,
+        snapshot: UsageSnapshot) -> RateWindowBindingQuotaProjection?
+    {
+        let lanes = ProviderDescriptorRegistry.descriptor(for: input.provider)
+            .presentation.primaryBindingQuotaLanes
+        let bindingWindows = lanes.compactMap { lane -> RateWindow? in
+            switch lane {
+            case .primary: nil
+            case .secondary: snapshot.secondary
+            case .tertiary: snapshot.tertiary
+            }
+        }
+        guard !bindingWindows.isEmpty else { return nil }
+        return RateWindow.bindingQuotaProjection(
+            primary: primary,
+            bindingLanes: bindingWindows,
+            now: input.now)
+    }
+
     struct PaceDetail {
         let leftLabel: String
         let rightLabel: String?
diff --git a/Sources/CodexBar/MenuCardView.swift b/Sources/CodexBar/MenuCardView.swift
@@ -1236,6 +1236,10 @@ extension UsageMenuCardView.Model {
             metrics.append(Self.primaryMetric(
                 input: input,
                 primary: primary,
+                bindingProjection: Self.bindingQuotaProjection(
+                    input: input,
+                    primary: primary,
+                    snapshot: snapshot),
                 percentStyle: percentStyle,
                 title: labels.primary))
         }
@@ -1317,6 +1321,7 @@ extension UsageMenuCardView.Model {
     private static func primaryMetric(
         input: Input,
         primary: RateWindow,
+        bindingProjection: RateWindowBindingQuotaProjection? = nil,
         percentStyle: PercentStyle,
         title: String? = nil) -> Metric
     {
@@ -1329,13 +1334,26 @@ extension UsageMenuCardView.Model {
             primary: primary)
         Self.applyPrimaryBalancePresentation(&presentation, input: input, primary: primary)
         Self.applyPrimaryResetPresentation(&presentation, input: input, primary: primary)
-        Self.applyPrimaryPacePresentation(&presentation, input: input, primary: primary)
+        if bindingProjection == nil {
+            Self.applyPrimaryPacePresentation(&presentation, input: input, primary: primary)
+        }
         Self.applyPrimaryFinalOverrides(&presentation, input: input, primary: primary)
+        if let bindingProjection {
+            let resetWindow = RateWindow(
+                usedPercent: bindingProjection.usedPercent,
+                windowMinutes: primary.windowMinutes,
+                resetsAt: bindingProjection.resetsAt,
+                resetDescription: bindingProjection.resetDescription)
+            presentation.resetText = Self.resetText(
+                for: resetWindow,
+                style: input.resetTimeDisplayStyle,
+                now: input.now)
+        }
+        let displayedUsedPercent = bindingProjection?.usedPercent ?? primary.usedPercent
         return Metric(
             id: "primary",
             title: title ?? L(input.metadata.sessionLabel),
-            percent: Self.clamped(
-                input.usageBarsShowUsed ? primary.usedPercent : primary.remainingPercent),
+            percent: Self.clamped(input.usageBarsShowUsed ? displayedUsedPercent : 100 - displayedUsedPercent),
             percentStyle: percentStyle,
             statusText: presentation.statusText,
             resetText: presentation.resetText,
diff --git a/Sources/CodexBarCore/Providers/Alibaba/AlibabaCodingPlanProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Alibaba/AlibabaCodingPlanProviderDescriptor.swift
@@ -84,8 +84,9 @@ public enum AlibabaCodingPlanProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "Alibaba Coding Plan cost summary is not supported." }),
             pace: .calendarMonthResetWindow,
-            presentation: ProviderUsagePresentation(menuCard: ProviderMenuCardPresentation(
-                showsPrimaryBalanceDescription: true)),
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary, .tertiary],
+                menuCard: ProviderMenuCardPresentation(showsPrimaryBalanceDescription: true)),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .web, .api],
                 pipeline: ProviderFetchPipeline(resolveStrategies: self.resolveStrategies)),
diff --git a/Sources/CodexBarCore/Providers/Alibaba/AlibabaTokenPlanProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Alibaba/AlibabaTokenPlanProviderDescriptor.swift
@@ -95,8 +95,9 @@ public enum AlibabaTokenPlanProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "Alibaba Token Plan cost summary is not supported." }),
             pace: .calendarMonthResetWindow,
-            presentation: ProviderUsagePresentation(menuCard: ProviderMenuCardPresentation(
-                showsPrimaryBalanceDescription: true)),
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary],
+                menuCard: ProviderMenuCardPresentation(showsPrimaryBalanceDescription: true)),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .web],
                 pipeline: ProviderFetchPipeline(resolveStrategies: self.resolveStrategies)),
diff --git a/Sources/CodexBarCore/Providers/Chutes/ChutesProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Chutes/ChutesProviderDescriptor.swift
@@ -44,6 +44,7 @@ public enum ChutesProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "Chutes cost history is not available from CodexBar." }),
             presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary],
                 menuCard: ProviderMenuCardPresentation(
                     showsPrimaryBalanceDescription: true,
                     hidesPrimaryResetWithoutDate: true),
diff --git a/Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift
@@ -196,6 +196,7 @@ public enum ClaudeProviderDescriptor {
                     return series
                 },
                 secondaryGloballyCapsPrimary: true,
+                primaryBindingQuotaLanes: [.secondary],
                 menuCard: ProviderMenuCardPresentation(
                     costVisibilityResolver: { context in
                         context.showOptionalUsage || context.snapshot?.loginMethod(for: .claude) == "Admin API"
diff --git a/Sources/CodexBarCore/Providers/ClinePass/ClinePassProviderDescriptor.swift b/Sources/CodexBarCore/Providers/ClinePass/ClinePassProviderDescriptor.swift
@@ -42,6 +42,8 @@ public enum ClinePassProviderDescriptor {
             tokenCost: ProviderTokenCostConfig(
                 supportsTokenCost: false,
                 noDataMessage: { "ClinePass cost history is not available via the usage-limits API." }),
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary, .tertiary]),
             fetchPlan: self.fetchPlan(),
             cli: ProviderCLIConfig(
                 name: "clinepass",
diff --git a/Sources/CodexBarCore/Providers/CommandCode/CommandCodeProviderDescriptor.swift b/Sources/CodexBarCore/Providers/CommandCode/CommandCodeProviderDescriptor.swift
@@ -44,6 +44,8 @@ public enum CommandCodeProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "Command Code cost summary is not yet supported." }),
             pace: .calendarMonthResetWindow,
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary]),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .web],
                 pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [CommandCodeWebFetchStrategy()] })),
diff --git a/Sources/CodexBarCore/Providers/Doubao/DoubaoProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Doubao/DoubaoProviderDescriptor.swift
@@ -63,6 +63,8 @@ public enum DoubaoProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "Doubao cost summary is not available." }),
             pace: .calendarMonthResetWindow,
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary, .tertiary]),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .cli, .api],
                 pipeline: ProviderFetchPipeline(resolveStrategies: self.resolveStrategies)),
diff --git a/Sources/CodexBarCore/Providers/ProviderUsagePresentation.swift b/Sources/CodexBarCore/Providers/ProviderUsagePresentation.swift
@@ -424,6 +424,9 @@ public struct ProviderUsagePresentation: Sendable {
     public let requestedMenuBarLaneOrders: [ProviderMenuBarMetric: [ProviderUsageLane]]
     public let automaticSelectionPrioritizesExhaustedWindow: Bool
     public let secondaryGloballyCapsPrimary: Bool
+    /// Longer quota lanes that must have room before the primary session lane is usable.
+    /// Kept separate from widget policy until those surfaces adopt the same multi-lane projection.
+    public let primaryBindingQuotaLanes: Set<ProviderUsageLane>
     public let menuCard: ProviderMenuCardPresentation
     public let menu: ProviderMenuDescriptorPresentation
     public let planRow: ProviderPlanRowPresentation
@@ -451,6 +454,7 @@ public struct ProviderUsagePresentation: Sendable {
         planUtilizationSeriesNormalizer: @escaping PlanUtilizationSeriesNormalizer = { series, _ in series },
         widgetRowLimitResolver: @escaping WidgetRowLimitResolver = { _, _ in nil },
         secondaryGloballyCapsPrimary: Bool = false,
+        primaryBindingQuotaLanes: Set<ProviderUsageLane> = [],
         menuCard: ProviderMenuCardPresentation = ProviderMenuCardPresentation(),
         menu: ProviderMenuDescriptorPresentation = ProviderMenuDescriptorPresentation(),
         planRow: ProviderPlanRowPresentation = ProviderPlanRowPresentation(),
@@ -475,6 +479,7 @@ public struct ProviderUsagePresentation: Sendable {
         self.planUtilizationSeriesNormalizer = planUtilizationSeriesNormalizer
         self.widgetRowLimitResolver = widgetRowLimitResolver
         self.secondaryGloballyCapsPrimary = secondaryGloballyCapsPrimary
+        self.primaryBindingQuotaLanes = primaryBindingQuotaLanes
         self.menuCard = menuCard
         self.menu = menu
         self.planRow = planRow
diff --git a/Sources/CodexBarCore/Providers/QwenCloud/QwenCloudProviderDescriptor.swift b/Sources/CodexBarCore/Providers/QwenCloud/QwenCloudProviderDescriptor.swift
@@ -52,6 +52,8 @@ public enum QwenCloudProviderDescriptor {
             tokenCost: ProviderTokenCostConfig(
                 supportsTokenCost: false,
                 noDataMessage: { "Qwen Cloud cost summary is not supported." }),
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary]),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .web],
                 pipeline: ProviderFetchPipeline(resolveStrategies: self.resolveStrategies)),
diff --git a/Sources/CodexBarCore/Providers/StepFun/StepFunProviderDescriptor.swift b/Sources/CodexBarCore/Providers/StepFun/StepFunProviderDescriptor.swift
@@ -88,6 +88,8 @@ public enum StepFunProviderDescriptor {
                 supportsTokenCost: false,
                 noDataMessage: { "StepFun per-day cost history is not available via API." }),
             pace: .calendarMonthResetWindow,
+            presentation: ProviderUsagePresentation(
+                primaryBindingQuotaLanes: [.secondary]),
             fetchPlan: ProviderFetchPlan(
                 sourceModes: [.auto, .web],
                 pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [StepFunWebFetchStrategy()] })),
diff --git a/Sources/CodexBarCore/Providers/Zai/ZaiProviderDescriptor.swift b/Sources/CodexBarCore/Providers/Zai/ZaiProviderDescriptor.swift
@@ -112,7 +112,8 @@ public enum ZaiProviderDescriptor {
                     return .resolved(ProviderUsagePresentation.mostConstrained(
                         context.snapshot.primary,
                         context.snapshot.secondary))
-                }),
+                },
+                primaryBindingQuotaLanes: [.secondary]),
             fetchPlan: self.fetchPlan(),
             cli: ProviderCLIConfig(
                 name: "zai",
diff --git a/Sources/CodexBarCore/Providers/ZenMux/ZenMuxProviderDescriptor.swift b/Sources/CodexBarCore/Providers/ZenMux/ZenMuxProviderDescriptor.swift
@@ -40,6 +40,7 @@ public enum ZenMuxProviderDescriptor {
                 noDataMessage: { "ZenMux cost history is not exposed by the Management API." }),
             presentation: ProviderUsagePresentation(
                 costPresenter: { _ in ProviderCostPresentation(menuCardStyle: .payAsYouGoBalance) },
+                primaryBindingQuotaLanes: [.secondary],
                 menuCard: ProviderMenuCardPresentation(
                     primaryDescriptionPlacement: .detailLeft,
                     hidesPrimaryResetWithoutDate: true)),
diff --git a/Sources/CodexBarCore/RateWindow+BindingCap.swift b/Sources/CodexBarCore/RateWindow+BindingCap.swift
@@ -0,0 +1,66 @@
+import Foundation
+
+public struct RateWindowBindingQuotaProjection: Sendable, Equatable {
+    public let usedPercent: Double
+    public let resetsAt: Date?
+    public let resetDescription: String?
+
+    public init(usedPercent: Double, resetsAt: Date?, resetDescription: String?) {
+        self.usedPercent = usedPercent
+        self.resetsAt = resetsAt
+        self.resetDescription = resetDescription
+    }
+}
+
+extension RateWindow {
+    /// The primary slot is the session lane even when a provider omits duration metadata.
+    private static let sessionWindowMinutes = 5 * 60
+
+    /// Projects the displayed primary percentage and reset through exhausted longer binding lanes.
+    /// Raw primary detail remains owned by the primary lane and is not replaced by this projection.
+    public static func bindingQuotaProjection(
+        primary: RateWindow,
+        bindingLanes: [RateWindow],
+        now: Date) -> RateWindowBindingQuotaProjection?
+    {
+        let primaryMinutes = primary.windowMinutes ?? Self.sessionWindowMinutes
+        let exhaustedBindingLanes = bindingLanes.filter { lane in
+            guard let minutes = lane.windowMinutes, minutes > primaryMinutes else { return false }
+            return Self.isActivelyExhausted(lane, now: now)
+        }
+        guard !exhaustedBindingLanes.isEmpty else { return nil }
+
+        var blockers = exhaustedBindingLanes
+        if Self.isActivelyExhausted(primary, now: now) {
+            blockers.append(primary)
+        }
+        let reset = Self.effectiveReset(blockers: blockers)
+        return RateWindowBindingQuotaProjection(
+            usedPercent: 100,
+            resetsAt: reset.date,
+            resetDescription: reset.description)
+    }
+
+    private static func isActivelyExhausted(_ window: RateWindow, now: Date) -> Bool {
+        guard window.remainingPercent <= 0 else { return false }
+        return window.resetsAt.map { $0 > now } ?? true
+    }
+
+    /// All exhausted gates must reset before the primary lane is usable again. Do not promise an
+    /// earlier known reset when another active blocker has no comparable reset date.
+    private static func effectiveReset(blockers: [RateWindow]) -> (date: Date?, description: String?) {
+        let unknownResetBlockers = blockers.filter { $0.resetsAt == nil }
+        if !unknownResetBlockers.isEmpty {
+            let description = unknownResetBlockers[0].resetDescription?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            guard blockers.count == 1, let description, !description.isEmpty else { return (nil, nil) }
+            return (nil, description)
+        }
+
+        let latest = blockers.max { lhs, rhs in
+            guard let lhsReset = lhs.resetsAt, let rhsReset = rhs.resetsAt else { return false }
+            return lhsReset < rhsReset
+        }
+        return (latest?.resetsAt, nil)
+    }
+}
diff --git a/Tests/CodexBarTests/MenuCardBindingQuotaTests.swift b/Tests/CodexBarTests/MenuCardBindingQuotaTests.swift
diff --git a/Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift b/Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift
diff --git a/Tests/CodexBarTests/ProviderPresentationPolicyCharacterizationTests.swift b/Tests/CodexBarTests/ProviderPresentationPolicyCharacterizationTests.swift
