cctally 1.44.2 → 1.45.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.45.0] - 2026-06-15
+
+### Added
+- Conversation viewer: the dashboard now marks any assistant turn that suffered a **prompt-cache failure** — where Claude re-created the bulk of its cached prompt prefix instead of reading it (most often on the first turn after you send a new message — usually well inside the cache TTL, not just on long idle gaps), re-billing those tokens at the higher cache-write rate. The failing turn gets an amber `⚡ CACHE REBUILT · <tokens> · +$<wasted>` chip in its header, and the conversation outline gains a matching amber landmark, a `⚡` quick-jump button (`c` / `C` keys), and a "Cache" count in the at-a-glance stats card. Detection is conservative (per model + thread: `cache_read` collapses below half its running high-water mark **and** ≥75% of the turn's context is freshly re-created, with the unavoidable first cache prime, model switches, and context compaction all excluded), so a typical session shows about one marker. The markers are on by default and can be turned off via the new `dashboard.cache_failure_markers` config key (or the dashboard's Settings → "Conversation viewer" toggle). The wasted-cost figure is a display-only estimate recomputed per read — no new database tables and no migration.
+
+## [1.44.3] - 2026-06-15
+
+### Fixed
+- `blocks` and the dashboard Blocks panel no longer split a single 5-hour window into two overlapping blocks when Anthropic's `rate_limits.5h.resets_at` jitters by one second across a 10-minute boundary (e.g. `20:39:59` vs `20:40:00`). The recorded-window loader identified each window by re-flooring the raw, jittery reset string to 10-minute buckets, so a 1-second straddle landed in two different buckets and rendered as two adjacent ~5h rows (with the bulk of the cost in the spurious *earlier* row, e.g. a phantom `6:30 p.m.` block alongside the real `6:40 p.m.` one); the weighted non-overlap scheduler then kept the phantom because its heavy canonical neighbor outweighed the real chain by a single point, and the #116 force-restore added the real anchor back without evicting the phantom. The loader now keys each window by the canonical, jitter-collapsed `five_hour_window_key` the `record-usage` path already stores — so a straddle collapses to one bucket and both the CLI and the dashboard show a single block with the correct total. The committed `five_hour_blocks` rollup was always correct; only this display path was affected, and it self-corrects on the next read with no migration (#201).
+- **Internal (test infra, no user-facing change): the per-migration golden byte-idempotency guard (#197) now passes on the public Linux CI matrix.** That guard compared each rebuilt golden to the committed `.sqlite` byte-for-byte, normalizing only the 4-byte writer-version header — but SQLite's whole on-disk page layout (page allocation / freelist / B-tree balancing) is not portable across library versions, and FTS5 stores its inverted index as version-dependent binary segments, so the goldens (generated on the maintainer's macOS SQLite 3.53.2) byte-mismatched the public Linux CI's SQLite 3.45.1 even though their logical content is identical. v1.44.2 was the guard's first exposure to a non-macOS SQLite (the matrix only runs on tag push / weekly cron / dispatch), so it went red. The guard is now two-tier: STRICT byte-idempotency on the goldens' origin SQLite version (the maintainer's machine, the full #197 guarantee that a regen won't dirty the committed file), falling back to a version-portable SEMANTIC fingerprint — `user_version` / `application_id` plus the canonical SQL dump of every real table, taken from an in-memory copy with the FTS5 virtual tables dropped — on any other SQLite version. Still catches real builder/data drift (verified non-vacuous); nothing to do on upgrade (#199).
+
 ## [1.44.2] - 2026-06-14
 
 ### Fixed

package/bin/_cctally_config.py

@@ -302,6 +302,7 @@ ALLOWED_CONFIG_KEYS = (
     "alerts.command_template",
     "dashboard.bind",
     "dashboard.expose_transcripts",
+    "dashboard.cache_failure_markers",
     "update.check.enabled",
     "update.check.ttl_hours",
     "statusline.visual_burn_rate",
@@ -478,6 +479,28 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return False
         return False
+    if key == "dashboard.cache_failure_markers":
+        # Boolean opt-OUT (spec §5). Default TRUE — absence is treated as ON
+        # (unlike dashboard.expose_transcripts, an opt-IN default of False).
+        # A hand-edited junk value surfaces the True default rather than
+        # crashing (mirrors dashboard.bind / expose_transcripts).
+        block = config.get("dashboard") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("cache_failure_markers")
+        if stored is None:
+            return True
+        if isinstance(stored, bool):
+            return stored
+        # Only str spellings are normalizable; any other JSON scalar surfaces
+        # the default (the shared normalizer's .strip() would AttributeError on
+        # a bare int — uncaught by `except ValueError`).
+        if isinstance(stored, str):
+            try:
+                return c._normalize_alerts_enabled_value(stored)
+            except ValueError:
+                return True
+        return True
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Defaults mirror `_is_update_check_due` (True / 24 hours).
         # Hand-edited junk surfaces as the default — matches dashboard.bind.
@@ -864,6 +887,49 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
                 f"{'true' if canonical else 'false'}"
             )
         return 0
+    if key == "dashboard.cache_failure_markers":
+        # Same read-modify-write posture as dashboard.expose_transcripts:
+        # validate first, then write under config_writer_lock with
+        # _load_config_unlocked (load_config inside the writer-lock
+        # self-deadlocks — fcntl.flock is per-fd). Preserves sibling
+        # dashboard.bind / dashboard.expose_transcripts. Reuse the shared
+        # bool-normalizer; catch + re-message with the actual key name (it
+        # hardcodes "alerts.enabled" in its ValueError text).
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for "
+                f"dashboard.cache_failure_markers: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("dashboard")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: dashboard config error: dashboard must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["cache_failure_markers"] = canonical
+            config["dashboard"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(
+                json.dumps(
+                    {"dashboard": {"cache_failure_markers": canonical}}, indent=2
+                )
+            )
+        else:
+            print(
+                f"dashboard.cache_failure_markers="
+                f"{'true' if canonical else 'false'}"
+            )
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
@@ -1236,6 +1302,22 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "dashboard.cache_failure_markers":
+        # Mirror the dashboard.expose_transcripts unset branch: drop only the
+        # cache_failure_markers leaf; if the dashboard block ends up empty, drop
+        # the parent too so config.json stays tidy. Sibling dashboard.bind /
+        # expose_transcripts survive. Unsetting restores the True (opt-out)
+        # default at read time.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("dashboard")
+            if isinstance(block, dict) and "cache_failure_markers" in block:
+                del block["cache_failure_markers"]
+                if not block:
+                    config.pop("dashboard", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",

package/bin/_cctally_dashboard.py

@@ -4912,6 +4912,18 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "notifier":           _alerts_cfg.get("notifier", "auto"),
         "command_configured": _alerts_cfg.get("command_template") is not None,
     }
+    # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec §5).
+    # Reuses the single `_cfg_for_alerts = load_config()` read above (no extra
+    # FS hit on the hot path). Default true — absence is treated as ON (opt-out,
+    # not opt-in); a hand-edited non-bool surfaces the default. The on/off toggle
+    # is honored entirely at client render time; the kernel + API always emit the
+    # marker data.
+    _dash_cfg = _cfg_for_alerts.get("dashboard") if isinstance(
+        _cfg_for_alerts.get("dashboard"), dict) else {}
+    _cfm = _dash_cfg.get("cache_failure_markers", True)
+    dashboard_prefs = {
+        "cache_failure_markers": _cfm if isinstance(_cfm, bool) else True,
+    }
 
     # Mirror update-state.json + update-suppress.json into the envelope
     # so the dashboard's amber "Update available" badge repaints from
@@ -5149,6 +5161,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "alerts":           alerts_array,
         "alerts_settings":  alerts_settings,
 
+        # Dashboard render-prefs mirror (cache-failure-markers opt-out, spec
+        # §5). Additive optional, like alerts_settings — envelope_version
+        # stays at 2. The client derives `markersEnabled` from this, defaulting
+        # to true when the field is undefined (older server / first tick).
+        "dashboard_prefs":  dashboard_prefs,
+
         # update-subcommand SSE mirror (see comment above the
         # `_load_update_state()` block). Shape matches GET
         # /api/update/status's payload (`{state, suppress}`) so the
@@ -5685,7 +5703,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
 
         # Reject unknown top-level keys (forward-compat hygiene).
         allowed_top_keys = {
-            "display", "alerts", "update", "cache_report", "budget",
+            "display", "alerts", "update", "cache_report", "budget", "dashboard",
         }
         for k in payload.keys():
             if k not in allowed_top_keys:
@@ -5701,12 +5719,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             and "update" not in payload
             and "cache_report" not in payload
             and "budget" not in payload
+            and "dashboard" not in payload
         ):
             self._respond_json(
                 400,
                 {"error": (
                     "body must contain at least one of: "
-                    "display, alerts, update, cache_report, budget"
+                    "display, alerts, update, cache_report, budget, dashboard"
                 )},
             )
             return
@@ -5835,6 +5854,52 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 )
                 return
 
+        # Pre-validate the dashboard block (spec §5). Only
+        # ``cache_failure_markers`` is dashboard-writable — a JSON boolean
+        # (string/int rejected, mirroring the strict bool checks for
+        # ``alerts.enabled``). ``dashboard.bind`` / ``dashboard.expose_transcripts``
+        # are bind-time / privacy-gate settings, NOT live-mutable, so they are
+        # rejected explicitly here (rather than silently dropped). Outside the
+        # config_writer_lock so a 400 short-circuit doesn't take the lock.
+        dashboard_validated: "dict | None" = None
+        if "dashboard" in payload:
+            dashboard_block = payload["dashboard"]
+            if not isinstance(dashboard_block, dict):
+                self._respond_json(
+                    400,
+                    {"error": "dashboard must be an object", "field": "dashboard"},
+                )
+                return
+            for leaf in dashboard_block.keys():
+                if leaf in ("bind", "expose_transcripts"):
+                    self._respond_json(
+                        400,
+                        {"error": (f"dashboard.{leaf} is not settable via the "
+                                   "dashboard (bind-time / privacy-gate setting)"),
+                         "field": f"dashboard.{leaf}"},
+                    )
+                    return
+                if leaf != "cache_failure_markers":
+                    self._respond_json(
+                        400,
+                        {"error": f"unknown dashboard settings key: {leaf}",
+                         "field": f"dashboard.{leaf}"},
+                    )
+                    return
+            dashboard_validated = {}
+            if "cache_failure_markers" in dashboard_block:
+                if not isinstance(dashboard_block["cache_failure_markers"], bool):
+                    self._respond_json(
+                        400,
+                        {"error": ("dashboard.cache_failure_markers must be a "
+                                   "JSON boolean"),
+                         "field": "dashboard.cache_failure_markers"},
+                    )
+                    return
+                dashboard_validated["cache_failure_markers"] = (
+                    dashboard_block["cache_failure_markers"]
+                )
+
         # Pre-validate update shape. Only `update.check.{enabled,ttl_hours}`
         # is settable today; any other key under `update` or `update.check`
         # is rejected so adding e.g. `update.banner.*` later is forward
@@ -6061,6 +6126,23 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 merged_cr.update(cache_report_validated)
                 merged["cache_report"] = merged_cr
 
+            if dashboard_validated is not None:
+                # Same hand-edited-junk guard as the other blocks: a non-dict
+                # stored ``dashboard`` block should surface as a recoverable
+                # 400, not a 500. Partial-merge so the (bind-time, CLI-only)
+                # ``bind`` / ``expose_transcripts`` siblings are PRESERVED —
+                # cache_failure_markers writes must never clobber them.
+                existing_dash = merged.get("dashboard")
+                if existing_dash is not None and not isinstance(existing_dash, dict):
+                    self._respond_json(
+                        400, {"error": "dashboard must be an object",
+                              "field": "dashboard"}
+                    )
+                    return
+                merged_dash = dict(existing_dash or {})
+                merged_dash.update(dashboard_validated)
+                merged["dashboard"] = merged_dash
+
             save_config(merged)
 
         # Build the response: subset of touched blocks.
@@ -6152,6 +6234,16 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             out["cache_report"] = {
                 "anomaly_threshold_pp": stored_threshold,
             }
+        if dashboard_validated is not None:
+            # Echo the persisted cache_failure_markers (the only dashboard-
+            # writable leaf) so the SettingsOverlay can repaint without a
+            # follow-up GET. Default true (opt-out) when nothing is persisted.
+            persisted_dash = merged.get("dashboard") or {}
+            out["dashboard"] = {
+                "cache_failure_markers": bool(
+                    persisted_dash.get("cache_failure_markers", True)
+                ),
+            }
         out["saved_at"] = (
             dt.datetime.now(dt.timezone.utc)
             .strftime("%Y-%m-%dT%H:%M:%SZ")

package/bin/_cctally_five_hour.py

@@ -307,7 +307,7 @@ def _load_recorded_five_hour_windows(
     try:
         with open_db() as conn:
             rows = conn.execute(
-                "SELECT five_hour_resets_at "
+                "SELECT five_hour_resets_at, five_hour_window_key "
                 "FROM weekly_usage_snapshots "
                 "WHERE five_hour_resets_at IS NOT NULL "
                 "  AND five_hour_resets_at >= ? "
@@ -326,7 +326,8 @@ def _load_recorded_five_hour_windows(
             canonical_rows: list[Any] = []
             try:
                 canonical_rows = conn.execute(
-                    "SELECT five_hour_resets_at, block_start_at "
+                    "SELECT five_hour_resets_at, block_start_at, "
+                    "       five_hour_window_key "
                     "FROM five_hour_blocks "
                     "WHERE five_hour_resets_at IS NOT NULL "
                     "  AND five_hour_resets_at >= ? "
@@ -378,9 +379,25 @@ def _load_recorded_five_hour_windows(
         # denied on parent dir) that propagate from open_db() before any
         # SQL runs. Either way, fall back to the heuristic anchor path.
         return [], {}, {}
+    # issue #201: identify each 5h window by its canonical, jitter-collapsed
+    # ``five_hour_window_key`` (the 10-min-floored epoch the record path
+    # already stored via the anchored ``_canonical_5h_window_key`` reuse)
+    # instead of re-flooring the raw ``five_hour_resets_at`` string. A
+    # 1-second reset jitter straddling a 10-minute floor boundary
+    # (``20:39:59`` vs ``20:40:00``) floors to two different buckets and
+    # would otherwise fork one physical window into two overlapping blocks
+    # — the exact split this column exists to prevent. Falls back to the
+    # pure floor for legacy rows whose key wasn't backfilled (``open_db``
+    # backfills NULL keys before this query runs, so this is defensive).
+    def _bucket_dt(window_key: Any, resets_dt: dt.datetime) -> dt.datetime:
+        if window_key is not None:
+            return dt.datetime.fromtimestamp(int(window_key), dt.timezone.utc)
+        return _c._floor_to_ten_minutes(resets_dt)
+
     counts: dict[dt.datetime, int] = {}
     for row in rows:
         raw = row["five_hour_resets_at"] if hasattr(row, "keys") else row[0]
+        wkey = row["five_hour_window_key"] if hasattr(row, "keys") else row[1]
         if raw is None:
             continue
         try:
@@ -391,7 +408,7 @@ def _load_recorded_five_hour_windows(
             d = d.replace(tzinfo=dt.timezone.utc)
         else:
             d = d.astimezone(dt.timezone.utc)
-        snapped = _c._floor_to_ten_minutes(d)
+        snapped = _bucket_dt(wkey, d)
         counts[snapped] = counts.get(snapped, 0) + 1
     # Overlay canonical rollup anchors at heavy weight. Same flooring
     # rule so a jittered raw value (e.g. 17:48Z) and its canonicalized
@@ -411,10 +428,16 @@ def _load_recorded_five_hour_windows(
     # truncated R keeps both blocks visible — without this fix the
     # earlier block's entries are silently rendered as a phantom
     # heuristic "~" row by `_group_entries_into_blocks`.
-    canonical_pairs: list[tuple[dt.datetime, dt.datetime]] = []
+    # issue #201: each triple is ``(wkey_dt, bs, rs)`` — ``wkey_dt`` is the
+    # canonical window_key (decoded to a UTC datetime) and is the SAME
+    # bucket identity used for the raw-snapshot counts above, so the heavy
+    # canonical overlay always lands in the same bucket as its supporting
+    # raw rows (never a jitter-split sibling bucket).
+    canonical_pairs: list[tuple[dt.datetime, dt.datetime, dt.datetime]] = []
     for row in canonical_rows:
         rs_raw = row["five_hour_resets_at"] if hasattr(row, "keys") else row[0]
         bs_raw = row["block_start_at"]      if hasattr(row, "keys") else row[1]
+        wkey   = row["five_hour_window_key"] if hasattr(row, "keys") else row[2]
         if rs_raw is None or bs_raw is None:
             continue
         try:
@@ -430,8 +453,8 @@ def _load_recorded_five_hour_windows(
             bs = bs.replace(tzinfo=dt.timezone.utc)
         else:
             bs = bs.astimezone(dt.timezone.utc)
-        canonical_pairs.append((bs, rs))
-    canonical_pairs.sort(key=lambda p: p[0])
+        canonical_pairs.append((_bucket_dt(wkey, rs), bs, rs))
+    canonical_pairs.sort(key=lambda p: p[1])
 
     # issue #76: canonical_intervals maps every floored R -> its EXACT
     # (block_start_at, five_hour_resets_at) — both UTC, rs un-floored
@@ -444,9 +467,8 @@ def _load_recorded_five_hour_windows(
     canonical_intervals: dict[
         dt.datetime, tuple[dt.datetime, dt.datetime]
     ] = {}
-    for bs, rs in canonical_pairs:
-        snapped = _c._floor_to_ten_minutes(rs)
-        canonical_intervals[snapped] = (bs, rs)
+    for wkey_dt, bs, rs in canonical_pairs:
+        canonical_intervals[wkey_dt] = (bs, rs)
 
     # Detect overlap-with-credit and replace the earlier R with a
     # credit-truncated anchor. The (anchor → real_block_start) map is
@@ -454,11 +476,12 @@ def _load_recorded_five_hour_windows(
     # real block_start_at on the display row (instead of the default
     # R - 5h, which would be hours earlier for a 2h-truncated block).
     block_start_overrides: dict[dt.datetime, dt.datetime] = {}
-    truncated_pairs: list[tuple[dt.datetime, dt.datetime]] = []
-    for i, (bs, rs) in enumerate(canonical_pairs):
+    truncated_pairs: list[tuple[dt.datetime, dt.datetime, dt.datetime]] = []
+    for i, (wkey_dt, bs, rs) in enumerate(canonical_pairs):
+        anchor_key = wkey_dt  # canonical window_key identity (issue #201)
         truncated_R = rs
         if i + 1 < len(canonical_pairs):
-            next_bs, _next_rs = canonical_pairs[i + 1]
+            _next_wk, next_bs, _next_rs = canonical_pairs[i + 1]
             if rs > next_bs:  # overlap with next block
                 # Look for a credit moment inside [next_bs, rs] — the
                 # part of the earlier block that overlaps the next.
@@ -471,24 +494,24 @@ def _load_recorded_five_hour_windows(
                         # drop one via its weight-tiebreaker.
                         if bs < cm_floored < rs:
                             truncated_R = cm_floored
+                            anchor_key = cm_floored
                             block_start_overrides[cm_floored] = bs
-                            # Rewrite canonical_intervals[snapped_orig]
-                            # to the truncated interval under the
-                            # truncated key. issue #76: the
-                            # partitioner reads canonical_intervals
-                            # for the exact bs/rs; the truncated entry
-                            # must reflect the credit-shifted upper
-                            # bound (cm_floored) AND the real bs (the
-                            # override) so partition + Phase 1.5
-                            # render the credit-shortened block
-                            # consistently.
-                            snapped_orig = _c._floor_to_ten_minutes(rs)
-                            canonical_intervals.pop(snapped_orig, None)
+                            # Rewrite canonical_intervals under the
+                            # truncated key. issue #76: the partitioner
+                            # reads canonical_intervals for the exact
+                            # bs/rs; the truncated entry must reflect the
+                            # credit-shifted upper bound (cm_floored) AND
+                            # the real bs (the override) so partition +
+                            # Phase 1.5 render the credit-shortened block
+                            # consistently. issue #201: the original
+                            # entry is keyed by the canonical window_key,
+                            # so pop under ``wkey_dt`` (not floor(rs)).
+                            canonical_intervals.pop(wkey_dt, None)
                             canonical_intervals[cm_floored] = (
                                 bs, cm_floored,
                             )
                             break
-        truncated_pairs.append((bs, truncated_R))
+        truncated_pairs.append((anchor_key, bs, truncated_R))
 
     # Truncated anchors are credit-adjusted and known-good; bypass the
     # `_select_non_overlapping_recorded_windows` weighted scheduler for
@@ -501,16 +524,16 @@ def _load_recorded_five_hour_windows(
     # input weight (so jittered same-bucket raw values still collapse)
     # but skip them when computing the overlap-safe subset.
     truncated_anchors: set[dt.datetime] = set()
-    for bs, rs in truncated_pairs:
-        snapped = _c._floor_to_ten_minutes(rs)
-        if rs != _c._floor_to_ten_minutes(rs):
-            if rs in block_start_overrides:
-                block_start_overrides[snapped] = block_start_overrides.pop(rs)
-        # Identify truncated anchors by membership in the override map
-        # (only credit-truncated entries land there).
-        if snapped in block_start_overrides:
-            truncated_anchors.add(snapped)
-        counts[snapped] = counts.get(snapped, 0) + _CANONICAL_WEIGHT_THRESHOLD
+    for anchor_key, _bs, _rs in truncated_pairs:
+        # ``anchor_key`` is already a floored canonical key — the window_key
+        # for an untruncated anchor (issue #201) or the credit-floored key
+        # for a truncated one — and the override map is keyed by it
+        # directly, so the legacy floor-relocation dance is no longer
+        # needed. Identify truncated anchors by membership in the override
+        # map (only credit-truncated entries land there).
+        if anchor_key in block_start_overrides:
+            truncated_anchors.add(anchor_key)
+        counts[anchor_key] = counts.get(anchor_key, 0) + _CANONICAL_WEIGHT_THRESHOLD
 
     non_truncated_items = [
         (a, w) for a, w in counts.items() if a not in truncated_anchors

package/bin/_lib_conversation_query.py

@@ -285,6 +285,105 @@ def _entry_cost(model, inp, out, cc, cr, cost_usd_raw) -> float:
     return _calculate_entry_cost(model or "", usage, cost_usd=cost_usd_raw)
 
 
+# --- Cache-failure detection (spec §1) -------------------------------------
+# A prompt-cache "failure" is an assistant turn that re-creates the bulk of its
+# cached prefix instead of reading it: cache_read collapses while cache_creation
+# balloons, re-billing those tokens at the higher cache-WRITE rate. We flag only
+# clear mid-session prefix losses (the Conservative profile, ~1 per session).
+#
+# Thresholds (maintainer-tunable module constants, NOT user config). Rationale
+# from a scan of 58 recent sessions (spec Evidence): a 0.5 running-max-collapse
+# threshold sits in the wide empty gap between the worst healthy turn and the
+# mildest failure, and the recreated-fraction guard (0.75) sits in the matching
+# fraction gap (healthy max 0.723 < 0.75 <= failure min 0.759), both with margin.
+_CACHE_FAILURE_COLLAPSE_FRACTION = 0.5   # cache_read must fall to <= half the prior running-max
+_CACHE_FAILURE_RECREATE_FRACTION = 0.75  # >= 75% of THIS turn's context freshly created
+_CACHE_FAILURE_CACHE_FLOOR = 20_000      # prior cache must be meaningful to "lose"
+_CACHE_FAILURE_CREATE_FLOOR = 20_000     # the re-creation must be substantial / real cost
+
+
+def _cache_failure_wasted_usd(model, lost):
+    """Marginal extra paid by re-creating `lost` previously-cached tokens at the
+    cache-WRITE rate instead of reading them at the cache-READ rate. Reuses the
+    pricing chokepoint `_calculate_entry_cost` (zero on unknown models — the
+    helper emits its own one-shot stderr warning, never raises). NEVER summed into
+    any cost-snapshot / budget / reconciled figure — a display-only estimate."""
+    write = _calculate_entry_cost(model or "", {"cache_creation_input_tokens": lost})
+    read = _calculate_entry_cost(model or "", {"cache_read_input_tokens": lost})
+    return write - read
+
+
+def _stamp_cache_failures(items):
+    """Stamp ``item["cache_failure"]`` on each assistant turn that re-creates the
+    bulk of its cached prefix instead of reading it (spec §1). Mutates `items` in
+    place; healthy turns are left WITHOUT the key (absent, not zero — matching the
+    ``tokens?`` "absent, not zero" convention).
+
+    Walks items in DOCUMENT ORDER (the order `_assemble_session` produces),
+    maintaining a running-max of ``cache_read`` keyed by ``(subagent_key, model)``
+    — ``None`` subagent_key = main session. The key is per-thread AND per-model
+    because Anthropic prompt caches are model-specific: a model switch within a
+    thread legitimately starts a fresh cache (cr ~ 0) and must not read as a loss,
+    and the compound key makes that the first turn under its own key (no prior rm).
+    The per-key running-max is RESET when a context-compaction boundary is crossed
+    (a ``meta`` item whose ``meta_kind == "compaction"``), since compaction
+    legitimately invalidates the prefix and the post-compaction re-prime is not a
+    failure.
+
+    For each assistant item with a ``tokens`` dict — cc = tokens["cache_creation"],
+    cr = tokens["cache_read"], rm = the running-max for this key BEFORE this turn —
+    flag iff rm >= CACHE_FLOOR and cc >= CREATE_FLOOR and cr <= COLLAPSE_FRACTION*rm
+    and cc/(cc+cr) >= RECREATE_FRACTION. The fourth term keeps the rule aligned
+    with the Evidence: it requires that most of THIS turn's context was freshly
+    created, not merely that cache_read dipped. After the check, update
+    ``running_max[key] = max(rm, cr)`` (a failure's small cr never lowers the
+    high-water mark; the next healthy turn re-establishes it).
+
+    Payload (lost-prefix basis — NOT raw cc, which would over-count when the turn
+    also writes genuinely-new cacheable content that was never cached):
+        lost            = min(cc, max(0, rm - cr))
+        tokens_recreated = lost
+        prev_cached      = rm
+        est_wasted_usd   = write(lost) - read(lost)
+
+    Items lacking a ``tokens`` dict (no session_entries row, or non-assistant
+    items other than a compaction meta) are skipped and do NOT move the
+    running-max. Order-dependent by construction; run over document-ordered items.
+    """
+    running_max = {}   # (subagent_key, model) -> high-water cache_read
+    for it in items:
+        # Context-compaction boundary resets the per-key prefix high-water mark:
+        # the post-compaction re-prime is a legitimate fresh build, not a loss.
+        # Reset the whole map (compaction invalidates every thread's prefix in
+        # this session view; a per-key reset would need a thread tag the meta row
+        # does not reliably carry).
+        if it.get("kind") == "meta" and it.get("meta_kind") == "compaction":
+            running_max.clear()
+            continue
+        if it.get("kind") != "assistant":
+            continue
+        tok = it.get("tokens")
+        if not isinstance(tok, dict):
+            continue                      # no session_entries row -> skip, don't move max
+        cc = tok.get("cache_creation", 0) or 0
+        cr = tok.get("cache_read", 0) or 0
+        key = (it.get("subagent_key"), it.get("model"))
+        rm = running_max.get(key, 0)
+        total = cc + cr
+        if (rm >= _CACHE_FAILURE_CACHE_FLOOR
+                and cc >= _CACHE_FAILURE_CREATE_FLOOR
+                and cr <= _CACHE_FAILURE_COLLAPSE_FRACTION * rm
+                and total > 0
+                and cc / total >= _CACHE_FAILURE_RECREATE_FRACTION):
+            lost = min(cc, max(0, rm - cr))
+            it["cache_failure"] = {
+                "tokens_recreated": lost,
+                "prev_cached": rm,
+                "est_wasted_usd": _cache_failure_wasted_usd(it.get("model"), lost),
+            }
+        running_max[key] = max(rm, cr)
+
+
 def _session_cost_map(conn, session_ids):
     """{session_id: total_cost_usd} for the given sessions. Joins
     conversation_messages turn keys to the single deduped session_entries row
@@ -862,6 +961,12 @@ def _assemble_session(conn, session_id):
             it.pop("_has_prose", None)
     header_cost = round(header_cost, 6)
 
+    # Stamp cache-failure markers (spec §1) AFTER tokens are on each item and
+    # while `items` is still document-ordered (the running-max walk is
+    # order-dependent). Healthy turns get no key (absent, not zero). Shared
+    # assembly -> the flag reaches BOTH the reader detail and the outline.
+    _stamp_cache_failures(items)
+
     # Strip the internal Phase-4b threading key from EVERY item (meta/human items
     # carry it too, not just assistant turns) so it never surfaces in the public
     # item JSON.
@@ -995,6 +1100,12 @@ def get_conversation_outline(conn, session_id):
     tool_counts, models = {}, {}
     error_count = 0
     tokens = {"input": 0, "output": 0, "cache_creation": 0, "cache_read": 0}
+    # Cache-failure aggregate (spec §2): count + summed lost-prefix tokens +
+    # summed wasted-cost over the flagged turns. Emitted only when count > 0
+    # (the per-turn "absent, not zero" convention; ~65% of sessions have zero).
+    cf_count = 0
+    cf_tokens = 0
+    cf_wasted = 0.0
     for it in items:
         kind = it["kind"]
         turn_counts["total"] += 1
@@ -1036,6 +1147,15 @@ def get_conversation_outline(conn, session_id):
                 t["tokens"] = tok
                 for k in tokens:
                     tokens[k] += tok.get(k, 0)
+            # Copy the cache-failure marker onto the OutlineTurn exactly where
+            # tokens is copied (assistant-only, rides the same source row) and
+            # accumulate the session-level aggregate (spec §2).
+            cf = it.get("cache_failure")
+            if cf is not None:
+                t["cache_failure"] = cf
+                cf_count += 1
+                cf_tokens += cf.get("tokens_recreated", 0)
+                cf_wasted += cf.get("est_wasted_usd", 0.0)
         if kind == "meta":
             t["meta_kind"] = it.get("meta_kind")
             t["skill_name"] = it.get("skill_name")
@@ -1046,12 +1166,17 @@ def get_conversation_outline(conn, session_id):
     d0 = _parse_outline_ts(ts_vals[0] if ts_vals else None)
     d1 = _parse_outline_ts(ts_vals[-1] if ts_vals else None)
     duration = int((d1 - d0).total_seconds()) if d0 and d1 else None
+    stats = {"turns": turn_counts, "tool_counts": tool_counts,
+             "error_count": error_count, "models": models,
+             "duration_seconds": duration, "tokens": tokens,
+             "cost_usd": asm["header_cost"]}
+    if cf_count:
+        stats["cache_failures"] = {"count": cf_count,
+                                   "tokens_recreated": cf_tokens,
+                                   "est_wasted_usd": cf_wasted}
     return {"session_id": session_id,
             "subagent_meta": asm["subagent_meta"],
-            "stats": {"turns": turn_counts, "tool_counts": tool_counts,
-                      "error_count": error_count, "models": models,
-                      "duration_seconds": duration, "tokens": tokens,
-                      "cost_usd": asm["header_cost"]},
+            "stats": stats,
             "turns": turns}