perf: background credits and dashboard fetch for regular refreshes

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ### Fixed
 - Menu bar: show extra-usage spend as currency text for Claude and Cursor when that metric is selected (#1107). Thanks @Yuxin-Qiao!
+- Codex: run regular credits and OpenAI dashboard refreshes in the background while coalescing overlapping refresh work (#1078). Thanks @ptstory!
 
 ## 0.29.0 — 2026-05-22
 

Sources/CodexBar/Providers/Codex/UsageStore+CodexRefresh.swift

@@ -13,6 +13,67 @@ extension UsageStore {
         self.makeFetchContext(provider: .codex, override: nil).fetcher
     }
 
+    func scheduleCreditsRefreshIfNeeded(minimumSnapshotUpdatedAt: Date? = nil) {
+        let refreshKey = self.codexCreditsRefreshKey(
+            expectedGuard: self.currentCodexAccountScopedRefreshGuard())
+        if let existing = self.creditsRefreshTask,
+           !existing.isCancelled,
+           self.creditsRefreshTaskKey == refreshKey
+        {
+            return
+        }
+
+        self.creditsRefreshTask?.cancel()
+        self.creditsRefreshTaskKey = refreshKey
+        self.creditsRefreshTask = Task(priority: .utility) { @MainActor [weak self] in
+            guard let self else { return }
+            defer {
+                if self.creditsRefreshTaskKey == refreshKey {
+                    self.creditsRefreshTask = nil
+                    self.creditsRefreshTaskKey = nil
+                }
+            }
+            await self.refreshCreditsIfNeeded(minimumSnapshotUpdatedAt: minimumSnapshotUpdatedAt)
+            guard !Task.isCancelled else { return }
+            self.persistWidgetSnapshot(reason: "credits")
+        }
+    }
+
+    func cancelScheduledCreditsRefresh() {
+        self.creditsRefreshTask?.cancel()
+        self.creditsRefreshTask = nil
+        self.creditsRefreshTaskKey = nil
+    }
+
+    func refreshCreditsNow(minimumSnapshotUpdatedAt: Date? = nil) async {
+        self.cancelScheduledCreditsRefresh()
+        await self.refreshCreditsIfNeeded(minimumSnapshotUpdatedAt: minimumSnapshotUpdatedAt)
+    }
+
+    func codexCreditsRefreshKey(expectedGuard: CodexAccountScopedRefreshGuard) -> String {
+        let sourceKey = switch expectedGuard.source {
+        case .liveSystem:
+            "live"
+        case let .managedAccount(id):
+            "managed:\(id.uuidString)"
+        }
+
+        let identityKey = switch expectedGuard.identity {
+        case let .providerAccount(id):
+            "provider:\(id)"
+        case let .emailOnly(normalizedEmail):
+            "email:\(normalizedEmail)"
+        case .unresolved:
+            "unresolved"
+        }
+
+        return [
+            sourceKey,
+            identityKey,
+            expectedGuard.accountKey ?? "account:nil",
+        ].joined(separator: "|")
+    }
+
     func refreshCreditsIfNeeded(minimumSnapshotUpdatedAt: Date? = nil) async {
         guard self.isEnabled(.codex) else { return }
         var expectedGuard = self.currentCodexAccountScopedRefreshGuard()
@@ -30,6 +91,7 @@ extension UsageStore {
         }
         do {
             let credits = try await self.loadLatestCodexCredits()
+            guard !Task.isCancelled else { return }
             guard self.shouldApplyCodexScopedNonUsageResult(expectedGuard: expectedGuard) else { return }
             await MainActor.run {
                 self.credits = credits
@@ -58,6 +120,7 @@ extension UsageStore {
                 snapshot: codexSnapshot,
                 now: codexSnapshot.updatedAt)
         } catch {
+            guard !Task.isCancelled else { return }
             let message = error.localizedDescription
             if message.localizedCaseInsensitiveContains("data not available yet") {
                 guard self.shouldApplyCodexScopedNonUsageResult(expectedGuard: expectedGuard) else { return }