feat: v0.15.0 — model-scoped weekly quota badge (fb[65%])

The usage API moved per-model weekly limits out of dedicated fields
(seven_day_opus/seven_day_sonnet — both now null) into a generic
limits[] array: kind=weekly_scoped entries carrying
scope.model.display_name. The op/sn badges silently died with that
contract change.

Parse the new shape generically and render only the scope matching
the model this session runs: fb[65%] on Fable 5, op[33%] on Opus.
Other models' scoped quotas stay hidden — the limit constraining the
session is signal, the rest is noise. Legacy field rendering kept for
old cached responses, skipped when scoped limits exist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v0.15.0 — 2026-07-05 — model-scoped weekly quota (`fb[65%]`)
+
+The usage API moved per-model weekly limits out of dedicated fields
+(`seven_day_opus` / `seven_day_sonnet` — both now arrive null) into a generic
+`limits[]` array: `kind=weekly_scoped` entries carrying
+`scope.model.display_name`. The old `op`/`sn` badges silently died with that
+contract change; this release reads the new shape.
+
+- Parse `limits[]` weekly_scoped entries generically — any model family the
+  API scopes a weekly limit to, current or future (Fable 5 being the one that
+  surfaced the change).
+- Render only the scope matching the model **this session** is running:
+  `fb[65%]` on a Fable 5 session, `op[33%]` on Opus. Other models' scoped
+  quotas stay hidden — the limit that constrains the session is signal, the
+  rest is noise.
+- Badge labels follow the existing `op`/`sn` convention: `fb` (fable), `hk`
+  (haiku); unknown families degrade to their first two letters rather than
+  hiding the quota behind an unmapped name.
+- Legacy `seven_day_opus`/`seven_day_sonnet` rendering is kept for old cached
+  responses but skipped whenever scoped limits exist (the new contract
+  supersedes it).
+- `build_usage_display` gains the session model as an optional 4th argument;
+  both call sites pass stdin's `model.id`.
+
+6 new tests (248 total).
+
 ## v0.14.0 — 2026-07-02 — 5h reset back to wall-clock (@14:30)
 
 v0.11.0 re-made a mistake v0.7.0 had already fixed and documented: it turned

README.md

@@ -82,7 +82,7 @@ Every component earns its place:
 | Effort | Compact lowercase badge: `lo` / `md` / `xh` / `max` / `ultra` / `auto` (`high` is the default and stays hidden). Dim for routine levels; `max` / `ultra` use the pressure color; `fast` shows in fast mode. |
 | Context bar | Merged with model. Green / yellow / red by window pressure. On 1M models the bar also carries the premium input-pricing band: yellow past 200k tokens, red past 800k — the % alone looks calm (320k = 32%) while every request bills at the premium rate. A real 0% (e.g. right after `/compact` resets the window) renders a visibly empty bar `[░░░░░░0%]` — the snap to empty *is* the refresh signal; the bar hides only when no context data exists at all. |
 | User tier | Neutral white-weight (MAX bold, PRO normal, dim otherwise) — identity, never a status color. Truncated display name. |
-| Quota | Integer percentages. The 5h badge always carries its reset time while a window is live — `5h[42%@14:30]` reads "42% used, resets at 14:30" — because on a 5h horizon the reset is the number you plan the current sitting around. Wall-clock, not a countdown, on purpose: Claude Code only re-renders the statusline on activity, so a relative "@1h38m" silently decays into a lie during idle gaps, while "@14:30" stays true in a frozen frame. (The 7d badge stays relative — `@5d` decays at day granularity, slower than any idle gap.) When a window's utilization climbs between renders, a reverse-video `+N` token appears right after the badge for ~60s: `5h[44%@14:32]+2` means "you just burned 2%". A drop (window reset) stays quiet — the fresh low number is its own signal. **7d is forecast, not leveled**: a learned per-weekday burn profile (EWMA over your own usage history) plus your recent 24h burn project whether the quota outlasts the window — your heavy Tuesday counts more than a generic average. The verdict is color alone; under pressure the badge shows explicit time remaining in the window: `7d[44%@5d]` red means "at your pace, dry days before the reset 5 days from now". Cold start (<14 days history) falls back to window-average pacing. Recovery color when reset is imminent. |
+| Quota | Integer percentages. The 5h badge always carries its reset time while a window is live — `5h[42%@14:30]` reads "42% used, resets at 14:30" — because on a 5h horizon the reset is the number you plan the current sitting around. Wall-clock, not a countdown, on purpose: Claude Code only re-renders the statusline on activity, so a relative "@1h38m" silently decays into a lie during idle gaps, while "@14:30" stays true in a frozen frame. (The 7d badge stays relative — `@5d` decays at day granularity, slower than any idle gap.) When a window's utilization climbs between renders, a reverse-video `+N` token appears right after the badge for ~60s: `5h[44%@14:32]+2` means "you just burned 2%". A drop (window reset) stays quiet — the fresh low number is its own signal. **7d is forecast, not leveled**: a learned per-weekday burn profile (EWMA over your own usage history) plus your recent 24h burn project whether the quota outlasts the window — your heavy Tuesday counts more than a generic average. The verdict is color alone; under pressure the badge shows explicit time remaining in the window: `7d[44%@5d]` red means "at your pace, dry days before the reset 5 days from now". Cold start (<14 days history) falls back to window-average pacing. Recovery color when reset is imminent. **Model-scoped weekly quota**: when the usage API carries a per-model weekly limit (`limits[]`, `kind=weekly_scoped`) for the model your session is running, it gets its own badge — `fb[65%]` on a Fable 5 session, `op[33%]` on Opus. Other models' scoped quotas stay hidden: only the limit constraining *this* session is signal. Supersedes the legacy `seven_day_opus`/`seven_day_sonnet` fields, which the API now sends as null. |
 | Extra usage | Monthly spend, limit, prepaid balance. `--extra auto` shows when quota runs out. |
 | Cache health | Detects observed prompt-cache rebuilds and cache-read drops. `cache!` on break, `cache~` when building. If a future Claude Code stdin includes TTL breakdown, `--cache always` can show `cache:1h@14:20`; current stdin usually exposes aggregate cache tokens only. Hidden when healthy by default. |
 
@@ -108,7 +108,8 @@ red, matching its Claude Code TUI color) = model family; everything else is
 | Prompt cache break detection | -- | Yes |
 | OAuth + macOS Keychain | -- | Yes |
 | Quota bump flash (+N) | -- | Yes |
-| 242 bats tests + CI | -- | Yes |
+| Model-scoped weekly quota (`fb`/`op`/`sn`) | -- | Yes |
+| 248 bats tests + CI | -- | Yes |
 
 ## Configuration
 
@@ -281,7 +282,7 @@ run. Setting only `CLAUDE_CACHE_DIR` keeps the legacy single-dir behavior.
 npm exec --yes bats -- t/
 ```
 
-242 tests across `t/statusline.bats` (230 statusline + integration) and
+248 tests across `t/statusline.bats` (236 statusline + integration) and
 `t/install.bats` (12 installer). CI runs on push and PR to `main`.
 
 ## Project Structure

statusline.sh

@@ -1693,10 +1693,24 @@ quota_bump_notice() {
     echo "${five_d:-0} ${seven_d:-0}"
 }
 
+# Two-letter badge label for a model-scoped limit, following the op/sn
+# convention. Unknown families degrade to their first two letters rather
+# than hiding the quota behind a name we haven't mapped yet.
+model_scope_abbrev() {
+    case "$1" in
+    opus*) echo "op" ;;
+    sonnet*) echo "sn" ;;
+    haiku*) echo "hk" ;;
+    fable*) echo "fb" ;;
+    *) printf '%.2s\n' "$1" ;;
+    esac
+}
+
 build_usage_display() {
     local usage_data="$1"
     local user_tier="${2:-}"  # MAX, PRO, ENT, TEAM, or empty
     local bump_state_file="${3:-}"  # optional: enables the +N bump flash
+    local current_model="${4:-}"  # model id/name of this session; gates scoped badges
 
     if [ -z "$usage_data" ]; then
         echo ""
@@ -1824,18 +1838,49 @@ build_usage_display() {
         parts+=("${DIM}7d${color}[${seven_int}%${reset_suffix}]${bump_part}${RESET}")
     fi
 
-    # Model-specific 7d quotas
+    # Model-scoped weekly quotas (limits[] kind=weekly_scoped, the contract
+    # that replaced seven_day_opus/sonnet — those now arrive null). Only the
+    # scope matching the model THIS session is burning renders: that is the
+    # number constraining you right now; other models' quotas are noise.
+    # Match is a substring test so scope "Fable" hits claude-fable-5.
+    local has_scoped=false
+    local scoped_tsv
+    scoped_tsv=$(echo "$usage_data" | jq -r '
+        .limits[]? | select(.kind == "weekly_scoped" and (.scope.model.display_name // "") != "")
+        | [(.scope.model.display_name | ascii_downcase), (.percent // 0)] | @tsv' 2>/dev/null)
+    if [ -n "$scoped_tsv" ]; then
+        has_scoped=true
+        local model_lc
+        model_lc=$(printf '%s' "$current_model" | tr '[:upper:]' '[:lower:]')
+        local scope_name scope_pct
+        while IFS=$'\t' read -r scope_name scope_pct; do
+            [ -n "$scope_name" ] || continue
+            case "$model_lc" in
+            *"$scope_name"*)
+                local scope_int=$(printf '%.0f' "$scope_pct" 2>/dev/null || echo 0)
+                if [ "$scope_int" -gt 0 ] 2>/dev/null; then
+                    local color=$(get_seven_day_color "$scope_int")
+                    parts+=("${DIM}$(model_scope_abbrev "$scope_name")${color}[${scope_int}%]${RESET}")
+                fi
+                ;;
+            esac
+        done <<<"$scoped_tsv"
+    fi
+
+    # Legacy model-specific 7d quotas (pre-limits[] responses only)
     # MAX users: show opus only (per your spec: "no need to show sonnet for max users")
     # Others: show sonnet
-    if [ "$user_tier" = "MAX" ]; then
-        if [ "$opus_int" -gt 0 ] 2>/dev/null; then
-            local color=$(get_seven_day_color "$opus_int")
-            parts+=("${DIM}op${color}[${opus_int}%]${RESET}")
-        fi
-    else
-        if [ "$sonnet_int" -gt 0 ] 2>/dev/null; then
-            local color=$(get_seven_day_color "$sonnet_int")
-            parts+=("${DIM}sn${color}[${sonnet_int}%]${RESET}")
+    if [ "$has_scoped" = false ]; then
+        if [ "$user_tier" = "MAX" ]; then
+            if [ "$opus_int" -gt 0 ] 2>/dev/null; then
+                local color=$(get_seven_day_color "$opus_int")
+                parts+=("${DIM}op${color}[${opus_int}%]${RESET}")
+            fi
+        else
+            if [ "$sonnet_int" -gt 0 ] 2>/dev/null; then
+                local color=$(get_seven_day_color "$sonnet_int")
+                parts+=("${DIM}sn${color}[${sonnet_int}%]${RESET}")
+            fi
         fi
     fi
 
@@ -2452,7 +2497,7 @@ if [ -n "$session_id" ] && [ "$_may_have_oauth" = true ]; then
             [ -n "$rl_seven_pct" ] && seven_int_cache=$(printf '%.0f' "$rl_seven_pct" 2>/dev/null || echo "$seven_int_cache")
         fi
 
-        quota_display=$(build_usage_display "$usage_data" "$user_tier" "$quota_state_file")
+        quota_display=$(build_usage_display "$usage_data" "$user_tier" "$quota_state_file" "${model_id:-$model_display}")
         [ -n "$quota_display" ] && quota_component="$quota_display"
 
         if [ -n "$quota_component" ]; then
@@ -2511,7 +2556,7 @@ if [ -n "$session_id" ] && [ "$_may_have_oauth" = true ]; then
             --arg sr "${rl_seven_reset}" \
             '{five_hour:{utilization:$fp,resets_at:(if $fr == "" then null else $fr end)},
               seven_day:{utilization:$sp,resets_at:(if $sr == "" then null else $sr end)}}')
-        quota_display=$(build_usage_display "$stdin_usage" "$user_tier" "$quota_state_file")
+        quota_display=$(build_usage_display "$stdin_usage" "$user_tier" "$quota_state_file" "${model_id:-$model_display}")
         [ -n "$quota_display" ] && quota_component="$quota_display"
         five_int=$(printf '%.0f' "${rl_five_pct:-0}" 2>/dev/null || echo 0)
         seven_int_cache=$(printf '%.0f' "${rl_seven_pct:-0}" 2>/dev/null || echo 0)

t/helpers.bash

@@ -39,7 +39,7 @@ debug_log() {
 # Source individual functions by extracting them from statusline.sh.
 # This is deliberate: we test the actual production code, not copies.
 eval "$(awk '
-    /^(abbreviate_model_id|get_runtime_model|format_reset_relative|format_reset_absolute|get_reset_seconds|format_duration|should_show_extra|get_cache_health|infer_cache_ttl_class|format_cache_active_time|build_cache_indicator|get_usage_color|get_seven_day_color|seven_day_elapsed|seven_day_pace|weekend_secs_ahead|get_adaptive_ttl|reap_stale_lock|merge_stdin_rate_limits|rotate_usage_log|build_seven_day_profile|seven_day_forecast|premium_band_level|abbrev_effort|effort_color|_epoch_from_ts|_fmt_epoch|render_bar|format_money_minor|oauth_token_expired|refresh_oauth_credentials_file|is_default_1m_family|get_context_limit|is_1m_model|rotate_debug_log|build_display_path|quota_bump_notice|record_fetch_error|fetch_error_remaining|fetch_error_badge|build_usage_display|build_extra_usage_display|build_user_info|get_user_tier)\(\)/ { capture=1 }
+    /^(abbreviate_model_id|get_runtime_model|format_reset_relative|format_reset_absolute|get_reset_seconds|format_duration|should_show_extra|get_cache_health|infer_cache_ttl_class|format_cache_active_time|build_cache_indicator|get_usage_color|get_seven_day_color|seven_day_elapsed|seven_day_pace|weekend_secs_ahead|get_adaptive_ttl|reap_stale_lock|merge_stdin_rate_limits|rotate_usage_log|build_seven_day_profile|seven_day_forecast|premium_band_level|abbrev_effort|effort_color|_epoch_from_ts|_fmt_epoch|render_bar|format_money_minor|oauth_token_expired|refresh_oauth_credentials_file|is_default_1m_family|get_context_limit|is_1m_model|rotate_debug_log|build_display_path|quota_bump_notice|record_fetch_error|fetch_error_remaining|fetch_error_badge|model_scope_abbrev|build_usage_display|build_extra_usage_display|build_user_info|get_user_tier)\(\)/ { capture=1 }
     capture { print }
     capture && /^}$/ { capture=0 }
 ' "$SCRIPT_DIR/statusline.sh")"

t/statusline.bats

@@ -230,6 +230,49 @@ setup() {
     [[ "$plain" != *"op["* ]]
 }
 
+@test "build_usage_display: scoped weekly limit shows for matching model" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":64,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Fable"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-fable-5")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"fb[64%]"* ]]
+}
+
+@test "build_usage_display: scoped weekly limit hidden for non-matching model" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":64,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Fable"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-opus-4-8")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" != *"fb["* ]]
+}
+
+@test "build_usage_display: scoped limits supersede legacy per-model fields" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"seven_day_opus":{"utilization":20},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":64,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Fable"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-fable-5")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"fb[64%]"* ]]
+    [[ "$plain" != *"op["* ]]
+}
+
+@test "build_usage_display: scoped limit for opus renders op badge on opus session" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":33,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Opus"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-opus-4-8")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"op[33%]"* ]]
+}
+
+@test "build_usage_display: unknown scoped model falls back to two-letter abbrev" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":42,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Zephyr"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-zephyr-1")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"ze[42%]"* ]]
+}
+
+@test "build_usage_display: zero-percent scoped limit is hidden" {
+    usage='{"five_hour":{"utilization":10},"seven_day":{"utilization":5},"limits":[{"kind":"weekly_scoped","group":"weekly","percent":0,"resets_at":"2099-01-05T00:00:00Z","scope":{"model":{"id":null,"display_name":"Fable"},"surface":null},"is_active":false}]}'
+    result=$(build_usage_display "$usage" "MAX" "" "claude-fable-5")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" != *"fb["* ]]
+}
+
 @test "build_usage_display: on-pace 7d hides runway and reset suffix" {
     # 7d 40% late in the window (reset in ~1d => ~6d elapsed) is well under
     # pace, so no runway hint, no @reset. The 5h reset time is always visible