Warn at startup when Albert daily quota is likely exhausted

Two complementary signals, surfaced as a single WarningMessage banner
when the TUI mounts:

- Persistent state: when the server returns a daily-quota 429 (rpd/tpd),
  write the model name, reason, body excerpt and UTC timestamp to
  ~/.albert-code/throttle_state.json. On the next launch the file is
  re-read and shown as a warning, with automatic decay at the next
  midnight UTC reset. Cleared on a successful call against the same
  model.
- Live estimate: fetch /v1/me/usage on startup, sum prompt_tokens since
  midnight UTC for the active model, compare to the documented EXP TPD
  (DOCUMENTED_MODEL_LIMITS). Warn at >= 80%, hard-warn at >= 95%. Best
  effort: /me/usage only returns the last N events so the estimate is a
  lower bound.

Threading: model.name is now passed alongside model.alias from
complete()/complete_streaming() down to _handle_429 so the persisted
event records the full model identifier (matches what /v1/models and
DOCUMENTED_MODEL_LIMITS expect).

New file albert_code/core/llm/quota_state.py with save/load/clear
helpers. THROTTLE_STATE_FILE added to global_paths.py.

Author: obook

albert_code/cli/textual_ui/app.py

@@ -330,6 +330,7 @@ def update_context_progress(stats: AgentStats) -> None:
         await self._show_dangerous_directory_warning()
         await self._resume_history_from_messages()
         await self._check_and_show_whats_new()
+        self.run_worker(self._check_quota_warning(), exclusive=False)
         self._schedule_update_notification()
         self.agent_loop.emit_new_session_telemetry()
 
@@ -1664,6 +1665,70 @@ async def _show_dangerous_directory_warning(self) -> None:
             )
             await self._mount_and_scroll(WarningMessage(warning, show_border=False))
 
+    async def _check_quota_warning(self) -> None:
+        """Combine persisted 429 (B) and live /me/usage estimation (A)."""
+        from albert_code.core.llm.quota import (
+            documented_limits_for,
+            fetch_albert_usage,
+            is_albert_provider,
+            sum_prompt_tokens_today,
+        )
+        from albert_code.core.llm.quota_state import (
+            is_event_still_relevant,
+            load_terminal_quota_event,
+        )
+
+        active_model = self.config.get_active_model()
+        provider = self.config.get_provider_for_model(active_model)
+        if not is_albert_provider(provider):
+            return
+
+        warnings: list[str] = []
+
+        # B - persisted terminal 429
+        event = load_terminal_quota_event()
+        if event is not None and is_event_still_relevant(event):
+            if event.model_name == active_model.name:
+                ts = event.recorded_at.strftime("%Y-%m-%d %H:%M UTC")
+                warnings.append(
+                    f"Daily quota was exhausted on `{event.model_name}` "
+                    f"at {ts}. Resets at midnight UTC. "
+                    f"Server: {event.body_excerpt}"
+                )
+            else:
+                ts = event.recorded_at.strftime("%H:%M UTC")
+                warnings.append(
+                    f"Earlier daily-quota 429 recorded on "
+                    f"`{event.model_name}` at {ts} (active model is "
+                    f"`{active_model.name}`, may be unaffected)."
+                )
+
+        # A - live /me/usage estimation
+        usage = await fetch_albert_usage(provider)
+        documented = documented_limits_for(active_model.name)
+        if usage is not None and documented is not None and documented.exp.tpd:
+            used_today = sum_prompt_tokens_today(usage, active_model.name)
+            tpd_limit = documented.exp.tpd
+            pct = used_today / tpd_limit * 100.0 if tpd_limit > 0 else 0.0
+            if pct >= 95.0:
+                warnings.append(
+                    f"TPD usage on `{active_model.name}` is at "
+                    f"{used_today:,}/{tpd_limit:,} ({pct:.0f}%) for today "
+                    f"(EXP tier). Likely to 429 on the next call."
+                )
+            elif pct >= 80.0:
+                warnings.append(
+                    f"TPD usage on `{active_model.name}` is at "
+                    f"{used_today:,}/{tpd_limit:,} ({pct:.0f}%) for today "
+                    f"(EXP tier). Approaching the daily ceiling."
+                )
+
+        if not warnings:
+            return
+        body = "⚠ Quota check\n\n" + "\n\n".join(f"- {line}" for line in warnings)
+        body += "\n\nUse `/limits` for the full picture or `/config` to switch model."
+        await self._mount_and_scroll(WarningMessage(body, show_border=False))
+
     async def _check_and_show_whats_new(self) -> None:
         if self._update_cache_repository is None:
             return

albert_code/core/llm/backend/generic.py

@@ -22,6 +22,10 @@
 from albert_code.core.llm.backend.base import APIAdapter, PreparedRequest
 from albert_code.core.llm.backend.vertex import VertexAnthropicAdapter
 from albert_code.core.llm.exceptions import BackendErrorBuilder, TerminalRateLimitError
+from albert_code.core.llm.quota_state import (
+    clear_terminal_quota_event_for_model,
+    save_terminal_quota_event,
+)
 from albert_code.core.llm.message_utils import merge_consecutive_user_messages
 from albert_code.core.llm.throttling import get_throttler
 from albert_code.core.types import (
@@ -575,7 +579,11 @@ async def complete(
 
         try:
             res_data, _ = await self._make_request(
-                url, req.body, headers, model_alias=model.alias
+                url,
+                req.body,
+                headers,
+                model_alias=model.alias,
+                model_name=model.name,
             )
             chunk = adapter.parse_response(res_data, self._provider)
             if chunk.usage is not None:
@@ -586,6 +594,7 @@ async def complete(
             else:
                 throttler.record_request()
             throttler.record_success(model_alias=model.alias)
+            clear_terminal_quota_event_for_model(model.name)
             return chunk
 
         except TerminalRateLimitError as e:
@@ -697,7 +706,11 @@ async def complete_streaming(
 
         try:
             async for res_data in self._make_streaming_request(
-                url, req.body, headers, model_alias=model.alias
+                url,
+                req.body,
+                headers,
+                model_alias=model.alias,
+                model_name=model.name,
             ):
                 chunk = adapter.parse_response(res_data, self._provider)
                 if chunk.usage is not None:
@@ -725,6 +738,7 @@ async def complete_streaming(
                 completion_tokens=last_usage.completion_tokens,
             )
             throttler.record_success(model_alias=model.alias)
+            clear_terminal_quota_event_for_model(model.name)
 
         except TerminalRateLimitError as e:
             raise BackendErrorBuilder.build_terminal_rate_limit(
@@ -772,18 +786,25 @@ async def _make_request(
         data: bytes,
         headers: dict[str, str],
         model_alias: str | None = None,
+        model_name: str | None = None,
     ) -> HTTPResponse:
         client = self._get_client()
         response = await client.post(url, content=data, headers=headers)
-        await self._handle_429(response, model_alias=model_alias)
+        await self._handle_429(
+            response, model_alias=model_alias, model_name=model_name
+        )
         response.raise_for_status()
 
         response_headers = dict(response.headers.items())
         response_body = response.json()
         return self.HTTPResponse(response_body, response_headers)
 
     async def _handle_429(
-        self, response: httpx.Response, *, model_alias: str | None = None
+        self,
+        response: httpx.Response,
+        *,
+        model_alias: str | None = None,
+        model_name: str | None = None,
     ) -> None:
         """If the upstream returned 429, log it, sleep Retry-After, then let
         async_retry retry. Also records the event on the throttler so it can
@@ -805,6 +826,11 @@ async def _handle_429(
             get_throttler(self._provider).record_rate_limit(
                 model_alias=model_alias
             )
+            save_terminal_quota_event(
+                model_name=model_name or model_alias or "unknown",
+                reason="daily-quota",
+                body_text=body_text,
+            )
             raise TerminalRateLimitError(
                 status=HTTP_TOO_MANY_REQUESTS,
                 headers=response.headers,
@@ -847,14 +873,17 @@ async def _make_streaming_request(
         data: bytes,
         headers: dict[str, str],
         model_alias: str | None = None,
+        model_name: str | None = None,
     ) -> AsyncGenerator[dict[str, Any]]:
         client = self._get_client()
         async with client.stream(
             method="POST", url=url, content=data, headers=headers
         ) as response:
             if not response.is_success:
                 await response.aread()
-            await self._handle_429(response, model_alias=model_alias)
+            await self._handle_429(
+                response, model_alias=model_alias, model_name=model_name
+            )
             response.raise_for_status()
             async for line in response.aiter_lines():
                 if line.strip() == "":

albert_code/core/llm/quota.py

@@ -62,6 +62,67 @@ def is_albert_provider(provider: ProviderConfig) -> bool:
     return provider.name == ALBERT_PROVIDER_NAME
 
 
+async def fetch_albert_usage(
+    provider: ProviderConfig, *, timeout: float = 10.0
+) -> list[dict[str, object]] | None:
+    """Fetch /v1/me/usage. Returns the list of usage events, or None on failure.
+
+    Albert returns a list of recent calls with their token counts; the
+    payload schema is `{object: "list", data: [...]}`. We just hand back
+    `data` as a list of dicts and let callers slice what they need.
+    """
+    if _check_albert_preconditions(provider) is not None:
+        return None
+    api_key = os.getenv(provider.api_key_env_var) or ""
+    url = f"{provider.api_base.rstrip('/')}/me/usage"
+    headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(timeout)) as client:
+            response = await client.get(url, headers=headers)
+            response.raise_for_status()
+            payload = response.json()
+    except httpx.HTTPError as exc:
+        logger.debug("Albert /me/usage fetch failed: %s", exc)
+        return None
+    except ValueError as exc:
+        logger.debug("Albert /me/usage returned non-JSON: %s", exc)
+        return None
+    data = payload.get("data") if isinstance(payload, dict) else None
+    return data if isinstance(data, list) else None
+
+
+def sum_prompt_tokens_today(
+    usage_events: list[dict[str, object]], model_name: str
+) -> int:
+    """Sum prompt_tokens for `model_name` calls that happened today (UTC).
+
+    Daily quotas reset at midnight UTC, so any event before today's
+    00:00 UTC doesn't consume the running counter.
+    """
+    import datetime as dt
+
+    midnight_utc = (
+        dt.datetime.now(dt.UTC)
+        .replace(hour=0, minute=0, second=0, microsecond=0)
+        .timestamp()
+    )
+    total = 0
+    for event in usage_events:
+        if not isinstance(event, dict):
+            continue
+        if event.get("model") != model_name:
+            continue
+        created = event.get("created")
+        if not isinstance(created, (int, float)) or created < midnight_utc:
+            continue
+        usage = event.get("usage") or {}
+        if isinstance(usage, dict):
+            tokens = usage.get("prompt_tokens", 0)
+            if isinstance(tokens, (int, float)):
+                total += int(tokens)
+    return total
+
+
 async def fetch_albert_quotas_detailed(
     provider: ProviderConfig, *, timeout: float = 10.0
 ) -> QuotaFetchResult:

albert_code/core/llm/quota_state.py

@@ -0,0 +1,110 @@
+"""Persistent record of the last terminal 429 (daily quota exhausted).
+
+Lets the next albert-code launch warn the user *before* the first call:
+if Qwen3-Coder TPD was exhausted at 22:30 UTC and you reopen at 08:00 UTC,
+the daily counter has not reset yet and the very first request will 429.
+
+Stored as a tiny JSON file in ALBERT_CODE_HOME so it survives restarts
+and machine reboots. Cross-process (other Albert clients on the same
+account) is not detected here - that's what option A (live /me/usage
+estimation) covers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import datetime as dt
+import json
+import logging
+
+from albert_code.core.paths.global_paths import THROTTLE_STATE_FILE
+
+logger = logging.getLogger(__name__)
+
+# Daily quota windows on Albert reset at midnight UTC. We never want to
+# show a stale "TPD exhausted" warning past the next reset.
+_RESET_HOUR_UTC = 0
+
+
+@dataclass(frozen=True)
+class TerminalQuotaEvent:
+    model_name: str
+    reason: str
+    body_excerpt: str
+    recorded_at_iso: str  # UTC ISO8601
+
+    @property
+    def recorded_at(self) -> dt.datetime:
+        return dt.datetime.fromisoformat(self.recorded_at_iso)
+
+
+def save_terminal_quota_event(
+    model_name: str, reason: str, body_text: str | None
+) -> None:
+    """Persist the last 429 daily-quota event. Best-effort, never raises."""
+    payload = TerminalQuotaEvent(
+        model_name=model_name,
+        reason=reason,
+        body_excerpt=(body_text or "")[:300],
+        recorded_at_iso=dt.datetime.now(dt.UTC).isoformat(),
+    )
+    try:
+        path = THROTTLE_STATE_FILE.path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(payload), indent=2), encoding="utf-8")
+    except OSError as exc:
+        logger.debug("Could not persist throttle state: %s", exc)
+
+
+def load_terminal_quota_event() -> TerminalQuotaEvent | None:
+    """Read the persisted 429 event. Returns None if absent or malformed."""
+    try:
+        text = THROTTLE_STATE_FILE.path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        logger.debug("Could not read throttle state: %s", exc)
+        return None
+    try:
+        data = json.loads(text)
+        return TerminalQuotaEvent(
+            model_name=data["model_name"],
+            reason=data["reason"],
+            body_excerpt=data.get("body_excerpt", ""),
+            recorded_at_iso=data["recorded_at_iso"],
+        )
+    except (json.JSONDecodeError, KeyError, TypeError) as exc:
+        logger.debug("Throttle state file is malformed: %s", exc)
+        return None
+
+
+def is_event_still_relevant(
+    event: TerminalQuotaEvent, *, now: dt.datetime | None = None
+) -> bool:
+    """A daily-quota 429 stays relevant until the next midnight UTC after it."""
+    now = now or dt.datetime.now(dt.UTC)
+    recorded = event.recorded_at
+    if recorded.tzinfo is None:
+        recorded = recorded.replace(tzinfo=dt.UTC)
+    next_reset = (recorded + dt.timedelta(days=1)).replace(
+        hour=_RESET_HOUR_UTC, minute=0, second=0, microsecond=0
+    )
+    return now < next_reset
+
+
+def clear_terminal_quota_event_for_model(model_name: str) -> None:
+    """Remove the persisted file if it concerns `model_name`.
+
+    Called on a successful call. Only clears state for the same model the
+    user just exercised - a successful call on `albert-large` shouldn't
+    silence a still-valid `albert-code` warning.
+    """
+    event = load_terminal_quota_event()
+    if event is None:
+        return
+    if event.model_name != model_name:
+        return
+    try:
+        THROTTLE_STATE_FILE.path.unlink(missing_ok=True)
+    except OSError as exc:
+        logger.debug("Could not clear throttle state: %s", exc)

albert_code/core/paths/global_paths.py

@@ -38,5 +38,8 @@ def _get_vibe_home() -> Path:
 )
 LOG_DIR = GlobalPath(lambda: ALBERT_CODE_HOME.path / "logs")
 LOG_FILE = GlobalPath(lambda: ALBERT_CODE_HOME.path / "logs" / "albert-code.log")
+THROTTLE_STATE_FILE = GlobalPath(
+    lambda: ALBERT_CODE_HOME.path / "throttle_state.json"
+)
 
 DEFAULT_TOOL_DIR = GlobalPath(lambda: ALBERT_CODE_ROOT / "core" / "tools" / "builtins")