cctally 1.21.2 → 1.22.0

package/bin/_lib_doctor.py

@@ -103,6 +103,43 @@ class DoctorState:
     dev_mode: bool
     app_dir: str
     is_dev_checkout: bool = False
+    # Issue #119: availability-aware install checks. Both precomputed by
+    # `doctor_gather_state` (the I/O layer) so the kernel stays pure —
+    # `shutil.which` and the on-disk legacy-link probe never run here.
+    # Defaulted (and placed last, after `is_dev_checkout`) so existing
+    # constructors that don't pass them still work and the dataclass's
+    # non-default-then-default field ordering stays valid.
+    #   * cctally_reachable_on_path — `shutil.which("cctally") is not None`;
+    #     channel-agnostic (brew `<prefix>/bin`, npm prefix, source
+    #     `~/.local/bin` all satisfy it). Lets `_check_install_path` pass
+    #     whenever the command is reachable, not only when `~/.local/bin`
+    #     is on PATH.
+    #   * symlinks_path_pinned — true iff cctally is reachable ONLY through
+    #     a legacy `~/.local/bin` link to a retired/foreign (e.g. Homebrew
+    #     keg) install (a live retired link with no `reachable_elsewhere`
+    #     fallback). The kernel can't tell this `wrong`-mode apart from an
+    #     ordinary occupied slot from `(name, state)` alone, so it's
+    #     precomputed; drives the PATH-fix remediation in
+    #     `_check_install_symlinks`.
+    #   * install_is_brew — true iff this cctally runs from a Homebrew keg
+    #     (`_setup_is_brew_install(repo_root)`). Channel knowledge the
+    #     kernel can't derive from `repo_root` (it does no I/O); drives the
+    #     channel-aware `_check_install_path` WARN remediation so a brew
+    #     install isn't told to fix a `~/.local/bin` it deliberately
+    #     doesn't use (#119 made brew `~/.local/bin`-free).
+    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)
@@ -145,6 +182,11 @@ def _max_severity(severities: list[str]) -> str:
 
 
 def _check_install_symlinks(s: DoctorState) -> CheckResult:
+    # Issue #119: the symlink state grew a fourth value, `stale` — a
+    # retired/foreign (e.g. Homebrew keg) link whose command IS still
+    # reachable elsewhere, so the link is safely-cleanable cruft, not a
+    # broken slot. Count `available = ok + stale` (both ⟹ reachable);
+    # `bad = wrong + missing` is what is genuinely actionable.
     if s.symlink_state is None:
         return CheckResult(
             id="install.symlinks", title="Symlinks",
@@ -152,35 +194,89 @@ def _check_install_symlinks(s: DoctorState) -> CheckResult:
             remediation="See logs", details={"reason": "gather returned None"},
         )
     total = len(s.symlink_state)
-    missing = [n for n, st in s.symlink_state if st != "ok"]
-    ok_count = total - len(missing)
-    if not missing:
+    stale = [n for n, st in s.symlink_state if st == "stale"]
+    bad = [n for n, st in s.symlink_state if st in ("wrong", "missing")]
+    available = total - len(bad)            # available = ok + stale
+    # "missing" carries the full `bad` list (wrong + missing); the key name is
+    # kept for JSON-schema stability even though it now spans both states.
+    details = {"present": available, "total": total,
+               "missing": bad, "stale": stale}
+    if not bad and not stale:
         return CheckResult(
             id="install.symlinks", title="Symlinks",
-            severity="ok", summary=f"{ok_count}/{total} available",
-            remediation=None,
-            details={"present": ok_count, "total": total, "missing": []},
+            severity="ok", summary=f"{available}/{total} available",
+            remediation=None, details=details,
         )
+    if not bad:   # stale only
+        return CheckResult(
+            id="install.symlinks", title="Symlinks",
+            severity="warn",
+            summary=f"{available}/{total} available; {len(stale)} stale link(s) to clean",
+            remediation="Run `cctally setup` to clean stale links",
+            details=details,
+        )
+    # bad present
+    if s.symlinks_path_pinned:
+        # Pinned-only-path (finding #2/#10): cctally runs ONLY through a
+        # legacy ~/.local/bin link to a keg, so its slot classes `wrong`
+        # but the command works. `cctally setup` deliberately won't remove
+        # the only reachable copy — the actionable fix is a PATH change.
+        # Keep this message in sync with the pinned guidance in _setup_install
+        # (bin/_cctally_setup.py).
+        remediation = (
+            "cctally is reachable only through a legacy ~/.local/bin link to a "
+            "Homebrew keg. Put <prefix>/bin on your PATH (e.g. `eval \"$(brew shellenv)\"`), "
+            "then run `cctally setup` to remove the legacy link."
+        )
+    else:
+        remediation = "Run `cctally setup`"
+    summary = f"{available}/{total} available; missing/broken {', '.join(bad)}"
+    if stale:
+        summary += f"; {len(stale)} stale"
     return CheckResult(
         id="install.symlinks", title="Symlinks",
-        severity="warn",
-        summary=f"{ok_count}/{total} available; missing {', '.join(missing)}",
-        remediation="Run `cctally setup`",
-        details={"present": ok_count, "total": total, "missing": missing},
+        severity="warn", summary=summary, remediation=remediation, details=details,
     )
 
 
 def _check_install_path(s: DoctorState) -> CheckResult:
-    if s.path_includes_local_bin:
+    # Issue #119: availability-aware. OK iff cctally is ACTUALLY reachable
+    # on $PATH via ANY channel — brew `<prefix>/bin`, npm prefix, or source
+    # `~/.local/bin` (`shutil.which`, precomputed in the I/O layer). Mere
+    # `~/.local/bin` membership is NOT sufficient: doctor can be launched by
+    # absolute path or from another UI with `~/.local/bin` on $PATH yet no
+    # `cctally` installed there (the brew-only #119 case), which must WARN.
+    # `path_includes_local_bin` is only a fail-soft fallback for when the
+    # reachability probe could not run (None), so a gather failure never
+    # hard-WARNs an otherwise-working install.
+    reachable = s.cctally_reachable_on_path
+    if reachable is None:
+        reachable = bool(s.path_includes_local_bin)
+    if reachable:
         return CheckResult(
             id="install.path", title="PATH",
-            severity="ok", summary="~/.local/bin on $PATH",
+            severity="ok", summary="cctally reachable on $PATH",
             remediation=None, details={},
         )
+    # Channel-aware remediation: a Homebrew keg keeps cctally on
+    # `<prefix>/bin` and deliberately owns no `~/.local/bin` symlinks
+    # (#119), so the `~/.local/bin` / `cctally setup` hint would be wrong
+    # for it — point brew users at `brew shellenv` instead (matching the
+    # pinned-only-path remediation in `_check_install_symlinks`). Source /
+    # npm installs keep the `~/.local/bin` + `cctally setup` guidance.
+    if s.install_is_brew:
+        remediation = (
+            "Put `<prefix>/bin` on your PATH (e.g. `eval \"$(brew shellenv)\"`)"
+        )
+    else:
+        remediation = (
+            "Append `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell rc, "
+            "or run `cctally setup`"
+        )
     return CheckResult(
         id="install.path", title="PATH",
-        severity="warn", summary="~/.local/bin not on $PATH",
-        remediation="Append `export PATH=\"$HOME/.local/bin:$PATH\"` to your shell rc",
+        severity="warn", summary="cctally not reachable on $PATH",
+        remediation=remediation,
         details={},
     )
 
@@ -675,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"})
 
 
@@ -905,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-04"
+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-04 (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,7 +265,7 @@ _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
+# - Captured: 2026-05-04 (see PRICING_SNAPSHOT_DATE)
 # - 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
@@ -411,8 +430,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 +449,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

package/bin/_lib_pricing_check.py

@@ -0,0 +1,201 @@
+"""Pure-fn kernel for the pricing-freshness check (spec 2026-05-29).
+
+No I/O, no import of `cctally`/`_lib_pricing` at module scope — every
+dependency (pricing predicates, tables, observed rows, LiteLLM snapshot)
+is passed in by the I/O glue in bin/cctally. Re-exported there like the
+other _lib_* kernels.
+"""
+from __future__ import annotations
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class CoverageGap:
+    provider: str        # "claude" | "codex"
+    model: str
+    kind: str            # "unpriced" | "fallback"
+    entry_count: int
+    token_total: int
+
+
+@dataclasses.dataclass(frozen=True)
+class DriftRow:
+    model: str
+    field: str           # "" for whole-model categories
+    ours: float | None
+    theirs: float | None
+
+
+@dataclasses.dataclass(frozen=True)
+class DriftResult:
+    value_drift: list[DriftRow]
+    missing_from_us: list[str]
+    ahead_of_litellm: list[str]   # informational; never actionable
+
+
+def classify_coverage(observed, resolve_claude, is_codex_fallback) -> list[CoverageGap]:
+    """observed: iterable of (provider, model, entry_count, token_total).
+
+    Claude model with resolve_claude(model) is None -> kind="unpriced".
+    Codex model with is_codex_fallback(model) True  -> kind="fallback".
+    Priced models produce no gap. Order preserved.
+    """
+    gaps: list[CoverageGap] = []
+    for provider, model, entry_count, token_total in observed:
+        if provider == "claude":
+            if resolve_claude(model) is None:
+                gaps.append(CoverageGap("claude", model, "unpriced", entry_count, token_total))
+        elif provider == "codex":
+            if is_codex_fallback(model):
+                gaps.append(CoverageGap("codex", model, "fallback", entry_count, token_total))
+    return gaps
+
+
+def _is_codex_scope(name: str) -> bool:
+    # The Codex models we track are the gpt-5* family (incl. -codex variants).
+    # Keep this in sync with CODEX_MODEL_PRICING's key prefixes.
+    return name.startswith("gpt-5")
+
+
+def scope_litellm(litellm: dict) -> dict[str, dict]:
+    """Filter a full LiteLLM model_prices map down to the models we track:
+    anthropic-provider Claude models, and the gpt-5* Codex family. Skips the
+    `sample_spec` doc entry and any entry lacking a dict body."""
+    scoped: dict[str, dict] = {}
+    for name, body in litellm.items():
+        if not isinstance(body, dict):
+            continue
+        provider = body.get("litellm_provider")
+        if provider == "anthropic" and name.startswith("claude-"):
+            scoped[name] = body
+        elif provider == "openai" and _is_codex_scope(name):
+            scoped[name] = body
+    return scoped
+
+
+_DRIFT_EPS = 1e-12  # cost-per-token values are tiny; compare with a small abs epsilon
+
+
+def _allow_index(allowlist):
+    field_suppress = set()   # (model, field)
+    model_suppress = set()   # model (no field -> suppresses missing_from_us)
+    for e in allowlist or []:
+        if e.get("field"):
+            field_suppress.add((e["model"], e["field"]))
+        else:
+            model_suppress.add(e["model"])
+    return field_suppress, model_suppress
+
+
+def diff_pricing(claude_tbl, codex_tbl, litellm_scoped, allowlist=None) -> DriftResult:
+    """Direction-aware drift between our embedded tables and the scoped LiteLLM
+    snapshot.
+
+    value_drift     — shared model, a cost field differs beyond _DRIFT_EPS
+                      (actionable, unless allowlisted by model+field).
+    missing_from_us — scoped LiteLLM model absent from our tables
+                      (actionable, unless allowlisted by model with no field).
+    ahead_of_litellm — model we price that scoped LiteLLM lacks (informational;
+                      NEVER actionable — we may legitimately lead the source).
+
+    Value-drift is one-directional: it only compares fields LiteLLM carries, so
+    a cost field present in our table but absent upstream is not value-compared
+    (ahead_of_litellm reports at model granularity only). That matches the
+    feature's intent — catch vendor price moves on fields we track.
+    """
+    field_suppress, model_suppress = _allow_index(allowlist)
+    ours = {**claude_tbl, **codex_tbl}
+    value_drift: list[DriftRow] = []
+    missing: list[str] = []
+    ahead: list[str] = []
+
+    for model, body in litellm_scoped.items():
+        if model in ours:
+            for field, theirs in body.items():
+                # Broad cost-field filter; the `mine is None` guard below is what
+                # keeps it safe (skips any upstream cost field we don't carry), so
+                # don't remove that guard thinking this filter is precise.
+                if not field.endswith("_cost_per_token") and "cost" not in field:
+                    continue
+                # bool is an int subclass — exclude it so a non-numeric "cost" flag
+                # can never be read as a 0/1 price.
+                if isinstance(theirs, bool) or not isinstance(theirs, (int, float)):
+                    continue
+                if (model, field) in field_suppress:
+                    continue
+                mine = ours[model].get(field)
+                if mine is None:
+                    continue  # we don't carry this field; not a value-drift signal
+                if abs(float(mine) - float(theirs)) > _DRIFT_EPS:
+                    value_drift.append(DriftRow(model, field, float(mine), float(theirs)))
+        else:
+            if model not in model_suppress:
+                missing.append(model)
+
+    for model in ours:
+        if model not in litellm_scoped:
+            ahead.append(model)
+
+    return DriftResult(value_drift=value_drift, missing_from_us=missing, ahead_of_litellm=ahead)
+
+
+def stale_allowlist_entries(allowlist, claude_tbl, codex_tbl, litellm_scoped) -> list:
+    """Return allowlist entries that NO LONGER correspond to a real divergence.
+
+    An entry is stale if, with it removed, diff_pricing reports nothing it would
+    have suppressed (i.e. the value now matches / the model is now present)."""
+    ours = {**claude_tbl, **codex_tbl}
+    stale: list = []
+    for e in allowlist or []:
+        model = e["model"]
+        if e.get("field"):
+            theirs = (litellm_scoped.get(model) or {}).get(e["field"])
+            mine = (ours.get(model) or {}).get(e["field"])
+            real = (theirs is not None and mine is not None
+                    and abs(float(mine) - float(theirs)) > _DRIFT_EPS)
+        else:
+            # model-suppress entry: real only if litellm has it AND we don't
+            real = (model in litellm_scoped and model not in ours)
+        if not real:
+            stale.append(e)
+    return stale
+
+
+_CLAUDE_REQUIRED = ("input_cost_per_token", "output_cost_per_token",
+                    "cache_creation_input_token_cost", "cache_read_input_token_cost")
+_CODEX_REQUIRED = ("input_cost_per_token", "cache_read_input_token_cost",
+                   "output_cost_per_token")
+
+
+def check_table_shapes(claude_tbl, codex_tbl, zero_sentinels) -> list:
+    """Provider-specific well-formedness. Claude entries need the 4 required
+    fields; Codex entries need the 3 base fields (NO cache_creation) and may
+    carry optional *_above_272k_tokens tiered fields. All present cost fields
+    must be >= 0. An all-zero Codex entry is allowed ONLY if its model is in
+    `zero_sentinels` (e.g. gpt-5.3-codex-spark mirroring upstream $0)."""
+    problems: list = []
+
+    def _check(model, body, required, allow_zero):
+        for f in required:
+            if f not in body:
+                problems.append(f"{model}: missing required field {f}")
+        cost_fields = {k: v for k, v in body.items() if "cost" in k}
+        for k, v in cost_fields.items():
+            if not isinstance(v, (int, float)) or v < 0:
+                problems.append(f"{model}: field {k} not a non-negative number ({v!r})")
+        if cost_fields and all(float(v) == 0.0 for v in cost_fields.values()) and not allow_zero:
+            problems.append(f"{model}: all cost fields zero but not a documented sentinel")
+
+    for model, body in claude_tbl.items():
+        _check(model, body, _CLAUDE_REQUIRED, allow_zero=False)
+    for model, body in codex_tbl.items():
+        _check(model, body, _CODEX_REQUIRED, allow_zero=model in zero_sentinels)
+    return problems
+
+
+def pricing_issue_action(drift_present: bool, existing_open: bool) -> str:
+    """Decide the cron's GitHub-issue action. Pure; the YAML executes it."""
+    if drift_present:
+        return "update" if existing_open else "create"
+    return "close" if existing_open else "noop"