feat(panel): show staleness hint on Codex card when local data is old

Codex has no live status-line hook (unlike Claude Code), so its rate-limit
numbers come from session logs it only writes intermittently and can lag the
live account. When the local snapshot is older than 15 minutes, the classic
panel's Codex card now shows an "about N minutes ago" tag plus an info tooltip
explaining why (and that staying offline avoids burning tokens). No network/API.

- menubar.py: compute codex staleness from rate_limits.updated_at into PopoverState
- panels/web_panel.py: pass codex.stale into the web payload
- assets/panels/classic.html: hidden tag + hover tooltip, dynamic text via textContent
- i18n.json: codex_stale_minutes/hours/tooltip across all 5 languages

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aqua5230

assets/panels/classic.html

@@ -95,6 +95,11 @@
       padding: 13px 15px 12px;
     }
 
+    .card[data-card="codex"] {
+      overflow: visible;
+      z-index: 2;
+    }
+
     .card::before {
       content: "";
       position: absolute;
@@ -148,6 +153,58 @@
       font-weight: 780;
     }
 
+    .codex-stale {
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      flex: none;
+      min-width: 0;
+      color: var(--warn);
+      font-size: 11px;
+      line-height: 1;
+      font-weight: 680;
+      white-space: nowrap;
+    }
+
+    .codex-stale[hidden] {
+      display: none;
+    }
+
+    .codex-stale-info {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 14px;
+      height: 14px;
+      color: var(--muted);
+      font-size: 12px;
+      line-height: 1;
+    }
+
+    .codex-stale-tooltip {
+      position: absolute;
+      z-index: 20;
+      top: calc(100% + 8px);
+      right: 0;
+      display: none;
+      width: max-content;
+      max-width: 260px;
+      padding: 8px 10px;
+      border-radius: 7px;
+      background: rgba(10, 14, 20, 0.96);
+      color: rgba(255, 255, 255, 0.94);
+      box-shadow: 0 10px 24px rgba(0, 0, 0, 0.28);
+      font-size: 11px;
+      line-height: 1.45;
+      font-weight: 500;
+      white-space: normal;
+    }
+
+    .codex-stale-info:hover .codex-stale-tooltip {
+      display: block;
+    }
+
     .card[data-card="projects"] .brand {
       display: grid;
       grid-template-columns: 30px minmax(0, 1fr);
@@ -478,6 +535,13 @@ <h1 data-i18n="claude_name">Claude Code</h1>
       <header class="brand">
         <img src="{{CODEX_ICON}}" alt="">
         <h1 data-i18n="codex_name">Codex</h1>
+        <div class="codex-stale" data-codex-stale hidden>
+          <span aria-hidden="true">⚠</span>
+          <span data-codex-stale-age></span>
+          <span class="codex-stale-info" aria-hidden="true">ⓘ
+            <span class="codex-stale-tooltip" data-codex-stale-tooltip></span>
+          </span>
+        </div>
       </header>
       <div class="row" data-row="session"></div>
       <div class="row" data-row="weekly"></div>
@@ -614,6 +678,22 @@ <h1 data-i18n="projects_title">Project Usage</h1>
       renderRow(name, "weekly", rows && rows.weekly);
     }
 
+    function renderCodexStale(stale) {
+      const staleEl = document.querySelector("[data-codex-stale]");
+      const ageEl = document.querySelector("[data-codex-stale-age]");
+      const tooltipEl = document.querySelector("[data-codex-stale-tooltip]");
+      if (!staleEl || !ageEl || !tooltipEl) return;
+      if (stale && stale.ageText) {
+        ageEl.textContent = stale.ageText;
+        tooltipEl.textContent = t("codex_stale_tooltip");
+        staleEl.hidden = false;
+        return;
+      }
+      ageEl.textContent = "";
+      tooltipEl.textContent = "";
+      staleEl.hidden = true;
+    }
+
     function renderProjects(projects) {
       const list = document.querySelector('[data-project-list]');
       if (!list) return;
@@ -676,6 +756,7 @@ <h1 data-i18n="projects_title">Project Usage</h1>
       applyStaticText();
       applyCard("claude", state.claude);
       applyCard("codex", state.codex);
+      renderCodexStale(state.codex && state.codex.stale);
       latestState = state;
       renderProjects(
         projectRange === "1d" ? state.projects

i18n.json

@@ -57,6 +57,9 @@
     "group_heavy": "高負載",
     "claude_name": "Claude Code",
     "codex_name": "Codex",
+    "codex_stale_minutes": "約 {minutes} 分鐘前",
+    "codex_stale_hours": "約 {hours} 小時前",
+    "codex_stale_tooltip": "Claude 有即時回報所以很準；Codex 沒有，usage 只能讀它本機偶爾留下的紀錄，可能比實際略舊。我們刻意不連網去補（連網會多燒你的 token）——繼續在終端機跑 Codex 就會自動更新。",
     "projects_title": "專案用量",
     "project_range_1d": "今日",
     "project_range_7d": "7 日",
@@ -336,6 +339,9 @@
     "group_heavy": "Heavy",
     "claude_name": "Claude Code",
     "codex_name": "Codex",
+    "codex_stale_minutes": "about {minutes} minutes ago",
+    "codex_stale_hours": "about {hours} hours ago",
+    "codex_stale_tooltip": "Claude is accurate because it reports in real time; Codex does not, so usage can only read the local records it leaves occasionally, which may be slightly older than reality. We intentionally do not go online to fill the gap (that would burn more of your tokens) — keep running Codex in the terminal and it will update automatically.",
     "projects_title": "Project Usage",
     "project_range_1d": "Today",
     "project_range_7d": "7 Days",
@@ -615,6 +621,9 @@
     "group_heavy": "高负载",
     "claude_name": "Claude Code",
     "codex_name": "Codex",
+    "codex_stale_minutes": "约 {minutes} 分钟前",
+    "codex_stale_hours": "约 {hours} 小时前",
+    "codex_stale_tooltip": "Claude 有实时回报所以很准；Codex 没有，usage 只能读取它本机偶尔留下的记录，可能比实际略旧。我们刻意不联网去补（联网会多消耗你的 token）——继续在终端机里运行 Codex 就会自动更新。",
     "projects_title": "项目用量",
     "project_range_1d": "今日",
     "project_range_7d": "7 日",
@@ -894,6 +903,9 @@
     "group_heavy": "高負荷",
     "claude_name": "Claude Code",
     "codex_name": "Codex",
+    "codex_stale_minutes": "約 {minutes} 分前",
+    "codex_stale_hours": "約 {hours} 時間前",
+    "codex_stale_tooltip": "Claude はリアルタイムに報告するので正確です。Codex にはそれがないため、usage は Codex がローカルに時々残す記録だけを読み取り、実際より少し古い場合があります。補うために意図的にネット接続はしません（接続するとあなたの token を余分に消費します）——ターミナルで Codex を使い続けると自動的に更新されます。",
     "projects_title": "プロジェクト使用量",
     "project_range_1d": "今日",
     "project_range_7d": "7日間",
@@ -1173,6 +1185,9 @@
     "group_heavy": "고부하",
     "claude_name": "Claude Code",
     "codex_name": "Codex",
+    "codex_stale_minutes": "약 {minutes}분 전",
+    "codex_stale_hours": "약 {hours}시간 전",
+    "codex_stale_tooltip": "Claude는 실시간으로 보고하므로 정확합니다. Codex는 그렇지 않아 usage가 Codex가 로컬에 가끔 남기는 기록만 읽을 수 있고, 실제보다 조금 오래된 값일 수 있습니다. 우리는 이를 보완하려고 일부러 온라인 연결을 하지 않습니다(연결하면 당신의 token을 더 쓰게 됩니다)——터미널에서 Codex를 계속 실행하면 자동으로 업데이트됩니다.",
     "projects_title": "프로젝트 사용량",
     "project_range_1d": "오늘",
     "project_range_7d": "7일",

menubar.py

@@ -19,7 +19,7 @@
 from datetime import UTC, datetime, timedelta
 from importlib import metadata
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 import objc
 from AppKit import (
@@ -298,6 +298,10 @@ class QuotaRowState:
     available: bool = True
 
 
+class CodexStaleState(TypedDict):
+    ageText: str
+
+
 @dataclass(slots=True)
 class PopoverState:
     language: str
@@ -315,6 +319,7 @@ class PopoverState:
     statusline: dict[str, object]
     show_install_button: bool = False
     hide_codex: bool = False
+    codex_stale: CodexStaleState | None = None
 
 
 def format_human_time(seconds: float, language: str = "en") -> str:
@@ -783,7 +788,7 @@ def _refresh(self, queue_if_busy: bool = False) -> None:
     def _refresh_in_background(self) -> None:
         try:
             outcome = asyncio.run(self._fetch())
-            codex_rows, codex_5h_pct, codex_model = self._codex_rows()
+            codex_rows, codex_5h_pct, codex_model, codex_stale = self._codex_rows()
             all_entries = self._load_history_entries()
             project_rows = self._project_rows(hours_back=24, entries=all_entries)
             project_rows_7d = self._project_rows(hours_back=168, entries=all_entries)
@@ -798,6 +803,7 @@ def _refresh_in_background(self) -> None:
                 project_rows_all,
                 history_entries=all_entries,
                 codex_model=codex_model,
+                codex_stale=codex_stale,
             )
         except Exception as exc:
             if os.environ.get("USAGE_DEBUG") == "1":
@@ -975,6 +981,7 @@ def _state_from_outcome(
         project_rows_all: list[tuple[str, int, float | None]],
         history_entries: list[UsageEntry] | None = None,
         codex_model: str = "unknown",
+        codex_stale: CodexStaleState | None = None,
     ) -> PopoverState:
         now = time.time()
         today_text = _today_title(self.mock, self.language, entries=history_entries)
@@ -1054,9 +1061,12 @@ def _state_from_outcome(
                 outcome.state == PollState.TOKEN_ERROR and self._statusline_setup_available()
             ),
             hide_codex=_hide_codex_enabled(),
+            codex_stale=codex_stale,
         )
 
-    def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None, str]:
+    def _codex_rows(
+        self,
+    ) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None, str, CodexStaleState | None]:
         if self.mock:
             now = time.time()
             self.burn_rate_trackers["codex_session"].record(now, 12.0)
@@ -1082,7 +1092,7 @@ def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None,
                     warning_max_seconds=24 * 3600,
                 ),
             )
-            return rows, 12, "gpt-5"
+            return rows, 12, "gpt-5", None
 
         try:
             rate_limits = codex_loader.load_rate_limits()
@@ -1096,10 +1106,14 @@ def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None,
                 _missing_row("Session", CODEX_COLOR, self.language),
                 _missing_row("Weekly", CODEX_COLOR, self.language),
             )
-            return rows, None, "unknown"
+            return rows, None, "unknown", None
         model = rate_limits.model or "unknown"
 
         now = time.time()
+        try:
+            codex_stale = self._codex_stale_state(rate_limits.updated_at, now)
+        except Exception:
+            codex_stale = None
         codex_5h_pct = (
             round(rate_limits.five_hour_pct) if rate_limits.five_hour_pct is not None else None
         )
@@ -1131,7 +1145,24 @@ def _codex_rows(self) -> tuple[tuple[QuotaRowState, QuotaRowState], int | None,
                 warning_max_seconds=24 * 3600,
             ),
         )
-        return rows, codex_5h_pct, model
+        return rows, codex_5h_pct, model, codex_stale
+
+    def _codex_stale_state(self, updated_at: str, now: float) -> CodexStaleState | None:
+        if not updated_at:
+            return None
+        timestamp = datetime.fromisoformat(updated_at.replace("Z", "+00:00"))
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.replace(tzinfo=UTC)
+        else:
+            timestamp = timestamp.astimezone(UTC)
+        age_seconds = now - timestamp.timestamp()
+        if age_seconds <= 900:
+            return None
+        if age_seconds < 3600:
+            minutes = max(1, int(age_seconds // 60))
+            return {"ageText": _t(self.language, "codex_stale_minutes", minutes=minutes)}
+        hours = max(1, int(age_seconds // 3600))
+        return {"ageText": _t(self.language, "codex_stale_hours", hours=hours)}
 
     def _history_sources_fingerprint(self) -> tuple[tuple[str, int, float], ...]:
         sources = (

panels/web_panel.py

@@ -271,6 +271,7 @@ def _state_payload(state: PopoverState) -> dict[str, object]:
         "codex": {
             "session": _row_payload(state.codex_session),
             "weekly": _row_payload(state.codex_weekly),
+            "stale": state.codex_stale,
         },
         "projects": [
             {

tests/test_menubar.py

@@ -1160,6 +1160,51 @@ def test_state_from_outcome_replaces_claude_reset_with_warning(
     assert state.claude_session.reset_text == "⚠ 按目前速度 18分鐘 就會用完(重置還要 51分鐘)"
 
 
+def test_codex_stale_state_uses_minutes_and_hides_fresh_data() -> None:
+    delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
+    delegate.language = "zh-TW"
+    now = datetime(2026, 1, 1, 1, 0, tzinfo=UTC).timestamp()
+
+    fresh = datetime(2026, 1, 1, 0, 50, tzinfo=UTC).isoformat()
+    stale = datetime(2026, 1, 1, 0, 30, tzinfo=UTC).isoformat()
+
+    assert delegate._codex_stale_state(fresh, now) is None
+    assert delegate._codex_stale_state(stale, now) == {"ageText": "約 30 分鐘前"}
+
+
+def test_codex_stale_state_uses_hours_after_sixty_minutes() -> None:
+    delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
+    delegate.language = "zh-TW"
+    now = datetime(2026, 1, 1, 3, 0, tzinfo=UTC).timestamp()
+    stale = "2026-01-01T00:30:00Z"
+
+    assert delegate._codex_stale_state(stale, now) == {"ageText": "約 2 小時前"}
+
+
+def test_codex_rows_ignores_invalid_stale_timestamp(monkeypatch: pytest.MonkeyPatch) -> None:
+    delegate = menubar.AppDelegate.alloc().initWithMock_interval_(False, 60)
+    monkeypatch.setattr("time.time", lambda: 1_700_000_000.0)
+    monkeypatch.setattr(
+        codex_loader,
+        "load_rate_limits",
+        lambda: codex_loader.CodexRateLimits(
+            five_hour_pct=12.0,
+            five_hour_resets_at=1_700_003_600.0,
+            seven_day_pct=34.0,
+            seven_day_resets_at=1_700_086_400.0,
+            model="gpt-test",
+            updated_at="not-a-timestamp",
+        ),
+    )
+
+    rows, codex_5h_pct, model, stale = delegate._codex_rows()
+
+    assert rows[0].available is True
+    assert codex_5h_pct == 12
+    assert model == "gpt-test"
+    assert stale is None
+
+
 def test_state_from_outcome_keeps_reset_when_burn_rate_is_not_positive(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: