claude-finops 0.7.2 → 0.9.0

package/finops/analytics.py

@@ -7,16 +7,19 @@ Every number returned is tagged with a `basis`:
   recommendation - suggested action, never a booked saving
 """
 import json
-import math
 import os
 import sqlite3
 import statistics
-from collections import Counter, defaultdict
+import sys
+import threading
+import time
+from collections import defaultdict
 from datetime import date, datetime, timedelta, timezone
 
 from .pricing import Pricing
+from .segments import is_compaction
 
-from .paths import ROOT, DB_PATH, SETTINGS_PATH, LOCAL_SETTINGS_PATH
+from .paths import DB_PATH, SETTINGS_PATH, LOCAL_SETTINGS_PATH
 
 UNAVAILABLE = "Unavailable from connected Claude data"
 
@@ -84,36 +87,131 @@ def detect_account():
     return {k: v for k, v in out.items() if v}
 
 
+def _is_num(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def _validate_settings(cur, defaults):
+    """Defensive coercion of settings.local.json's numeric leaves.
+
+    Every value under budgets/limits must be a number, null, or (for
+    per_project_usd/per_model_usd) a dict of numbers; alert_thresholds_pct must be
+    a list of numbers 0..1000. Anything else is dropped and the shipped default
+    (from settings.json) is used instead, with a warning.
+    """
+    bad = []
+    for section in ("budgets", "limits"):
+        want = defaults.get(section, {})
+        have = cur.get(section)
+        if not isinstance(have, dict):
+            bad.append(section)
+            cur[section] = want
+            continue
+        fixed = dict(have)
+        for k, v in list(have.items()):
+            if k.startswith("_"):
+                continue
+            if k in ("per_project_usd", "per_model_usd"):
+                if not isinstance(v, dict) or not all(_is_num(x) for x in v.values()):
+                    bad.append(f"{section}.{k}")
+                    fixed[k] = want.get(k, {})
+            elif not (v is None or _is_num(v)):
+                bad.append(f"{section}.{k}")
+                fixed[k] = want.get(k)
+        cur[section] = fixed
+    pct = cur.get("alert_thresholds_pct")
+    if not (isinstance(pct, list) and all(_is_num(x) and 0 <= x <= 1000 for x in pct)):
+        if pct is not None:
+            bad.append("alert_thresholds_pct")
+        cur["alert_thresholds_pct"] = defaults.get("alert_thresholds_pct", [])
+    for path in bad:
+        print(f"finops: settings.local.json has an invalid '{path}'; using the shipped default",
+              file=sys.stderr)
+    return cur
+
+
 def load_settings():
     """Shared defaults (settings.json) + this machine's overrides (settings.local.json)."""
     with open(SETTINGS_PATH) as fh:
-        cur = json.load(fh)
+        base = json.load(fh)
     # Detected identity first, so a configured settings.json still wins below.
     detected = detect_account()
-    acct = cur.setdefault("account", {})
+    acct = base.setdefault("account", {})
     for k, v in detected.items():
         if not acct.get(k):
             acct[k] = v
+    cur = json.loads(json.dumps(base))   # deep copy: base stays the fallback default
     if os.path.exists(LOCAL_SETTINGS_PATH):
-        with open(LOCAL_SETTINGS_PATH) as fh:
-            _merge(cur, json.load(fh))
-    return cur
+        try:
+            with open(LOCAL_SETTINGS_PATH) as fh:
+                local = json.load(fh)
+        except (OSError, ValueError) as exc:
+            print(f"finops: settings.local.json unreadable ({exc}); using shipped defaults",
+                  file=sys.stderr)
+            local = {}
+        if isinstance(local, dict):
+            _merge(cur, local)
+        else:
+            print("finops: settings.local.json is not an object; using shipped defaults",
+                  file=sys.stderr)
+    return _validate_settings(cur, base)
 
 
 def _d(s):
     return datetime.strptime(s, "%Y-%m-%d").date()
 
 
+def _cumsum(values):
+    total = 0.0
+    for v in values:
+        total += v or 0.0
+        yield total
+
+
 class Analytics:
     def __init__(self, db_path=DB_PATH):
-        self.db = sqlite3.connect(db_path, check_same_thread=False)
-        self.db.row_factory = sqlite3.Row
+        # One connection per thread. The HTTP server is threaded, and a single sqlite
+        # connection shared across threads fails under concurrent use with "bad
+        # parameter or other API misuse" — which is exactly what a page firing several
+        # requests at once produces. Every connection is tracked so close() can release
+        # them all before the warehouse file is swapped on sync.
+        self._db_path = db_path
+        self._local = threading.local()
+        self._conns = []
+        self._conns_lock = threading.Lock()
         self.pricing = Pricing()
         self.settings = load_settings()
         self.meta = {r["key"]: r["value"] for r in self.db.execute("SELECT * FROM meta")}
         row = self.db.execute("SELECT MIN(day) a, MAX(day) b FROM requests WHERE day<>''").fetchone()
         self.first_day, self.last_day = row["a"], row["b"]
 
+    _today = None                      # tests set this; production uses the clock
+
+    def today(self):
+        return self._today or datetime.now(timezone.utc).date()
+
+    @property
+    def db(self):
+        c = getattr(self._local, "conn", None)
+        if c is None:
+            c = sqlite3.connect(self._db_path)
+            c.row_factory = sqlite3.Row
+            self._local.conn = c
+            with self._conns_lock:
+                self._conns.append(c)
+        return c
+
+    def close(self):
+        """Close every thread's connection, so the warehouse file can be replaced."""
+        with self._conns_lock:
+            conns, self._conns = self._conns, []
+        for c in conns:
+            try:
+                c.close()
+            except Exception:
+                pass
+        self._local = threading.local()
+
     def q(self, sql, params=()):
         return [dict(r) for r in self.db.execute(sql, params)]
 
@@ -136,7 +234,10 @@ class Analytics:
             cl.append("r.model IN (%s)" % ",".join("?" * len(f["models"]))); p += f["models"]
         if f.get("projects"):
             cl.append("r.project_id IN (%s)" % ",".join("?" * len(f["projects"])))
-            p += [int(x) for x in f["projects"]]
+            try:
+                p += [int(x) for x in f["projects"]]
+            except (TypeError, ValueError):
+                raise ValueError("projects must be integers")
         if f.get("sessions"):
             cl.append("r.session_id IN (%s)" % ",".join("?" * len(f["sessions"]))); p += f["sessions"]
         if f.get("categories"):
@@ -152,10 +253,36 @@ class Analytics:
             cl.append("r.billable_tokens >= ?"); p.append(int(f["min_tokens"]))
         return (" AND ".join(cl) if cl else "1=1"), p
 
+    def daily_series(self, f, days=None, end=None):
+        """Per-day cost/token series with idle days present as zeros.
+
+        A plain GROUP BY day only returns days you actually worked, so a mean taken
+        over it is a per-ACTIVE-day rate. Every projection here multiplies that rate
+        by calendar days remaining, so the zero days have to be filled in or the
+        forecast is inflated by exactly the share of days you were idle.
+        """
+        w, p = self.where(f)
+        rows = self.q(f"""SELECT r.day, SUM(r.est_cost_usd) cost, SUM(r.billable_tokens) tokens,
+                          COUNT(*) requests FROM requests r WHERE {w} AND r.day <> ''
+                          GROUP BY 1 ORDER BY 1""", p)
+        if not rows:
+            return []
+        by_day = {r["day"]: r for r in rows}
+        last = _d(end) if end else max(_d(rows[-1]["day"]), self.today())
+        first = _d(rows[0]["day"])
+        if days:
+            first = max(first, last - timedelta(days=days - 1))
+        out, cur = [], first
+        while cur <= last:
+            k = cur.isoformat()
+            out.append(by_day.get(k) or {"day": k, "cost": 0.0, "tokens": 0, "requests": 0})
+            cur += timedelta(days=1)
+        return out
+
     # ---------------- billing period ----------------
     def billing_period(self, today=None):
         bp = self.settings["billing_period"]
-        today = today or (_d(self.last_day) if self.last_day else date.today())
+        today = today or self.today()
         anchor = int(bp.get("anchor_day", 1))
         if today.day >= anchor:
             start = today.replace(day=min(anchor, 28))
@@ -208,6 +335,7 @@ class Analytics:
                             f" FROM requests r WHERE {w} AND {extra}", p + ep)
 
         tot["cost_today"] = spend("r.day = ?", [today])
+        tot["cost_yesterday"] = spend("r.day = ?", [(_d(today) - timedelta(days=1)).isoformat()])
         tot["cost_week"] = spend("r.day >= ?", [wk])
         tot["cost_period"] = spend("r.day >= ? AND r.day <= ?", [bp["start"], bp["end"]])
         tot["billing_period"] = bp
@@ -233,14 +361,13 @@ class Analytics:
         elapsed = max(bp["elapsed_days"], 1)
         daily_avg = used_cost / elapsed
 
-        # Trailing rates are measured over the last N days of ACTUAL activity, not
-        # only the slice inside the billing period — early in a period that slice is
-        # too short to be a rate. This keeps burn and forecast on one methodology.
-        recent = self.q(f"""SELECT r.day, SUM(r.est_cost_usd) cost,
-                            SUM(r.billable_tokens) tokens, COUNT(*) requests
-                            FROM requests r WHERE {w} AND r.day <> ''
-                            GROUP BY 1 ORDER BY 1""", p)
-        last7, last14 = recent[-7:], recent[-14:]
+        # Trailing rates are measured over the last N CALENDAR days, not only the
+        # slice inside the billing period — early in a period that slice is too short
+        # to be a rate. Idle days count as zero, because these rates get multiplied by
+        # calendar days remaining. This keeps burn and forecast on one methodology.
+        yesterday = (self.today() - timedelta(days=1)).isoformat()
+        last7 = self.daily_series(f, days=7, end=yesterday)
+        last14 = self.daily_series(f, days=14, end=yesterday)
         avg7 = (sum(r["cost"] for r in last7) / len(last7)) if last7 else 0.0
         tok_avg7 = (sum(r["tokens"] for r in last7) / len(last7)) if last7 else 0.0
         # the projection rate matches Analytics.forecast()'s "expected" scenario
@@ -261,7 +388,8 @@ class Analytics:
             "projected_period_cost": projected,
             "projected_period_tokens": used_tokens + tok_burn * bp["remaining_days"],
             "forecast_basis": "forecast",
-            "forecast_note": ("Projection uses the %d-day mean daily spend, the same rate as the "
+            "forecast_note": ("Projection uses the %d-calendar-day mean daily spend, idle days "
+                              "included as zero — the same rate as the "
                               "Forecast view's expected scenario." % len(last14)),
             "series": rows,
             "allowances": {},
@@ -277,7 +405,7 @@ class Analytics:
                 continue
             remaining = allowance - used_val
             pct = 100.0 * used_val / allowance
-            days_left = (remaining / rate) if rate > 0 else None
+            days_left = (remaining / rate) if rate > 0 and remaining > 0 else None
             proj = used_val + rate * bp["remaining_days"]
             out["allowances"][label] = {
                 "configured": True, "allowance": allowance, "used": used_val,
@@ -286,6 +414,7 @@ class Analytics:
                 "days_until_limit": (round(days_left, 1) if days_left is not None else None),
                 "limit_date": ((_d(bp["today"]) + timedelta(days=days_left)).isoformat()
                                if days_left is not None and days_left < 3650 else None),
+                "exceeded": remaining <= 0,
                 "projected_end_of_period": proj,
                 "projected_overage_pct": round(100.0 * (proj - allowance) / allowance, 1),
                 "status": self._status(pct),
@@ -316,6 +445,30 @@ class Analytics:
                  AVG(r.context_tokens) avg_context
           FROM requests r WHERE {w} AND r.day <> '' GROUP BY 1 ORDER BY 1""", p)
 
+    def heatmap(self, f=None):
+        """Spend by weekday x hour, in this machine's local time (Monday first).
+
+        Transcripts stamp UTC; bucketing on that would put a 10am IST session at
+        4am. SQLite's 'localtime' modifier applies the local offset, half-hour
+        zones included. Date filters still apply to UTC days like every view.
+        """
+        w, p = self.where(f)
+        rows = self.q(f"""
+          SELECT CAST(strftime('%w', r.ts, 'localtime') AS INTEGER) wd,
+                 CAST(strftime('%H', r.ts, 'localtime') AS INTEGER) hr,
+                 COALESCE(SUM(r.est_cost_usd),0) cost, COALESCE(SUM(r.billable_tokens),0) tokens,
+                 COUNT(*) requests
+          FROM requests r WHERE {w} AND r.ts <> '' GROUP BY 1, 2""", p)
+        grid = {(d, h): {"dow": d, "hour": h, "cost": 0.0, "tokens": 0, "requests": 0}
+                for d in range(7) for h in range(24)}
+        for r in rows:
+            if r["wd"] is None or r["hr"] is None:
+                continue
+            c = grid[((r["wd"] + 6) % 7, r["hr"])]
+            c["cost"], c["tokens"], c["requests"] = r["cost"], r["tokens"], r["requests"]
+        return {"cells": [grid[(d, h)] for d in range(7) for h in range(24)],
+                "tz": time.strftime("%Z"), "cost_basis": "estimated"}
+
     # ---------------- models ----------------
     def models(self, f=None):
         w, p = self.where(f)
@@ -332,6 +485,24 @@ class Analytics:
           FROM requests r WHERE {w} GROUP BY r.model ORDER BY cost DESC""", p)
         tc = sum(r["cost"] for r in rows) or 1
         tt = sum(r["tokens"] for r in rows) or 1
+        # Utilisation is measured against the window that actually served each request —
+        # a long-context variant has a bigger one — and requests that ran over a window
+        # this price table cannot explain are counted, not averaged into a figure above
+        # 100%, which is what dividing by the base model's window used to produce.
+        util = {}
+        for v in self.q(f"""SELECT r.model, r.priced_as, r.unpriced_long_context u,
+                              COUNT(*) n, AVG(r.context_tokens) avg_ctx
+                            FROM requests r WHERE {w}
+                            GROUP BY r.model, r.priced_as, r.unpriced_long_context""", p):
+            u = util.setdefault(v["model"], {"num": 0.0, "den": 0, "over": 0, "long": 0})
+            win = self.pricing.context_window(v["priced_as"] or v["model"])
+            if v["u"] or not win:
+                u["over"] += v["n"]
+                continue
+            u["num"] += v["n"] * 100.0 * (v["avg_ctx"] or 0) / win
+            u["den"] += v["n"]
+            if v["priced_as"] and v["priced_as"].endswith("[1m]"):
+                u["long"] += v["n"]
         for r in rows:
             r["display_name"] = self.pricing.display_name(r["model"])
             r["tier"] = self.pricing.tier(r["model"])
@@ -343,8 +514,10 @@ class Analytics:
             r["output_per_input"] = (r["output_tokens"] / (r["input_tokens"] + r["cache_read_tokens"]
                                      + r["cache_write_tokens"])) if r["tokens"] else 0
             r["tokens_per_request"] = r["tokens"] / r["requests"] if r["requests"] else 0
-            r["utilization_pct"] = (round(100.0 * (r["avg_context"] or 0) / r["context_window"], 1)
-                                    if r["context_window"] else None)
+            u = util.get(r["model"], {})
+            r["utilization_pct"] = round(u["num"] / u["den"], 1) if u.get("den") else None
+            r["over_window_requests"] = u.get("over", 0)
+            r["long_context_requests"] = u.get("long", 0)
         priced = [r for r in rows if r["tokens"] and r["tier"] != "none"]
         superlatives = {}
         if priced:
@@ -381,7 +554,7 @@ class Analytics:
             r["budget_used_pct"] = round(100.0 * r["cost"] / b, 1) if b else None
         return rows
 
-    def sessions(self, f=None, limit=500, order="cost"):
+    def sessions(self, f=None, limit=500, order="cost", offset=0):
         w, p = self.where(f)
         ob = {"cost": "cost DESC", "tokens": "tokens DESC", "duration": "s.duration_s DESC",
               "recent": "s.started_at DESC", "prompts": "prompts DESC"}.get(order, "cost DESC")
@@ -398,17 +571,32 @@ class Analytics:
                  GROUP_CONCAT(DISTINCT r.model) models
           FROM requests r JOIN sessions s ON s.id = r.session_id
           JOIN projects pr ON pr.id = s.project_id
-          WHERE {w} GROUP BY s.id ORDER BY {ob} LIMIT ?""", p + [limit])
+          WHERE {w} GROUP BY s.id ORDER BY {ob} LIMIT ? OFFSET ?""", p + [limit, offset])
         for r in rows:
             r["cost_per_prompt"] = r["cost"] / r["prompts"] if r["prompts"] else None
             r["tokens_per_prompt"] = r["tokens"] / r["prompts"] if r["prompts"] else None
             r["tokens_per_request"] = r["tokens"] / r["requests"] if r["requests"] else 0
-            r["output_ratio"] = r["output_tokens"] / r["tokens"] if r["tokens"] else 0
-            r["cache_hit_ratio"] = (r["cache_read_tokens"] /
-                                    (r["cache_read_tokens"] + r["cache_write_tokens"])
-                                    if (r["cache_read_tokens"] + r["cache_write_tokens"]) else None)
+            r["output_ratio"] = (r["output_tokens"] or 0) / r["tokens"] if r["tokens"] else 0
+            cr, cw = r["cache_read_tokens"] or 0, r["cache_write_tokens"] or 0
+            r["cache_hit_ratio"] = (cr / (cr + cw)) if (cr + cw) else None
         return rows
 
+    def sessions_total(self, f=None):
+        w, p = self.where(f)
+        return self.one(f"SELECT COUNT(DISTINCT s.id) n FROM requests r "
+                         f"JOIN sessions s ON s.id = r.session_id "
+                         f"JOIN projects pr ON pr.id = s.project_id WHERE {w}", p)["n"]
+
+    def prompts_total(self, f=None, search=None):
+        w, p = self.where(f)
+        extra, ep = "", []
+        if search:
+            extra = (" AND r.prompt_id IN (SELECT id FROM prompts pr WHERE pr.text LIKE ? "
+                     "OR pr.session_id LIKE ? OR pr.category LIKE ?)")
+            ep = [f"%{search}%"] * 3
+        return self.one(f"SELECT COUNT(DISTINCT r.prompt_id) n FROM requests r "
+                         f"WHERE {w}{extra} AND r.prompt_id IS NOT NULL", p + ep)["n"]
+
     def prompts(self, f=None, limit=300, offset=0, order="cost", search=None):
         w, p = self.where(f)
         ob = {"cost": "pcost DESC", "tokens": "ptokens DESC", "recent": "pr.ts DESC",
@@ -490,7 +678,6 @@ class Analytics:
             p["category_evidence"] = json.loads(p.get("category_evidence") or "[]")
         except Exception:
             p["category_evidence"] = []
-        p["advisor"] = self.prompt_advisor(p)
         return p
 
     def session_detail(self, sid):
@@ -512,6 +699,11 @@ class Analytics:
         s["files"] = self.q(
             "SELECT path, GROUP_CONCAT(DISTINCT op) ops, COUNT(*) n FROM files_touched"
             " WHERE session_id=? GROUP BY path ORDER BY n DESC LIMIT 100", (sid,))
+        # Cowork transcripts live under the desktop app's own config dir, where
+        # `claude --resume` would not find them.
+        cowork = "local-agent-mode-sessions" in (s.get("source_file") or "")
+        s["resume"] = (f"claude --resume {sid}"
+                       if (s.get("agent") or "claude") == "claude" and not cowork else None)
         return s
 
     # ---------------- categories ----------------
@@ -543,6 +735,252 @@ class Analytics:
         }
 
     # ---------------- efficiency ----------------
+    def hygiene(self, f=None, top=12, trajectory_points=80):
+        """Context and session hygiene: what it cost to keep re-sending a large prefix.
+
+        Everything here is observed. For each session: the context size of every
+        request in order, the request at which it first crossed each configured
+        threshold, and what was spent from that point on. Across the range: the share
+        of spend in requests above each threshold. No compaction is simulated and no
+        saving is estimated — how much a fresh session would have saved depends on what
+        the work still needed, which the transcript does not say.
+
+        Subagent (sidechain) turns are excluded: they run against their own prefix, so
+        mixing them into the parent session's trajectory would misstate both.
+        """
+        cfg = self.settings.get("hygiene", {})
+        thresholds = sorted(int(x) for x in cfg.get("context_thresholds", [100000, 150000]))
+        w, p = self.where(f)
+        rows = self.q(f"""SELECT r.session_id, r.ts, r.context_tokens ctx, r.est_cost_usd cost
+                          FROM requests r WHERE {w} AND r.is_sidechain = 0 AND r.ts <> ''
+                          ORDER BY r.session_id, r.ts""", p)
+        compact_rows = self.q("SELECT session_id, ts FROM prompts WHERE source='slash:/compact'"
+                              " AND ts <> '' ORDER BY session_id, ts")
+        compacts_by_session = defaultdict(list)
+        for cr in compact_rows:
+            compacts_by_session[cr["session_id"]].append(cr["ts"])
+
+        total = sum(r["cost"] or 0 for r in rows)
+        above = {t: {"requests": 0, "cost_usd": 0.0, "sessions": 0, "cost_after_first_cross_usd": 0.0}
+                 for t in thresholds}
+        sessions = {}
+        for r in rows:
+            cost, ctx = (r["cost"] or 0.0), (r["ctx"] or 0)
+            s = sessions.setdefault(r["session_id"], {
+                "session_id": r["session_id"], "requests": 0, "cost_usd": 0.0,
+                "max_context": 0, "first_cross": {t: None for t in thresholds},
+                "first_cross_idx": {t: None for t in thresholds},
+                "cost_after": {t: 0.0 for t in thresholds}, "traj": [], "compactions": 0,
+                "ever_crossed": {t: False for t in thresholds}, "_next_compact_idx": 0})
+            prev_ctx = s["traj"][-1][0] if s["traj"] else 0
+            compact_ts = compacts_by_session.get(r["session_id"], [])
+            crossed_compact = (s["_next_compact_idx"] < len(compact_ts)
+                               and r["ts"] > compact_ts[s["_next_compact_idx"]])
+            if crossed_compact:
+                s["_next_compact_idx"] += 1
+            if is_compaction(prev_ctx, ctx, thresholds[0]) or crossed_compact:
+                s["compactions"] += 1
+                s["first_cross"] = {t: None for t in thresholds}
+            idx = s["requests"]
+            s["requests"] += 1
+            s["cost_usd"] += cost
+            s["max_context"] = max(s["max_context"], ctx)
+            s["traj"].append((ctx, cost))
+            for t in thresholds:
+                if ctx >= t:
+                    above[t]["requests"] += 1
+                    above[t]["cost_usd"] += cost
+                    if s["first_cross"][t] is None:
+                        s["first_cross"][t] = idx
+                        s["ever_crossed"][t] = True
+                    if s["first_cross_idx"][t] is None:
+                        s["first_cross_idx"][t] = idx   # the ORIGINAL crossing; never reset
+                if s["first_cross"][t] is not None:
+                    s["cost_after"][t] += cost
+        for s in sessions.values():
+            for t in thresholds:
+                if s["ever_crossed"][t]:
+                    above[t]["sessions"] += 1
+                    above[t]["cost_after_first_cross_usd"] += s["cost_after"][t]
+
+        rank_t = thresholds[-1]
+        ranked = sorted(sessions.values(), key=lambda s: -s["cost_after"][rank_t])[:top]
+        ids = [s["session_id"] for s in ranked]
+        meta = {}
+        if ids:
+            ph = ",".join("?" * len(ids))
+            meta = {m["id"]: m for m in self.q(f"""SELECT s.id, s.title, pj.name project
+                                                FROM sessions s JOIN projects pj ON pj.id=s.project_id
+                                                WHERE s.id IN ({ph})""", ids)}
+
+        def downsample(traj):
+            n = len(traj)
+            if n <= trajectory_points:
+                return traj
+            step = n / trajectory_points
+            return [traj[int(i * step)] for i in range(trajectory_points)]
+
+        out_sessions = []
+        for s in ranked:
+            m = meta.get(s["session_id"], {})
+            traj = downsample(s["traj"])
+            out_sessions.append({
+                "session_id": s["session_id"], "title": m.get("title"), "project": m.get("project"),
+                "requests": s["requests"], "cost_usd": s["cost_usd"], "max_context": s["max_context"],
+                "compactions": s["compactions"],
+                "first_cross": {str(t): s["first_cross"][t] for t in thresholds},
+                "first_cross_idx": {str(t): s["first_cross_idx"][t] for t in thresholds},
+                "ever_crossed": {str(t): s["ever_crossed"][t] for t in thresholds},
+                "cost_after": {str(t): s["cost_after"][t] for t in thresholds},
+                "cost_after_pct": {str(t): (round(100.0 * s["cost_after"][t] / s["cost_usd"], 1)
+                                            if s["cost_usd"] else 0.0) for t in thresholds},
+                "context_trajectory": [c for c, _ in traj],
+                "cumulative_cost": [round(x, 4) for x in _cumsum(cost for _, cost in traj)],
+                "basis": "actual",
+            })
+        return {
+            "thresholds": thresholds,
+            "rank_threshold": rank_t,
+            "requests": len(rows), "sessions": len(sessions), "cost_usd": total,
+            "above": {str(t): {
+                **v,
+                "share_pct": round(100.0 * v["cost_usd"] / total, 1) if total else 0.0,
+                "share_after_first_cross_pct": (round(100.0 * v["cost_after_first_cross_usd"] / total, 1)
+                                                if total else 0.0),
+            } for t, v in above.items()},
+            "sessions_ranked": out_sessions,
+            "excluded": "subagent turns (own prefix)",
+            "undetectable": ["/clear"],
+            "note": ("Observed shares of spend. Nothing here estimates what compaction or a "
+                     "fresh session would have saved. Auto-compaction is not recorded; it is "
+                     "detected as the context dropping by more than half. A typed /compact is "
+                     "recorded and also counts."),
+            "basis": "actual",
+        }
+
+    def ttl_replay(self, f=None):
+        """5m vs 1h cache TTL over real segments — arithmetic, no behavioural assumption.
+
+        Gated on reconciliation: if replaying the TTL you actually used cannot reproduce
+        the cost that was logged, the counterfactual is not trustworthy either and no
+        number is returned.
+        """
+        from .segments import replay, split_segments
+        w, p = self.where(f)
+        turns = self.q(f"""SELECT r.session_id, r.ts, r.model, r.priced_as, r.is_sidechain, r.agent_id,
+                             r.input_tokens, r.output_tokens, r.cache_read_tokens,
+                             r.cache_write_5m, r.cache_write_1h, r.est_cost_usd, r.context_tokens ctx
+                           FROM requests r WHERE {w} AND r.agent='claude' AND r.ts <> ''
+                           ORDER BY r.session_id, r.ts""", p)
+        segs = split_segments(turns)
+        out = replay(segs, self.pricing)
+        out["turns"] = len(turns)
+        out["undetectable_boundaries"] = ["/clear"]
+        out["note"] = ("Segments break at session start, subagent start, model change and "
+                       "compaction. Auto-compaction is not recorded; it is detected as the "
+                       "context dropping by more than half. A typed /compact is recorded and "
+                       "also counts.")
+        return out
+
+    def long_context_pricing(self, f=None):
+        """Requests whose context exceeded the model's standard window.
+
+        These could only have been served by the long-context variant, which bills at a
+        premium. Where a `[1m]` price list exists they are already repriced; where it
+        does not, they are billed at the standard rate and the estimate is LOW — that is
+        a gap in config/pricing.json, not in the data, so it is reported rather than
+        guessed at.
+        """
+        w, p = self.where(f)
+        rows = self.q(f"""SELECT r.model, r.priced_as, r.unpriced_long_context u,
+                            COUNT(*) n, SUM(r.est_cost_usd) cost, MAX(r.context_tokens) mx
+                          FROM requests r WHERE {w} AND r.context_tokens > 0
+                            AND (r.priced_as LIKE '%[1m]' OR r.unpriced_long_context = 1)
+                          GROUP BY r.model, r.priced_as, r.unpriced_long_context""", p)
+        repriced = [r for r in rows if not r["u"]]
+        unpriced = [r for r in rows if r["u"]]
+
+        # rows priced against no known model at all (model_known=0) are a distinct gap:
+        # not "over the standard window", but "no rate for this model in pricing.json".
+        unknown_rows = self.q(f"""SELECT r.model, COUNT(*) n, SUM(r.est_cost_usd) cost
+                                  FROM requests r WHERE {w} AND r.model_known = 0
+                                    AND r.model LIKE 'claude%'
+                                  GROUP BY r.model""", p)
+        unknown_requests = sum(r["n"] for r in unknown_rows)
+        unknown_models = sorted({r["model"] for r in unknown_rows})
+
+        return {
+            "repriced": repriced,
+            "unpriced": unpriced,
+            "repriced_requests": sum(r["n"] for r in repriced),
+            "unpriced_requests": sum(r["n"] for r in unpriced),
+            "unpriced_cost_usd": sum(r["cost"] or 0 for r in unpriced),
+            "unpriced_models": sorted({r["model"] for r in unpriced}),
+            "unknown_model_requests": unknown_requests,
+            "unknown_model_cost_usd": sum(r["cost"] or 0 for r in unknown_rows),
+            "unknown_models": unknown_models,
+            "message": (
+                "%d requests exceeded their model's standard context window with no "
+                "long-context price configured, so their cost is understated. Add a "
+                "\"<model>[1m]\" entry to config/pricing.json for: %s."
+                % (sum(r["n"] for r in unpriced), ", ".join(sorted({r["model"] for r in unpriced})))
+                if unpriced else ""),
+            "unknown_message": (
+                "%d requests used a claude-* model with no entry in pricing.json at "
+                "all, so their cost is a fallback guess. Add pricing.json entries for: %s."
+                % (unknown_requests, ", ".join(unknown_models))
+                if unknown_rows else ""),
+            "basis": "estimated",
+        }
+
+    def cache_cost_split(self, f=None):
+        """Cache read vs write split by estimated cost, not just by token count.
+
+        A read is billed at a fraction of the input rate and a write at a premium, so
+        the token split and the dollar split are different numbers — writes are a small
+        share of cache tokens and a much larger share of cache spend. Reporting only the
+        token ratio overstates how healthy caching is, which is why the scorecard grades
+        this dimension on cost. Prices are re-derived per model here rather than read off
+        requests.est_cost_usd, which is a single blended figure per request.
+        """
+        w, p = self.where(f)
+        rows = self.q(f"""SELECT model,
+                            SUM(cache_read_tokens) cr,
+                            SUM(cache_write_5m) w5, SUM(cache_write_1h) w1
+                          FROM requests r WHERE {w} GROUP BY model""", p)
+        read_tok = w5_tok = w1_tok = 0
+        read_cost = w5_cost = w1_cost = 0.0
+        for r in rows:
+            cr, w5, w1 = (r["cr"] or 0), (r["w5"] or 0), (r["w1"] or 0)
+            read_tok += cr
+            w5_tok += w5
+            w1_tok += w1
+            read_cost += self.pricing.estimate(r["model"], cache_read=cr)
+            w5_cost += self.pricing.estimate(r["model"], cache_write_5m=w5)
+            w1_cost += self.pricing.estimate(r["model"], cache_write_1h=w1)
+
+        write_tok = w5_tok + w1_tok
+        write_cost = w5_cost + w1_cost
+        tok_total = read_tok + write_tok
+        cost_total = read_cost + write_cost
+        per_read = (read_cost / read_tok) if read_tok else 0
+        per_write = (write_cost / write_tok) if write_tok else 0
+        return {
+            "read_tokens": read_tok, "write_tokens": write_tok,
+            "write_5m_tokens": w5_tok, "write_1h_tokens": w1_tok,
+            "read_cost_usd": read_cost, "write_cost_usd": write_cost,
+            "write_5m_cost_usd": w5_cost, "write_1h_cost_usd": w1_cost,
+            "read_token_share": (read_tok / tok_total) if tok_total else None,
+            "read_cost_share": (read_cost / cost_total) if cost_total else None,
+            "write_cost_share": (write_cost / cost_total) if cost_total else None,
+            # how much more a write token costs than a read token, same workload
+            "write_vs_read_multiple": (per_write / per_read) if per_read else None,
+            # 1h writes cost more per token than 5m writes; whether that premium is worth
+            # paying depends on the real inter-turn gaps, which ttl_replay() prices
+            "write_1h_token_share": (w1_tok / write_tok) if write_tok else None,
+            "basis": "estimated",
+        }
+
     def efficiency(self, f=None):
         w, p = self.where(f)
         t = self.one(f"""SELECT SUM(input_tokens) i, SUM(output_tokens) o,
@@ -554,6 +992,29 @@ class Analytics:
         tot = t["tot"] or 1
         prompt_side = (t["i"] or 0) + (t["cr"] or 0) + (t["cw"] or 0)
         cache_total = (t["cr"] or 0) + (t["cw"] or 0)
+        cache_cost = self.cache_cost_split(f)
+
+        # Break-even margin: how much of cache spend came back as read discount, net of
+        # write premium. +1 = all discount, -1 = all premium, computed per model since
+        # rates differ.
+        bm_rows = self.q(f"""SELECT COALESCE(priced_as, model) priced_as, SUM(cache_read_tokens) cr,
+                                SUM(cache_write_5m) w5, SUM(cache_write_1h) w1
+                             FROM requests r WHERE {w} GROUP BY COALESCE(priced_as, model)""", p)
+        discount = premium = cache_cost_total = 0.0
+        for r in bm_rows:
+            model = r["priced_as"]
+            reads, w5, w1 = (r["cr"] or 0), (r["w5"] or 0), (r["w1"] or 0)
+            rt = self.pricing.rates(model) or {}
+            inp = float(rt.get("input") or 0)
+            read_rate = float(rt.get("cache_read") or 0)
+            w5_rate = float(rt.get("cache_write_5m") or 0)
+            w1_rate = float(rt.get("cache_write_1h") or 0)
+            discount += reads * (inp - read_rate) / 1e6
+            premium += (w5 * (w5_rate - inp) + w1 * (w1_rate - inp)) / 1e6
+            cache_cost_total += (reads * read_rate + w5 * w5_rate + w1 * w1_rate) / 1e6
+        breakeven_margin = (max(-1.0, min(1.0, (discount - premium) / cache_cost_total))
+                            if cache_cost_total else None)
+
         sess = self.sessions(f, limit=100000, order="cost")
         scored = [s for s in sess if s["tokens"] and s["prompts"]]
         for s in scored:
@@ -564,6 +1025,7 @@ class Analytics:
             "output_per_input": ((t["o"] or 0) / prompt_side) if prompt_side else 0,
             "thinking_share_of_output": ((t["think"] or 0) / (t["o"] or 1)),
             "cache_hit_ratio": ((t["cr"] or 0) / cache_total) if cache_total else None,
+            "cache_read_cost_share": cache_cost["read_cost_share"],
             "tokens_per_request": tot / (t["n"] or 1),
             "avg_context_tokens": t["avgctx"],
             "cost_per_1k_output": (1000.0 * (t["cost"] or 0) / (t["o"] or 1)),
@@ -571,10 +1033,14 @@ class Analytics:
                                 max(self.one(f"SELECT COUNT(DISTINCT r.prompt_id) n FROM requests r WHERE {w}", p)["n"], 1)),
             "cache": {
                 "reads": t["cr"], "writes": t["cw"],
+                "cost_split": cache_cost,
+                "breakeven_margin": breakeven_margin,
                 "cost_with_cache": t["cost"], "cost_without_cache": t["cost_nc"],
-                "estimated_savings_usd": (t["cost_nc"] or 0) - (t["cost"] or 0),
-                "savings_pct": (round(100.0 * ((t["cost_nc"] or 0) - (t["cost"] or 0))
-                                      / (t["cost_nc"] or 1), 1)),
+                # Named for what it is. This used to be "estimated_savings_usd", and the
+                # UI called it a saving; it is the gap to a run that never happened.
+                "uncached_counterfactual_delta_usd": (t["cost_nc"] or 0) - (t["cost"] or 0),
+                "uncached_counterfactual_pct": (round(100.0 * ((t["cost_nc"] or 0) - (t["cost"] or 0))
+                                                      / (t["cost_nc"] or 1), 1)),
                 "basis": "estimated",
             },
             "low_efficiency_sessions": scored[:10],
@@ -662,23 +1128,22 @@ class Analytics:
                           ORDER BY cost DESC LIMIT 15""", p + [rules["long_prompt_chars"]])
         budget_chars = rules["long_prompt_chars"]
         for r in rows:
-            over_tokens = max(r["char_len"] - budget_chars, 0) / 4.0   # ~4 chars/token
-            resent = over_tokens * max(r["requests"], 1)
-            r["excess"] = (r["cost"] * resent / r["tokens"]) if r["tokens"] else 0
+            r["excess"] = 0.0
         if rows:
             add("high", "long_prompts",
                 f"{len(rows)} very long prompts (>{budget_chars:,} chars)",
                 "Long pasted prompts inflate the cached prefix re-sent on every following turn.",
                 rows, "Move large pasted context into a file and reference it, or summarize first.",
                 "prompt_id",
-                f"share of spend from prompt text beyond {budget_chars:,} characters, re-sent per request")
+                "none claimed — flagged for review only")
 
-        # 2. duplicate prompts — excess is the cost of the repeats, not the first ask.
-        dups = self.q(f"""SELECT pr.norm_hash, COUNT(*) n, substr(MIN(pr.text),1,160) preview,
+        # 2. duplicate prompts — excess is the cost of the repeats, not the first ask,
+        #    counted only within a single session so cross-session coincidences don't count.
+        dups = self.q(f"""SELECT pr.norm_hash, pr.session_id, COUNT(*) n, substr(MIN(pr.text),1,160) preview,
                           SUM(pr.est_cost_usd) cost, SUM(pr.billable_tokens) tokens,
                           MIN(pr.est_cost_usd) first_cost, GROUP_CONCAT(pr.id) prompt_ids
                           FROM prompts pr WHERE {pfilter} AND pr.char_len > 25
-                          GROUP BY pr.norm_hash HAVING n > 1
+                          GROUP BY pr.norm_hash, pr.session_id HAVING n > 1
                           ORDER BY cost DESC LIMIT 15""", p)
         for d in dups:
             d["prompt_id"] = int(d["prompt_ids"].split(",")[0])
@@ -692,11 +1157,18 @@ class Analytics:
 
         # 3. low-yield sessions — excess is what the session cost ABOVE what the same
         #    output would have cost at your own median session efficiency.
+        #    The baseline is drawn from the SAME population that is eligible to be
+        #    flagged — sessions above huge_session_tokens, inside the current filter.
+        #    Grading big sessions against the median of all sessions punishes them for
+        #    something inherent to long agentic work: output ratio falls as a session
+        #    grows, so a small-session median flags most large sessions by construction.
         ratios = [r["x"] for r in self.q(
-            "SELECT CAST(output_tokens AS REAL)/billable_tokens x FROM sessions"
-            " WHERE billable_tokens > 100000")]
+            f"""SELECT CAST(s.output_tokens AS REAL)/s.billable_tokens x FROM sessions s
+                WHERE {sfilter} AND s.billable_tokens > ?""",
+            p + [rules["huge_session_tokens"]])]
         median_ratio = statistics.median(ratios) if ratios else 0.0
         cutoff = median_ratio * rules["low_output_ratio_vs_median"]
+        baseline_n = len(ratios)
         low = self.q(f"""SELECT s.id session_id, s.title, s.billable_tokens tokens,
                          s.output_tokens out_tokens, s.est_cost_usd cost, s.request_count requests,
                          (CAST(s.output_tokens AS REAL)/MAX(s.billable_tokens,1)) output_ratio,
@@ -706,16 +1178,15 @@ class Analytics:
                          ORDER BY cost DESC LIMIT 15""",
                      p + [rules["huge_session_tokens"], cutoff])
         for r in low:
-            # at the median ratio the same output needs out/median tokens, so the
-            # baseline cost scales by (actual ratio / median ratio)
-            r["excess"] = r["cost"] * (1 - (r["output_ratio"] / median_ratio)) if median_ratio else 0
+            r["excess"] = 0.0
         if low:
-            add("high", "low_yield_sessions",
+            add("medium", "low_yield_sessions",
                 f"{len(low)} large sessions yielded under {cutoff*100:.2f}% output tokens",
-                f"Your median session turns {median_ratio*100:.2f}% of billable tokens into output. "
-                f"These ran well below that while consuming heavy context.",
+                f"Among your {baseline_n} comparably large sessions the median turns "
+                f"{median_ratio*100:.2f}% of billable tokens into output. These ran well below "
+                f"that while consuming heavy context.",
                 low, "Start a fresh session or /compact once a thread stops producing new output.",
-                "session_id", "spend above what the same output would cost at your median session efficiency")
+                "session_id", "none claimed — the same output at another ratio is a counterfactual")
 
         # 4. frontier model on small tasks — excess is computed against the cheaper tier.
         frontier = [m for m, v in self.pricing.models.items()
@@ -733,59 +1204,70 @@ class Analytics:
             small = self.q(f"""SELECT pr.id prompt_id, substr(pr.text,1,160) preview, pr.category,
                                pr.session_id, pr.est_cost_usd cost, pr.output_tokens out_tokens,
                                pr.billable_tokens tokens, pr.models, pr.input_tokens,
-                               pr.cache_read_tokens, pr.cache_write_tokens
+                               pr.cache_read_tokens, pr.cache_write_tokens,
+                               (SELECT COALESCE(SUM(rq.cache_write_5m),0) FROM requests rq
+                                  WHERE rq.prompt_id = pr.id) c5,
+                               (SELECT COALESCE(SUM(rq.cache_write_1h),0) FROM requests rq
+                                  WHERE rq.prompt_id = pr.id) c1
                                FROM prompts pr WHERE {pfilter}
-                                 AND pr.output_tokens < ? AND pr.est_cost_usd > 0
+                                 AND pr.output_tokens < ? AND pr.tool_calls = 0 AND pr.est_cost_usd > 0
                                  AND EXISTS (SELECT 1 FROM requests r2 WHERE r2.prompt_id=pr.id
                                              AND r2.model IN ({ph}))
                                ORDER BY cost DESC LIMIT 15""",
                            p + [rules["simple_task_output_tokens"]] + frontier)
             for r in small:
-                alt = (self.pricing.estimate(cheaper, r["input_tokens"], r["out_tokens"],
-                                             r["cache_read_tokens"], r["cache_write_tokens"], 0)
-                       if cheaper else r["cost"])
-                r["excess"] = max(r["cost"] - alt, 0)
+                r["excess"] = 0.0
             if small:
                 add("medium", "frontier_on_small_tasks",
                     f"{len(small)} frontier-model prompts produced under "
                     f"{rules['simple_task_output_tokens']} output tokens",
                     "Short, simple turns running on the most expensive model tier.",
                     small, "Route short lookups and confirmations to a cheaper model tier.",
-                    "prompt_id",
-                    f"difference against the same tokens priced at {self.pricing.display_name(cheaper)}"
-                    if cheaper else "n/a")
+                    "prompt_id", "none claimed")
 
         # 5. tool loops — excess is the share of the loop beyond the threshold.
+        loop_calls = rules.get("tool_loop_calls", 40)
         loops = self.q(f"""SELECT pr.id prompt_id, substr(pr.text,1,160) preview, pr.session_id,
                            pr.tool_calls tools, pr.est_cost_usd cost, pr.billable_tokens tokens
-                           FROM prompts pr WHERE {pfilter} AND pr.tool_calls > 40
-                           ORDER BY cost DESC LIMIT 15""", p)
+                           FROM prompts pr WHERE {pfilter} AND pr.tool_calls > ?
+                           ORDER BY cost DESC LIMIT 15""", p + [loop_calls])
         for r in loops:
-            r["excess"] = r["cost"] * max(r["tools"] - 40, 0) / max(r["tools"], 1)
+            r["excess"] = 0.0
         if loops:
-            add("medium", "tool_loops", f"{len(loops)} prompts triggered 40+ tool calls",
+            add("medium", "tool_loops", f"{len(loops)} prompts triggered {loop_calls}+ tool calls",
                 "Long agentic loops re-send the whole conversation each step, so cost grows super-linearly.",
                 loops, "Split the task, or give more precise instructions up front.", "prompt_id",
-                "share of the loop beyond the first 40 tool calls")
+                "none claimed")
 
-        # 6. poor cache reuse — excess is the write premium over plain input pricing.
+        # 6. poor cache reuse — excess is the break-even: the cache-write premium over
+        #    plain input pricing, minus the discount actually earned on the reads.
         poor = self.q(f"""SELECT s.id session_id, s.title, proj.name project,
                           s.cache_read_tokens reads, s.cache_write_tokens writes,
+                          (SELECT COALESCE(SUM(r.cache_write_5m),0) FROM requests r WHERE r.session_id=s.id) w5,
+                          (SELECT COALESCE(SUM(r.cache_write_1h),0) FROM requests r WHERE r.session_id=s.id) w1,
                           s.est_cost_usd cost, s.request_count requests, s.models
                           FROM sessions s JOIN projects proj ON proj.id=s.project_id
-                          WHERE {sfilter} AND s.cache_write_tokens > 500000
-                            AND s.cache_read_tokens < s.cache_write_tokens * 3
-                          ORDER BY cost DESC LIMIT 15""", p)
+                          WHERE {sfilter} AND s.cache_write_tokens > ?
+                          ORDER BY cost DESC""", p + [rules.get("poor_cache_min_writes", 500_000)])
+        flagged = []
         for r in poor:
             m = (r["models"] or "").split(",")[0]
             rt = self.pricing.rates(m)
-            premium = float(rt.get("cache_write_5m", 0)) - float(rt.get("input", 0))
-            r["excess"] = max(r["writes"] * premium / 1_000_000.0, 0)
+            g = lambda k: float(rt.get(k, 0.0))
+            # break-even: premium paid on writes minus discount earned on reads
+            net = (r["w5"] * (g("cache_write_5m") - g("input"))
+                   + r["w1"] * (g("cache_write_1h") - g("input"))
+                   - r["reads"] * (g("input") - g("cache_read"))) / 1_000_000.0
+            if net > 0:
+                r["excess"] = net
+                flagged.append(r)
+        poor = flagged[:15]
         if poor:
             add("medium", "poor_cache_reuse", f"{len(poor)} sessions wrote cache they barely reused",
                 "Cache writes cost more than plain input; they only pay off when read back repeatedly.",
                 poor, "Keep related work in one continuous session so the cached prefix is reused.",
-                "session_id", "the cache-write premium over plain input pricing on those writes")
+                "session_id", "cache-write premium minus the read discount actually earned, "
+                              "at this model's rates")
 
         # 7. long-lived sparse sessions — informational, no excess claimed.
         idle = self.q(f"""SELECT s.id session_id, s.title, proj.name project, s.duration_s,
@@ -863,436 +1345,120 @@ class Analytics:
                         "touched — money worth reviewing. Estimated excess is how much more that "
                         "work cost than a reasonable baseline, and is the actual waste figure. "
                         "Both are estimates.",
+                "excess_note": "Estimated excess is claimed only where the baseline is measured: the cost of "
+                               "repeating an identical prompt in the same session, and cache writes that were "
+                               "never read back enough to pay for themselves. Everything else is exposed spend "
+                               "to review, not waste.",
                 "basis": "estimated"}
 
     # ---------------- recommendations ----------------
-    # ---------------- model switch advisor ----------------
-    # Which work needs the frontier model and which does not. "keep" = reasoning-heavy work
-    # where a cheaper model is a quality risk; the rest is routed down a tier.
-    SWITCH_RULES = {
-        "casual": ("economy", "high"), "other": ("economy", "medium"),
-        "documentation": ("balanced", "high"), "writing": ("balanced", "high"),
-        "learning": ("balanced", "high"), "testing": ("balanced", "medium"),
-        "research": ("balanced", "medium"), "data_analysis": ("balanced", "medium"),
-        "automation": ("balanced", "medium"), "coding": ("balanced", "low"),
-        "refactoring": ("balanced", "low"),
-        "debugging": ("keep", None), "architecture": ("keep", None),
-        "planning": ("keep", None), "code_review": ("keep", None),
-    }
-    TIER_RANK = {"economy": 0, "balanced": 1, "frontier": 2}
-
-    # How each vendor's agent is told to change model. Used by model_switch() and by the
-    # model_downgrade recommendations, which must name the agent they keep you inside.
-    SWITCH_HOW_BY_AGENT = {
-        "anthropic": {"agent": "Claude Code", "session": "/model <name>",
-                      "project": '"model": "<name>" in <repo>/.claude/settings.json'},
-        "openai": {"agent": "Codex", "session": "/model in Codex, or codex -m <name>",
-                   "project": 'model = "<name>" in ~/.codex/config.toml (or a profile)'},
-        "google": {"agent": "Gemini CLI", "session": "/model in Gemini CLI, or gemini -m <name>",
-                   "project": '"model": {"name": "<name>"} in <repo>/.gemini/settings.json'},
-    }
-
-    def _cheapest(self, tier, provider=None):
-        """Cheapest model in a tier — from the same provider, since an agent can only
-        switch between its own vendor's models (Codex can't run Haiku)."""
-        ms = [m for m, v in self.pricing.models.items() if v.get("tier") == tier
-              and (provider is None or v.get("provider", "anthropic") == provider)]
-        return min(ms, key=lambda m: self.pricing.rates(m).get("output", 1e9)) if ms else None
-
-    # ---------------- evidence: what the cheaper model actually did ----------------
-    # model_switch() reprices your tokens on a cheaper model, which assumes the cheaper
-    # model would have done the same work in the same number of turns. Often it would
-    # not: a weaker model can take five times the turns on the same task, and the
-    # repricing then promises a saving that never arrives.
-    #
-    # Where you have already run more than one model on the same kind of work, we do not
-    # have to assume anything. This compares what each model actually cost per prompt on
-    # that category, and how much work it took to get there.
-
-    MIN_PROMPTS = 8          # below this a per-category average is noise, not evidence
-    SAVING_FLOOR_PCT = 20    # smaller gaps are inside the noise of what you happened to ask
-    TURN_TOLERANCE = 1.35    # more turns than this and the cheaper model was grinding
-    REPEAT_TOLERANCE = 12.0  # percentage points of extra re-asking we will accept
-
-    def model_evidence(self, f=None):
-        """Back-test a model switch against your own history.
-
-        For every category where you ran more than one model, report what each one
-        actually cost per prompt and what it took: turns, tool calls, and how often you
-        had to ask the same thing again. A candidate is only recommended when it was
-        genuinely cheaper per prompt *and* did not need materially more work to get
-        there — which is the part a repricing cannot see.
+    # How close to the ceiling counts as "near". 90% was the cut the old reprice used
+    # to decide a request could not move to a smaller window; it is kept as the
+    # observation threshold because that is where re-read cost visibly concentrates.
+    NEAR_WINDOW_PCT = 0.9
+
+    def context_window_fit(self, f=None):
+        """How much spend ran near the ceiling of the context window actually in use.
+
+        This is the one piece of the old model-switch reprice worth keeping — the
+        window check — turned from a what-if into an observation. Nothing is
+        repriced and no alternative model is assumed. A request is "near" when its
+        prompt side is at least NEAR_WINDOW_PCT of its model's window, and "over"
+        when it exceeds it, which can only mean the long-context variant served it.
         """
         w, p = self.where(f)
-        # The filter is request-scoped, so select the prompts it touches as a subquery.
-        # Joining requests directly would repeat each prompt once per request and quietly
-        # multiply both the counts and every average by the turn count.
-        scope = f"pr.id IN (SELECT r.prompt_id FROM requests r WHERE {w})"
-        # Single-model prompts only: a prompt answered by two models cannot be
-        # attributed to either, and mixed rows would blur the comparison.
-        clean = ("pr.models IS NOT NULL AND pr.models NOT LIKE '%,%' "
-                 "AND pr.models != '<synthetic>' AND pr.est_cost_usd > 0")
-        rows = self.q(f"""SELECT COALESCE(pr.category,'other') category, pr.models model,
-            pr.agent agent, COUNT(*) prompts, SUM(pr.est_cost_usd) cost,
-            AVG(pr.est_cost_usd) cost_per_prompt,
-            AVG(pr.request_count) turns, AVG(pr.tool_calls) tools,
-            AVG(pr.output_tokens) out_tokens, AVG(pr.max_context_tokens) ctx
-            FROM prompts pr WHERE {scope} AND {clean}
-            GROUP BY 1, 2, 3 HAVING prompts >= ?""", p + [self.MIN_PROMPTS])
-
-        repeats = {(r["category"], r["model"]): r["pct"] for r in self.q(f"""
-            SELECT COALESCE(pr.category,'other') category, pr.models model,
-                ROUND(100.0 * SUM(CASE WHEN dup.n > 1 THEN 1 ELSE 0 END) / COUNT(*), 1) pct
-            FROM prompts pr
-            LEFT JOIN (SELECT norm_hash, COUNT(*) n FROM prompts GROUP BY norm_hash) dup
-                   ON dup.norm_hash = pr.norm_hash
-            WHERE {scope} AND {clean}
-            GROUP BY 1, 2""", p)}
-
-        by_cat = defaultdict(list)
-        for r in rows:
-            r["repeat_pct"] = repeats.get((r["category"], r["model"]), 0.0) or 0.0
-            r["name"] = self.pricing.display_name(r["model"])
-            r["tier"] = self.pricing.tier(r["model"])
-            by_cat[r["category"]].append(r)
-
-        out, total_save = [], 0.0
-        for cat, models in by_cat.items():
-            if len(models) < 2:
-                continue
-            # The incumbent is what you spend the most on here — that is the bill a
-            # switch would actually change.
-            cur = max(models, key=lambda m: m["cost"])
-            rule = self.SWITCH_RULES.get(cat, ("balanced", "low"))[0]
-            cands = []
-            for m in models:
-                if m["model"] == cur["model"] or m["cost_per_prompt"] >= cur["cost_per_prompt"]:
-                    continue
-                # Only models the same agent can run. Telling a Claude Code user to use a
-                # GPT model is not a setting change, it is a different tool, and the
-                # comparison would be between two different ways of working.
-                if m["agent"] != cur["agent"]:
-                    continue
-                save_pct = 100.0 * (1 - m["cost_per_prompt"] / cur["cost_per_prompt"])
-                turn_ratio = (m["turns"] / cur["turns"]) if cur["turns"] else 1.0
-                repeat_delta = m["repeat_pct"] - cur["repeat_pct"]
-                # Observed, not repriced: what your own prompts cost on each side.
-                save = (cur["cost_per_prompt"] - m["cost_per_prompt"]) * cur["prompts"]
-                if save_pct < self.SAVING_FLOOR_PCT:
-                    verdict, why = "marginal", (
-                        f"Only {save_pct:.0f}% cheaper per prompt — inside the noise of what "
-                        f"you happened to ask each model.")
-                elif turn_ratio > self.TURN_TOLERANCE:
-                    verdict, why = "risky", (
-                        f"Cost {save_pct:.0f}% less per prompt but took {turn_ratio:.1f}x the "
-                        f"turns ({m['turns']:.0f} vs {cur['turns']:.0f}). It got there by "
-                        f"grinding, and that is the cost the headline number misses.")
-                elif repeat_delta > self.REPEAT_TOLERANCE:
-                    verdict, why = "risky", (
-                        f"{save_pct:.0f}% cheaper per prompt, but you re-asked "
-                        f"{m['repeat_pct']:.0f}% of these prompts against "
-                        f"{cur['repeat_pct']:.0f}% on {cur['name']} — rework you paid for twice.")
-                elif rule == "keep":
-                    verdict, why = "caution", (
-                        f"{save_pct:.0f}% cheaper per prompt and no more turns, but {cat.replace('_',' ')} "
-                        f"is reasoning-heavy work where a miss is expensive in ways this data "
-                        f"cannot show. Worth a trial, not a default.")
-                else:
-                    verdict, why = "supported", (
-                        f"{save_pct:.0f}% cheaper per prompt on {m['prompts']} of your own "
-                        f"{cat.replace('_',' ')} prompts, in {turn_ratio:.1f}x the turns "
-                        f"({m['turns']:.0f} vs {cur['turns']:.0f}) with "
-                        f"{'less' if repeat_delta <= 0 else 'similar'} re-asking. "
-                        f"This is measured, not modelled.")
-                cands.append({
-                    "model": m["model"], "name": m["name"], "tier": m["tier"],
-                    "prompts": m["prompts"], "cost_per_prompt": m["cost_per_prompt"],
-                    "turns": m["turns"], "tools": m["tools"], "repeat_pct": m["repeat_pct"],
-                    "savings_pct": round(save_pct, 1), "turn_ratio": round(turn_ratio, 2),
-                    "repeat_delta": round(repeat_delta, 1),
-                    "estimated_savings_usd": round(save, 2), "verdict": verdict, "why": why})
-            if not cands:
-                continue
-            cands.sort(key=lambda c: (c["verdict"] != "supported", -c["estimated_savings_usd"]))
-            best = cands[0] if cands[0]["verdict"] == "supported" else None
-            if best:
-                total_save += best["estimated_savings_usd"]
-            out.append({
-                "category": cat,
-                "agent": cur["agent"],
-                "current": {"model": cur["model"], "name": cur["name"], "prompts": cur["prompts"],
-                            "cost": cur["cost"], "cost_per_prompt": cur["cost_per_prompt"],
-                            "turns": cur["turns"], "tools": cur["tools"],
-                            "repeat_pct": cur["repeat_pct"]},
-                "candidates": cands,
-                "recommended": best["model"] if best else None,
-                "recommended_name": best["name"] if best else None,
-                "estimated_savings_usd": best["estimated_savings_usd"] if best else 0.0,
-                "verdict": best["verdict"] if best else cands[0]["verdict"],
-                "why": best["why"] if best else cands[0]["why"],
-                "rule": rule,
-            })
-        out.sort(key=lambda c: -c["estimated_savings_usd"])
-        return {
-            "categories": out,
-            "estimated_savings_usd": round(total_save, 2),
-            "min_prompts": self.MIN_PROMPTS,
-            "basis": "actual",
-            "method": (f"Compares what each model actually cost per prompt on the same category "
-                       f"of work, using only categories where you ran both with at least "
-                       f"{self.MIN_PROMPTS} prompts each. Turns and re-asked prompts are shown "
-                       f"because a cheaper model that needs more of both is not cheaper. "
-                       f"Nothing here is repriced or modelled."),
-            "caveat": ("Your prompts were not randomly assigned to models, so a category can "
-                       "differ in difficulty between them. Treat this as strong evidence for a "
-                       "trial, not proof."),
-        }
-
-    def model_switch(self, f=None):
-        """Per-request what-if: reprice each request on the model its work needs.
-
-        Token counts are held constant (actual); costs on both sides are estimated at the
-        configured prices. Requests whose context exceeds the target's window stay put.
-        """
-        w, p = self.where(f)
-        rows = self.q(f"""SELECT r.model, r.is_sidechain side, r.agent_type,
-            COALESCE(pr.category,'other') category, r.context_tokens ctx,
-            pj.id project_id, pj.name project,
-            r.prompt_id, r.session_id, r.input_tokens i, r.output_tokens o,
-            r.cache_read_tokens cr, r.cache_write_5m c5, r.cache_write_1h c1, r.est_cost_usd cost
-            FROM requests r LEFT JOIN prompts pr ON pr.id=r.prompt_id
-            JOIN projects pj ON pj.id=r.project_id WHERE {w}""", p)
-        target_of = {}
-        agents, proj_prov = set(), {}
-        groups, projects = {}, defaultdict(lambda: defaultdict(float))
-        total = blocked = 0.0
-        blocked_n = 0
+        rows = self.q(f"""SELECT r.model, r.priced_as, r.context_tokens ctx, r.est_cost_usd cost
+                          FROM requests r WHERE {w}""", p)
+        per = {}
+        unknown = {"requests": 0, "cost_usd": 0.0}
+        total_n = total_cost = near_cost = over_cost = 0.0
+        near_n = over_n = 0
         for r in rows:
             cost = r["cost"] or 0.0
-            total += cost
-            tier = self.pricing.tier(r["model"])
-            if tier not in self.TIER_RANK:
-                continue
-            if r["side"]:
-                is_explore = (r["agent_type"] or "").lower() == "explore"
-                want, conf = ("economy", "high") if is_explore else ("balanced", "medium")
-                scope = f"Subagent: {r['agent_type'] or 'general'}"
-            else:
-                want, conf = self.SWITCH_RULES.get(r["category"], ("balanced", "low"))
-                scope = f"Prompts: {r['category'].replace('_', ' ')}"
-            pj = projects[(r["project_id"], r["project"])]
-            pj["cost"] += cost
-            if tier == "frontier":
-                pj["frontier_cost"] += cost
-                proj_prov[(r["project_id"], r["project"])] = \
-                    self.pricing.rates(r["model"]).get("provider", "anthropic")
-            if want == "keep" or self.TIER_RANK[want] >= self.TIER_RANK[tier]:
-                if want == "keep" and tier == "frontier":
-                    pj["keep_cost"] += cost
-                continue
-            prov = self.pricing.rates(r["model"]).get("provider", "anthropic")
-            if (want, prov) not in target_of:
-                target_of[(want, prov)] = self._cheapest(want, prov)
-            tgt = target_of[(want, prov)]
-            agents.add(prov)
-            if not tgt:
-                continue
-            win = self.pricing.context_window(tgt) or 0
-            if win and (r["ctx"] or 0) > win * 0.9:
-                blocked += cost
-                blocked_n += 1
-                continue
-            alt = self.pricing.estimate(tgt, r["i"] or 0, r["o"] or 0, r["cr"] or 0,
-                                        r["c5"] or 0, r["c1"] or 0)
-            if alt >= cost:
-                continue
-            key = (scope, r["model"], tgt)
-            g = groups.setdefault(key, {"scope": scope, "current_model": r["model"],
-                                        "recommended_model": tgt, "confidence": conf,
-                                        "requests": 0, "prompts": set(), "sessions": set(),
-                                        "cost": 0.0, "alt": 0.0})
-            g["requests"] += 1
-            g["prompts"].add(r["prompt_id"])
-            g["sessions"].add(r["session_id"])
-            g["cost"] += cost
-            g["alt"] += alt
-            pj["savings"] += cost - alt
-
-        out = []
-        for g in groups.values():
-            save = g["cost"] - g["alt"]
-            if save < 0.5:
-                continue
-            out.append({**g, "prompts": len(g["prompts"] - {None}), "sessions": len(g["sessions"]),
-                        "current_name": self.pricing.display_name(g["current_model"]),
-                        "recommended_name": self.pricing.display_name(g["recommended_model"]),
-                        "estimated_savings_usd": save,
-                        "estimated_savings_pct": round(100 * save / g["cost"], 1) if g["cost"] else 0})
-        out.sort(key=lambda x: -x["estimated_savings_usd"])
-
-        by_conf = defaultdict(float)
-        for g in out:
-            by_conf[g["confidence"]] += g["estimated_savings_usd"]
-
-        proj = []
-        for (pid, name), v in projects.items():
-            if v["frontier_cost"] < 1:
+            total_n += 1
+            total_cost += cost
+            win = self.pricing.context_window(r["priced_as"] or r["model"])
+            if not win:
+                unknown["requests"] += 1
+                unknown["cost_usd"] += cost
                 continue
-            balanced = self._cheapest("balanced", proj_prov.get((pid, name), "anthropic"))
-            keep_pct = round(100 * v["keep_cost"] / v["frontier_cost"], 1)
-            default = "keep" if keep_pct >= 50 else "switch"
-            proj.append({"project": name, "project_id": pid, "cost": v["cost"],
-                         "frontier_cost": v["frontier_cost"], "keep_pct": keep_pct,
-                         "estimated_savings_usd": v["savings"],
-                         "suggested_default": (self.pricing.display_name(balanced)
-                                               if default == "switch" and balanced else "Keep current"),
-                         "why": (f"{keep_pct}% of frontier spend here is debugging/architecture/"
-                                 f"planning/review, which benefits from the top model."
-                                 if default == "keep" else
-                                 f"Only {keep_pct}% of frontier spend here is reasoning-heavy work. "
-                                 f"Make {self.pricing.display_name(balanced)} the default and "
-                                 f"switch up with /model only for hard problems.")})
-        proj.sort(key=lambda x: -x["estimated_savings_usd"])
-
+            m = per.setdefault(r["model"], {
+                "model": r["model"], "display_name": self.pricing.display_name(r["model"]),
+                "context_window": win, "requests": 0, "cost_usd": 0.0,
+                "near_requests": 0, "near_cost_usd": 0.0,
+                "over_requests": 0, "over_cost_usd": 0.0})
+            m["requests"] += 1
+            m["cost_usd"] += cost
+            ctx = r["ctx"] or 0
+            if ctx > win:
+                m["over_requests"] += 1; m["over_cost_usd"] += cost
+                over_n += 1; over_cost += cost
+            elif ctx >= win * self.NEAR_WINDOW_PCT:
+                m["near_requests"] += 1; m["near_cost_usd"] += cost
+                near_n += 1; near_cost += cost
+        out = sorted(per.values(), key=lambda m: -(m["near_cost_usd"] + m["over_cost_usd"]))
+        for m in out:
+            m["near_or_over_cost_pct"] = (round(100.0 * (m["near_cost_usd"] + m["over_cost_usd"])
+                                                / m["cost_usd"], 1) if m["cost_usd"] else 0.0)
         return {
-            "total_cost_usd": total,
-            "switches": out,
-            "projects": proj,
-            "savings_by_confidence": dict(by_conf),
-            "estimated_savings_usd": sum(by_conf.values()),
-            "safe_savings_usd": by_conf.get("high", 0) + by_conf.get("medium", 0),
-            "blocked_by_context_usd": blocked, "blocked_by_context_requests": blocked_n,
-            "rules": {k: v[0] for k, v in self.SWITCH_RULES.items()},
-            "how": {"session": "/model <name> in Claude Code",
-                    "project": '"model": "<name>" in <repo>/.claude/settings.json',
-                    "subagent": "model: haiku (or sonnet) in the agent's frontmatter in .claude/agents/"},
-            "how_by_agent": self.SWITCH_HOW_BY_AGENT,
-            "providers": sorted(agents),
-            "caveat": "Same token counts repriced on the cheaper model. Output quality and any "
-                      "extra turns a cheaper model might need are not modelled. Try it on a "
-                      "sample of work before switching everything.",
-            "basis": "recommendation",
+            "threshold_pct": int(self.NEAR_WINDOW_PCT * 100),
+            "models": out,
+            "requests": int(total_n), "cost_usd": total_cost,
+            "near_requests": near_n, "near_cost_usd": near_cost,
+            "over_requests": over_n, "over_cost_usd": over_cost,
+            "near_or_over_cost_pct": (round(100.0 * (near_cost + over_cost) / total_cost, 1)
+                                      if total_cost else 0.0),
+            "unknown_window": unknown,
+            "basis": "actual",
         }
 
     def recommendations(self, f=None):
         w, p = self.where(f)
         recs = []
 
-        # Frontier work a cheaper model could have done. Candidates are always from the
-        # same vendor: an agent can only switch within its own family (Codex can't run
-        # Haiku), so mixed frontier spend is split per vendor before anything is compared.
-        # Each recommendation offers the ladder — one step down (balanced) and the floor
-        # (economy) — priced separately, because that trade-off is the user's to make.
-        frontier_by_provider = defaultdict(list)
-        for m, v in self.pricing.models.items():
-            if v.get("tier") == "frontier":
-                frontier_by_provider[v.get("provider", "anthropic")].append(m)
-
-        for prov, models in sorted(frontier_by_provider.items()):
-            cands = []
-            for tier in ("balanced", "economy"):
-                c = self._cheapest(tier, prov)
-                if c and c not in cands:
-                    cands.append(c)
-            if not cands:
-                continue           # this vendor exposes nothing cheaper to move to
-            ph = ",".join("?" * len(models))
-            rows = self.q(f"""SELECT pr.category, COUNT(DISTINCT pr.id) prompts,
-                              GROUP_CONCAT(DISTINCT r.model) mods,
-                              SUM(r.est_cost_usd) cost, SUM(r.input_tokens) i,
-                              SUM(r.output_tokens) o, SUM(r.cache_read_tokens) cr,
-                              SUM(r.cache_write_5m) c5, SUM(r.cache_write_1h) c1
-                              FROM prompts pr JOIN requests r ON r.prompt_id=pr.id
-                              WHERE {w} AND r.model IN ({ph})
-                              GROUP BY pr.category HAVING prompts >= 3 AND cost > 0.5
-                              ORDER BY cost DESC""", p + models)
-            for r in rows:
-                # The same rules the Model switch dashboard applies, so the two pages can
-                # never contradict each other: work the rules say to keep on a frontier
-                # model is not offered a downgrade at all.
-                target, conf = self.SWITCH_RULES.get(r["category"], ("balanced", "low"))
-                if target == "keep":
-                    continue
-                alts = []
-                for m in cands:
-                    alt = self.pricing.estimate(m, r["i"], r["o"], r["cr"], r["c5"], r["c1"])
-                    if alt >= r["cost"] * 0.9:
-                        continue   # too close to the current cost to be worth the quality risk
-                    alts.append({
-                        "model": m, "name": self.pricing.display_name(m),
-                        "tier": self.pricing.tier(m),
-                        "estimated_cost_usd": alt,
-                        "estimated_savings_usd": r["cost"] - alt,
-                        "estimated_savings_pct": round(100.0 * (r["cost"] - alt) / r["cost"], 1),
-                    })
-                if not alts:
-                    continue
-                # Safest step first: balanced before economy, so the ladder reads as
-                # increasing saving and increasing risk.
-                alts.sort(key=lambda a: -self.TIER_RANK.get(a["tier"], 0))
-                for a in alts:
-                    a["suggested"] = a["tier"] == target
-                # The headline is the tier the rules actually recommend for this kind of
-                # work, not simply the smallest step; the rest stay on offer below it.
-                head = next((a for a in alts if a["suggested"]), alts[0])
-                agent = self.SWITCH_HOW_BY_AGENT.get(prov, {}).get("agent", prov)
-                recs.append({
-                    "type": "model_downgrade",
-                    "confidence": conf or "low",
-                    "title": f"Consider a cheaper {agent} model for '{r['category']}' work",
-                    "current_model": ", ".join(self.pricing.display_name(m)
-                                               for m in (r["mods"] or "").split(",") if m),
-                    "recommended_model": head["name"],
-                    "provider": prov,
-                    "agent": agent,
-                    "alternatives": alts,
-                    "scope": f"{r['prompts']} prompts categorized as {r['category']}",
-                    "actual_cost_usd": r["cost"],
-                    "estimated_alternative_cost_usd": head["estimated_cost_usd"],
-                    "estimated_savings_usd": head["estimated_savings_usd"],
-                    "estimated_savings_pct": head["estimated_savings_pct"],
-                    "caveat": f"Both options stay inside {agent}, so this is a setting change, not "
-                              "a change of agent. Assumes identical token usage on the cheaper "
-                              "model. Output quality is not modelled — validate on a sample "
-                              "before switching.",
-                    "basis": "recommendation",
-                })
-        # Biggest opportunity first, now that several vendors can each contribute one.
-        recs.sort(key=lambda r: -r["estimated_savings_usd"])
 
+        # What follows are observations, not priced savings. The cache item used to
+        # carry the no-cache counterfactual as a "saving" (tens of thousands of dollars
+        # on a bill a fraction of that) and the context item multiplied its spend by a
+        # guessed 20%. Neither number was something the method could support, so
+        # neither is shown; what is observable is.
         eff = self.efficiency(f)
         c = eff["cache"]
-        if c["reads"] and c["estimated_savings_usd"] > 0:
+        split = c.get("cost_split") or {}
+        if c["reads"] and split.get("read_cost_share"):
             recs.append({
-                "type": "cache_working", "confidence": "high",
-                "title": "Prompt caching is already saving money — keep sessions long-lived",
+                "type": "cache_working", "confidence": "observed",
+                "title": "Prompt caching is doing its job — keep sessions long-lived",
+                "detail": (f"Reads are {split['read_cost_share']*100:.0f}% of your cache cost "
+                           f"({eff['cache_hit_ratio']*100:.0f}% of cache tokens). Restarting "
+                           f"sessions throws that prefix away and pays to write it again."),
                 "actual_cost_usd": c["cost_with_cache"],
-                "estimated_alternative_cost_usd": c["cost_without_cache"],
-                "estimated_savings_usd": c["estimated_savings_usd"],
-                "estimated_savings_pct": c["savings_pct"],
-                "caveat": "Savings vs a hypothetical no-cache baseline at configured list prices.",
-                "basis": "recommendation",
+                "estimated_alternative_cost_usd": None,
+                "estimated_savings_usd": None, "estimated_savings_pct": None,
+                "caveat": "No saving is claimed: what an uncached run would have cost is a "
+                          "counterfactual, not money you avoided.",
+                "basis": "actual",
             })
 
         ctx = self.context_analysis(f)
         if ctx["large_context_cost_pct"] > 15:
             recs.append({
-                "type": "context_reduction", "confidence": "medium",
+                "type": "context_reduction", "confidence": "observed",
                 "title": f"{ctx['large_context_cost_pct']}% of spend comes from >"
                          f"{ctx['threshold']//1000}K-context requests",
+                "detail": (f"{ctx['large_context_requests']:,} requests re-sent a large prefix "
+                           f"on every turn. /compact or a fresh session resets it; how much "
+                           f"that would have saved depends on what the work needed, and is "
+                           f"not estimated here."),
                 "scope": f"{ctx['large_context_requests']:,} requests",
                 "actual_cost_usd": ctx["large_context_cost"],
-                "estimated_savings_usd": ctx["large_context_cost"] * 0.2,
-                "estimated_savings_pct": 20.0,
-                "caveat": "Assumes a 20% context reduction is achievable via /compact and tighter "
-                          "file scoping. Not a measured saving.",
-                "basis": "recommendation",
+                "estimated_alternative_cost_usd": None,
+                "estimated_savings_usd": None, "estimated_savings_pct": None,
+                "caveat": "Observed share of spend. No reduction is assumed.",
+                "basis": "actual",
             })
-        recs.sort(key=lambda r: -(r.get("estimated_savings_usd") or 0))
-        return {"recommendations": recs,
-                "total_estimated_savings_usd": sum(r.get("estimated_savings_usd") or 0
-                                                   for r in recs if r["type"] != "cache_working"),
-                "basis": "recommendation"}
+        recs.sort(key=lambda r: -(r.get("actual_cost_usd") or 0))
+        return {"recommendations": recs, "basis": "actual"}
 
     # ---------------- forecast ----------------
     def forecast(self, f=None):
@@ -1302,42 +1468,46 @@ class Analytics:
                           FROM requests r WHERE {w} AND r.day <> '' GROUP BY 1 ORDER BY 1""", p)
         if not rows:
             return {"available": False, "message": "No usage in the selected range."}
-        recent = rows[-14:]
-        costs = [r["cost"] for r in recent]
-        mean = statistics.fmean(costs)
-        sd = statistics.pstdev(costs) if len(costs) > 1 else 0.0
+        # calendar days, idle days as zero, excluding today (still partial) — the rate
+        # below is multiplied by calendar days remaining, so a per-active-day mean
+        # would overstate every scenario and a partial today would understate it
+        yesterday = (self.today() - timedelta(days=1)).isoformat()
+        recent = [r for r in self.daily_series(f, days=14, end=yesterday)]   # complete days only
+        priced = [r["cost"] for r in recent]
+        sample_days = sum(1 for c in priced if c > 0)
+        mean = statistics.fmean(priced) if priced else 0.0
+        sd = statistics.pstdev(priced) if len(priced) > 1 else 0.0
         in_period = [r for r in rows if bp["start"] <= r["day"] <= bp["end"]]
         used = sum(r["cost"] for r in in_period)
         used_tok = sum(r["tokens"] for r in in_period)
         left = bp["remaining_days"]
+        insufficient = sample_days < 7
 
-        def band(rate):
-            return {"daily_rate": rate, "end_of_period_cost": used + rate * left}
+        def band(rate, spread=0.0):
+            # spend on different days is treated as independent, so the spread of a
+            # sum over `left` days grows with sqrt(left), not left
+            return {"daily_rate": rate,
+                    "end_of_period_cost": used + rate * left + spread * (left ** 0.5)}
 
-        scenarios = {
-            "conservative": band(max(mean - sd, 0)),
-            "expected": band(mean),
-            "high": band(mean + sd),
-        }
-        tok_mean = statistics.fmean([r["tokens"] for r in recent])
-        today_rows = [r for r in rows if r["day"] == bp["today"]]
-        hours = max(datetime.now(timezone.utc).hour, 1)
-        eod = (today_rows[0]["cost"] / hours * 24) if today_rows else mean
+        scenarios = {"expected": band(mean)}
+        if not insufficient:
+            scenarios["conservative"] = band(mean, -sd)
+            scenarios["high"] = band(mean, sd)
+            scenarios["conservative"]["end_of_period_cost"] = max(
+                scenarios["conservative"]["end_of_period_cost"], used)
 
-        wk_start = (_d(bp["today"]) - timedelta(days=_d(bp["today"]).weekday())).isoformat()
-        wk_used = sum(r["cost"] for r in rows if r["day"] >= wk_start)
-        wk_left = 6 - _d(bp["today"]).weekday()
+        tok_mean = statistics.fmean([r["tokens"] for r in recent]) if recent else 0.0
 
         out = {
             "available": True,
-            "method": "14-day mean daily spend with ±1 standard deviation bands",
-            "sample_days": len(recent),
+            "method": ("mean of the last 14 complete calendar days (idle days as zero); "
+                       "bands are ±1 sd × sqrt(days remaining)"),
+            "sample_days": sample_days,
+            "insufficient_history": insufficient,
             "daily_mean": mean, "daily_stdev": sd,
             "period_used": used, "period_used_tokens": used_tok,
             "remaining_days": left,
             "scenarios": scenarios,
-            "end_of_day_cost": eod,
-            "end_of_week_cost": wk_used + mean * max(wk_left, 0),
             "end_of_period_tokens": used_tok + tok_mean * left,
             "estimated_monthly_cost": used + mean * left,
             "basis": "forecast",
@@ -1409,34 +1579,55 @@ class Analytics:
         w, p = self.where(f)
         cfg = self.settings["anomaly"]
         found = []
-        days = self.q(f"""SELECT r.day, SUM(r.est_cost_usd) cost, SUM(r.billable_tokens) tokens,
-                          COUNT(*) requests FROM requests r WHERE {w} AND r.day<>''
-                          GROUP BY 1 ORDER BY 1""", p)
-        if len(days) >= 5:
-            vals = [d["cost"] for d in days]
-            mean, sd = statistics.fmean(vals), (statistics.pstdev(vals) or 1e-9)
-            for d in days:
-                z = (d["cost"] - mean) / sd
-                ratio = d["cost"] / mean if mean else 0
-                if z >= cfg["daily_zscore"] and ratio >= cfg["daily_ratio"]:
+        yesterday = (self.today() - timedelta(days=1)).isoformat()
+        series = [d for d in self.daily_series(dict(f or {}, agents=["claude"]), end=yesterday)]
+        priced = [d for d in series if d["cost"] > 0]
+        if len(priced) >= 14:
+            # Median/MAD, not mean/stdev: unpriced $0 days from agents without pricing
+            # data (e.g. Cursor) would otherwise pollute the mean/sd baseline and
+            # either mask real spikes or manufacture fake ones. MAD is scaled by
+            # 1.4826 so it estimates the same thing a standard deviation would under
+            # a normal distribution, without a few extreme days inflating it the way
+            # a real stdev would.
+            vals = [d["cost"] for d in priced]
+            med = statistics.median(vals)
+            mad = statistics.median(abs(v - med) for v in vals) * 1.4826 or 1e-9
+            for d in priced:
+                score = (d["cost"] - med) / mad
+                ratio = d["cost"] / med if med else 0
+                if score >= cfg.get("daily_robust_z", 3.5) and ratio >= cfg["daily_ratio"]:
                     found.append({
                         "severity": "high", "type": "daily_spike", "date": d["day"],
                         "title": f"{d['day']} spend was {ratio:.1f}x your daily average",
-                        "detail": f"${d['cost']:,.2f} vs a ${mean:,.2f} daily mean (z={z:.1f}).",
-                        "metric_value": d["cost"], "baseline": mean, "ratio": round(ratio, 2),
+                        "detail": f"${d['cost']:,.2f} vs a ${med:,.2f} median priced day (robust z={score:.1f}).",
+                        "metric_value": d["cost"], "baseline": med, "ratio": round(ratio, 2),
                         "drilldown": {"filter": {"start": d["day"], "end": d["day"]}},
                         "basis": "estimated",
                     })
         sess = self.sessions(f, limit=100000, order="cost")
         if len(sess) >= 5:
-            vals = [s["tokens"] for s in sess]
-            mean = statistics.fmean(vals) or 1
-            for s in sess[:40]:
+            # Median, not mean: session token counts are heavily right-skewed, and a
+            # mean lets the outliers inflate the very baseline they are measured
+            # against — which understates how far out they really are. Candidates are
+            # ranked by tokens too, since that is the metric being tested; ordering by
+            # cost hid token-heavy work on cheap models.
+            # Sessions with no token data (Cursor transcripts don't always carry it)
+            # are not comparable and would drag the baseline down.
+            vals = [s["tokens"] for s in sess if (s["tokens"] or 0) > 0]
+            mean = (statistics.median(vals) if vals else 0) or 1
+            # Session sizes are heavy-tailed enough that any fixed multiple of the
+            # baseline still matches a fifth of them, so the threshold alone cannot
+            # keep this list short. Take the most extreme few and leave room for the
+            # other anomaly types, which have much smaller ratios and would otherwise
+            # be sorted off the end of the list.
+            outliers = 0
+            for s in sorted(sess, key=lambda x: -(x["tokens"] or 0))[:40]:
                 ratio = s["tokens"] / mean
-                if ratio >= cfg["session_ratio"]:
+                if ratio >= cfg["session_ratio"] and outliers < cfg.get("max_session_outliers", 5):
+                    outliers += 1
                     found.append({
-                        "severity": "medium", "type": "session_outlier",
-                        "title": f"Session consumed {ratio:.1f}x the average session tokens",
+                        "severity": "low", "type": "session_outlier",
+                        "title": f"Among your largest sessions: {ratio:.1f}x the median",
                         "detail": f"{s['title'] or s['session_id'][:8]} — {s['tokens']:,} tokens, "
                                   f"${s['cost']:,.2f} in {s['project']}.",
                         "metric_value": s["tokens"], "baseline": mean, "ratio": round(ratio, 2),
@@ -1445,7 +1636,7 @@ class Analytics:
                     })
         # week-over-week model shift
         if self.last_day:
-            end = _d(self.last_day)
+            end = self.today() - timedelta(days=1)   # anchor on yesterday, not last_day
             cur_s = (end - timedelta(days=6)).isoformat()
             prev_s, prev_e = (end - timedelta(days=13)).isoformat(), (end - timedelta(days=7)).isoformat()
             for m in self.q(f"SELECT DISTINCT r.model FROM requests r WHERE {w}", p):
@@ -1471,46 +1662,27 @@ class Analytics:
     # ---------------- scorecard ----------------
     def scorecard(self, f=None):
         eff = self.efficiency(f)
-        ctx = self.context_analysis(f)
         wst = self.waste(f)
         bud = self.budgets(f)
-        mdl = self.models(f)
         dims = []
 
         def dim(name, score, detail, weight=1.0):
             dims.append({"name": name, "score": max(0, min(100, round(score))),
                          "detail": detail, "weight": weight})
 
-        chr_ = eff["cache_hit_ratio"]
-        if chr_ is None:
-            dim("Cache efficiency", 50, "No cache activity in range", 1.0)
+        hy = self.hygiene(f)
+        thr = max(int(t) for t in hy["above"])
+        share = hy["above"][str(thr)]["share_pct"]
+        dim("Context share", 100 - share,
+            f"{share:.0f}% of spend ran above {thr//1000}K context.", 1.0)
+
+        margin = eff["cache"].get("breakeven_margin")
+        if margin is None:
+            dim("Cache break-even", 50, "No cache activity in range", 1.0)
         else:
-            dim("Cache efficiency", chr_ * 100,
-                f"{chr_*100:.1f}% of cache tokens were reads (reuse) rather than writes.", 1.2)
-
-        sc_cfg = self.settings.get("scorecard", {})
-        target = sc_cfg.get("target_output_ratio", 0.0088)
-        outr = eff["output_ratio"]
-        dim("Token efficiency", min(outr / target, 1.0) * 100,
-            f"Output is {outr*100:.2f}% of billable tokens against a "
-            f"{target*100:.2f}% reference.", 1.2)
-
-        big_pct = ctx["large_context_cost_pct"]
-        dim("Context efficiency", 100 - big_pct,
-            f"{big_pct}% of spend came from requests above "
-            f"{ctx['threshold']//1000}K context.", 1.0)
-
-        excess = wst["excess_pct"]
-        dim("Waste control", 100 - min(excess, 100),
-            f"{excess}% of spend is estimated excess over a reasonable baseline "
-            f"({wst['exposed_pct']}% of spend sits in items a rule touched).", 1.3)
-
-        priced = [r for r in mdl["rows"] if r["tier"] != "none" and r["cost"]]
-        frontier_pct = (100.0 * sum(r["cost"] for r in priced if r["tier"] == "frontier")
-                        / (sum(r["cost"] for r in priced) or 1))
-        allow = sc_cfg.get("frontier_cost_share_allowance_pct", 40)
-        dim("Model selection", 100 - max(frontier_pct - allow, 0) * 1.5,
-            f"{frontier_pct:.0f}% of spend is on frontier-tier models.", 1.1)
+            dim("Cache break-even", 50 + margin * 50,
+                f"Caching returned {margin*100:.0f}% of its cost as read discount net of "
+                "write premium.", 1.0)
 
         ml = next((l for l in bud["lines"] if l["name"] == "Monthly spend"), None)
         if ml and ml.get("configured"):
@@ -1519,12 +1691,7 @@ class Analytics:
                 f"Forecast is {fp:.0f}% of the configured monthly budget.", 1.3)
         else:
             dim("Budget adherence", 50,
-                "No monthly budget configured — set one in config/settings.json to be graded.", 0.4)
-
-        cpo = eff["cost_per_1k_output"]
-        cpo_target = sc_cfg.get("target_cost_per_1k_output_usd", 0.30)
-        dim("Cost efficiency", 100 - min(cpo / (cpo_target * 2) * 100, 100),
-            f"${cpo:.3f} estimated per 1K output tokens.", 1.0)
+                "No monthly budget configured — set one in config/settings.json to be measured.", 0.4)
 
         tw = sum(d["weight"] for d in dims)
         total = round(sum(d["score"] * d["weight"] for d in dims) / tw)
@@ -1532,8 +1699,7 @@ class Analytics:
         weak = sorted(dims, key=lambda d: d["score"])[:3]
         top = wst["findings"][0] if wst["findings"] else None
         return {
-            "score": total, "grade": ("A" if total >= 85 else "B" if total >= 70
-                                      else "C" if total >= 55 else "D" if total >= 40 else "F"),
+            "score": total,
             "dimensions": dims,
             "what_is_good": [f"{d['name']}: {d['detail']}" for d in strong if d["score"] >= 60],
             "needs_attention": [f"{d['name']}: {d['detail']}" for d in weak if d["score"] < 70],
@@ -1570,16 +1736,9 @@ class Analytics:
         for r in recs["recommendations"][:2]:
             if r["type"] == "cache_working":
                 continue
-            # Name the models. A saving is meaningless without the swap it assumes, and
-            # the options are what the reader actually has to choose between.
-            opts = " or ".join(f"{a['name']} (~${a['estimated_savings_usd']:,.0f}, "
-                               f"{a['estimated_savings_pct']}%)" for a in r.get("alternatives", []))
-            swap = f"{r['current_model']} → {opts}. " if opts else ""
             actions.append({"priority": 3, "kind": "recommendation", "text": r["title"],
-                            "detail": f"{swap}Estimated saving ~${r['estimated_savings_usd']:,.2f} "
-                                      f"({r['estimated_savings_pct']}%) on the suggested option. "
-                                      f"{r['caveat']}",
-                            "basis": "recommendation"})
+                            "detail": r.get("detail") or r.get("caveat") or "",
+                            "basis": r.get("basis", "recommendation")})
         ml = next((l for l in bud["lines"] if l["name"] == "Monthly spend"), None)
         if ml and ml.get("configured") and ml.get("forecast_pct"):
             if ml["forecast_pct"] >= 90:
@@ -1599,64 +1758,15 @@ class Analytics:
                     "detail": "; ".join(f"\"{x['preview'][:60]}…\" (${x['pcost']:,.2f})" for x in pr),
                     "basis": "estimated"})
         actions.sort(key=lambda a: a["priority"])
-        savings = recs["total_estimated_savings_usd"]
+        # No "savings opportunity" range: the old one was a guessed 20% of large-context
+        # spend, then 0.6x of that for a low end. Neither factor came from the data.
         return {
             "question": "What should I do today?",
             "actions": actions[:6],
-            "estimated_savings_range_usd": [round(savings * 0.6, 2), round(savings, 2)],
             "generated_from": "Live dashboard data for the current filter selection.",
             "basis": "mixed: see per-item basis",
         }
 
-    # ---------------- prompt-level advisor ----------------
-    def prompt_advisor(self, p):
-        """Deterministic, evidence-based analysis of one prompt. Estimates only."""
-        reasons, suggestions = [], []
-        chars = p.get("char_len") or 0
-        ctx = p.get("max_context_tokens") or 0
-        tools = p.get("tool_calls") or 0
-        out = p.get("output_tokens") or 0
-        tot = p.get("billable_tokens") or 0
-        reduction = 0.0
-        if chars > 4000:
-            reasons.append(f"The prompt itself is {chars:,} characters, which is cached and "
-                           f"re-sent on every follow-up turn.")
-            suggestions.append("Move long pasted content into a file and reference the path.")
-            reduction += 0.10
-        if ctx > 150000:
-            reasons.append(f"It ran with up to {ctx:,} context tokens per request.")
-            suggestions.append("Run /compact or start a fresh session before a task this large.")
-            reduction += 0.25
-        if tools > 40:
-            reasons.append(f"It triggered {tools} tool calls; each one re-sends the conversation.")
-            suggestions.append("Split into smaller, explicitly scoped sub-tasks.")
-            reduction += 0.15
-        if tot and out / tot < 0.01:
-            reasons.append(f"Only {100*out/tot:.2f}% of the tokens were output — most of the "
-                           f"cost was re-reading context.")
-            suggestions.append("Narrow the files and history in scope before asking.")
-            reduction += 0.10
-        models = (p.get("models") or "")
-        if "opus" in models and out < 400:
-            reasons.append("A frontier-tier model produced a short answer.")
-            suggestions.append("Route short turns to a cheaper model tier.")
-            reduction += 0.20
-        if not reasons:
-            return {"available": False,
-                    "message": "No cost-driver pattern detected for this prompt."}
-        reduction = min(reduction, 0.6)
-        return {
-            "available": True,
-            "why_expensive": reasons,
-            "suggestions": suggestions,
-            "estimated_token_reduction_pct": round(reduction * 100),
-            "estimated_cost_reduction_pct": round(reduction * 100 * 0.85),
-            "estimated_cost_reduction_usd": round((p.get("est_cost_usd") or 0) * reduction * 0.85, 2),
-            "disclaimer": "ESTIMATE from structural heuristics. Not a measured saving and not a "
-                          "guarantee of equivalent output quality.",
-            "basis": "recommendation",
-        }
-
     # ---------------- claude code / developer ----------------
     def developer(self, f=None):
         w, p = self.where(f)