feat: v0.12.0 — quota bump flash (+N when 5h/7d usage climbs)

When a window's utilization climbs between renders, flash the increment
in bold at the badge's current color for ~60s: 5h[44%+2@1h18m].
Bold-as-emphasis keeps the three color lanes unambiguous.

State is per-session (sessions/<sid>_quota_seen, same lifecycle as
_cache_health): the flash compares against what THIS statusline last
rendered, so concurrent sessions each get their own notice. First
sighting quiet; climb records; unchanged keeps a fresh notice; drop
(window reset) clears silently.

Also cleans v0.11.0 leftovers in test helpers (dead countdown constants,
format_reset_absolute extraction). 218 tests (9 new).

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

Author: lroolle

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v0.12.0 — 2026-07-02 — quota bump flash (+N when 5h/7d usage climbs)
+
+### Added
+
+- **Bump flash**: when the 5h or 7d utilization climbs between renders, the
+  badge shows the increment in bold at its current color for ~60s:
+  `5h[44%+2@1h18m]` / `7d[10%+1]` — "you just burned 2%". Vivid without a
+  new hue, so the three color lanes stay unambiguous (bold is emphasis, not
+  a fourth status color).
+- `quota_bump_notice()` + per-session state file
+  (`sessions/<session_id>_quota_seen`, same lifecycle as `_cache_health`).
+  Per-session on purpose: the flash compares against what THIS statusline
+  last rendered, so concurrent sessions each get their own notice instead
+  of racing over shared account state.
+- Semantics: first sighting is quiet; a climb records the increment; an
+  unchanged value keeps a still-fresh notice alive; a second climb
+  overwrites (latest increment, not a running sum — "+N" answers "what just
+  happened"); a drop (window reset) clears silently, the fresh low number
+  being its own signal.
+- `QUOTA_BUMP_NOTICE_SECS` (60) constant; `BOLD`/`NO_BOLD` attribute
+  toggles (`ESC[22;1m` / `ESC[22m` — 22-first so bold applies cleanly even
+  inside recovery-dimmed text).
+
+### Fixed
+
+- Test helpers still defined the countdown constants and extracted
+  `format_reset_absolute` — both removed in v0.11.0; cleaned up.
+
+218 tests (9 new), shellcheck warning count unchanged.
+
 ## v0.11.0 — 2026-07-02 — always-on 5h countdown + post-compact bar reset
 
 Two changes driven by live use: "how long until my 5h window resets" was

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 window countdown while a window is live — `5h[42%@1h20m]` reads "42% used, resets in 1h20m" — because on a 5h horizon the time remaining is the number you plan the current sitting around. Same `@remaining` language as the 7d badge; relative, not wall-clock, so no mental subtraction. **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 window countdown while a window is live — `5h[42%@1h20m]` reads "42% used, resets in 1h20m" — because on a 5h horizon the time remaining is the number you plan the current sitting around. Same `@remaining` language as the 7d badge; relative, not wall-clock, so no mental subtraction. When a window's utilization climbs between renders, the badge flashes the increment for ~60s in bold at its current color: `5h[44%+2@1h18m]` 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. |
 | 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. |
 

statusline.sh

@@ -25,6 +25,7 @@ debug_mode=false
 # build_usage_display); these gate the recovery color and extra visibility.
 FIVE_HOUR_RECOVERY_SECS=1800     # recovery color when reset <= 30min
 SEVEN_DAY_RECOVERY_SECS=43200    # recovery color when reset <= 12h
+QUOTA_BUMP_NOTICE_SECS=60        # how long a quota "+N" bump flash stays up
 SEVEN_DAY_WINDOW_SECS=604800     # weekly quota window (fixed 7d) for pace math
 EXTRA_AUTO_UTIL_PCT=50           # show extra when its own utilization >= 50%
 CACHE_BREAK_MIN_TOKENS=2000      # ignore cache drops below this (noise)
@@ -367,6 +368,10 @@ CYAN='\033[0;36m'
 DIM_CYAN='\033[2;36m'
 WHITE='\033[0;37m'
 BOLD_WHITE='\033[1;37m'
+# Attribute toggles for a brief emphasis at the CURRENT hue (quota bump flash).
+# 22 first clears any dim so bold applies cleanly even inside DIM_GREEN text.
+BOLD='\033[22;1m'
+NO_BOLD='\033[22m'
 RESET='\033[0m'
 
 # Usage quota tracking
@@ -1540,9 +1545,68 @@ seven_day_forecast() {
     }'
 }
 
+# Short-lived "+N" notice when a quota window's utilization climbs between
+# renders. State is per-session ("what THIS statusline last rendered"), so
+# concurrent sessions each get their own flash instead of racing over shared
+# account state. Echoes "<five_delta> <seven_delta>"; 0 = quiet. Rules per
+# window: first sighting is quiet; a climb records the increment and shows it
+# for QUOTA_BUMP_NOTICE_SECS; an unchanged value keeps a still-fresh notice
+# alive; a drop (window reset) clears silently — the fresh low number is its
+# own signal. A second climb inside the window overwrites the notice (latest
+# increment, not a running sum: "+N" answers "what just happened").
+quota_bump_notice() {
+    local five_cur="$1" seven_cur="$2" state_file="$3"
+    [ -n "$state_file" ] || { echo "0 0"; return 0; }
+    local now="${STATUSLINE_TEST_NOW_EPOCH:-$(date +%s)}"
+
+    local five_seen="" five_at=0 five_d=0 seven_seen="" seven_at=0 seven_d=0
+    if [ -f "$state_file" ]; then
+        eval "$(jq -r '
+            @sh "five_seen=\(.five.seen // "")",
+            @sh "five_at=\(.five.bump_at // 0)",
+            @sh "five_d=\(.five.delta // 0)",
+            @sh "seven_seen=\(.seven.seen // "")",
+            @sh "seven_at=\(.seven.bump_at // 0)",
+            @sh "seven_d=\(.seven.delta // 0)"
+        ' "$state_file" 2>/dev/null)"
+    fi
+
+    # _judge <cur> <seen> <bump_at> <delta> -> "<bump_at> <delta>" (delta 0 = quiet)
+    _judge() {
+        local cur="$1" seen="$2" at="${3:-0}" d="${4:-0}"
+        if [ -z "$seen" ] || [ -z "$cur" ]; then echo "0 0"; return; fi
+        if [ "$cur" -gt "$seen" ] 2>/dev/null; then
+            echo "$now $((cur - seen))"
+        elif [ "$cur" -lt "$seen" ] 2>/dev/null; then
+            echo "0 0"
+        elif [ "$d" -gt 0 ] 2>/dev/null && [ $((now - at)) -lt "$QUOTA_BUMP_NOTICE_SECS" ] 2>/dev/null; then
+            echo "$at $d"
+        else
+            echo "0 0"
+        fi
+    }
+
+    read -r five_at five_d <<<"$(_judge "$five_cur" "$five_seen" "$five_at" "$five_d")"
+    read -r seven_at seven_d <<<"$(_judge "$seven_cur" "$seven_seen" "$seven_at" "$seven_d")"
+
+    mkdir -p "$(dirname "$state_file")" 2>/dev/null
+    local tmp="${state_file}.tmp.$$"
+    jq -n -c \
+        --argjson fs "${five_cur:-0}" --argjson fa "$five_at" --argjson fd "$five_d" \
+        --argjson ss "${seven_cur:-0}" --argjson sa "$seven_at" --argjson sd "$seven_d" \
+        --argjson up "$now" \
+        '{five:{seen:$fs,bump_at:$fa,delta:$fd},
+          seven:{seen:$ss,bump_at:$sa,delta:$sd},
+          updated_at:$up}' >"$tmp" 2>/dev/null && mv -f "$tmp" "$state_file" 2>/dev/null
+    rm -f "$tmp" 2>/dev/null
+
+    echo "${five_d:-0} ${seven_d:-0}"
+}
+
 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
 
     if [ -z "$usage_data" ]; then
         echo ""
@@ -1564,6 +1628,11 @@ build_usage_display() {
     local opus_int=$(printf '%.0f' "$opus_util" 2>/dev/null || echo 0)
     local sonnet_int=$(printf '%.0f' "$sonnet_util" 2>/dev/null || echo 0)
 
+    local five_bump=0 seven_bump=0
+    if [ -n "$bump_state_file" ]; then
+        read -r five_bump seven_bump <<<"$(quota_bump_notice "$five_int" "$seven_int" "$bump_state_file")"
+    fi
+
     local parts=()
 
     # 5h quota (always show if >0)
@@ -1586,7 +1655,11 @@ build_usage_display() {
             local rel=$(format_reset_relative "$five_reset")
             [ -n "$rel" ] && reset_suffix="${DIM}@${rel}${color}"
         fi
-        parts+=("${DIM}5h${color}[${five_int}%${reset_suffix}]${RESET}")
+        # Bump flash: bold "+N" at the badge's current hue — vivid without a
+        # new color, so the status lanes stay unambiguous.
+        local bump_part=""
+        [ "$five_bump" -gt 0 ] 2>/dev/null && bump_part="${BOLD}+${five_bump}${NO_BOLD}${color}"
+        parts+=("${DIM}5h${color}[${five_int}%${bump_part}${reset_suffix}]${RESET}")
     fi
 
     # 7d aggregate quota (if present and >0). Color comes from PACE, not level:
@@ -1653,7 +1726,9 @@ build_usage_display() {
             fi
             reset_suffix="${DIM}@${rem}${color}"
         fi
-        parts+=("${DIM}7d${color}[${seven_int}%${reset_suffix}]${RESET}")
+        local bump_part=""
+        [ "$seven_bump" -gt 0 ] 2>/dev/null && bump_part="${BOLD}+${seven_bump}${NO_BOLD}${color}"
+        parts+=("${DIM}7d${color}[${seven_int}%${bump_part}${reset_suffix}]${RESET}")
     fi
 
     # Model-specific 7d quotas
@@ -2237,6 +2312,9 @@ if [ -n "$session_id" ] && [ "$_may_have_oauth" = true ]; then
     cache_file="$CLAUDE_ACCOUNT_DIR/usage.cache"
     lock_file="$CLAUDE_ACCOUNT_DIR/usage.lock"
     err_file="$CLAUDE_ACCOUNT_DIR/usage.err"
+    # Per-session bump state: the "+N" flash compares against what THIS
+    # statusline last rendered (same lifecycle as _cache_health).
+    quota_state_file="$CLAUDE_CACHE_DIR/${stdin_session_id:-global}_quota_seen"
 
     five_int=0
     seven_int_cache=0
@@ -2283,7 +2361,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_display=$(build_usage_display "$usage_data" "$user_tier" "$quota_state_file")
         [ -n "$quota_display" ] && quota_component="$quota_display"
 
         if [ -n "$quota_component" ]; then
@@ -2344,7 +2422,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_display=$(build_usage_display "$stdin_usage" "$user_tier" "$quota_state_file")
         [ -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

@@ -17,13 +17,14 @@ DIM_RED='\033[2;31m'
 DIM_YELLOW='\033[2;33m'
 CYAN='\033[0;36m'
 DIM_CYAN='\033[2;36m'
+BOLD='\033[22;1m'
+NO_BOLD='\033[22m'
 RESET='\033[0m'
 
 # Threshold constants (must match statusline.sh)
-FIVE_HOUR_COUNTDOWN_SECS=7200
 FIVE_HOUR_RECOVERY_SECS=1800
-SEVEN_DAY_COUNTDOWN_SECS=259200
 SEVEN_DAY_RECOVERY_SECS=43200
+QUOTA_BUMP_NOTICE_SECS=60
 SEVEN_DAY_WINDOW_SECS=604800
 EXTRA_AUTO_UTIL_PCT=50
 CACHE_BREAK_MIN_TOKENS=2000
@@ -38,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|build_usage_display|build_extra_usage_display|build_user_info|get_user_tier)\(\)/ { capture=1 }
+    /^(abbreviate_model_id|get_runtime_model|format_reset_relative|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|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

@@ -1148,6 +1148,24 @@ JSON
     rm -rf "$tmpdir"
 }
 
+@test "integration: 5h utilization climb flashes +N on the next render" {
+    tmpdir=$(mktemp -d)
+    mkdir -p "$tmpdir/.claude"
+    echo '{"claudeAiOauth":{"accessToken":"fake"}}' > "$tmpdir/.claude/.credentials.json"
+    five_reset=$(date -d '+3 hours 30 minutes' +%s)
+    seven_reset=$(date -d '+5 days' +%s)
+    payload() {
+        echo "{\"session_id\":\"sess-bump\",\"model\":{\"id\":\"claude-opus-4-8\",\"display_name\":\"Opus\"},\"cwd\":\"/tmp/test\",\"workspace\":{\"current_dir\":\"/tmp/test\"},\"cost\":{\"total_cost_usd\":0,\"total_lines_added\":0,\"total_lines_removed\":0,\"total_api_duration_ms\":0},\"version\":\"2.1.197\",\"context_window\":{\"used_percentage\":10,\"context_window_size\":200000},\"rate_limits\":{\"five_hour\":{\"used_percentage\":$1,\"resets_at\":$five_reset},\"seven_day\":{\"used_percentage\":12,\"resets_at\":$seven_reset}}}"
+    }
+    payload 40 | HOME="$tmpdir" CLAUDE_DATA_DIR="$tmpdir/.claude/statusline" CLAUDE_CACHE_DIR="$tmpdir/sessions" bash "$SCRIPT_DIR/statusline.sh" >/dev/null
+    result=$(payload 43 | HOME="$tmpdir" CLAUDE_DATA_DIR="$tmpdir/.claude/statusline" CLAUDE_CACHE_DIR="$tmpdir/sessions" bash "$SCRIPT_DIR/statusline.sh")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"5h[43%+3@"* ]]
+    # State is per-session and lives beside the cache-health files.
+    [ -f "$tmpdir/sessions/sess-bump_quota_seen" ]
+    rm -rf "$tmpdir"
+}
+
 # --- get_reset_seconds ---
 
 @test "get_reset_seconds: future timestamp returns positive seconds" {
@@ -1206,6 +1224,79 @@ JSON
     [[ "$plain" == *"5h[30%]"* ]]
 }
 
+# --- quota bump notice (+N flash when utilization climbs between renders) ---
+
+@test "quota_bump_notice: first sighting is quiet" {
+    tmpdir=$(mktemp -d)
+    result=$(quota_bump_notice 42 10 "$tmpdir/state")
+    [ "$result" = "0 0" ]
+    rm -rf "$tmpdir"
+}
+
+@test "quota_bump_notice: climb emits the increment per window" {
+    tmpdir=$(mktemp -d)
+    quota_bump_notice 42 10 "$tmpdir/state" >/dev/null
+    result=$(quota_bump_notice 45 11 "$tmpdir/state")
+    [ "$result" = "3 1" ]
+    rm -rf "$tmpdir"
+}
+
+@test "quota_bump_notice: unchanged value keeps a fresh notice alive" {
+    tmpdir=$(mktemp -d)
+    STATUSLINE_TEST_NOW_EPOCH=1000 quota_bump_notice 42 10 "$tmpdir/state" >/dev/null
+    STATUSLINE_TEST_NOW_EPOCH=1010 quota_bump_notice 44 10 "$tmpdir/state" >/dev/null
+    result=$(STATUSLINE_TEST_NOW_EPOCH=1030 quota_bump_notice 44 10 "$tmpdir/state")
+    [ "$result" = "2 0" ]
+    rm -rf "$tmpdir"
+}
+
+@test "quota_bump_notice: notice expires after QUOTA_BUMP_NOTICE_SECS" {
+    tmpdir=$(mktemp -d)
+    STATUSLINE_TEST_NOW_EPOCH=1000 quota_bump_notice 42 10 "$tmpdir/state" >/dev/null
+    STATUSLINE_TEST_NOW_EPOCH=1010 quota_bump_notice 44 10 "$tmpdir/state" >/dev/null
+    result=$(STATUSLINE_TEST_NOW_EPOCH=1071 quota_bump_notice 44 10 "$tmpdir/state")
+    [ "$result" = "0 0" ]
+    rm -rf "$tmpdir"
+}
+
+@test "quota_bump_notice: window reset (drop) clears silently" {
+    tmpdir=$(mktemp -d)
+    quota_bump_notice 80 10 "$tmpdir/state" >/dev/null
+    quota_bump_notice 85 10 "$tmpdir/state" >/dev/null
+    result=$(quota_bump_notice 3 10 "$tmpdir/state")
+    [ "$result" = "0 0" ]
+    rm -rf "$tmpdir"
+}
+
+@test "quota_bump_notice: no state file disables the machinery" {
+    result=$(quota_bump_notice 42 10 "")
+    [ "$result" = "0 0" ]
+}
+
+@test "build_usage_display: bump renders +N inside the badge" {
+    tmpdir=$(mktemp -d)
+    usage1='{"five_hour":{"utilization":42},"seven_day":{"utilization":10}}'
+    usage2='{"five_hour":{"utilization":45},"seven_day":{"utilization":12}}'
+    build_usage_display "$usage1" "" "$tmpdir/state" >/dev/null
+    result=$(build_usage_display "$usage2" "" "$tmpdir/state")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"5h[45%+3]"* ]]
+    [[ "$plain" == *"7d[12%+2]"* ]]
+    rm -rf "$tmpdir"
+}
+
+@test "build_usage_display: bump composes with the 5h countdown suffix" {
+    tmpdir=$(mktemp -d)
+    reset_time=$(date -u -d '+2 hours 30 minutes' '+%Y-%m-%dT%H:%M:%SZ')
+    usage1="{\"five_hour\":{\"utilization\":42,\"resets_at\":\"$reset_time\"},\"seven_day\":{\"utilization\":10}}"
+    usage2="{\"five_hour\":{\"utilization\":45,\"resets_at\":\"$reset_time\"},\"seven_day\":{\"utilization\":10}}"
+    build_usage_display "$usage1" "" "$tmpdir/state" >/dev/null
+    result=$(build_usage_display "$usage2" "" "$tmpdir/state")
+    plain=$(strip_ansi "$result")
+    [[ "$plain" == *"5h[45%+3@2h"* ]]
+    rm -rf "$tmpdir"
+}
+
 @test "build_usage_display: 5h at 85% with reset in 20min uses recovery color" {
     reset_time=$(date -u -d '+20 minutes' '+%Y-%m-%dT%H:%M:%SZ')
     usage="{\"five_hour\":{\"utilization\":85,\"resets_at\":\"$reset_time\"},\"seven_day\":{\"utilization\":10}}"