glm-quota-line 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.3.1
+
+- Fixed "quota unavailable" on api.z.ai / open.bigmodel.cn: the quota endpoint now returns `{"code":200,...}` without a top-level `success` flag, which made every response parse as unavailable (#6)
+- Added support for credit-based Coding Plans: their 5h/weekly windows are reported as `CREDIT_LIMIT` entries (`usage`/`currentValue`/`remaining`) instead of `TOKENS_LIMIT`, which previously produced no quotas (#6)
+
 ## 1.3.0
 
 - Added `commands` subcommand: list every command with a machine-readable schema via `--json` (name / summary / sideEffect / args / examples), for AI agents and scripting

package/README.en.md

@@ -1,7 +1,8 @@
 <h1 align="center">glm-quota-line</h1>
 
 <p align="center">
-  A Zhipu GLM Coding Plan quota monitor built for Claude Code. Accurate, real-time data from the official site — no window switching, just glance and go.
+  A Zhipu GLM Coding Plan quota monitor built for Claude Code<br>
+  <strong>Focus on coding without switching windows to check your quota</strong>
 </p>
 
 <p align="center">
@@ -15,20 +16,25 @@
   <a href="./README.md">简体中文</a>
 </p>
 
-## Features
+## Core Value
 
-- **Terminal quick check** — run `glm-quota-line` in any terminal to view your quota (including MCP) without launching Claude Code
-- **Claude Code status line** — auto-embeds in the status bar after install, shows quota balance, reset time, and context window usage in real time
-- **Bar visualization** — default bar style shows remaining quota at a glance; weekly quota shows theoretical budget shadow
-- **Weekly pacing analysis** — calculates usage speed based on work days, auto-highlights when exceeding theoretical budget
-- **JSON output** — `--json` flag outputs structured data for scripting
-- **Interactive configuration** — `glm-quota-line configure` launches a TUI with live preview and per-component controls
-- **Component-level control** — each display component (plan, 5h, week, reset, context) can be individually toggled and styled
-- **Smart caching** — tiered refresh by session, TTL, and token usage; `SessionStart` hook pre-refreshes so new sessions never show stale data
-- **Domestic + international endpoints** — auto-detects `open.bigmodel.cn` and `api.z.ai`
-- **Zero dependencies** — no runtime deps, single-purpose CLI
+**Accurate data from official site** → **Real-time status bar display** → **Smart pacing alerts**
 
-## Quick Start
+After installation, the quota appears automatically in the Claude Code status bar:
+
+```
+GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% 11:10 | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
+```
+
+**See at a glance**:
+- Plan remaining quota (91%) with progress bar
+- Weekly quota consumption (47%) + theoretical budget shadow (▒)
+- Time until reset (14:47)
+- Context window usage (45%)
+
+Auto-color alerts when pacing exceeds budget, preventing workflow interruption.
+
+## 30-Second Quick Start
 
 **One-time query (no install needed):**
 
@@ -36,20 +42,14 @@
 npx glm-quota-line
 ```
 
-**Status line integration (global install required):**
+**Status line integration (recommended):**
 
 ```bash
 npm install -g glm-quota-line
 glm-quota-line install
 ```
 
-Done. Your Claude Code status bar will now show the quota:
-
-```
-GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
-```
-
-You can also run `glm-quota-line` directly in the terminal to check your quota without launching Claude Code.
+Done. You can run `glm-quota-line` anytime in the terminal to check usage without launching Claude Code.
 
 Upgrade:
 
@@ -58,88 +58,41 @@ npm install -g glm-quota-line
 glm-quota-line check-update
 ```
 
-## Configuration
-
-All options are optional. Persist with `glm-quota-line config set`, or override per-invocation with CLI flags.
-
-### style — Output layout
-
-| Value | Description | Example |
-|---|---|---|
-| `bar` (default) | Progress bar | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% \| 14:47 \| ctx ███░░░ 45%` |
-| `text` | Full text | `GLM Lite \| 5h 91% \| week 47% \| reset 14:47 \| ctx 45%` |
-| `compact` | Compact mode | `GLM 5h 91% W 47% \| 14:47` |
-
-```bash
-glm-quota-line config set style compact
-```
-
-### theme — Color theme
+## Common Workflows
 
-| Value | Description |
-|---|---|
-| `dark` (default) | Dark terminal, light pine-green accents |
-| `light` | White/light terminal, teal-blue accents |
-| `mono` | Grayscale, minimal distraction |
+### 📊 Quick quota check
 
 ```bash
-glm-quota-line config set theme light
+glm-quota-line
 ```
 
-Quota percentage colors change automatically based on remaining amount:
-
-- Green — remaining >= 60%
-- Yellow — remaining 30%–60%
-- Red — remaining < 30%
+### 🎨 Customize status bar style
 
-### display — Quota metric
-
-| Value | Description |
-|---|---|
-| `left` (default) | Show remaining quota (bar fills with remaining) |
-| `used` | Show used quota (bar fills with used) |
+**Recommended**: Use interactive configuration with live preview
 
 ```bash
-glm-quota-line config set display used
-```
-
-### work-days — Work days per week
-
-Set the number of work days per week (1–7) for weekly quota theoretical budget and pacing analysis. Default: 5.
-
-```bash
-glm-quota-line config set work-days 6
+glm-quota-line configure
 ```
 
-Pacing analysis calculates theoretical budget based on elapsed work days:
-- Green — usage speed ≤ 1.1x theoretical
-- Yellow — usage speed 1.1x–1.3x theoretical
-- Red — usage speed > 1.3x theoretical
-
-### reset-format — Reset time format
-
-Controls how the reset time is displayed in the status line.
+For manual configuration, see [Quick Customization](#quick-customization)
 
-| Value | Description | Example |
-|---|---|---|
-| `time` (default) | Show the reset time point | `reset 14:47` |
-| `countdown` | Show the remaining countdown | `reset 52m` / `reset 2d 5h` |
+### 🤖 Change model or adjust context window
 
 ```bash
-glm-quota-line config set reset-format countdown
+# When Zhipu releases a new model, no need to wait for npm updates — write the local overlay immediately:
+glm-quota-line model set glm-5.3 400K
+# View all models and their context window sizes
+glm-quota-line model list
 ```
 
-The weekly quota also shows the reset info (time point or countdown) alongside its progress bar.
-
-### --json — JSON output
-
-Output structured JSON format (terminal mode only, ignored in status line mode):
+### 🔧 Script integration
 
 ```bash
 glm-quota-line --json
 ```
 
-Example output:
+Outputs structured JSON data:
+
 ```json
 {
   "level": "Lite",
@@ -149,12 +102,6 @@ Example output:
       "leftPercent": 91,
       "usedPercent": 9,
       "nextResetTime": 1715257200000
-    },
-    {
-      "label": "week",
-      "leftPercent": 47,
-      "usedPercent": 53,
-      "nextResetTime": 1715744400000
     }
   ],
   "mcp": {
@@ -164,29 +111,83 @@ Example output:
 }
 ```
 
-### minimalist — Minimal mode
+### ⚠️ Quota exhausted or display issues
+
+See [Troubleshooting](#troubleshooting)
+
+## Quick Customization
+
+### Recommended: Interactive configuration
+
+```bash
+glm-quota-line configure  # Live preview, WYSIWYG
+```
+
+**Key bindings**:
+- `↑↓` select component, `Enter` to edit, `Tab` to cycle style, `Space` to toggle
+- `g` for global options (theme, display mode, minimalist, raw-values, reset format)
+- `s` to save, `q` to quit
+
+### Common config (non-interactive)
+
+#### Style & theme
+
+```bash
+glm-quota-line config set style compact  # Compact mode
+glm-quota-line config set theme light    # Light theme
+glm-quota-line config set theme mono     # Grayscale minimal
+```
+
+**Style comparison**:
+
+| Style | Description | Example |
+|---|---|---|
+| `bar` (default) | Progress bar | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% 11:10 \| 14:47 \| ctx ███░░░ 45%` |
+| `text` | Full text | `GLM Lite \| 5h 91% \| week 47% 11:10 \| reset 14:47 \| ctx 45%` |
+| `compact` | Compact mode | `GLM 5h 91% W 47% 11:10 \| 14:47` |
 
-Hide all labels, show only progress bars and values.
+#### Display options
 
 ```bash
-glm-quota-line config set minimalist true
+glm-quota-line config set display used           # Show used instead of remaining
+glm-quota-line config set reset-format countdown  # Countdown mode (e.g., reset 52m)
+glm-quota-line config set minimalist true         # Hide label text
 ```
 
-Effect:
-- Off: `GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% | 14:47`
-- On: `█████████░ 91% | ▒▒▒▒░░░░░ 47% | 14:47`
+**Color logic**:
 
-### raw-values — Raw values
+Quota percentage auto-colors based on remaining amount:
+- 🟢 Green — remaining >= 60%
+- 🟡 Yellow — remaining 30%–60%
+- 🔴 Red — remaining < 30%
 
-Hide all labels and show raw values directly.
+Pacing analysis auto-colors based on usage speed:
+- 🟢 Green — usage speed ≤ 1.1x theoretical
+- 🟡 Yellow — usage speed 1.1x–1.3x theoretical
+- 🔴 Red — usage speed > 1.3x theoretical
+
+<details>
+<summary><b>Advanced configuration options</b> (click to expand)</summary>
+
+### Work days setting
+
+Set the number of work days per week (1–7) for weekly quota theoretical budget and pacing analysis. Default: 5.
+
+```bash
+glm-quota-line config set work-days 6
+```
+
+### Raw values mode
+
+Display raw values directly, without percentages.
 
 ```bash
 glm-quota-line config set raw-values true
 ```
 
-### auth-token / base-url — Custom auth
+### Custom authentication
 
-If Claude Code runs behind a gateway or proxy and the injected `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` are not the real values:
+If Claude Code runs behind a gateway or proxy, you can override auth credentials:
 
 ```bash
 glm-quota-line config set auth-token <your-real-token>
@@ -197,41 +198,91 @@ glm-quota-line config set base-url https://api.z.ai/api/anthropic
 
 Clear with `glm-quota-line config unset auth-token` / `base-url`.
 
-Auth source priority (highest to lowest):
-
+**Auth priority** (highest to lowest):
 1. Values persisted via `config set`
 2. Environment variables `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`
 3. `env` field in `~/.claude/settings.json`
 
-### reset — Restore defaults
+### Factory reset
 
-One-shot reset of user config. Install state is preserved (status line / hook are not removed).
+One-shot reset of user config. Install state is preserved (status line/hook not removed).
 
 ```bash
-glm-quota-line config reset            # reset all user config (interactive confirm)
-glm-quota-line config reset --models   # reset only custom model mappings (modelMap)
-glm-quota-line config reset --yes      # skip confirmation (scripts / CI)
+glm-quota-line config reset            # Reset all user config (interactive confirm)
+glm-quota-line config reset --models   # Reset only custom model mappings (modelMap)
+glm-quota-line config reset --yes      # Skip confirmation (scripts/CI)
 ```
 
-- Default scope: all global config keys (theme/display/style/work-days/minimalist/raw-values/reset-format/auth-token/base-url), component layout (lines), and custom model mappings (modelMap).
-- `--models` limits the reset to modelMap only; other config is left untouched.
-- In non-interactive sessions (no TTY) `--yes` is required, otherwise it errors out — to avoid accidental deletion.
-- After reset the status line still works — model mappings fall back to the bundled table (`data/models.json`).
+- Default scope: all global config, component layout, custom model mappings
+- `--models` limits reset to modelMap only; other config untouched
+- Non-interactive sessions (no TTY) require `--yes` or error out
+- After reset, status line still works — model mappings fall back to bundled defaults
 
-### configure — Interactive TUI setup
+</details>
 
-Launch a terminal UI with live preview to adjust component toggles, styles, and global options.
+## Advanced Features
+
+<details>
+<summary><b>Model mapping management</b> (new model support)</summary>
+
+Manage context window size mapping per model. Context window usage percentage is computed from this mapping.
 
 ```bash
-glm-quota-line configure
+glm-quota-line model list                    # List all models and their context window size
+glm-quota-line model get <model-id>          # Show the size of a given model
+glm-quota-line model set <model-id> <size>   # Set model size (e.g., 300K or 300000)
+glm-quota-line model remove <model-id>       # Remove custom mapping (built-in reverts to default)
 ```
 
-Key bindings:
-- `↑↓` select component, `Enter` to edit, `Tab` to cycle style, `Space` to toggle
-- `g` to enter global options (theme, display mode, minimalist, raw-values)
-- `s` to save, `q` to quit
+**Example `list` output**:
+
+```
+glm-4.5-air  128K
+glm-4.7      200K
+glm-5-turbo  200K
+glm-5.2      1M *
+```
+
+The `*` marker indicates a user-configured mapping.
+
+**Two-layer design**:
+- Bundled `data/models.json` as default base
+- `modelMap` in `~/.claude/glm-quota-line.json` as user overlay (merged key-by-key at runtime)
+
+**Advantage**: When Zhipu releases a new model, no need to wait for npm package updates — just run `model set <new-model> <size>` to write the local overlay and it takes effect immediately.
+
+To clear all custom model mappings and return to bundled defaults: `glm-quota-line config reset --models --yes`.
+
+</details>
+
+<details>
+<summary><b>Agent / Automation interface</b></summary>
+
+If you are an AI agent (Claude Code / Cursor / Codex) or script author, the following interface is guaranteed stable:
+
+```bash
+# Get full machine-readable schema of all commands in one call
+glm-quota-line commands --json
+
+# Focused help for a single command or command group
+glm-quota-line model --help
+glm-quota-line config set --help
+```
+
+**Conventions**:
+- **Exit codes**: `0` on success, `1` on error
+- **Side-effect tags**: Each command tagged `read` (safe for automation), `write` (persists config/model map), `mutating` (modifies Claude Code integration), or `interactive` (requires TTY)
+- **Non-blocking**: No command blocks waiting for input
+- **Read query**: `glm-quota-line --json` emits structured quota data
+
+Typical agent workflow: Run `commands --json` to discover capabilities → invoke command → parse stdout.
 
-Components:
+</details>
+
+<details>
+<summary><b>Component-level control</b></summary>
+
+Through component mode in `glm-quota-line configure`, each display component can be individually toggled and styled. See [Quick Customization](#quick-customization) for key bindings; component capabilities:
 
 | Component | Description | Styleable | Hideable |
 |---|---|---|---|
@@ -241,45 +292,55 @@ Components:
 | `reset` | Reset time | — | ✓ |
 | `ctx` | Context window usage | ✓ (bar/text) | ✓ |
 
-### model — Context window management
+</details>
+
+## Troubleshooting
+
+### Quota not displaying
 
-Manage the context window size mapping per model. The context window usage percentage is computed from this mapping.
+**Possible causes**:
+1. Auth info missing or expired
+2. Non-GLM provider (endpoint not `open.bigmodel.cn` or `api.z.ai`)
+3. Network connection issues
 
+**Solutions**:
 ```bash
-glm-quota-line model list                    # list all models and their context window size
-glm-quota-line model get <model-id>          # show the size of a given model
-glm-quota-line model set <model-id> <size>   # set a model size (e.g. 300K or 300000)
-glm-quota-line model remove <model-id>       # remove a custom mapping (built-in model reverts to default)
+# Check auth status
+glm-quota-line
+
+# If shows "auth expired", update auth info
+glm-quota-line config set auth-token <your-token>
+glm-quota-line config set base-url https://open.bigmodel.cn/api/anthropic
 ```
 
-Example `list` output:
+### Shows "quota unavailable"
 
-```
-glm-4.7        200K
-glm-5.1        200K
-glm-5.2        300K *
-```
+**Possible causes**:
+- Zhipu API interface issues
+- Network connection problems
 
-The `*` marker indicates a user-configured mapping.
+**Solutions**:
+- Retry later (tool auto-retries)
+- Check network connection
+- If persistent, may be Zhipu service issues
 
-The model mapping is a two-layer system: the bundled `data/models.json` is the default base, and the `modelMap` in `~/.claude/glm-quota-line.json` is the user overlay (merged key-by-key at runtime). **When Zhipu releases a new model, you don't need to wait for an npm package update — just run `model set <new-model> <size>` to write the local overlay and it takes effect immediately.**
+### Install/uninstall issues
 
-To clear all custom model mappings and return to the bundled default table, run `glm-quota-line config reset --models --yes`.
+**Status bar not updating**:
+```bash
+glm-quota-line uninstall
+glm-quota-line install --force
+```
 
-## Recommended Combinations
+`install --force` backs up previous config; `uninstall` restores when possible.
 
-| Use case | Config |
-|---|---|
-| Dark terminal (default) | `style=bar`, `theme=dark` |
-| Light terminal | `style=bar`, `theme=light` |
-| Minimal setup | `style=compact`, `theme=mono` |
-| Track usage | `style=bar`, `display=used` |
-| Countdown reset | `reset-format=countdown` |
-| Scripting | `--json` |
-| 6-day work week | `work-days=6` |
-| Minimal values | `minimalist=true` |
-| Custom model | `glm-quota-line model set glm-5.2 300K` |
-| Interactive setup | `glm-quota-line configure` |
+### Debug mode
+
+Set `GLM_QUOTA_DEBUG=1` to output context window debug info to stderr:
+
+```bash
+GLM_QUOTA_DEBUG=1 glm-quota-line
+```
 
 ## Command Reference
 
@@ -298,43 +359,20 @@ glm-quota-line model list
 glm-quota-line model get <model-id>
 glm-quota-line model set <model-id> <size>
 glm-quota-line model remove <model-id>
-```
-
-Run `glm-quota-line --help` for full descriptions.
-
-## For Agents / Automation
-
-If you are an AI agent (Claude Code / Cursor / Codex) or a script author, the following surface is guaranteed stable:
-
-```bash
-# Get the full machine-readable schema of every command in one call
-# (name / summary / sideEffect / args / examples)
 glm-quota-line commands --json
-
-# Focused help for a single command or command group
-glm-quota-line model --help
-glm-quota-line config set --help
 ```
 
-Conventions:
-- **Exit codes**: `0` on success, `1` on error.
-- **Side-effect tagging**: every command is tagged `read` (safe for automation), `write` (persists config / model map), `mutating` (modifies Claude Code integration), or `interactive` (requires a TTY).
-- **Non-blocking**: no command blocks waiting for input (`config reset` needs `--yes` in non-interactive sessions; `configure` prints a hint instead of launching the TUI when there is no TTY).
-- **Read query**: `glm-quota-line --json` emits structured quota data (5h / week / MCP + reset times).
-
-Typical agent workflow: run `commands --json` to discover capabilities → invoke the command you need → parse stdout.
+Run `glm-quota-line --help` for full descriptions.
 
-## Notes
+## Technical Notes
 
 - Shows `TOKENS_LIMIT` and `MCP_LIMIT` / `TIME_LIMIT` quotas
-- Weekly quota progress bar shadow (▒) is a daily pacing baseline: the theoretical budget based on elapsed work days — the more the filled bar (█) extends past the shadow, the faster you're consuming
-- Context window usage is shown by default; toggle via `glm-quota-line configure`
-- Context window usage is computed from raw tokens using the local model map; if the current model id is not in the map, the context segment is not shown (no guessing)
-- Each component can be individually toggled and styled via `glm-quota-line configure`
-- Missing auth returns `GLM | auth expired`; API failures return `GLM | quota unavailable`
-- `install` does not replace an unmanaged status line unless `--force` is used
-- `install --force` backs up the previous entry; `uninstall` restores it when possible
-- Set `GLM_QUOTA_DEBUG=1` to output context window debug info to stderr
+- Weekly quota progress bar shadow (▒) is the daily pacing baseline: theoretical budget based on elapsed work days
+- Context window usage computed from raw tokens using local model map; falls back to API-provided percentage when mapping unavailable
+- Smart caching: tiered refresh by session, TTL, and token usage; `SessionStart` hook pre-refreshes so new sessions never show stale data
+- Auto-detects domestic (`open.bigmodel.cn`) and international (`api.z.ai`) endpoints
+- Non-GLM providers automatically disable quota queries
+- Zero runtime dependencies
 
 ## License
 

package/README.md

@@ -1,7 +1,8 @@
 <h1 align="center">glm-quota-line</h1>
 
 <p align="center">
-  为 Claude Code 打造的智谱 GLM Coding Plan 配额监控工具。数据精准同步官网，无需切换窗口，随时掌握用量。
+  为 Claude Code 打造的智谱 GLM Coding Plan 配额监控工具<br>
+  <strong>让你专注编码而不用频繁切换窗口检查配额</strong>
 </p>
 
 <p align="center">
@@ -15,20 +16,25 @@
   <a href="./README.en.md">English</a>
 </p>
 
-## 功能
+## 核心价值
 
-- **终端快速查询** — 直接运行 `glm-quota-line` 即可在终端查看配额（含 MCP），无需启动 Claude Code
-- **Claude Code 状态栏** — 安装后自动嵌入状态栏，实时显示配额余额、重置时间和上下文窗口用量
-- **进度条可视化** — 默认 bar 风格，一眼看清剩余比例；周配额显示理论预算阴影
-- **智能配速分析** — 根据工作日和已过时间计算配额使用速度，超速时自动变色警示
-- **JSON 输出** — 支持 `--json` 参数输出结构化数据，便于脚本调用
-- **交互式配置** — `glm-quota-line configure` 启动 TUI 界面，实时预览、逐项调整组件开关与样式
-- **组件级控制** — 每个显示组件（套餐、5h、周、重置、上下文）可单独开关和设置样式
-- **智能缓存** — 按会话、TTL 和 token 用量分级刷新；`SessionStart` hook 预刷新，新会话不显示旧数据
-- **国内 + 国际端点** — 自动识别 `open.bigmodel.cn` 和 `api.z.ai`
-- **零依赖** — 无运行时依赖，单一用途
+**数据精准同步官网** → **状态栏实时显示** → **智能配速警示**
 
-## 快速开始
+安装后，Claude Code 底部状态栏会自动显示配额：
+
+```
+GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% 11:10 | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
+```
+
+**一眼看清**：
+- 套餐剩余量（91%）和进度条
+- 周配额消耗情况（47%）+ 理论预算阴影（▒）
+- 距离重置时间（14:47）
+- 上下文窗口用量（45%）
+
+超速时自动变色警示，避免配额耗尽中断工作流。
+
+## 30 秒快速开始
 
 **一次性查询（无需安装）：**
 
@@ -36,20 +42,14 @@
 npx glm-quota-line
 ```
 
-**状态栏集成（需要全局安装）：**
+**状态栏集成（推荐）：**
 
 ```bash
 npm install -g glm-quota-line
 glm-quota-line install
 ```
 
-安装完成。Claude Code 底部状态栏会自动显示配额：
-
-```
-GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% 11:10 | 14:47 | ctx ███░░░ 45% (glm-4.7/200K)
-```
-
-也可以直接在终端运行 `glm-quota-line` 快速查看用量，无需启动 Claude Code。
+安装完成。可以随时在终端运行 `glm-quota-line` 快速查看用量，无需启动 Claude Code。
 
 升级版本：
 
@@ -58,150 +58,136 @@ npm install -g glm-quota-line
 glm-quota-line check-update
 ```
 
-## 配置项
-
-所有配置均为可选，按需调整。通过 `glm-quota-line config set` 持久化，或用 CLI 参数临时覆盖。
+## 常见工作流
 
-### style — 输出布局
-
-| 值 | 说明 | 示例 |
-|---|---|---|
-| `bar`（默认） | 进度条可视化 | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% 11:10 \| 14:47 \| ctx ███░░░ 45%` |
-| `text` | 完整文本 | `GLM Lite \| 5h 91% \| week 47% 11:10 \| reset 14:47 \| ctx 45%` |
-| `compact` | 紧凑模式 | `GLM 5h 91% W 47% 11:10 \| 14:47` |
+### 📊 我想快速查看配额
 
 ```bash
-glm-quota-line config set style compact
+glm-quota-line
 ```
 
-### theme — 主题配色
+### 🎨 我想定制状态栏样式
 
-| 值 | 说明 |
-|---|---|
-| `dark`（默认） | 深色终端，浅松绿配色 |
-| `light` | 浅色/白色终端，天青蓝配色 |
-| `mono` | 灰阶，极简低干扰 |
+**推荐方式**：使用交互式配置（实时预览效果）
 
 ```bash
-glm-quota-line config set theme light
+glm-quota-line configure
 ```
 
-配额百分比会根据剩余量自动变色：
+手动配置参见[快速定制](#快速定制)
 
-- 绿色 — 剩余 >= 60%
-- 黄色 — 剩余 30%–60%
-- 红色 — 剩余 < 30%
+### 🤖 我想更换模型或调整上下文窗口
 
-### display — 显示指标
+```bash
+# 智谱发布新模型时，无需等 npm 更新，立即写入本地覆盖：
+glm-quota-line model set glm-5.3 400K
+# 查看当前所有模型及其上下文窗口
+glm-quota-line model list
+```
 
-| 值 | 说明 |
-|---|---|
-| `left`（默认） | 显示剩余量（进度条填充 = 剩余比例） |
-| `used` | 显示已用量（进度条填充 = 已用比例） |
+### 🔧 我想在脚本中调用
 
 ```bash
-glm-quota-line config set display used
+glm-quota-line --json
 ```
 
-### work-days — 每周工作日
-
-设置每周工作日数量（1-7），用于计算周配额的理论预算和配速分析。默认 5 天。
+输出结构化 JSON 数据：
 
-```bash
-glm-quota-line config set work-days 6
+```json
+{
+  "level": "Lite",
+  "quotas": [
+    {
+      "label": "5h",
+      "leftPercent": 91,
+      "usedPercent": 9,
+      "nextResetTime": 1715257200000
+    }
+  ],
+  "mcp": {
+    "leftPercent": 85,
+    "usedPercent": 15
+  }
+}
 ```
 
-配速分析会根据已过工作日计算理论预算，并判断使用速度：
-- 绿色 — 使用速度 ≤ 1.1x 理论值
-- 黄色 — 使用速度 1.1x–1.3x 理论值
-- 红色 — 使用速度 > 1.3x 理论值
+### ⚠️ 配额用完了或显示异常
+
+参见[故障排查](#故障排查)
 
-### minimalist — 极简模式
+## 快速定制
 
-隐藏所有标签文字，只保留进度条和数值。
+### 推荐方式：交互式配置
 
 ```bash
-glm-quota-line config set minimalist true
+glm-quota-line configure  # 实时预览，所见即所得
 ```
 
-效果对比：
-- 关闭：`GLM Lite █████████░ 91% | W ▒▒▒▒░░░░░ 47% 11:10 | 14:47`
-- 开启：`█████████░ 91% | ▒▒▒▒░░░░░ 47% 11:10 | 14:47`
+**操作方式**：
+- `↑↓` 选择组件，`Enter` 进入编辑，`Tab` 切换样式，`Space` 开关显示
+- `g` 进入全局选项（主题、显示模式、极简模式、原始数值、重置时间格式）
+- `s` 保存，`q` 退出
 
-### raw-values — 原始数值
+### 常用配置（非交互式）
 
-隐藏所有标签文字，直接显示原始数值。
+#### 风格主题
 
 ```bash
-glm-quota-line config set raw-values true
+glm-quota-line config set style compact  # 紧凑模式
+glm-quota-line config set theme light    # 浅色主题
+glm-quota-line config set theme mono     # 灰阶极简
 ```
 
-### reset-format — 重置时间格式
-
-控制状态栏中重置时间的显示格式。
+**风格对比**：
 
-| 值 | 说明 | 示例 |
+| 风格 | 说明 | 示例 |
 |---|---|---|
-| `time`（默认） | 显示重置时间点 | `reset 14:47` |
-| `countdown` | 显示剩余倒计时 | `reset 52m` / `reset 2d 5h` |
+| `bar`（默认） | 进度条可视化 | `GLM Lite █████████░ 91% \| W ▒▒▒▒░░░░░ 47% 11:10 \| 14:47 \| ctx ███░░░ 45%` |
+| `text` | 完整文本 | `GLM Lite \| 5h 91% \| week 47% 11:10 \| reset 14:47 \| ctx 45%` |
+| `compact` | 紧凑模式 | `GLM 5h 91% W 47% 11:10 \| 14:47` |
+
+#### 显示内容
 
 ```bash
-glm-quota-line config set reset-format countdown
+glm-quota-line config set display used           # 显示已用量而非剩余量
+glm-quota-line config set reset-format countdown  # 倒计时模式（如 reset 52m）
+glm-quota-line config set minimalist true         # 极简模式（隐藏标签文字）
 ```
 
-周配额也会同步显示重置信息（时间点或倒计时）。
+**配色逻辑**：
 
-### --json — JSON 输出
+配额百分比会根据剩余量自动变色：
+- 🟢 绿色 — 剩余 >= 60%
+- 🟡 黄色 — 剩余 30%–60%
+- 🔴 红色 — 剩余 < 30%
 
-输出结构化 JSON 格式（仅终端模式，状态栏模式忽略）：
+配速分析会根据使用速度变色：
+- 🟢 绿色 — 使用速度 ≤ 1.1x 理论值
+- 🟡 黄色 — 使用速度 1.1x–1.3x 理论值
+- 🔴 红色 — 使用速度 > 1.3x 理论值
 
-```bash
-glm-quota-line --json
-```
+<details>
+<summary><b>高级配置选项</b>（点击展开）</summary>
 
-输出示例：
-```json
-{
-  "level": "Lite",
-  "quotas": [
-    {
-      "label": "5h",
-      "leftPercent": 91,
-      "usedPercent": 9,
-      "nextResetTime": 1715257200000
-    },
-    {
-      "label": "week",
-      "leftPercent": 47,
-      "usedPercent": 53,
-      "nextResetTime": 1715744400000
-    }
-  ],
-  "mcp": {
-    "leftPercent": 85,
-    "usedPercent": 15
-  }
-}
+### 工作日设置
+
+设置每周工作日数量（1-7），用于计算周配额的理论预算和配速分析。默认 5 天。
+
+```bash
+glm-quota-line config set work-days 6
 ```
 
-### reset — 恢复出厂配置
+### 原始数值模式
 
-一键重置用户配置,保留安装状态(不卸载状态栏/hook)。
+直接显示原始数值，不显示百分比。
 
 ```bash
-glm-quota-line config reset            # 交互确认后重置全部用户配置
-glm-quota-line config reset --models   # 只清空自定义模型映射(modelMap)
-glm-quota-line config reset --yes      # 跳过确认(脚本/CI 用)
+glm-quota-line config set raw-values true
 ```
 
-- 默认重置范围:所有全局配置项(theme/display/style/work-days/minimalist/raw-values/reset-format/auth-token/base-url)、组件布局(lines)、自定义模型映射(modelMap)。
-- `--models` 限定只清 modelMap,其它配置不动。
-- 非交互环境(无 TTY)必须加 `--yes`,否则报错退出,避免误删。
-- 重置后状态栏仍正常工作——模型映射会回退到包内默认表(`data/models.json`)。
-
-### auth-token / base-url — 自定义鉴权
+### 自定义鉴权
 
-当 Claude Code 运行在代理或网关后面时，注入的 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` 可能不是实际值，可手动覆盖：
+当 Claude Code 运行在代理或网关后面时，可手动覆盖鉴权信息：
 
 ```bash
 glm-quota-line config set auth-token <your-real-token>
@@ -212,36 +198,32 @@ glm-quota-line config set base-url https://api.z.ai/api/anthropic
 
 清除：`glm-quota-line config unset auth-token` / `base-url`。
 
-鉴权来源优先级（从高到低）：
-
+**鉴权优先级**（从高到低）：
 1. `config set` 持久化的值
 2. 环境变量 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`
 3. `~/.claude/settings.json` 中的 `env` 字段
 
-### configure — 交互式 TUI 配置
+### 恢复出厂配置
 
-启动终端交互界面，实时预览状态栏效果，逐项调整组件开关、样式和全局选项。
+一键重置用户配置，保留安装状态（不卸载状态栏/hook）。
 
 ```bash
-glm-quota-line configure
+glm-quota-line config reset            # 交互确认后重置全部用户配置
+glm-quota-line config reset --models   # 只清空自定义模型映射(modelMap)
+glm-quota-line config reset --yes      # 跳过确认(脚本/CI 用)
 ```
 
-操作方式：
-- `↑↓` 选择组件，`Enter` 进入编辑，`Tab` 切换样式，`Space` 开关显示
-- `g` 进入全局选项（主题、显示模式、极简模式、原始数值、重置时间格式）
-- `s` 保存，`q` 退出
+- 默认重置范围：所有全局配置项、组件布局、自定义模型映射
+- `--models` 限定只清 modelMap，其它配置不动
+- 非交互环境(无 TTY)必须加 `--yes`，否则报错退出
+- 重置后状态栏仍正常工作——模型映射会回退到包内默认表
 
-组件列表：
+</details>
 
-| 组件 | 说明 | 可设置样式 | 可隐藏 |
-|---|---|---|---|
-| `level` | 套餐级别（如 GLM Lite） | — | ✓ |
-| `5h` | 5 小时配额 | ✓ (bar/text) | —（必需） |
-| `week` | 周配额 | ✓ (bar/text) | ✓ |
-| `reset` | 重置时间 | — | ✓ |
-| `ctx` | 上下文窗口用量 | ✓ (bar/text) | ✓ |
+## 高级功能
 
-### model — 模型上下文窗口管理
+<details>
+<summary><b>模型映射管理</b>（新模型支持）</summary>
 
 管理模型的上下文窗口大小映射。上下文窗口用量百分比基于此映射计算。
 
@@ -252,34 +234,113 @@ glm-quota-line model set <model-id> <size>   # 设置模型大小（如 300K 或
 glm-quota-line model remove <model-id>       # 移除自定义映射（内置模型恢复默认值）
 ```
 
-`list` 输出示例：
+**`list` 输出示例**：
 
 ```
-glm-4.7        200K
-glm-5.1        200K
-glm-5.2        300K *
+glm-4.5-air  128K
+glm-4.7      200K
+glm-5-turbo  200K
+glm-5.2      1M *
 ```
 
 `*` 标记表示用户自定义的映射。
 
-模型映射采用双层结构:包内 `data/models.json` 作为默认底层,`~/.claude/glm-quota-line.json` 里的 `modelMap` 作为用户覆盖层(运行时逐键覆盖)。**智谱发布新模型时,无需等待 npm 包更新——直接 `model set <新模型> <大小>` 写入本地覆盖层即可立刻生效。**
+**双层结构设计**：
+- 包内 `data/models.json` 作为默认底层
+- `~/.claude/glm-quota-line.json` 里的 `modelMap` 作为用户覆盖层（运行时逐键覆盖）
 
-想清空所有自定义模型映射、回到包内默认表:执行 `glm-quota-line config reset --models --yes`。
+**优势**：智谱发布新模型时，无需等待 npm 包更新——直接 `model set <新模型> <大小>` 写入本地覆盖层即可立刻生效。
 
-## 推荐搭配
+想清空所有自定义模型映射、回到包内默认表：执行 `glm-quota-line config reset --models --yes`。
 
-| 使用场景 | 配置 |
-|---|---|
-| 深色终端（默认） | `style=bar`, `theme=dark` |
-| 浅色终端 | `style=bar`, `theme=light` |
-| 极简工作流 | `style=compact`, `theme=mono` |
-| 关注已用量 | `style=bar`, `display=used` |
-| 倒计时重置 | `reset-format=countdown` |
-| 脚本调用 | `--json` |
-| 6 天工作制 | `work-days=6` |
-| 极简数值 | `minimalist=true` |
-| 自定义模型 | `glm-quota-line model set glm-5.2 300K` |
-| 交互式配置 | `glm-quota-line configure` |
+</details>
+
+<details>
+<summary><b>Agent / 自动化接口</b></summary>
+
+如果你是 AI agent（Claude Code / Cursor / Codex）或脚本作者，以下接口保证稳定：
+
+```bash
+# 一次调用拿到所有命令的 machine-readable schema
+glm-quota-line commands --json
+
+# 查看单个命令或命令组的聚焦帮助
+glm-quota-line model --help
+glm-quota-line config set --help
+```
+
+**约定**：
+- **退出码**：成功 `0`，失败 `1`
+- **副作用标注**：每个命令标为 `read`（只读）、`write`（改配置）、`mutating`（改 Claude Code 集成）、`interactive`（需 TTY）
+- **非阻塞**：所有命令都不会卡住等待输入
+- **只读查询**：`glm-quota-line --json` 输出结构化配额数据
+
+典型 agent 工作流：先 `commands --json` 了解能力 → 调用需要的命令 → 读取 stdout 解析结果。
+
+</details>
+
+<details>
+<summary><b>组件级控制</b></summary>
+
+通过 `glm-quota-line configure` 的组件模式，可单独控制每个显示组件的开关和样式。操作键见[快速定制](#快速定制)，各组件能力如下：
+
+| 组件 | 说明 | 可设置样式 | 可隐藏 |
+|---|---|---|---|
+| `level` | 套餐级别（如 GLM Lite） | — | ✓ |
+| `5h` | 5 小时配额 | ✓ (bar/text) | —（必需） |
+| `week` | 周配额 | ✓ (bar/text) | ✓ |
+| `reset` | 重置时间 | — | ✓ |
+| `ctx` | 上下文窗口用量 | ✓ (bar/text) | ✓ |
+
+</details>
+
+## 故障排查
+
+### 配额不显示
+
+**可能原因**：
+1. 鉴权信息缺失或过期
+2. 非 GLM 提供商（端点不是 `open.bigmodel.cn` 或 `api.z.ai`）
+3. 网络连接问题
+
+**解决方法**：
+```bash
+# 检查鉴权状态
+glm-quota-line
+
+# 如果显示 "auth expired"，更新鉴权信息
+glm-quota-line config set auth-token <your-token>
+glm-quota-line config set base-url https://open.bigmodel.cn/api/anthropic
+```
+
+### 显示 "quota unavailable"
+
+**可能原因**：
+- 智谱 API 接口异常
+- 网络连接问题
+
+**解决方法**：
+- 稍后重试（工具会自动重试）
+- 检查网络连接
+- 如果持续出现，可能是智谱服务问题
+
+### 安装/卸载问题
+
+**状态栏没有更新**：
+```bash
+glm-quota-line uninstall
+glm-quota-line install --force
+```
+
+`install --force` 会备份旧配置，`uninstall` 会在可能时恢复。
+
+### 调试模式
+
+设置 `GLM_QUOTA_DEBUG=1` 可输出上下文窗口调试信息到 stderr：
+
+```bash
+GLM_QUOTA_DEBUG=1 glm-quota-line
+```
 
 ## 命令参考
 
@@ -298,44 +359,20 @@ glm-quota-line model list
 glm-quota-line model get <model-id>
 glm-quota-line model set <model-id> <size>
 glm-quota-line model remove <model-id>
-```
-
-运行 `glm-quota-line --help` 查看完整说明。
-
-## 给 Agent / 自动化
-
-如果你是 AI agent(Claude Code / Cursor / Codex)或脚本作者,以下接口保证稳定:
-
-```bash
-# 一次调用拿到所有命令的 machine-readable schema(name / summary / sideEffect / args / examples)
 glm-quota-line commands --json
-
-# 查看单个命令或命令组的聚焦帮助
-glm-quota-line model --help
-glm-quota-line config set --help
 ```
 
-约定:
-- **退出码**:成功 `0`,失败 `1`。
-- **副作用标注**:每个命令标为 `read`(只读,自动化安全)、`write`(改配置/模型映射)、`mutating`(改 Claude Code 集成)、`interactive`(需 TTY)。
-- **非阻塞**:所有命令都不会卡住等待输入(仅 `config reset` 在非交互环境需 `--yes`,`configure` 在非 TTY 时打印提示而非启动 TUI)。
-- **只读查询**:`glm-quota-line --json` 输出结构化配额数据(5h/week/MCP + 重置时间)。
-
-典型 agent 工作流:先 `commands --json` 了解能力 → 调用需要的命令 → 读取 stdout 解析结果。
+运行 `glm-quota-line --help` 查看完整说明。
 
-## 说明
+## 技术说明
 
 - 展示 `TOKENS_LIMIT` 配额和 `MCP_LIMIT` / `TIME_LIMIT` 配额
-- 周配额进度条中的阴影（▒）是每日应耗基准线：根据已过工作日计算的理论预算，已用部分（█）超过阴影越多，说明消耗越快
-- 状态栏默认显示上下文窗口用量和模型信息，可通过 `glm-quota-line configure` 交互式关闭
-- 每个组件可单独控制开关和样式，通过 `glm-quota-line configure` 交互式调整
+- 周配额进度条中的阴影（▒）是每日应耗基准线：根据已过工作日计算的理论预算
 - 上下文窗口使用率优先从原始 token 数计算，当模型映射不可用时回退到 API 提供的百分比
-- 模型上下文窗口大小可通过 `glm-quota-line model` 命令自定义，支持查看、设置、移除和批量导入
-- 鉴权缺失返回 `GLM | auth expired`；接口异常返回 `GLM | quota unavailable`
-- 非 GLM 提供商（非智谱 AI 端点）会自动禁用配额查询
-- `install` 默认不会覆盖非本工具管理的状态栏，除非使用 `--force`
-- `install --force` 会备份旧配置，`uninstall` 会在可能时恢复
-- 设置 `GLM_QUOTA_DEBUG=1` 可输出上下文窗口调试信息到 stderr
+- 智能缓存：按会话、TTL 和 token 用量分级刷新；`SessionStart` hook 预刷新，新会话不显示旧数据
+- 支持国内（`open.bigmodel.cn`）和国际（`api.z.ai`）端点自动识别
+- 非 GLM 提供商会自动禁用配额查询
+- 零运行时依赖
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glm-quota-line",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Zhipu GLM Coding Plan quota monitor for Claude Code status line.",
   "type": "module",
   "license": "MIT",

package/src/cli/commands.js

@@ -91,8 +91,10 @@ const CONFIG_KEYS = {
   }
 };
 
+// Derived from CONFIG_KEYS so the supported list can never drift from the
+// actually-handled keys (a previous hardcoded message omitted reset-format).
 const SUPPORTED_CONFIG_KEYS_MESSAGE =
-  "Supported config keys: style, display, theme, auth-token, base-url, work-days, minimalist, raw-values\n";
+  `Supported config keys: ${Object.keys(CONFIG_KEYS).join(", ")}\n`;
 
 export async function handleCommand(args, output = process.stdout, dependencies = {}) {
   const getVersion = dependencies.getVersion || getPackageVersion;

package/src/cli/registry.js

@@ -5,6 +5,12 @@
 // When you add a branch to handleCommand in commands.js (or a subcommand in
 // modelCommand.js / configCommand.js), add a matching entry here. The
 // integration test asserts every registry entry maps to a real dispatch branch.
+//
+// Note: `session-start-refresh` is intentionally NOT registered here. It is an
+// internal hook command wired up by install.js into Claude Code's SessionStart
+// hooks; it is dispatchable (see commands.js) but deliberately omitted from the
+// public command surface (commands --json / --help / README) so users don't
+// invoke it directly.
 
 // sideEffect: read | write | interactive | mutating
 //   read        — no persisted state change, safe for automation
@@ -206,10 +212,6 @@ export const COMMAND_GROUPS = {
   config: ["config show", "config set", "config unset", "config reset"]
 };
 
-export function getCommand(key) {
-  return COMMAND_REGISTRY[key] || null;
-}
-
 export function allCommands() {
   return Object.values(COMMAND_REGISTRY);
 }

package/src/core/context/cache.js

@@ -61,6 +61,10 @@ export async function writeCtxCache(data, filePath = CACHE_FILE) {
   if (!isValidCached(data)) {
     return;
   }
+  // Fill savedAt here (not at call sites): getContextData's return shape has no
+  // savedAt, so callers would otherwise write `undefined` and the field would
+  // vanish from the JSON. Centralizing it mirrors quota cache's writeSuccessCache
+  // and keeps the timestamp reliable for future staleness checks.
   const payload = {
     modelId: data.modelId,
     usedPercent: data.usedPercent,
@@ -68,7 +72,7 @@ export async function writeCtxCache(data, filePath = CACHE_FILE) {
     windowSize: data.windowSize,
     severity: VALID_SEVERITIES.has(data.severity) ? data.severity : "neutral",
     sessionId: data.sessionId || "",
-    savedAt: data.savedAt
+    savedAt: Number.isFinite(data.savedAt) ? data.savedAt : Date.now()
   };
   try {
     await fs.mkdir(path.dirname(filePath), { recursive: true });

package/src/core/context/index.js

@@ -94,7 +94,3 @@ export function createRenderData(contextData, style = "bar") {
   }
   return formatForRender(contextData, style);
 }
-
-export { getModelSize, setModelSize, removeModel, mergeModelMap, getAllModels } from "./models.js";
-export { getSeverity, calculateTokenCount } from "./calculator.js";
-export { formatForRender, buildBar, formatWindowSize, formatModelSuffix } from "./formatter.js";

package/src/core/context/models.js

@@ -101,10 +101,6 @@ export function getModelSize(modelId) {
   return findByKey(modelMap, modelId)?.value;
 }
 
-export function hasModel(modelId) {
-  return findByKey(modelMap, modelId) !== undefined;
-}
-
 export function setModelSize(modelId, size) {
   if (typeof modelId !== "string" || !modelId) {
     return;
@@ -128,10 +124,6 @@ export function mergeModelMap(newMap) {
   }
 }
 
-export function getAllModels() {
-  return { ...modelMap };
-}
-
 export function removeModel(modelId) {
   if (typeof modelId !== "string" || !modelId) {
     return false;

package/src/core/quota/parse.js

@@ -107,7 +107,7 @@ function pickSecondaryTokenLimit(tokenLimits, primaryLimit) {
 
 function pickPrimaryAndSecondaryTokenLimits(limits) {
   const tokenLimits = limits
-    .filter((limit) => limit?.type === "TOKENS_LIMIT")
+    .filter((limit) => limit?.type === "TOKENS_LIMIT" || limit?.type === "CREDIT_LIMIT")
     .map((limit, index) => ({ ...limit, _index: index }));
 
   if (tokenLimits.length === 0) {
@@ -186,7 +186,8 @@ export function parseQuotaResponse(response) {
     return { kind: "unavailable" };
   }
 
-  if (payload.success !== true) {
+  // The current quota endpoint returns code:200 without a success flag
+  if (payload.success !== true && payload.code !== 200) {
     if (payload.code === 1001 || payload.code === 401 || isAuthFailureMessage(payload.msg)) {
       return { kind: "auth_error" };
     }

package/src/core/quota/service.js

@@ -8,6 +8,7 @@ import { parseQuotaResponse } from "./parse.js";
 import {
   RATE_LIMIT_RETRY_TTL_MS,
   REFRESH_BANDS,
+  STALE_SUCCESS_MAX_AGE_MS,
   UNAVAILABLE_RETRY_TTL_MS
 } from "../../shared/constants.js";
 
@@ -36,6 +37,17 @@ function getEffectiveTtlMs(cached) {
   return getRefreshTtlMs(cached?.result?.leftPercent);
 }
 
+// A cached success value bridges transient failures only while it is still
+// fresh. Once it is older than STALE_SUCCESS_MAX_AGE_MS we stop masking the
+// real (unavailable) state — otherwise an exhausted quota freezes the status
+// bar at the pre-exhaustion percentage indefinitely.
+function isStaleSuccessUsable(cached, now) {
+  if (!cached?.result || !Number.isFinite(cached.savedAt)) {
+    return false;
+  }
+  return now - cached.savedAt < STALE_SUCCESS_MAX_AGE_MS;
+}
+
 function shouldRefreshQuota(cached, cacheTtlMs, now, sessionId) {
   if (!cached) {
     return true;
@@ -88,15 +100,29 @@ export async function resolveQuotaStatus(config, options = {}) {
   }
 
   if (parsed.kind === "rate_limited") {
+    // GLM signals quota exhaustion as HTTP 429, indistinguishable from a
+    // genuine rate limit. Bridge with the stale value only while it is still
+    // fresh; a sustained 429 past the stale window must surface the real
+    // state rather than freeze the bar at a pre-exhaustion percentage.
     await writeFailureCache(config.cacheFilePath, cached, {
       now,
       sessionId,
       failureKind: "rate_limited"
     });
-    return getCachedStatus(cached);
+    if (isStaleSuccessUsable(cached, now)) {
+      return cached.result;
+    }
+    // Stale value expired (or never existed). With an expired cache we must
+    // NOT return the frozen old value — surface the real `rate_limited`.
+    // With no prior cache at all, fall back to `unavailable` to preserve the
+    // first-run contract (no quota has ever been seen).
+    return cached?.result ? parsed : getCachedStatus(cached);
   }
 
-  if (cached?.result) {
+  // Sustained unavailability: bridge with the stale success value only while
+  // it is still fresh. Past the stale window, surface the real state so a
+  // truly exhausted quota is not hidden behind a frozen old percentage.
+  if (isStaleSuccessUsable(cached, now)) {
     await writeFailureCache(config.cacheFilePath, cached, {
       now,
       sessionId,

package/src/shared/constants.js

@@ -58,6 +58,10 @@ export const REFRESH_BANDS = [
 export const LOW_QUOTA_THRESHOLD = 30;
 export const RATE_LIMIT_RETRY_TTL_MS = 180_000;
 export const UNAVAILABLE_RETRY_TTL_MS = 120_000;
+// A cached *success* value is only trusted to bridge transient failures for
+// this long. Past it, a sustained `unavailable` must surface instead of
+// freezing the status bar at a pre-exhaustion percentage. 10 min.
+export const STALE_SUCCESS_MAX_AGE_MS = 600_000;
 export const DEFAULT_DISPLAY_MODE = "left";
 export const DEFAULT_STYLE = "bar";
 export const DEFAULT_THEME = "dark";
@@ -209,6 +213,6 @@ export function normalizeConfig(config) {
   return { global, lines };
 }
 
-// Re-exported for backward compatibility
+// Re-exported for test imports
 export { migrateOldConfig } from "./migration.js";
 

package/src/shared/migration.js

@@ -44,10 +44,3 @@ export function needsMigration(config) {
   // Legacy ctxEnabled without lines config requires migration
   return typeof config.ctxEnabled === "boolean" && !config.lines;
 }
-
-export function applyMigration(config) {
-  if (needsMigration(config)) {
-    return migrateOldConfig(config);
-  }
-  return config;
-}

package/src/shared/utils.js

@@ -26,11 +26,6 @@ export function clampPercent(value) {
   return Math.min(100, Math.max(0, n));
 }
 
-export function clampRoundPercent(value) {
-  const percent = clampPercent(value);
-  return percent !== null ? Math.round(percent) : null;
-}
-
 export function asFiniteNumber(value) {
   return Number.isFinite(value) ? value : null;
 }