aiuse 3.3.2__tar.gz → 3.3.4__tar.gz

{aiuse-3.3.2/src/aiuse.egg-info → aiuse-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiuse
-Version: 3.3.2
+Version: 3.3.4
 Summary: Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments
 Author: djbclark
 License-Expression: MIT
@@ -74,7 +74,6 @@ for the actual agent CLI whose quota it tracks:
 | Muse (Meta)                 | `muse`                        |
 | Devin                       | `devin`                       |
 | ClinePass                   | `cline`                       |
-| Hyper                       | `crush`                       |
 | DeepSeek, OpenRouter        | no CLI — per-token $ API only |
 
 `aiuse --json` exposes this same mapping per account row as `cli_binary`

{aiuse-3.3.2 → aiuse-3.3.4}/README.md

@@ -33,7 +33,6 @@ for the actual agent CLI whose quota it tracks:
 | Muse (Meta)                 | `muse`                        |
 | Devin                       | `devin`                       |
 | ClinePass                   | `cline`                       |
-| Hyper                       | `crush`                       |
 | DeepSeek, OpenRouter        | no CLI — per-token $ API only |
 
 `aiuse --json` exposes this same mapping per account row as `cli_binary`

{aiuse-3.3.2 → aiuse-3.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aiuse"
-version = "3.3.2"
+version = "3.3.4"
 description = "Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments"
 readme = "README.md"
 requires-python = ">=3.11"

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/__init__.py

@@ -1,3 +1,3 @@
 """Aggregate provider quotas and flag use-it-or-lose-it allotments."""
 
-__version__ = "3.3.2"
+__version__ = "3.3.4"

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/analysis/history.py

@@ -128,7 +128,9 @@ def save_snapshot(
     # Self-describing at rest: windows carry state/pool_family and accounts
     # carry usable_now/binding_window/available_at, so even a naive reader of
     # the cache file cannot misread a consumed share as free headroom.
-    snap_dict = enrich_snapshot(snapshot.to_dict(), notes=load_active_notes())
+    from aiuse.client_limits import load_client_limits
+
+    snap_dict = enrich_snapshot(snapshot.to_dict(), notes=load_active_notes(), client_limits=load_client_limits())
     payload = {
         "schema_version": SCHEMA_VERSION,
         "collection_id": f"{ts}-{os.getpid()}",

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/analysis/selfdescribe.py

@@ -48,6 +48,7 @@ SEMANTICS: dict[str, str] = {
     "fresh": "age_seconds <= fresh threshold (default 1500s); when false, re-collect before trusting ok states",
     "summary_lines": "one human line per pool; always shows used AND left, never a bare percentage",
     "agent_notes": "exhaustion overrides reported by agents (source: agent-reported); expire at their reset time, after which a live collector reading wins",
+    "client_limits": "per-client rate limits the quota windows cannot show, read passively (e.g. agy CLI 429s from its own logs); state limited means that client is failing now while another client (agy ACP) may still work; usable_now stays quota-based",
     "excluded": "--available only: usable pools the operator ruled out (analysis.excluded_pools), with the reason; never route to them",
     "disabled_services": "operator-disabled providers (config [disabled_services]) with the reason; no rows are collected for them — do not route to or spend them until the operator removes the entry",
 }
@@ -221,13 +222,25 @@ def enrich_snapshot(
     *,
     now: datetime | None = None,
     notes: list[Mapping[str, Any]] | None = None,
+    client_limits: Mapping[str, list[dict[str, Any]]] | None = None,
 ) -> dict[str, Any]:
-    """Enrich accounts in place and attach summary_lines / semantics."""
+    """Enrich accounts in place and attach summary_lines / semantics.
+
+    ``client_limits`` (provider -> entries, from aiuse.client_limits) replaces
+    each matching account's ``client_limits``; read-time evidence wins over
+    whatever a cached snapshot carried.
+    """
     now = now or utcnow()
     accounts = [a for a in (snap.get("accounts") or []) if isinstance(a, dict)]
     collected = snap.get("collected_at")
     for account in accounts:
         enrich_account(account, collected_at=collected, now=now, notes=notes)
+        if client_limits is not None:
+            limits = client_limits.get(str(account.get("provider") or ""))
+            if limits:
+                account["client_limits"] = [dict(entry) for entry in limits]
+            else:
+                account.pop("client_limits", None)
     snap["accounts"] = accounts
     snap["summary_lines"] = summary_lines(pool_entries(snap))
     snap["semantics"] = dict(SEMANTICS)
@@ -322,6 +335,7 @@ def pool_entries(snap: Mapping[str, Any]) -> list[dict[str, Any]]:
                     "available_at": min(resets).isoformat() if resets else None,
                     "models_hint": hints.get(family),
                     "age_seconds": account.get("age_seconds"),
+                    **({"client_limits": account["client_limits"]} if account.get("client_limits") else {}),
                     "windows": windows,
                 }
             )
@@ -382,6 +396,16 @@ def summary_line(pool: Mapping[str, Any]) -> str:
             seg += " [agent-reported]"
         segments.append(seg)
     line = f"{lead}: " + "; ".join(segments)
+    for limit in pool.get("client_limits") or []:
+        if isinstance(limit, dict) and limit.get("state") == "limited":
+            client = limit.get("cli_binary") or limit.get("client") or "client"
+            line += (
+                f" [{client} {limit.get('client') or 'client'} rate-limited: 429 x{limit.get('failed_attempts', '?')}"
+            )
+            when = parse_dt(limit.get("last_limited_at"))
+            if when is not None:
+                line += f", last {max(0, int((utcnow() - when).total_seconds() // 60))}m ago"
+            line += "; ACP may still work]"
     if pool.get("usable_now") is False:
         line += " -> NOT usable now"
     elif all(str(w.get("state")) == "unknown" for w in pool.get("windows") or []):

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/cli.py

@@ -530,8 +530,9 @@ def _main_inner(argv: list[str] | None = None) -> int:
     insights = history_insights(snapshot, analysis_cfg=analysis_cfg)
     from aiuse.agent_notes import load_active_notes
     from aiuse.analysis.selfdescribe import SCHEMA_VERSION, enrich_snapshot
+    from aiuse.client_limits import load_client_limits
 
-    snap_dict = enrich_snapshot(snapshot.to_dict(), notes=load_active_notes())
+    snap_dict = enrich_snapshot(snapshot.to_dict(), notes=load_active_notes(), client_limits=load_client_limits(config))
     payload = {
         "schema_version": SCHEMA_VERSION,
         "contract_url": "https://github.com/djbclark/aiuse/blob/main/docs/json-contract.md",
@@ -1092,7 +1093,9 @@ def _run_available(args: argparse.Namespace) -> int:
         snap_dict = snapshot.to_dict()
         source = "live"
 
-    enrich_snapshot(snap_dict, notes=notes)
+    from aiuse.client_limits import load_client_limits
+
+    enrich_snapshot(snap_dict, notes=notes, client_limits=load_client_limits(config))
     fresh = freshness(snap_dict.get("collected_at"), threshold_seconds=threshold)
     # [disabled_services] is the stronger, overall disable: rows are normally
     # filtered at collection, but a cache written by an older build (or with

aiuse-3.3.4/src/aiuse/client_limits.py

@@ -0,0 +1,159 @@
+"""Per-client rate limits that quota windows cannot show (issue #33).
+
+agy (Antigravity) has two clients on one account: the ``agy`` CLI and the ACP
+server (``acp-run agy``). On 2026-10-03 every CLI generation request answered
+``RESOURCE_EXHAUSTED (code 429)`` for hours while both quota windows showed
+headroom and the ACP server kept working. aiuse reads quota, so it reported
+the pool as fully usable.
+
+This module is a **passive** signal: it reads the agy CLI's own log files and
+never sends a request (no probe, no agy launch). The CLI retries a failed
+generation in-process and logs each attempt::
+
+    I1005 06:45:54.279416    2773 run.go:395] Run: attempt 1 failed (RESOURCE_EXHAUSTED (code 429): ...), retrying in 4s
+
+A 429 attempt within the lookback window (default 60 minutes) marks the CLI
+client ``limited``. The quota numbers and ``usable_now`` are left alone: the
+quota is real and the ACP client may still serve it, so hiding the pool would
+also hide a working route. The signal rides along as ``client_limits`` on the
+antigravity account and its routing entries, and in their summary lines.
+
+The logs carry no positive "generation succeeded" marker, so a lockout clears
+only by ageing out of the lookback window.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from aiuse.models import utcnow
+
+DEFAULT_LOOKBACK_MINUTES = 60.0
+# Never read more than this many recent log files per scan (each is ~200 lines).
+_MAX_FILES = 50
+
+_LINE = re.compile(
+    r"^[IWEF](?P<month>\d\d)(?P<day>\d\d) (?P<clock>\d\d:\d\d:\d\d(?:\.\d+)?)\s+\d+\s+\S+\]\s+"
+    r"Run: attempt (?P<attempt>\d+) failed \((?P<error>RESOURCE_EXHAUSTED[^)]*\))"
+)
+_FILE_DATE = re.compile(r"cli-(?P<year>\d{4})(?P<month>\d\d)(?P<day>\d\d)_")
+
+
+def agy_cli_log_dir() -> Path:
+    return Path.home() / ".gemini" / "antigravity-cli" / "log"
+
+
+def lookback_minutes(config: dict[str, Any] | None) -> float:
+    """``analysis.agy_cli_lockout_minutes`` (0 disables the scan)."""
+    analysis = (config or {}).get("analysis")
+    value = analysis.get("agy_cli_lockout_minutes") if isinstance(analysis, dict) else None
+    if value is None:
+        return DEFAULT_LOOKBACK_MINUTES
+    try:
+        return max(0.0, float(value))
+    except (TypeError, ValueError):
+        return DEFAULT_LOOKBACK_MINUTES
+
+
+def _line_time(match: re.Match[str], file_year: int, file_month: int) -> datetime | None:
+    """glog stamps are local time with no year; the file name supplies the year."""
+    month, day = int(match["month"]), int(match["day"])
+    year = file_year + 1 if month < file_month else file_year  # Dec -> Jan rollover
+    clock = match["clock"]
+    try:
+        naive = datetime.strptime(f"{year}-{month:02d}-{day:02d} {clock}", "%Y-%m-%d %H:%M:%S.%f")
+    except ValueError:
+        try:
+            naive = datetime.strptime(f"{year}-{month:02d}-{day:02d} {clock}", "%Y-%m-%d %H:%M:%S")
+        except ValueError:
+            return None
+    return naive.astimezone().astimezone(timezone.utc)
+
+
+def scan_agy_cli_lockout(
+    *,
+    lookback: timedelta = timedelta(minutes=DEFAULT_LOOKBACK_MINUTES),
+    now: datetime | None = None,
+    log_dir: Path | None = None,
+) -> dict[str, Any] | None:
+    """The agy CLI's recent 429 evidence as one ``client_limits`` entry, or None."""
+    if lookback.total_seconds() <= 0:
+        return None
+    now = now or utcnow()
+    directory = log_dir if log_dir is not None else agy_cli_log_dir()
+    since = now - lookback
+    try:
+        entries = [entry for entry in os.scandir(directory) if entry.name.startswith("cli-") and entry.is_file()]
+    except OSError:
+        return None
+    recent: list[tuple[float, Path]] = []
+    for entry in entries:
+        try:
+            mtime = entry.stat().st_mtime
+        except OSError:
+            continue
+        if mtime >= since.timestamp():
+            recent.append((mtime, Path(entry.path)))
+    recent.sort(reverse=True)
+
+    failed_attempts = 0
+    runs: set[str] = set()
+    last_at: datetime | None = None
+    last_error = ""
+    evidence: Path | None = None
+    for _mtime, path in recent[:_MAX_FILES]:
+        named = _FILE_DATE.search(path.name)
+        file_year = int(named["year"]) if named else now.year
+        file_month = int(named["month"]) if named else now.month
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            if "RESOURCE_EXHAUSTED" not in line:
+                continue
+            match = _LINE.match(line)
+            if match is None:
+                continue
+            at = _line_time(match, file_year, file_month)
+            if at is None or at < since or at > now + timedelta(minutes=5):
+                continue
+            failed_attempts += 1
+            runs.add(path.name)
+            if last_at is None or at > last_at:
+                last_at, last_error, evidence = at, match["error"], path
+    if last_at is None:
+        return None
+    minutes_ago = max(0, int((now - last_at).total_seconds() // 60))
+    run_word = "run" if len(runs) == 1 else "runs"
+    return {
+        "client": "cli",
+        "cli_binary": "agy",
+        "state": "limited",
+        "source": "agy-cli-log",
+        "last_limited_at": last_at.isoformat(),
+        "failed_attempts": failed_attempts,
+        "runs": len(runs),
+        "lookback_minutes": round(lookback.total_seconds() / 60.0, 1),
+        "error": last_error,
+        "evidence": str(evidence) if evidence else None,
+        "message": (
+            f"agy CLI got RESOURCE_EXHAUSTED (429) on {failed_attempts} attempts in {len(runs)} {run_word}, "
+            f"last {minutes_ago}m ago, although the quota windows may show headroom; "
+            "the ACP route (acp-run agy) is a separate client and may still work"
+        ),
+    }
+
+
+def load_client_limits(config: dict[str, Any] | None = None) -> dict[str, list[dict[str, Any]]]:
+    """Provider -> active per-client limits, read passively at report time."""
+    minutes = lookback_minutes(config)
+    limits: dict[str, list[dict[str, Any]]] = {}
+    agy = scan_agy_cli_lockout(lookback=timedelta(minutes=minutes)) if minutes > 0 else None
+    if agy is not None:
+        limits["antigravity"] = [agy]
+    return limits

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/collectors/__init__.py

@@ -5,6 +5,7 @@ from .caut import collect_caut
 from .clinepass import collect_clinepass
 from .codexbar import collect_codexbar
 from .cswap import collect_cswap
+from .deepseek import collect_deepseek
 from .hermes import collect_hermes
 from .muse import collect_muse
 from .opencode_go import collect_opencode_go
@@ -27,6 +28,7 @@ __all__ = [
     "collect_openusage_sh",
     "collect_opencode_go",
     "collect_opencode_zen",
+    "collect_deepseek",
     "collect_openrouter",
     "collect_qwencloud",
     "collect_bailian",

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/collectors/bailian.py

@@ -21,7 +21,9 @@ the ``qwencloud`` collector reads (canonical providers ``alibaba`` vs
 
 from __future__ import annotations
 
+import json
 from datetime import datetime, timezone
+from pathlib import Path
 from typing import Any
 
 from aiuse.models import AccountUsage, BillingKind, QuotaWindow, coerce_float
@@ -51,10 +53,16 @@ def collect_bailian(*, timeout: float = 45.0) -> list[AccountUsage]:
         except CollectorError as exc:
             message = str(exc)
             if _looks_unauthenticated(message):
-                # No console login on this machine: quiet, like muse/clinepass.
-                return []
+                # Both subcommands share the one console session: stop here.
+                return _unauthenticated(message)
             errors.append(f"{subcommand}: {message}")
             continue
+        payload_error = _payload_error(payload)
+        if payload_error is not None:
+            if _looks_unauthenticated(payload_error):
+                return _unauthenticated(payload_error)
+            errors.append(f"{subcommand}: {payload_error}")
+            continue
         account = _account_from_payload(payload, plan=plan)
         if account is not None:
             accounts.append(account)
@@ -112,4 +120,49 @@ def _looks_unauthenticated(message: str) -> bool:
         or "not authenticated" in lowered
         or "auth login" in lowered
         or "login required" in lowered
+        or "not logged in" in lowered
+        or "session" in lowered
+        and "expired" in lowered
     )
+
+
+LOGIN_HINT = "run `bl auth login --console` to sign in again"
+
+
+def _config_path() -> Path:
+    return Path.home() / ".bailian" / "config.json"
+
+
+def _unauthenticated(message: str) -> list[AccountUsage]:
+    """The console session is missing or expired (aiuse-oja).
+
+    On a machine where bl was never set up this stays quiet, like
+    muse/clinepass. Once ``~/.bailian/config.json`` exists the operator has
+    logged in before, so the session has expired: say so on one alibaba row.
+    That row outranks CodexBar's cookie-based alibaba errors in the source
+    priority, so the board shows the fix instead of an unrelated cookie
+    failure. bl is not re-run and nothing tries to log in.
+    """
+    if not _config_path().exists():
+        return []
+    expired = "expired" in message.lower() or "not logged in" in message.lower()
+    reason = "bl console session expired or not logged in" if expired else "bl console login missing"
+    return [
+        AccountUsage(
+            source="bailian",
+            provider="alibaba",
+            billing_kind=BillingKind.SUBSCRIPTION_WINDOW,
+            error=f"{reason}; {LOGIN_HINT}",
+        )
+    ]
+
+
+def _payload_error(payload: Any) -> str | None:
+    """bl's ``{"error": {"message": ..., "hint": ...}}`` envelope as one line."""
+    if not isinstance(payload, dict) or "error" not in payload:
+        return None
+    error = payload.get("error")
+    if isinstance(error, dict):
+        parts = [str(error.get(key)).strip() for key in ("message", "hint") if error.get(key)]
+        return " ".join(parts) or json.dumps(error)
+    return str(error)

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/collectors/base.py

@@ -14,6 +14,10 @@ class CollectorError(RuntimeError):
     pass
 
 
+class CollectorTimeout(CollectorError):
+    """A collector subprocess was killed at its timeout (it hung, not failed)."""
+
+
 # Keep in sync with ai.config.DEFAULT_SUBPROCESS_TIMEOUT (import avoided to
 # keep this module free of config load side effects for unit tests).
 DEFAULT_RUN_TIMEOUT = 45.0
@@ -118,7 +122,7 @@ def run_json(
     except FileNotFoundError as exc:
         raise CollectorError(f"command not found: {argv[0]}") from exc
     except subprocess.TimeoutExpired as exc:
-        raise CollectorError(f"timed out after {timeout}s: {' '.join(argv)}") from exc
+        raise CollectorTimeout(f"timed out after {timeout}s: {' '.join(argv)}") from exc
 
     stdout = (proc.stdout or "").strip()
     stderr = (proc.stderr or "").strip()

{aiuse-3.3.2 → aiuse-3.3.4}/src/aiuse/collectors/codexbar.py

@@ -12,6 +12,7 @@ from aiuse.models import (
     BillingKind,
     QuotaWindow,
     UsageCredits,
+    canonical_provider,
     classify_window_minutes,
     keep_copilot_report_window,
     parse_dt,
@@ -20,8 +21,8 @@ from aiuse.models import (
 from aiuse.models import coerce_float as _f
 from aiuse.models import coerce_int as _int_or_none
 
-from .base import CollectorError, run_json, which
-from .throttle import QueryGate
+from .base import CollectorError, CollectorTimeout, run_json, which
+from .throttle import QueryGate, TimeoutBackoff
 
 # Providers that are typically pure prepaid / API balance (not use-or-lose monthly)
 PREPAID_HINTS = {
@@ -41,11 +42,23 @@ PREPAID_HINTS = {
 # unreasonable number of processes for a very long explicit --providers list.
 _MAX_CONCURRENT_PROVIDER_QUERIES = 16
 
-# CodexBar `auto` for these providers prefers a local heuristic that can diverge
-# from server-authoritative quotas. OpenCode Go's local path sums SQLite costs
-# against hardcoded $12/$30/$60 caps; the live billing page is the real limit.
-# Force `--source web` first, then fall back to auto if web is unavailable.
-_WEB_PREFERRED_PROVIDERS = frozenset({"opencodego"})
+# After a provider's query hangs until its timeout, skip it for this long
+# (doubling per further consecutive timeout, capped at 12x). One hanging
+# provider otherwise holds every aiuse run, including each scheduled sample,
+# at the full CodexBar timeout. [collectors.codexbar] timeout_backoff overrides;
+# 0 disables. See aiuse-e9d and docs/collector-concurrency.md.
+DEFAULT_TIMEOUT_BACKOFF_SECONDS = 1800.0
+
+# Providers queried with a specific CodexBar `--source` first, falling back to
+# `auto` when that source returns nothing usable.
+#
+# - opencodego -> web: `auto` prefers a local heuristic that sums SQLite costs
+#   against hardcoded $12/$30/$60 caps; the live billing page is the real limit.
+# - antigravity -> oauth: `auto` reads the agy CLI, which spawns agy three times
+#   per probe and boots its language server each time (issue #34). `oauth`
+#   reads stored Google auth and spawns nothing; when it has no credentials
+#   the CLI path still runs, gated by query_min_interval.
+_PREFERRED_SOURCES: dict[str, str] = {"opencodego": "web", "antigravity": "oauth"}
 
 _SLOT_LABELS: dict[str, tuple[str, str, str]] = {
     # CodexBar maps Copilot primary→premium, secondary→chat (no tertiary /
@@ -109,6 +122,9 @@ def collect_codexbar(
     timeout: float = 45.0,
     discovery_timeout: float | None = None,
     min_intervals: dict[str, float] | None = None,
+    skip_providers: frozenset[str] | None = None,
+    provider_timeouts: dict[str, float] | None = None,
+    timeout_backoff: float | None = DEFAULT_TIMEOUT_BACKOFF_SECONDS,
 ) -> list[AccountUsage]:
     if not which("codexbar"):
         raise CollectorError("codexbar not found on PATH")
@@ -124,12 +140,26 @@ def collect_codexbar(
         if discovered:
             provider_list = discovered
 
+    if skip_providers:
+        # [disabled_services]: never spawn a query (or surface its timeout) for a
+        # provider the operator turned off, even if CodexBar still has it enabled.
+        kept = [p for p in provider_list if p is None or canonical_provider(p) not in skip_providers]
+        if not kept:
+            return []
+        provider_list = kept
+
     accounts: list[AccountUsage] = []
     errors: list[str] = []
     reuse_notes: dict[str, str] = {}
 
+    backoff = TimeoutBackoff("codexbar", base=timeout_backoff) if timeout_backoff else None
     for provider_arg, outcome in _query_providers(
-        provider_list, timeout=timeout, min_intervals=min_intervals, reuse_notes=reuse_notes
+        provider_list,
+        timeout=timeout,
+        min_intervals=min_intervals,
+        reuse_notes=reuse_notes,
+        provider_timeouts=provider_timeouts,
+        backoff=backoff,
     ):
         if isinstance(outcome, CollectorError):
             name = provider_arg or "enabled providers"
@@ -212,6 +242,8 @@ def _query_providers(
     timeout: float = 45.0,
     min_intervals: dict[str, float] | None = None,
     reuse_notes: dict[str, str] | None = None,
+    provider_timeouts: dict[str, float] | None = None,
+    backoff: TimeoutBackoff | None = None,
 ) -> list[tuple[str | None, Any]]:
     """Run one `codexbar usage` call per entry in provider_list, concurrently.
 
@@ -224,15 +256,35 @@ def _query_providers(
     Providers listed in ``min_intervals`` go through a cross-process
     :class:`QueryGate`; when one is throttled its last stored payload is
     returned instead and ``reuse_notes[provider]`` explains why.
+
+    ``provider_timeouts`` overrides ``timeout`` per provider. With a
+    ``backoff``, a provider whose last query hung is skipped (its error says
+    until when) and a fresh hang is recorded for the next run.
     """
     deduped: list[str | None] = list(dict.fromkeys(provider_list))
     intervals = min_intervals or {}
+    per_provider = {str(k).strip().lower(): float(v) for k, v in (provider_timeouts or {}).items()}
     notes = reuse_notes if reuse_notes is not None else {}
 
     def run(provider_arg: str | None) -> Any:
-        if provider_arg is not None and intervals.get(provider_arg.lower(), 0) > 0:
-            return _query_provider_gated(provider_arg, intervals[provider_arg.lower()], timeout=timeout, notes=notes)
-        return _query_provider(provider_arg, timeout=timeout)
+        if provider_arg is None:
+            return _query_provider(None, timeout=timeout)
+        provider = provider_arg.lower()
+        provider_timeout = per_provider.get(provider, timeout)
+        if backoff is not None:
+            reason = backoff.blocked(provider)
+            if reason is not None:
+                return CollectorError(reason)
+        if intervals.get(provider, 0) > 0:
+            outcome = _query_provider_gated(provider_arg, intervals[provider], timeout=provider_timeout, notes=notes)
+        else:
+            outcome = _query_provider(provider_arg, timeout=provider_timeout)
+        if backoff is not None:
+            if isinstance(outcome, CollectorTimeout):
+                backoff.record_timeout(provider, provider_timeout)
+            elif provider_arg not in notes:  # a live answer, not a throttled reuse
+                backoff.clear(provider)
+        return outcome
 
     if len(deduped) <= 1:
         return [(provider_arg, run(provider_arg)) for provider_arg in deduped]
@@ -257,7 +309,7 @@ def _query_provider_gated(
     with QueryGate(provider, min_interval=min_interval, wait=timeout + 15.0) as gate:
         if gate.allowed:
             outcome = _query_provider(provider_arg, timeout=timeout)
-            gate.record("codexbar", outcome)
+            gate.record("codexbar", outcome, usable=_usable_usage_payload(outcome))
             return outcome
         reused_at = gate.reused_from("codexbar")
         if reused_at is not None:
@@ -272,13 +324,13 @@ def _query_provider(provider_arg: str | None, *, timeout: float = 45.0) -> Any:
     if provider_arg is not None:
         argv.extend(["--provider", provider_arg])
 
-    prefer_web = provider_arg is not None and provider_arg.lower() in _WEB_PREFERRED_PROVIDERS
-    if prefer_web:
-        web_outcome = _run_codexbar_usage([*argv, "--source", "web"], timeout=timeout)
-        if _usable_usage_payload(web_outcome):
-            return web_outcome
-        # Web failed or returned only errors — fall through to CodexBar auto
-        # (local heuristic) so the provider still appears in the report.
+    preferred = _PREFERRED_SOURCES.get(provider_arg.lower()) if provider_arg is not None else None
+    if preferred is not None:
+        preferred_outcome = _run_codexbar_usage([*argv, "--source", preferred], timeout=timeout)
+        if _usable_usage_payload(preferred_outcome):
+            return preferred_outcome
+        # The preferred source failed or returned only errors — fall through to
+        # CodexBar auto so the provider still appears in the report.
 
     return _run_codexbar_usage(argv, timeout=timeout)