Add quota exhaustion projection overlay to usage bars

[kmatsunami]

Summary

Extend the existing usage bars so they can forecast the expected usage at the quota reset time based on the current consumption velocity, and overlay that forecast on top of the current bar.

Today CodexBar already computes UsagePace, but that answers a different question: it compares current usage with an even-budget baseline. What is still missing is the direct answer users want from the bar itself: if I keep consuming at the current rate until reset, where will this window end up?

Problem

The current UI can tell me:

• how much of the window is used / left
• when the window resets
• whether I am ahead of or behind an even pace
• when I might run out

But it does not show the projected final percentage for the current window. Users still have to mentally convert +7% or Runs out in 3d into a final quota outcome.

Non-goals for the first rollout

• No changes to menu bar title text or brand-icon display modes.
• No widget-specific forecast UI.
• No historical or smoothed forecast model.
• No provider-specific forecast heuristics beyond existing RateWindow timing data.

Execution split

• #6 owns forecast math and the raw projection contract.
• #5 owns the progress bar API and forecast marker rendering primitives.
• #4 owns shared metric/view-model fields and forecast text formatting only.
• #3 owns end-to-end wiring and row visibility decisions.
• #2 owns post-integration docs and regression coverage.

To avoid overlap, forecast must be computed in one place only: downstream UI issues consume the projection contract and must not recompute forecast directly from RateWindow.

Acceptance Criteria

• Usage rows can show a projected end-of-window percentage on the same bar as current usage.
• The textual forecast states the projected percentage at reset.
• Forecast is hidden when the window does not have enough timing information.
• Forecast values over 100% are preserved in text and capped only for drawing.
• Existing pace / historical risk behavior for Codex and Claude is not regressed.
• Unit tests and docs cover the new projection semantics.

[kmatsunami]

Implementation breakdown for parallel execution:

Parallel start:

• Implement quota projection math model and core tests #6 Implement quota projection math model and core tests
• Refactor UsageProgressBar to support a dedicated forecast overlay #5 Refactor UsageProgressBar to support a dedicated forecast overlay

Then:

• Add forecast fields and formatting to the shared metric view model #4 Add forecast fields and formatting to the shared metric view model
  • blocked by Implement quota projection math model and core tests #6
• Integrate quota projection into menu card and provider detail rows #3 Integrate quota projection into menu card and provider detail rows
  • blocked by Refactor UsageProgressBar to support a dedicated forecast overlay #5
  • blocked by Add forecast fields and formatting to the shared metric view model #4
• Document forecast behavior and add post-integration regression coverage #2 Document forecast behavior and add post-integration regression coverage
  • blocked by Integrate quota projection into menu card and provider detail rows #3

Parent tracking:

• This parent issue is marked as blocked by Document forecast behavior and add post-integration regression coverage #2, Integrate quota projection into menu card and provider detail rows #3, Add forecast fields and formatting to the shared metric view model #4, Refactor UsageProgressBar to support a dedicated forecast overlay #5, and Implement quota projection math model and core tests #6 so the dependency graph reflects the full rollout.

Issue links:

• Implement quota projection math model and core tests #6 Implement quota projection math model and core tests #6
• Refactor UsageProgressBar to support a dedicated forecast overlay #5 Refactor UsageProgressBar to support a dedicated forecast overlay #5
• Add forecast fields and formatting to the shared metric view model #4 Add forecast fields and formatting to the shared metric view model #4
• Integrate quota projection into menu card and provider detail rows #3 Integrate quota projection into menu card and provider detail rows #3
• Document forecast behavior and add post-integration regression coverage #2 Document forecast behavior and add post-integration regression coverage #2

[kmatsunami]

Implementation is locally complete, but the issue should stay open until the remaining delivery work is done.

Remaining tasks:

• Push the implementation branch to a writable remote and open a PR against kmatsunami/CodexBar
• Run the full swift test suite in a fully provisioned Xcode environment, not only ./Scripts/compile_and_run.sh
• Do manual UI QA for the forecast overlay across used / remaining display modes and the providers that expose timed quota windows
• Confirm the visual treatment for overflow forecasts (>100%) and near-equal current-vs-forecast values on the actual menu UI

Notes:

• ./Scripts/compile_and_run.sh and pnpm check were made to pass in the local CLT-based environment
• A compatibility workaround was needed for CLT-only builds (SwiftUI @Entry macro and dependency preview macros), so PR review should explicitly confirm that keeping the compatibility path is acceptable upstream