cctally 1.21.3 → 1.22.1

package/bin/_lib_alerts_payload.py

@@ -192,3 +192,53 @@ def _build_alert_payload_five_hour(
             "primary_model": primary_model,
         },
     }
+
+
+def _alert_text_budget(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for an equiv-$ budget threshold alert.
+
+    ``week_start_at`` is an instant, but the budget alert text doesn't render
+    it (the subtitle is the threshold, the body the dollar progress) — so no
+    ``format_display_dt`` call is needed here. ``tz`` is accepted for
+    signature parity with peer ``_alert_text_*`` builders and intentionally
+    unused.
+    """
+    threshold = int(payload["threshold"])
+    title = "cctally - budget"
+    subtitle = f"{threshold}% of budget"
+    ctx = payload.get("context") or {}
+    spent = float(ctx.get("spent_usd") or 0.0)
+    budget = float(ctx.get("budget_usd") or 0.0)
+    consumption = float(ctx.get("consumption_pct") or 0.0)
+    body = f"${spent:,.2f} of ${budget:,.2f} ({consumption:.0f}% of budget)"
+    return title, subtitle, body
+
+
+def _build_alert_payload_budget(
+    *,
+    threshold: int,
+    crossed_at_utc: str,
+    week_start_at: str,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+) -> dict:
+    """Build the alert payload for an equiv-$ budget threshold crossing.
+
+    See ``_build_alert_payload_weekly`` for the ``alerted_at == crossed_at``
+    rationale (set-then-dispatch invariant). ``axis: "budget"`` is the third
+    alert axis (Task 4 surfaces it in the dashboard Recent-alerts panel).
+    """
+    return {
+        "id": f"budget:{week_start_at}:{threshold}",
+        "axis": "budget",
+        "threshold": int(threshold),
+        "crossed_at": crossed_at_utc,
+        "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "context": {
+            "week_start_at": week_start_at,
+            "budget_usd": float(budget_usd),
+            "spent_usd": float(spent_usd),
+            "consumption_pct": float(consumption_pct),
+        },
+    }

package/bin/_lib_budget.py

@@ -0,0 +1,133 @@
+"""Pure-function kernel for `cctally budget` (no I/O — every dep injected).
+
+Mirrors the _lib_statusline.py / _lib_doctor.py / _lib_pricing_check.py
+pattern. Re-exported on the cctally module. See
+docs/superpowers/specs/2026-05-29-cctally-budget-design.md §3.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+# Early in the week / no data → projections are unreliable; annotate LOW CONF
+# (mirrors forecast's thin-data caution). Tunable single source of truth.
+_BUDGET_LOW_CONF_ELAPSED_FRACTION = 0.15
+# Fallback warn fraction when alert_thresholds is empty (alerts silenced) but
+# we still render a verdict.
+_BUDGET_DEFAULT_WARN_FRACTION = 0.90
+
+
+def project_linear(
+    current: float,
+    remaining: float,
+    rate_low: float,
+    rate_high: float,
+) -> tuple[float, float]:
+    """Project ``current + rate * remaining`` for a (low, high) rate band.
+
+    Pure; unit-agnostic — percent for forecast, dollars for budget. The caller
+    is responsible for passing ``rate_low <= rate_high`` if it wants ordered
+    output; this primitive does NOT sort (forecast sorts the outputs to stay a
+    byte-exact no-op vs its goldens; budget passes a pre-ordered band).
+    """
+    return (current + rate_low * remaining, current + rate_high * remaining)
+
+
+@dataclass(frozen=True)
+class BudgetInputs:
+    target_usd: float
+    spent_usd: float            # cumulative equiv-$ this subscription week
+    recent_24h_usd: float       # trailing-24h equiv-$ (recent-rate projection)
+    week_start_at: dt.datetime  # effective (post-reset) week start, tz-aware
+    week_end_at: dt.datetime    # tz-aware
+    now: dt.datetime            # tz-aware
+    alert_thresholds: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class BudgetStatus:
+    spent_usd: float
+    remaining_usd: float                # target - spent (may be < 0)
+    consumption_pct: float              # spent / target * 100 (monotonic key)
+    elapsed_fraction: float             # [0, 1]
+    projected_eow_low_usd: float
+    projected_eow_high_usd: float
+    verdict: str                        # "ok" | "warn" | "over"
+    daily_budget_remaining_usd: float   # remaining / remaining-days
+    daily_pace_usd: float               # current burn $/day (week-average)
+    low_confidence: bool
+    crossed_thresholds: tuple[int, ...]
+
+
+def compute_budget_status(inputs: BudgetInputs) -> BudgetStatus:
+    """Compute budget status from injected inputs. Pure; deterministic."""
+    target = float(inputs.target_usd)
+    spent = float(inputs.spent_usd)
+
+    total_seconds = (inputs.week_end_at - inputs.week_start_at).total_seconds()
+    elapsed_seconds = (inputs.now - inputs.week_start_at).total_seconds()
+    # Clamp elapsed into [0, total] so a now before/after the window stays sane.
+    if total_seconds <= 0:
+        elapsed_seconds = 0.0
+        elapsed_fraction = 0.0
+    else:
+        elapsed_seconds = max(0.0, min(elapsed_seconds, total_seconds))
+        elapsed_fraction = elapsed_seconds / total_seconds
+    remaining_seconds = max(0.0, total_seconds - elapsed_seconds)
+
+    elapsed_hours = elapsed_seconds / 3600.0
+    remaining_hours = remaining_seconds / 3600.0
+    remaining_days = remaining_hours / 24.0
+
+    consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+    remaining_usd = target - spent
+
+    # Dollar rates ($/hour). Week-average from spend-so-far; recent from
+    # trailing-24h spend. Ordered band low<=high for project_linear.
+    rate_avg = (spent / elapsed_hours) if elapsed_hours > 0 else 0.0
+    rate_recent = float(inputs.recent_24h_usd) / 24.0
+    rate_low = min(rate_avg, rate_recent)
+    rate_high = max(rate_avg, rate_recent)
+
+    projected_low, projected_high = project_linear(
+        spent, remaining_hours, rate_low, rate_high
+    )
+
+    daily_pace_usd = rate_avg * 24.0
+    daily_budget_remaining_usd = (
+        (remaining_usd / remaining_days) if remaining_days > 0 else remaining_usd
+    )
+
+    thresholds = tuple(sorted(set(int(t) for t in inputs.alert_thresholds)))
+    if thresholds:
+        warn_fraction = min(thresholds) / 100.0
+    else:
+        warn_fraction = _BUDGET_DEFAULT_WARN_FRACTION
+
+    projected = max(projected_low, projected_high)
+    if spent > target or projected > target:
+        verdict = "over"
+    elif projected >= warn_fraction * target:
+        verdict = "warn"
+    else:
+        verdict = "ok"
+
+    low_confidence = (
+        elapsed_fraction < _BUDGET_LOW_CONF_ELAPSED_FRACTION or spent <= 0.0
+    )
+
+    crossed = tuple(t for t in thresholds if consumption_pct + 1e-9 >= t)
+
+    return BudgetStatus(
+        spent_usd=spent,
+        remaining_usd=remaining_usd,
+        consumption_pct=consumption_pct,
+        elapsed_fraction=elapsed_fraction,
+        projected_eow_low_usd=projected_low,
+        projected_eow_high_usd=projected_high,
+        verdict=verdict,
+        daily_budget_remaining_usd=daily_budget_remaining_usd,
+        daily_pace_usd=daily_pace_usd,
+        low_confidence=low_confidence,
+        crossed_thresholds=crossed,
+    )

package/bin/_lib_doctor.py

@@ -130,6 +130,16 @@ class DoctorState:
     cctally_reachable_on_path: Optional[bool] = None
     symlinks_path_pinned: bool = False
     install_is_brew: bool = False
+    # Pricing coverage (spec §5.1): the list[CoverageGap] of unpriced (Claude
+    # $0) / fallback (Codex gpt-5) models observed in the trailing 30-day
+    # window, populated by `doctor_gather_state` via `_pricing_observed_models`
+    # + `classify_coverage`. None means the cache could not be read (or the
+    # classification raised) — the check degrades to OK ("no cached usage to
+    # assess"), consistent with the kernel's degradation posture. Each element
+    # is a `_lib_pricing_check.CoverageGap` (provider/model/kind/entry_count/
+    # token_total); the kernel only reads `.kind`/`.model`/`.entry_count`/
+    # `.token_total`, so any duck-typed equivalent works for tests.
+    pricing_coverage: Optional[list] = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -761,6 +771,67 @@ def _check_data_post_credit_milestones(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_pricing_coverage(s: DoctorState) -> CheckResult:
+    """WARN when recent (30-day) session data contains a model cctally cannot
+    price exactly (spec §5.1).
+
+    Two gap kinds (classified upstream in `_lib_pricing_check.classify_coverage`,
+    populated by `doctor_gather_state`):
+      * ``unpriced`` — a Claude model `_resolve_model_pricing` returns None for;
+        it silently contributes $0 (the serious undercount failure mode).
+      * ``fallback`` — a Codex model approximated via `gpt-5` pricing.
+
+    ``s.pricing_coverage is None`` means the cache could not be read (or the
+    classification raised) → OK ("no cached usage to assess"), matching the
+    rest of the kernel's degradation posture. An empty list → OK. Any gap →
+    WARN (a data-quality signal, deliberately NOT FAIL — doctor FAIL exits 2;
+    consistent with the other WARN-family Data checks).
+
+    ``details`` is a structured dict (sibling-check convention): two lists of
+    ``{model, entry_count, token_total}`` keyed by gap kind, so a `--json`
+    consumer can machine-read each gap. The human summary + remediation point
+    at `cctally pricing-check` and the pricing tables.
+    """
+    gaps = s.pricing_coverage
+    if not gaps:
+        return CheckResult(
+            id="pricing.coverage", title="Coverage",
+            severity="ok",
+            summary="all observed models priced",
+            remediation=None,
+            details={"unpriced": [], "fallback": []},
+        )
+
+    def _row(g) -> dict:
+        return {
+            "model": g.model,
+            "entry_count": g.entry_count,
+            "token_total": g.token_total,
+        }
+
+    unpriced = [_row(g) for g in gaps if g.kind == "unpriced"]
+    fallback = [_row(g) for g in gaps if g.kind == "fallback"]
+
+    parts: list[str] = []
+    if unpriced:
+        parts.append(f"{len(unpriced)} unpriced (Claude $0)")
+    if fallback:
+        parts.append(f"{len(fallback)} fallback (Codex gpt-5)")
+    # Defensive: a gap whose kind is neither (shouldn't happen) still WARNs.
+    summary = "; ".join(parts) if parts else f"{len(gaps)} coverage gaps"
+
+    return CheckResult(
+        id="pricing.coverage", title="Coverage",
+        severity="warn",
+        summary=summary,
+        remediation=(
+            "Run `cctally pricing-check`, then update CLAUDE_MODEL_PRICING / "
+            "CODEX_MODEL_PRICING in bin/_lib_pricing.py"
+        ),
+        details={"unpriced": unpriced, "fallback": fallback},
+    )
+
+
 _LOOPBACK_HOSTS = frozenset({"loopback", "127.0.0.1", "::1", "localhost"})
 
 
@@ -991,6 +1062,9 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("data.forked_buckets", "_check_data_forked_buckets"),
         ("data.post_credit_milestones", "_check_data_post_credit_milestones"),
     )),
+    ("pricing", "Pricing", (
+        ("pricing.coverage", "_check_pricing_coverage"),
+    )),
     ("safety", "Safety", (
         ("safety.dashboard_bind", "_check_safety_dashboard_bind"),
         ("safety.config_json_valid", "_check_safety_config_json_valid"),

package/bin/_lib_pricing.py

@@ -46,9 +46,28 @@ def _chip_for_model(name: str) -> str:
     return "other"
 
 
+# Date the embedded pricing snapshots below were last verified against
+# vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
+# is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
+PRICING_SNAPSHOT_DATE = "2026-05-30"
+PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
+
+# Canonical machine-readable pricing source (Claude values + Codex values).
+LITELLM_PRICES_URL = (
+    "https://raw.githubusercontent.com/BerriAI/litellm/main/"
+    "model_prices_and_context_window.json"
+)
+
+# Deliberate divergences from LiteLLM the drift check must NOT flag. Each
+# entry suppresses either a specific value mismatch ({"model","field","reason"})
+# or an intentionally-omitted in-scope model ({"model","reason"} — no field).
+# Guarded by `stale_allowlist_entries` (tests/test_pricing_check.py): an entry
+# that no longer corresponds to a real divergence fails the suite.
+PRICING_DRIFT_ALLOWLIST: list[dict] = []
+
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-05-04
+# - Captured: 2026-05-30 (see PRICING_SNAPSHOT_DATE)
 # - Verified by maintainer against docs.claude.com/en/docs/about-claude/pricing;
 #   update in PRs touching this table.
 CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
@@ -246,12 +265,12 @@ _unknown_model_warnings: set[str] = set()
 #
 # Codex (OpenAI) API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-05-04
-# - Models listed are those observed in ~/.codex/sessions/ at implementation
-#   time plus common Codex/GPT-5 variants. Models absent from this table fall
-#   back to `gpt-5` pricing with isFallback=true (matches upstream's
-#   LEGACY_FALLBACK_MODEL behavior); a one-shot stderr warning is emitted per
-#   unknown model name.
+# - Captured: 2026-05-30 (see PRICING_SNAPSHOT_DATE)
+# - As of the 2026-05-30 sync (issue #123) this carries every openai-provider
+#   gpt-5* model the LiteLLM snapshot lists, so `pricing-check`'s scope finds
+#   nothing missing. Models absent from this table still fall back to `gpt-5`
+#   pricing with isFallback=true (matches upstream's LEGACY_FALLBACK_MODEL
+#   behavior); a one-shot stderr warning is emitted per unknown model name.
 #
 # Billing rules:
 # - reasoning_output_tokens is billed at the *output* rate (matches
@@ -333,12 +352,185 @@ CODEX_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "output_cost_per_token": 4.5e-06,
     },
     "gpt-5.5": {
-        # Source: OpenAI published pricing (announced 2026-04-23). Input
-        # $5.00/M, cached $0.50/M, output $30.00/M. No above-272k tier
-        # announced. Add tiered fields here when LiteLLM publishes them.
+        # Source: LiteLLM model_prices_and_context_window.json (announced
+        # 2026-04-23). Input $5.00/M, cached $0.50/M, output $30.00/M. The
+        # above-272k tier ($10.00/M / $1.00/M / $45.00/M) was published in the
+        # 2026-05-30 sync (issue #123) and matches the dated alias below.
         "input_cost_per_token": 5e-06,
         "cache_read_input_token_cost": 5e-07,
         "output_cost_per_token": 3e-05,
+        "input_cost_per_token_above_272k_tokens": 1e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 1e-06,
+        "output_cost_per_token_above_272k_tokens": 4.5e-05,
+    },
+    # ── Issue #123: full gpt-5.x LiteLLM sync (2026-05-30 snapshot) ──
+    # Exact model_prices_and_context_window.json values for every
+    # openai-provider gpt-5* model `pricing-check`'s scope flags but the
+    # curated set above didn't carry (bare/dated/-chat/-pro/-mini/-nano/
+    # -search variants). The four *-pro models omit cache_read upstream; we
+    # set it to input_cost_per_token / 4 (the documented LiteLLM cache
+    # fallback) so the table stays well-formed and cached-input turns price.
+    "gpt-5-2025-08-07": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5-chat": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5-chat-latest": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5-mini": {
+        "input_cost_per_token": 2.5e-07,
+        "cache_read_input_token_cost": 2.5e-08,
+        "output_cost_per_token": 2e-06,
+    },
+    "gpt-5-mini-2025-08-07": {
+        "input_cost_per_token": 2.5e-07,
+        "cache_read_input_token_cost": 2.5e-08,
+        "output_cost_per_token": 2e-06,
+    },
+    "gpt-5-nano": {
+        "input_cost_per_token": 5e-08,
+        "cache_read_input_token_cost": 5e-09,
+        "output_cost_per_token": 4e-07,
+    },
+    "gpt-5-nano-2025-08-07": {
+        "input_cost_per_token": 5e-08,
+        "cache_read_input_token_cost": 5e-09,
+        "output_cost_per_token": 4e-07,
+    },
+    "gpt-5-pro": {
+        # *-pro: LiteLLM omits cache_read; input/4 documented fallback.
+        "input_cost_per_token": 1.5e-05,
+        "cache_read_input_token_cost": 3.75e-06,
+        "output_cost_per_token": 0.00012,
+    },
+    "gpt-5-pro-2025-10-06": {
+        # *-pro: LiteLLM omits cache_read; input/4 documented fallback.
+        "input_cost_per_token": 1.5e-05,
+        "cache_read_input_token_cost": 3.75e-06,
+        "output_cost_per_token": 0.00012,
+    },
+    "gpt-5-search-api": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5-search-api-2025-10-14": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5.1": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5.1-2025-11-13": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5.1-chat-latest": {
+        "input_cost_per_token": 1.25e-06,
+        "cache_read_input_token_cost": 1.25e-07,
+        "output_cost_per_token": 1e-05,
+    },
+    "gpt-5.2-2025-12-11": {
+        "input_cost_per_token": 1.75e-06,
+        "cache_read_input_token_cost": 1.75e-07,
+        "output_cost_per_token": 1.4e-05,
+    },
+    "gpt-5.2-chat-latest": {
+        "input_cost_per_token": 1.75e-06,
+        "cache_read_input_token_cost": 1.75e-07,
+        "output_cost_per_token": 1.4e-05,
+    },
+    "gpt-5.2-pro": {
+        # *-pro: LiteLLM omits cache_read; input/4 documented fallback.
+        "input_cost_per_token": 2.1e-05,
+        "cache_read_input_token_cost": 5.25e-06,
+        "output_cost_per_token": 0.000168,
+    },
+    "gpt-5.2-pro-2025-12-11": {
+        # *-pro: LiteLLM omits cache_read; input/4 documented fallback.
+        "input_cost_per_token": 2.1e-05,
+        "cache_read_input_token_cost": 5.25e-06,
+        "output_cost_per_token": 0.000168,
+    },
+    "gpt-5.3-chat-latest": {
+        "input_cost_per_token": 1.75e-06,
+        "cache_read_input_token_cost": 1.75e-07,
+        "output_cost_per_token": 1.4e-05,
+    },
+    "gpt-5.4-2026-03-05": {
+        "input_cost_per_token": 2.5e-06,
+        "cache_read_input_token_cost": 2.5e-07,
+        "output_cost_per_token": 1.5e-05,
+        "input_cost_per_token_above_272k_tokens": 5e-06,
+        "cache_read_input_token_cost_above_272k_tokens": 5e-07,
+        "output_cost_per_token_above_272k_tokens": 2.25e-05,
+    },
+    "gpt-5.4-mini-2026-03-17": {
+        "input_cost_per_token": 7.5e-07,
+        "cache_read_input_token_cost": 7.5e-08,
+        "output_cost_per_token": 4.5e-06,
+    },
+    "gpt-5.4-nano": {
+        "input_cost_per_token": 2e-07,
+        "cache_read_input_token_cost": 2e-08,
+        "output_cost_per_token": 1.25e-06,
+    },
+    "gpt-5.4-nano-2026-03-17": {
+        "input_cost_per_token": 2e-07,
+        "cache_read_input_token_cost": 2e-08,
+        "output_cost_per_token": 1.25e-06,
+    },
+    "gpt-5.4-pro": {
+        "input_cost_per_token": 3e-05,
+        "cache_read_input_token_cost": 3e-06,
+        "output_cost_per_token": 0.00018,
+        "input_cost_per_token_above_272k_tokens": 6e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 6e-06,
+        "output_cost_per_token_above_272k_tokens": 0.00027,
+    },
+    "gpt-5.4-pro-2026-03-05": {
+        "input_cost_per_token": 3e-05,
+        "cache_read_input_token_cost": 3e-06,
+        "output_cost_per_token": 0.00018,
+        "input_cost_per_token_above_272k_tokens": 6e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 6e-06,
+        "output_cost_per_token_above_272k_tokens": 0.00027,
+    },
+    "gpt-5.5-2026-04-23": {
+        "input_cost_per_token": 5e-06,
+        "cache_read_input_token_cost": 5e-07,
+        "output_cost_per_token": 3e-05,
+        "input_cost_per_token_above_272k_tokens": 1e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 1e-06,
+        "output_cost_per_token_above_272k_tokens": 4.5e-05,
+    },
+    "gpt-5.5-pro": {
+        "input_cost_per_token": 3e-05,
+        "cache_read_input_token_cost": 3e-06,
+        "output_cost_per_token": 0.00018,
+        "input_cost_per_token_above_272k_tokens": 6e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 6e-06,
+        "output_cost_per_token_above_272k_tokens": 0.00027,
+    },
+    "gpt-5.5-pro-2026-04-23": {
+        "input_cost_per_token": 3e-05,
+        "cache_read_input_token_cost": 3e-06,
+        "output_cost_per_token": 0.00018,
+        "input_cost_per_token_above_272k_tokens": 6e-05,
+        "cache_read_input_token_cost_above_272k_tokens": 6e-06,
+        "output_cost_per_token_above_272k_tokens": 0.00027,
     },
 }
 
@@ -411,8 +603,16 @@ def _is_codex_fallback(model: str) -> bool:
     return model not in CODEX_MODEL_PRICING
 
 
-def _resolve_model_pricing(model: str) -> dict[str, Any] | None:
-    """Look up pricing for a model name. Returns None if unknown."""
+def _resolve_model_pricing(model: str, warn: bool = True) -> dict[str, Any] | None:
+    """Look up pricing for a model name. Returns None if unknown.
+
+    `warn=True` (default) emits a one-shot `[cost] unknown model` stderr warning
+    on a miss — correct for cost computation. Detection-only callers (e.g. the
+    doctor pricing-coverage scan, whose whole job is to find unpriced models)
+    pass `warn=False` so they don't fire the cost-engine warning as a side
+    effect, and don't poison `_unknown_model_warnings` (which would suppress a
+    later genuine cost-path warning for the same model).
+    """
     pricing = CLAUDE_MODEL_PRICING.get(model)
     if pricing is not None:
         return pricing
@@ -422,7 +622,7 @@ def _resolve_model_pricing(model: str) -> dict[str, Any] | None:
             pricing = CLAUDE_MODEL_PRICING.get(stripped)
             if pricing is not None:
                 return pricing
-    if model not in _unknown_model_warnings:
+    if warn and model not in _unknown_model_warnings:
         _unknown_model_warnings.add(model)
         _eprint(f"[cost] unknown model, treating cost as $0: {model}")
     return None