Add canonical display-session metrics for downstream dashboards

headroom/cli/proxy.py

@@ -324,6 +324,7 @@ Usage:
 Endpoints:
   GET  /health     Health check
   GET  /stats      Detailed statistics
+  GET  /stats-history Durable compression history + display session
   GET  /metrics    Prometheus metrics
 
 Press Ctrl+C to stop.

headroom/proxy/savings_tracker.py

@@ -1,8 +1,8 @@
-"""Durable proxy savings history tracking.
+"""Durable proxy savings and display-session tracking.
 
-Persists cumulative proxy compression savings to a local JSON file so
-historical charts survive proxy restarts and can be shared by multiple
-Headroom frontends.
+Persists cumulative proxy compression savings plus a canonical display session
+window to a local JSON file so historical charts and dashboard session stats
+survive proxy restarts and can be shared by multiple Headroom frontends.
 """
 
 from __future__ import annotations
@@ -23,9 +23,10 @@ logger = logging.getLogger(__name__)
 HEADROOM_SAVINGS_PATH_ENV_VAR = "HEADROOM_SAVINGS_PATH"
 DEFAULT_SAVINGS_DIR = ".headroom"
 DEFAULT_SAVINGS_FILE = "proxy_savings.json"
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 DEFAULT_MAX_HISTORY_POINTS = 5000
 DEFAULT_MAX_HISTORY_AGE_DAYS = 365
+DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60
 
 try:
     import litellm
@@ -140,6 +141,48 @@ def _estimate_compression_savings_usd(model: str, tokens_saved: int) -> float:
         return 0.0
 
 
+def _estimate_input_cost_usd(
+    model: str,
+    input_tokens: int,
+    *,
+    cache_read_tokens: int = 0,
+    cache_write_tokens: int = 0,
+    uncached_input_tokens: int = 0,
+) -> float:
+    """Estimate input spend in USD for a request.
+
+    Uses provider cache pricing when a complete cache breakdown is available and
+    otherwise falls back to list-price input tokens.
+    """
+    total_input_tokens = _coerce_int(input_tokens)
+    if total_input_tokens <= 0 or not LITELLM_AVAILABLE:
+        return 0.0
+
+    cache_read = _coerce_int(cache_read_tokens)
+    cache_write = _coerce_int(cache_write_tokens)
+    uncached = _coerce_int(uncached_input_tokens)
+
+    try:
+        resolved = _resolve_litellm_model(model)
+        info = litellm.model_cost.get(resolved, {})
+        input_cost_per_token = info.get("input_cost_per_token")
+        if not input_cost_per_token:
+            return 0.0
+
+        if cache_read + cache_write + uncached > 0:
+            cache_read_cost = info.get("cache_read_input_token_cost", input_cost_per_token)
+            cache_write_cost = info.get("cache_creation_input_token_cost", input_cost_per_token)
+            return (
+                float(cache_read) * float(cache_read_cost)
+                + float(cache_write) * float(cache_write_cost)
+                + float(uncached) * float(input_cost_per_token)
+            )
+
+        return float(total_input_tokens) * float(input_cost_per_token)
+    except Exception:
+        return 0.0
+
+
 def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:
     """Normalize persisted history entries across schema shapes."""
     timestamp: datetime | None = None
@@ -178,6 +221,49 @@ def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:
     }
 
 
+def _empty_display_session() -> dict[str, Any]:
+    return {
+        "requests": 0,
+        "tokens_saved": 0,
+        "compression_savings_usd": 0.0,
+        "total_input_tokens": 0,
+        "total_input_cost_usd": 0.0,
+        "savings_percent": 0.0,
+        "started_at": None,
+        "last_activity_at": None,
+    }
+
+
+def _normalize_display_session(entry: Any) -> dict[str, Any]:
+    if not isinstance(entry, dict):
+        return _empty_display_session()
+
+    started_at = _parse_timestamp(entry.get("started_at"))
+    last_activity_at = _parse_timestamp(entry.get("last_activity_at"))
+
+    if started_at is None or last_activity_at is None or last_activity_at < started_at:
+        return _empty_display_session()
+
+    tokens_saved = _coerce_int(entry.get("tokens_saved"))
+    total_input_tokens = _coerce_int(entry.get("total_input_tokens"))
+    total_before = tokens_saved + total_input_tokens
+    savings_percent = round((tokens_saved / total_before * 100) if total_before > 0 else 0.0, 2)
+
+    return {
+        "requests": _coerce_int(entry.get("requests")),
+        "tokens_saved": tokens_saved,
+        "compression_savings_usd": round(
+            _coerce_float(entry.get("compression_savings_usd")),
+            6,
+        ),
+        "total_input_tokens": total_input_tokens,
+        "total_input_cost_usd": round(_coerce_float(entry.get("total_input_cost_usd")), 6),
+        "savings_percent": savings_percent,
+        "started_at": _to_utc_iso(started_at),
+        "last_activity_at": _to_utc_iso(last_activity_at),
+    }
+
+
 class SavingsTracker:
     """Persist bounded proxy compression savings history."""
 
@@ -186,10 +272,15 @@ class SavingsTracker:
         path: str | None = None,
         max_history_points: int = DEFAULT_MAX_HISTORY_POINTS,
         max_history_age_days: int = DEFAULT_MAX_HISTORY_AGE_DAYS,
+        display_session_inactivity_minutes: int = DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES,
     ) -> None:
         self._path = Path(path or get_default_savings_storage_path())
         self._max_history_points = max_history_points
         self._max_history_age_days = max_history_age_days
+        self._display_session_inactivity_minutes = max(
+            _coerce_int(display_session_inactivity_minutes, DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES),
+            1,
+        )
         self._lock = threading.Lock()
         self._state = self._load_state()
 
@@ -257,6 +348,126 @@ class SavingsTracker:
             self._save_locked()
             return True
 
+    def record_request(
+        self,
+        *,
+        model: str,
+        input_tokens: int,
+        tokens_saved: int,
+        cache_read_tokens: int = 0,
+        cache_write_tokens: int = 0,
+        uncached_input_tokens: int = 0,
+        total_input_tokens: int | None = None,
+        total_input_cost_usd: float | None = None,
+        timestamp: datetime | str | None = None,
+    ) -> bool:
+        """Persist a canonical display-session update for every request."""
+        timestamp_dt = (
+            _parse_timestamp(timestamp)
+            if isinstance(timestamp, str)
+            else timestamp.astimezone(timezone.utc)
+            if isinstance(timestamp, datetime)
+            else _utc_now()
+        )
+        if timestamp_dt is None:
+            timestamp_dt = _utc_now()
+
+        delta_tokens_saved = _coerce_int(tokens_saved)
+        delta_input_tokens = _coerce_int(input_tokens)
+        delta_savings_usd = _estimate_compression_savings_usd(model, delta_tokens_saved)
+        delta_input_cost_usd = _estimate_input_cost_usd(
+            model,
+            delta_input_tokens,
+            cache_read_tokens=cache_read_tokens,
+            cache_write_tokens=cache_write_tokens,
+            uncached_input_tokens=uncached_input_tokens,
+        )
+
+        with self._lock:
+            lifetime = self._state["lifetime"]
+            previous_total_input_tokens = lifetime["total_input_tokens"]
+            previous_total_input_cost_usd = lifetime["total_input_cost_usd"]
+
+            next_total_input_tokens = max(
+                previous_total_input_tokens + delta_input_tokens,
+                _coerce_int(
+                    total_input_tokens,
+                    default=previous_total_input_tokens + delta_input_tokens,
+                ),
+            )
+            next_total_input_cost_usd = round(
+                max(
+                    previous_total_input_cost_usd + delta_input_cost_usd,
+                    _coerce_float(
+                        total_input_cost_usd,
+                        default=previous_total_input_cost_usd + delta_input_cost_usd,
+                    ),
+                ),
+                6,
+            )
+            session_input_tokens_delta = max(
+                next_total_input_tokens - previous_total_input_tokens,
+                0,
+            )
+            session_input_cost_delta = round(
+                max(next_total_input_cost_usd - previous_total_input_cost_usd, 0.0),
+                6,
+            )
+
+            lifetime["requests"] += 1
+            lifetime["tokens_saved"] += delta_tokens_saved
+            lifetime["compression_savings_usd"] = round(
+                lifetime["compression_savings_usd"] + delta_savings_usd,
+                6,
+            )
+            lifetime["total_input_tokens"] = next_total_input_tokens
+            lifetime["total_input_cost_usd"] = next_total_input_cost_usd
+
+            session = self._state["display_session"]
+            last_activity = _parse_timestamp(session.get("last_activity_at"))
+            if last_activity is None or self._is_display_session_expired(
+                last_activity,
+                reference_time=timestamp_dt,
+            ):
+                session = _empty_display_session()
+                session["started_at"] = _to_utc_iso(timestamp_dt)
+                self._state["display_session"] = session
+
+            session["requests"] += 1
+            session["tokens_saved"] += delta_tokens_saved
+            session["compression_savings_usd"] = round(
+                session["compression_savings_usd"] + delta_savings_usd,
+                6,
+            )
+            session["total_input_tokens"] += session_input_tokens_delta
+            session["total_input_cost_usd"] = round(
+                session["total_input_cost_usd"] + session_input_cost_delta,
+                6,
+            )
+            total_before = session["tokens_saved"] + session["total_input_tokens"]
+            session["savings_percent"] = round(
+                (session["tokens_saved"] / total_before * 100) if total_before > 0 else 0.0,
+                2,
+            )
+            session["last_activity_at"] = _to_utc_iso(timestamp_dt)
+            if session.get("started_at") is None:
+                session["started_at"] = session["last_activity_at"]
+
+            if delta_tokens_saved > 0:
+                self._state["history"].append(
+                    {
+                        "timestamp": _to_utc_iso(timestamp_dt),
+                        "total_tokens_saved": lifetime["tokens_saved"],
+                        "compression_savings_usd": lifetime["compression_savings_usd"],
+                        "total_input_tokens": lifetime["total_input_tokens"],
+                        "total_input_cost_usd": lifetime["total_input_cost_usd"],
+                    }
+                )
+                self._trim_history_locked(reference_time=timestamp_dt)
+
+            self._save_locked()
+            return True
+
     def stats_preview(self, recent_points: int = 20) -> dict[str, Any]:
         """Return a compact preview for `/stats`."""
         snapshot = self.snapshot()
@@ -264,6 +475,8 @@ class SavingsTracker:
             "schema_version": snapshot["schema_version"],
             "storage_path": snapshot["storage_path"],
             "lifetime": snapshot["lifetime"],
+            "display_session": snapshot["display_session"],
+            "display_session_policy": snapshot["display_session_policy"],
             "history_points": len(snapshot["history"]),
             "recent_history": snapshot["history"][-recent_points:],
             "retention": snapshot["retention"],
@@ -284,6 +497,8 @@ class SavingsTracker:
             "generated_at": _to_utc_iso(_utc_now()),
             "storage_path": snapshot["storage_path"],
             "lifetime": snapshot["lifetime"],
+            "display_session": snapshot["display_session"],
+            "display_session_policy": snapshot["display_session_policy"],
             "history": history,
             "series": series,
             "exports": {
@@ -339,6 +554,10 @@ class SavingsTracker:
                 "schema_version": SCHEMA_VERSION,
                 "storage_path": str(self._path),
                 "lifetime": dict(self._state["lifetime"]),
+                "display_session": self._display_session_snapshot_locked(),
+                "display_session_policy": {
+                    "rollover_inactivity_minutes": self._display_session_inactivity_minutes,
+                },
                 "history": history,
                 "retention": {
                     "max_history_points": self._max_history_points,
@@ -350,11 +569,13 @@ class SavingsTracker:
         return {
             "schema_version": SCHEMA_VERSION,
             "lifetime": {
+                "requests": 0,
                 "tokens_saved": 0,
                 "compression_savings_usd": 0.0,
                 "total_input_tokens": 0,
                 "total_input_cost_usd": 0.0,
             },
+            "display_session": _empty_display_session(),
             "history": [],
         }
 
@@ -386,11 +607,13 @@ class SavingsTracker:
         normalized_history.sort(key=lambda item: item["timestamp"])
 
         lifetime_raw = raw.get("lifetime", {})
+        lifetime_requests = 0
         lifetime_tokens_saved = 0
         lifetime_savings_usd = 0.0
         lifetime_input_tokens = 0
         lifetime_input_cost_usd = 0.0
         if isinstance(lifetime_raw, dict):
+            lifetime_requests = _coerce_int(lifetime_raw.get("requests"))
             lifetime_tokens_saved = _coerce_int(lifetime_raw.get("tokens_saved"))
             lifetime_savings_usd = _coerce_float(lifetime_raw.get("compression_savings_usd"))
             lifetime_input_tokens = _coerce_int(lifetime_raw.get("total_input_tokens"))
@@ -415,11 +638,13 @@ class SavingsTracker:
         state = {
             "schema_version": SCHEMA_VERSION,
             "lifetime": {
+                "requests": lifetime_requests,
                 "tokens_saved": lifetime_tokens_saved,
                 "compression_savings_usd": round(lifetime_savings_usd, 6),
                 "total_input_tokens": lifetime_input_tokens,
                 "total_input_cost_usd": round(lifetime_input_cost_usd, 6),
             },
+            "display_session": _normalize_display_session(raw.get("display_session")),
             "history": normalized_history,
         }
 
@@ -463,6 +688,7 @@ class SavingsTracker:
             payload = {
                 "schema_version": SCHEMA_VERSION,
                 "lifetime": self._state["lifetime"],
+                "display_session": self._state["display_session"],
                 "history": self._state["history"],
             }
             json_data = json.dumps(payload, indent=2)
@@ -487,6 +713,47 @@ class SavingsTracker:
         except OSError as e:
             logger.warning("Failed to save savings history to %s: %s", self._path, e)
 
+    def _display_session_snapshot_locked(
+        self,
+        reference_time: datetime | None = None,
+    ) -> dict[str, Any]:
+        session = dict(self._state["display_session"])
+        last_activity = _parse_timestamp(session.get("last_activity_at"))
+        if last_activity is None or self._is_display_session_expired(
+            last_activity,
+            reference_time=reference_time,
+        ):
+            return _empty_display_session()
+
+        total_before = _coerce_int(session.get("tokens_saved")) + _coerce_int(
+            session.get("total_input_tokens")
+        )
+        session["savings_percent"] = round(
+            (_coerce_int(session.get("tokens_saved")) / total_before * 100)
+            if total_before > 0
+            else 0.0,
+            2,
+        )
+        session["compression_savings_usd"] = round(
+            _coerce_float(session.get("compression_savings_usd")),
+            6,
+        )
+        session["total_input_cost_usd"] = round(
+            _coerce_float(session.get("total_input_cost_usd")),
+            6,
+        )
+        return session
+
+    def _is_display_session_expired(
+        self,
+        last_activity: datetime,
+        *,
+        reference_time: datetime | None = None,
+    ) -> bool:
+        return (reference_time or _utc_now()) - last_activity > timedelta(
+            minutes=self._display_session_inactivity_minutes
+        )
+
     def _build_rollup(self, history: list[dict[str, Any]], bucket: str) -> list[dict[str, Any]]:
         if not history:
             return []

headroom/proxy/server.py

@@ -1269,6 +1269,7 @@ class PrometheusMetrics:
         waste_signals: dict[str, int] | None = None,
         cache_read_tokens: int = 0,
         cache_write_tokens: int = 0,
+        uncached_input_tokens: int = 0,
     ):
         """Record metrics for a request."""
         async with self._lock:
@@ -1342,14 +1343,17 @@ class PrometheusMetrics:
             if len(self.savings_history) > 500:
                 self.savings_history = self.savings_history[-500:]
 
-            if tokens_saved > 0:
-                total_input_tokens, total_input_cost_usd = self._current_savings_tracker_totals()
-                self.savings_tracker.record_compression_savings(
-                    model=model,
-                    tokens_saved=tokens_saved,
-                    total_input_tokens=total_input_tokens,
-                    total_input_cost_usd=total_input_cost_usd,
-                )
+            total_input_tokens, total_input_cost_usd = self._current_savings_tracker_totals()
+            self.savings_tracker.record_request(
+                model=model,
+                input_tokens=input_tokens,
+                tokens_saved=tokens_saved,
+                cache_read_tokens=cache_read_tokens,
+                cache_write_tokens=cache_write_tokens,
+                uncached_input_tokens=uncached_input_tokens,
+                total_input_tokens=total_input_tokens,
+                total_input_cost_usd=total_input_cost_usd,
+            )
 
     async def record_rate_limited(self):
         async with self._lock:
@@ -3082,6 +3086,7 @@ class HeadroomProxy:
                     waste_signals=waste_signals_dict,
                     cache_read_tokens=cr_tokens,
                     cache_write_tokens=cw_tokens,
+                    uncached_input_tokens=uncached_input_tokens,
                 )
 
                 # Log request
@@ -4843,6 +4848,7 @@ class HeadroomProxy:
                     pipeline_timing=pipeline_timing,
                     cache_read_tokens=cache_read_tokens,
                     cache_write_tokens=cache_write_tokens,
+                    uncached_input_tokens=uncached_input_tokens,
                 )
 
         return StreamingResponse(
@@ -7386,6 +7392,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         - Request metrics (total, cached, failed, by model/provider)
         - Token usage and savings
         - Cost tracking
+        - Canonical persisted display_session metrics for downstream dashboards
         - Compression (CCR) statistics
         - Telemetry/TOIN (data flywheel) statistics
         - Cache and rate limiter stats
@@ -7483,6 +7490,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)
         total_tokens_all_layers = compression_tokens + cli_tokens_avoided
         persistent_savings = m.savings_tracker.stats_preview()
+        display_session = persistent_savings.get("display_session", {})
 
         return {
             "summary": summary,
@@ -7558,6 +7566,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             else {},
             "waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},
             "savings_history": m.savings_history[-100:],  # Last 100 data points
+            "display_session": display_session,
             "persistent_savings": persistent_savings,
             "prefix_cache": prefix_cache_stats,
             "cost": _merge_cost_stats(
@@ -7605,7 +7614,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         format: Literal["json", "csv"] = "json",
         series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",
     ):
-        """Get durable proxy compression savings history for frontends."""
+        """Get durable proxy compression history plus display-session state."""
         if format == "csv":
             filename = f"headroom-stats-history-{series}.csv"
             return Response(

tests/test_proxy_savings_history.py

@@ -18,15 +18,21 @@ from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, Saving
 from headroom.proxy.server import ProxyConfig, create_app
 
 
-def _record_request(client: TestClient, *, model: str, tokens_saved: int) -> None:
+def _record_request(
+    client: TestClient,
+    *,
+    model: str,
+    tokens_saved: int,
+    input_tokens: int = 120,
+) -> None:
     proxy = client.app.state.proxy
     if proxy.cost_tracker:
-        proxy.cost_tracker.record_tokens(model, tokens_saved, 120)
+        proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)
     asyncio.run(
         proxy.metrics.record_request(
             provider="openai",
             model=model,
-            input_tokens=120,
+            input_tokens=input_tokens,
             output_tokens=24,
             tokens_saved=tokens_saved,
             latency_ms=15.0,
@@ -99,13 +105,15 @@ def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
     tracker = SavingsTracker(path=str(path), max_history_points=1, max_history_age_days=2)
     snapshot = tracker.snapshot()
 
-    assert snapshot["schema_version"] == 1
+    assert snapshot["schema_version"] == 2
     assert snapshot["lifetime"] == {
+        "requests": 0,
         "tokens_saved": 30,
         "compression_savings_usd": pytest.approx(0.03),
         "total_input_tokens": 0,
         "total_input_cost_usd": 0.0,
     }
+    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
     assert snapshot["history"] == [
         {
             "timestamp": "2026-03-27T09:00:00Z",
@@ -129,11 +137,13 @@ def test_non_dict_savings_state_resets_to_default(tmp_path):
     snapshot = tracker.snapshot()
 
     assert snapshot["lifetime"] == {
+        "requests": 0,
         "tokens_saved": 0,
         "compression_savings_usd": 0.0,
         "total_input_tokens": 0,
         "total_input_cost_usd": 0.0,
     }
+    assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
     assert snapshot["history"] == []
 
 
@@ -223,9 +233,17 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
     assert savings_tracker_module._estimate_compression_savings_usd(
         "claude-sonnet-4-6", 100
     ) == pytest.approx(0.2)
+    assert savings_tracker_module._estimate_input_cost_usd(
+        "claude-sonnet-4-6",
+        100,
+        cache_read_tokens=10,
+        cache_write_tokens=5,
+        uncached_input_tokens=85,
+    ) == pytest.approx(0.2)
 
     fake_litellm.model_cost = {}
     assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
 
     monkeypatch.setattr(
         fake_litellm,
@@ -237,6 +255,86 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
 
     monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)
     assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+    assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
+
+
+def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(
+    tmp_path, monkeypatch
+):
+    path = tmp_path / "proxy_savings.json"
+    tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_estimate_compression_savings_usd",
+        lambda model, tokens_saved: tokens_saved / 1000.0,
+    )
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_estimate_input_cost_usd",
+        lambda model, input_tokens, **kwargs: input_tokens / 1000.0,
+    )
+
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=120,
+        tokens_saved=0,
+        timestamp="2026-03-27T09:00:00Z",
+    )
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=80,
+        tokens_saved=20,
+        timestamp="2026-03-27T09:10:00Z",
+    )
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),
+    )
+    active_session = tracker.snapshot()["display_session"]
+    assert active_session == {
+        "requests": 2,
+        "tokens_saved": 20,
+        "compression_savings_usd": pytest.approx(0.02),
+        "total_input_tokens": 200,
+        "total_input_cost_usd": pytest.approx(0.2),
+        "savings_percent": pytest.approx(9.09),
+        "started_at": "2026-03-27T09:00:00Z",
+        "last_activity_at": "2026-03-27T09:10:00Z",
+    }
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),
+    )
+    assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()
+
+    tracker.record_request(
+        model="gpt-4o",
+        input_tokens=50,
+        tokens_saved=5,
+        timestamp="2026-03-27T10:05:00Z",
+    )
+
+    monkeypatch.setattr(
+        savings_tracker_module,
+        "_utc_now",
+        lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),
+    )
+    rolled = tracker.snapshot()
+    assert rolled["lifetime"]["requests"] == 3
+    assert rolled["display_session"] == {
+        "requests": 1,
+        "tokens_saved": 5,
+        "compression_savings_usd": pytest.approx(0.005),
+        "total_input_tokens": 50,
+        "total_input_cost_usd": pytest.approx(0.05),
+        "savings_percent": pytest.approx(9.09),
+        "started_at": "2026-03-27T10:05:00Z",
+        "last_activity_at": "2026-03-27T10:05:00Z",
+    }
 
 
 def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):
@@ -407,11 +505,15 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
         history = client.get("/stats-history")
         assert history.status_code == 200
         history_data = history.json()
-        assert history_data["schema_version"] == 1
+        assert history_data["schema_version"] == 2
         assert history_data["storage_path"] == str(savings_path)
         assert history_data["lifetime"]["tokens_saved"] == 40
         assert history_data["lifetime"]["total_input_tokens"] == 120
         assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)
+        assert history_data["display_session"]["requests"] == 1
+        assert history_data["display_session"]["tokens_saved"] == 40
+        assert history_data["display_session"]["total_input_tokens"] == 120
+        assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)
         assert list(history_data["series"].keys()) == ["hourly", "daily", "weekly", "monthly"]
         assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]
         assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120
@@ -419,10 +521,14 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
             0.24
         )
 
+        assert stats_data["display_session"] == history_data["display_session"]
+        assert stats_data["persistent_savings"]["display_session"] == history_data["display_session"]
+
     with TestClient(create_app(config)) as client:
         history = client.get("/stats-history")
         assert history.status_code == 200
         assert history.json()["lifetime"]["tokens_saved"] == 40
+        assert history.json()["display_session"]["requests"] == 1
 
         _record_request(client, model="gpt-4o", tokens_saved=15)
 
@@ -430,7 +536,12 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
         assert updated["lifetime"]["tokens_saved"] == 55
         assert updated["lifetime"]["total_input_tokens"] == 240
         assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+        assert updated["lifetime"]["requests"] == 2
         assert len(updated["history"]) == 2
+        assert updated["display_session"]["requests"] == 2
+        assert updated["display_session"]["tokens_saved"] == 55
+        assert updated["display_session"]["total_input_tokens"] == 240
+        assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)
         assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240
         assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)
 
@@ -438,6 +549,7 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
         assert persisted["lifetime"]["tokens_saved"] == 55
         assert persisted["lifetime"]["total_input_tokens"] == 240
         assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+        assert persisted["display_session"]["requests"] == 2
 
 
 def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):