cctally 1.44.3 → 1.45.0

package/CHANGELOG.md

@@ -5,6 +5,11 @@ 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

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/_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}