serve: bound /usage per provider so one slow provider can't stall the response

`serveUsage` collected providers in a sequential loop with no per-provider
timeout, so a single slow or hung provider (e.g. a CLI/web fetch that never
returns) blocked the whole `/usage` handler. The only backstop was the outer
request deadline, which returns a 504 with an empty body and discards every
provider already collected — and because that 504 is not `.ok`, the
last-known-good merge (`mergeLastGoodUsageItems`, which requires `.ok`) never
ran. Net effect: one stuck provider made the entire endpoint return nothing,
which pushed shell/Zellij consumers onto degraded CLI fallback.

Collect providers concurrently, bounding each with `BoundedTaskJoin` at a
budget strictly below the outer request deadline (`serveProviderTimeout`).
A provider over budget now contributes a provider error row instead of
blocking the others, so the response stays `.ok`, the cache can restore that
row from last-known-good, and every healthy provider still renders. Each
provider's timeout clock starts when its task is spawned, so a hung provider
cannot serialize the others' deadlines. Results merge in caller-provided
provider order regardless of completion order. The serve usage context's
`webTimeout` is aligned to the per-provider budget (was a fixed 60s that
exceeded the 30s request deadline).

Adds CLIServeRouterTests coverage for the timeout budget and for a hung
provider degrading to an error row without blocking siblings.

Author: enieuwy

CHANGELOG.md

@@ -7,6 +7,7 @@
 
 ### Fixed
 - Mistral: restore Vibe monthly-plan usage by forwarding only required console session cookies. Thanks @lfmundim!
+- CLI server: collect providers concurrently with a per-provider timeout when serving `/usage` so one slow or hung provider degrades to its own error row while the others still return fresh data, instead of stalling the whole response into an empty timeout. Thanks @enieuwy!
 
 ## 0.37.3 — 2026-06-23
 

Sources/CodexBarCLI/CLIServeCommand.swift

@@ -419,6 +419,14 @@ private enum CLIServeArgumentError: LocalizedError {
     }
 }
 
+private struct CLIServeProviderTimeoutError: LocalizedError {
+    let provider: UsageProvider
+
+    var errorDescription: String? {
+        "\(self.provider.rawValue) usage timed out"
+    }
+}
+
 extension CodexBarCLI {
     static let defaultServeRequestTimeout: TimeInterval = 30
 
@@ -561,7 +569,8 @@ extension CodexBarCLI {
                 await Self.serveUsage(
                     provider: provider,
                     config: snapshot.config,
-                    refreshInterval: runtime.refreshInterval)
+                    refreshInterval: runtime.refreshInterval,
+                    requestTimeout: runtime.requestTimeout)
             }
         case let .cost(provider):
             let snapshot: CLIServeConfigSnapshot
@@ -691,7 +700,8 @@ extension CodexBarCLI {
     private static func serveUsage(
         provider rawProvider: String?,
         config: CodexBarConfig,
-        refreshInterval: TimeInterval) async -> CLILocalHTTPResponse
+        refreshInterval: TimeInterval,
+        requestTimeout: TimeInterval) async -> CLILocalHTTPResponse
     {
         let selection: ProviderSelection
         do {
@@ -710,6 +720,12 @@ extension CodexBarCLI {
             return Self.serveError(status: .internalServerError, message: error.localizedDescription)
         }
 
+        // Bound each provider strictly below the outer request deadline so a
+        // single slow/hung provider degrades to its own error row while every
+        // other provider still returns fresh data, instead of stalling the whole
+        // response and being discarded by the deadline's empty 504.
+        let providerTimeout = Self.serveProviderTimeout(requestTimeout: requestTimeout)
+
         let browserDetection = BrowserDetection()
         let command = UsageCommandContext(
             format: .json,
@@ -718,7 +734,7 @@ extension CodexBarCLI {
             antigravityPlanDebug: false,
             augmentDebug: false,
             webDebugDumpHTML: false,
-            webTimeout: 60,
+            webTimeout: providerTimeout,
             verbose: false,
             useColor: false,
             resetStyle: Self.resetTimeDisplayStyleFromDefaults(),
@@ -731,23 +747,95 @@ extension CodexBarCLI {
             persistCLISessions: true,
             persistentCLISessionIdleWindow: Self.serveCLISessionIdleWindow(refreshInterval: refreshInterval))
 
-        var output = UsageCommandOutput()
-        for provider in selection.asList {
-            let providerOutput = await ProviderInteractionContext.$current.withValue(.background) {
+        let output = await Self.serveCollectUsageOutputs(
+            providers: selection.asList,
+            providerTimeout: providerTimeout)
+        { provider in
+            await ProviderInteractionContext.$current.withValue(.background) {
                 await Self.fetchUsageOutputs(
                     provider: provider,
                     status: nil,
                     tokenContext: tokenContext,
                     command: command)
             }
-            output.merge(providerOutput)
         }
 
         return Self.serveJSON(
             output.payload,
             usageCacheKeys: output.payload.map(\.cacheAccountKey))
     }
 
+    /// Per-provider fetch budget for `/usage`. Each provider is bounded strictly
+    /// below the outer request deadline so the deadline (which yields an empty
+    /// 504 and discards every collected provider) stays a last resort, never the
+    /// primary cutoff. When the outer deadline is disabled (`requestTimeout == 0`)
+    /// each provider is still bounded so `/usage` cannot hang indefinitely.
+    static func serveProviderTimeout(requestTimeout: TimeInterval) -> TimeInterval {
+        let disabledDeadlineBudget: TimeInterval = 25
+        guard requestTimeout > 0, requestTimeout.isFinite else { return disabledDeadlineBudget }
+        // 0.8x keeps the budget strictly below the finite deadline at every
+        // value (including sub-second timeouts), so the empty-504 deadline can
+        // never preempt a provider's own bound.
+        return requestTimeout * 0.8
+    }
+
+    /// Collects usage for each provider concurrently, bounding every provider by
+    /// `providerTimeout`. A provider that exceeds its budget contributes a
+    /// provider error row instead of blocking the others, so the overall response
+    /// still renders every healthy provider. (Per-account error rows that carry a
+    /// cache key are merged with last-known-good by `CLIServeResponseCache`; a
+    /// timeout row is account-agnostic and is not reconstructed, matching the
+    /// existing "a timeout cannot prove the active account" cache rule.) Each
+    /// provider's timeout clock starts when its task is spawned, so a hung
+    /// provider cannot serialize the others' deadlines; results are merged in the
+    /// caller's provider order regardless of completion order.
+    static func serveCollectUsageOutputs(
+        providers: [UsageProvider],
+        providerTimeout: TimeInterval,
+        fetch: @Sendable @escaping (UsageProvider) async -> UsageCommandOutput) async -> UsageCommandOutput
+    {
+        let grace = Duration.seconds(max(0, providerTimeout))
+        let indexed = await withTaskGroup(of: (Int, UsageCommandOutput).self) { group in
+            for (index, provider) in providers.enumerated() {
+                group.addTask {
+                    let task = Task<UsageCommandOutput, Error> { await fetch(provider) }
+                    let join = BoundedTaskJoin(sourceTask: task)
+                    switch await join.value(joinGrace: grace) {
+                    case let .value(output):
+                        return (index, output)
+                    case .failure, .timedOut:
+                        return (index, Self.serveProviderTimeoutOutput(provider: provider))
+                    }
+                }
+            }
+            var collected: [(Int, UsageCommandOutput)] = []
+            for await item in group {
+                collected.append(item)
+            }
+            return collected
+        }
+
+        var output = UsageCommandOutput()
+        for (_, providerOutput) in indexed.sorted(by: { $0.0 < $1.0 }) {
+            output.merge(providerOutput)
+        }
+        return output
+    }
+
+    /// Provider-level error row for a fetch that exceeded its per-provider budget.
+    static func serveProviderTimeoutOutput(provider: UsageProvider) -> UsageCommandOutput {
+        var output = UsageCommandOutput()
+        output.exitCode = .failure
+        output.payload.append(Self.makeProviderErrorPayload(
+            provider: provider,
+            account: nil,
+            source: "auto",
+            status: nil,
+            error: CLIServeProviderTimeoutError(provider: provider),
+            kind: .provider))
+        return output
+    }
+
     private static func serveCost(provider rawProvider: String?, config: CodexBarConfig) async -> CLILocalHTTPResponse {
         let selection: ProviderSelection
         do {

Tests/CodexBarTests/CLIServeRouterTests.swift

@@ -221,6 +221,52 @@ struct CLIServeRouterTests {
         #expect(!CodexBarCLI.shouldCacheServeResponse(routeError))
     }
 
+    @Test
+    func `serve provider timeout stays below the request deadline`() {
+        #expect(abs(CodexBarCLI.serveProviderTimeout(requestTimeout: 30) - 24) < 1e-9)
+        #expect(abs(CodexBarCLI.serveProviderTimeout(requestTimeout: 10) - 8) < 1e-9)
+        // Outer deadline disabled (0) or non-finite: still bound each provider.
+        #expect(CodexBarCLI.serveProviderTimeout(requestTimeout: 0) == 25)
+        #expect(CodexBarCLI.serveProviderTimeout(requestTimeout: .infinity) == 25)
+        // Finite deadlines stay strictly below the request timeout at every
+        // value, including sub-second ones.
+        #expect(CodexBarCLI.serveProviderTimeout(requestTimeout: 1) < 1)
+        #expect(abs(CodexBarCLI.serveProviderTimeout(requestTimeout: 0.5) - 0.4) < 1e-9)
+    }
+
+    @Test
+    func `serve usage collection bounds a hung provider without blocking others`() async {
+        let providers: [UsageProvider] = [.codex, .claude, .gemini]
+        let start = Date()
+        let output = await CodexBarCLI.serveCollectUsageOutputs(
+            providers: providers,
+            providerTimeout: 0.1)
+        { provider in
+            if provider == .claude {
+                try? await Task.sleep(for: .seconds(30))
+                return UsageCommandOutput(sections: ["late:\(provider.rawValue)"])
+            }
+            return UsageCommandOutput(sections: ["ok:\(provider.rawValue)"])
+        }
+        let elapsed = Date().timeIntervalSince(start)
+
+        // The hung provider must not serialize or stall the others.
+        #expect(elapsed < 5)
+        // Fast providers render in caller order; the hung one yields no section.
+        #expect(output.sections == ["ok:codex", "ok:gemini"])
+        // The hung provider degrades to a single provider error row.
+        #expect(output.payload.count == 1)
+        #expect(output.payload.first?.provider == UsageProvider.claude.rawValue)
+        #expect(output.payload.first?.error != nil)
+        #expect(output.payload.first?.error?.kind == .provider)
+        // The timeout row is account-agnostic: it carries no cache key, so the
+        // cache's keyed last-good merge intentionally does not reconstruct it
+        // (a timeout cannot prove which account is active).
+        #expect(output.payload.first?.cacheAccountKey == nil)
+        #expect(output.payload.first?.account == nil)
+        #expect(output.exitCode == .failure)
+    }
+
     @Test
     func `serve cache uses stable Codex account identities`() {
         let storedID = UUID()