tokenol 0.3.0__tar.gz → 0.3.2__tar.gz

{tokenol-0.3.0 → tokenol-0.3.2}/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to tokenol are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] — 2026-04-28
+
+### Fixed
+- **Dashboard fallback endpoints no longer freeze on stale turn counts.**
+  The 0.3.1 `/api/snapshot` fast-path stopped refreshing
+  `app.state.snapshot_result`, so every endpoint that fell back to it
+  (`/api/hourly`, `/api/daily`, `/api/models`, `/api/recent`, `/api/session/*`,
+  `/api/project/*`, `/api/breakdown/*`, `/api/search`, `/api/model/*`,
+  `/api/tool/*`) silently froze at first-page-load turn counts. Symptom: the
+  HIT% panel showed live turns but switching to $/KW, CTX, Cache Reuse, Output,
+  or Cost rendered stale numbers. Fix: `SnapshotBroadcaster` now exposes its
+  freshest `SnapshotResult`, and fallback endpoints prefer it over the
+  app-level cache.
+
+## [0.3.1] — 2026-04-27
+
+### Fixed
+- **Dashboard auto-update self-heals from SSE drift.** The live dashboard
+  could intermittently freeze on stale tile/chart values while the SSE
+  connection appeared healthy (dot green, messages arriving), requiring a
+  hard reload. Reproduced reliably in long-lived browser tabs; root cause
+  is browser-environmental (extension hooks, accumulated tab state, or
+  long-lived `EventSource` quirks). Fix is a layered, root-cause-agnostic
+  resilience set in the static client:
+  - `/api/snapshot` polling backstop every 30 s while the tab is visible —
+    state self-heals within 30 s even if SSE delivery silently breaks.
+  - Force-reconnect on `visibilitychange → visible` when the last message
+    is older than 15 s (browsers throttle background-tab timers/SSE).
+  - 90 s SSE staleness watchdog (silent stalls don't always fire `onerror`).
+  - Live "last update Ns ago" tooltip on the SSE dot for at-a-glance
+    freshness.
+
+### Changed
+- `/api/snapshot` reuses `SnapshotBroadcaster.cached_payload(period)` when
+  an SSE group is live for the requested period, avoiding a redundant full
+  rebuild. Cuts the snapshot fetch from ~175 ms to ~100 ms (mostly JSON
+  serialization), making the new poll backstop essentially free.
+
 ## [0.3.0] — 2026-04-27
 
 ### Changed

{tokenol-0.3.0 → tokenol-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenol
-Version: 0.3.0
+Version: 0.3.2
 Summary: Audit Claude Code JSONL session logs: track cost, cache health, context blow-ups, and 5h-window pressure.
 Project-URL: Homepage, https://github.com/farhanferoz/tokenol
 Project-URL: Issues, https://github.com/farhanferoz/tokenol/issues
@@ -148,7 +148,11 @@ tokenol serve --all-projects --tick 2s --reference 25
 tokenol serve --open
 ```
 
-The dashboard updates via SSE as Claude Code writes events to disk. Main page layout (top to bottom):
+The dashboard updates via SSE as Claude Code writes events to disk. The server gates rebuilds on JSONL file changes — when no files have changed, it idles at near-zero CPU and forces a refresh at most once a minute (so time-windowed panels like Recent Activity don't drift more than ~60 s from wall clock). Multiple browser tabs share a single producer, so opening more tabs does not multiply server cost.
+
+If SSE delivery silently stalls (browser tab throttling, extension hooks, long-lived `EventSource` quirks), the client self-heals: it polls `/api/snapshot` every 30 s as a backstop, force-reconnects on tab-visibility return, and runs a 90 s staleness watchdog. `/api/snapshot` reuses the broadcaster's cached payload while an SSE group is live, so the backstop costs only a JSON serialize. Hover the live-status dot for a "last update Ns ago" indicator.
+
+Main page layout (top to bottom):
 
 | Panel | What it shows |
 |---|---|
@@ -173,7 +177,7 @@ Keyboard shortcuts: `?` Glossary · `/` Find · `,` Settings · `Esc` close/back
 
 ### Preferences
 
-User preferences (tick cadence and threshold overrides) are saved to:
+User preferences (gate-poll cadence and threshold overrides) are saved to:
 
 ```
 $XDG_CONFIG_HOME/tokenol/prefs.json   # default: ~/.config/tokenol/prefs.json
@@ -197,6 +201,8 @@ Shape:
 }
 ```
 
+`tick_seconds` is how often the server stat-checks the JSONL files for changes (cheap). The full snapshot only rebuilds on a detected change or once per ~60 s heartbeat — so a long `tick_seconds` mainly reduces stat-syscall noise, not rebuild cost.
+
 Reset to defaults via the Settings modal (`POST /api/prefs {"thresholds": "reset"}`).
 
 ### Session drill-down

{tokenol-0.3.0 → tokenol-0.3.2}/README.md

@@ -115,7 +115,11 @@ tokenol serve --all-projects --tick 2s --reference 25
 tokenol serve --open
 ```
 
-The dashboard updates via SSE as Claude Code writes events to disk. Main page layout (top to bottom):
+The dashboard updates via SSE as Claude Code writes events to disk. The server gates rebuilds on JSONL file changes — when no files have changed, it idles at near-zero CPU and forces a refresh at most once a minute (so time-windowed panels like Recent Activity don't drift more than ~60 s from wall clock). Multiple browser tabs share a single producer, so opening more tabs does not multiply server cost.
+
+If SSE delivery silently stalls (browser tab throttling, extension hooks, long-lived `EventSource` quirks), the client self-heals: it polls `/api/snapshot` every 30 s as a backstop, force-reconnects on tab-visibility return, and runs a 90 s staleness watchdog. `/api/snapshot` reuses the broadcaster's cached payload while an SSE group is live, so the backstop costs only a JSON serialize. Hover the live-status dot for a "last update Ns ago" indicator.
+
+Main page layout (top to bottom):
 
 | Panel | What it shows |
 |---|---|
@@ -140,7 +144,7 @@ Keyboard shortcuts: `?` Glossary · `/` Find · `,` Settings · `Esc` close/back
 
 ### Preferences
 
-User preferences (tick cadence and threshold overrides) are saved to:
+User preferences (gate-poll cadence and threshold overrides) are saved to:
 
 ```
 $XDG_CONFIG_HOME/tokenol/prefs.json   # default: ~/.config/tokenol/prefs.json
@@ -164,6 +168,8 @@ Shape:
 }
 ```
 
+`tick_seconds` is how often the server stat-checks the JSONL files for changes (cheap). The full snapshot only rebuilds on a detected change or once per ~60 s heartbeat — so a long `tick_seconds` mainly reduces stat-syscall noise, not rebuild cost.
+
 Reset to defaults via the Settings modal (`POST /api/prefs {"thresholds": "reset"}`).
 
 ### Session drill-down

{tokenol-0.3.0 → tokenol-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenol"
-version = "0.3.0"
+version = "0.3.2"
 description = "Audit Claude Code JSONL session logs: track cost, cache health, context blow-ups, and 5h-window pressure."
 readme = "README.md"
 license = { text = "MIT" }

{tokenol-0.3.0 → tokenol-0.3.2}/src/tokenol/__init__.py

@@ -1,3 +1,3 @@
 """tokenol — Claude Code usage & efficiency audit tool."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{tokenol-0.3.0 → tokenol-0.3.2}/src/tokenol/serve/app.py

@@ -113,6 +113,16 @@ def _build_and_cache_snapshot(request: Request, period: str = "today") -> Snapsh
     return result
 
 
+def _current_snapshot_result(request: Request) -> SnapshotResult:
+    """Prefer the broadcaster's latest build; fall back to the app cache or a fresh build."""
+    broadcaster = getattr(request.app.state, "broadcaster", None)
+    if broadcaster is not None:
+        latest = broadcaster.latest_result()
+        if latest is not None:
+            return latest
+    return request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+
+
 def create_app(
     config: ServerConfig | None = None,
     prefs_path: Path | None = None,
@@ -182,11 +192,18 @@ def create_app(
 
     @app.get("/api/snapshot")
     async def api_snapshot(request: Request, period: str = "today"):
+        # Reuse the broadcaster's cached payload when a SSE group is live for
+        # this period — avoids a second full rebuild for polling backstops.
+        broadcaster = getattr(request.app.state, "broadcaster", None)
+        if broadcaster is not None:
+            cached = broadcaster.cached_payload(period)
+            if cached is not None:
+                return JSONResponse(cached)
         return JSONResponse(_build_and_cache_snapshot(request, period=period).payload)
 
     @app.get("/api/session/{session_id}")
     async def api_session_detail(session_id: str, request: Request):
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         session = next((s for s in result.sessions if s.session_id == session_id), None)
         if session is None:
             raise HTTPException(status_code=404, detail="Session not found")
@@ -194,7 +211,7 @@ def create_app(
 
     @app.get("/api/session/{session_id}/turn/{turn_idx}")
     async def api_turn_detail(session_id: str, turn_idx: int, request: Request):
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         session = next((s for s in result.sessions if s.session_id == session_id), None)
         if session is None:
             raise HTTPException(status_code=404, detail="Session not found")
@@ -211,7 +228,7 @@ def create_app(
             raise HTTPException(status_code=400, detail="Invalid cwd encoding") from None
         if range not in ("1d", "7d", "14d", "30d", "all"):
             raise HTTPException(status_code=400, detail="Invalid range — use 1d, 7d, 14d, 30d, or all")
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         detail = await asyncio.get_running_loop().run_in_executor(
             None,
             lambda: build_project_detail(cwd, result.sessions, range_key=range),
@@ -228,7 +245,7 @@ def create_app(
             raise HTTPException(status_code=400, detail="Invalid date format — use YYYY-MM-DD") from None
         if parsed_date > date.today():
             raise HTTPException(status_code=400, detail="Future dates not supported")
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         detail = await asyncio.get_running_loop().run_in_executor(
             None,
             lambda: build_day_detail(parsed_date, result.turns, result.sessions),
@@ -265,7 +282,7 @@ def create_app(
             parsed = date.fromisoformat(target_date)
         except ValueError:
             raise HTTPException(status_code=400, detail="Invalid date — use YYYY-MM-DD") from None
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         return JSONResponse(build_hourly_panel(parsed, result.turns, result.sessions, metric, project, model))
 
     @app.get("/api/daily")
@@ -282,7 +299,7 @@ def create_app(
             raise HTTPException(status_code=400, detail=f"Unknown metric — valid: {sorted(VALID_METRICS)}")
         if range not in ("7d", "30d", "90d", "all"):
             raise HTTPException(status_code=400, detail="range must be 7d, 30d, 90d, or all")
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         # Fall back silently to the longest available window when the requested range
         # exceeds the data we have — return 200 with a `note` so the UI can caption it.
         # Returning 400 here forced clients to special-case "policy" failures even though
@@ -311,7 +328,7 @@ def create_app(
 
     @app.get("/api/models")
     async def api_models(request: Request, range: str = "today"):
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today())
         turns = [t for t in result.turns if t.timestamp.date() >= since] if since else result.turns
         return JSONResponse(build_models_panel(turns, range))
@@ -320,7 +337,7 @@ def create_app(
     async def api_recent(request: Request, window: str = "60m"):
         if window not in _WINDOW_MINUTES:
             raise HTTPException(status_code=400, detail=f"window must be one of: {list(_WINDOW_MINUTES)}")
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         now = datetime.now(tz=timezone.utc)
         return JSONResponse(build_recent_activity_panel(
             result.turns, result.sessions, now, _WINDOW_MINUTES[window]
@@ -328,7 +345,7 @@ def create_app(
 
     @app.get("/api/model/{name}")
     async def api_model_detail(name: str, request: Request):
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         detail = build_model_detail(name, result.turns, result.sessions)
         if detail is None:
             raise HTTPException(status_code=404, detail="Model not found")
@@ -336,7 +353,7 @@ def create_app(
 
     @app.get("/api/tool/{name}")
     async def api_tool_detail(name: str, request: Request):
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         detail = build_tool_detail(name, result.turns, result.sessions)
         if detail is None:
             raise HTTPException(status_code=404, detail="Tool not found")
@@ -346,7 +363,7 @@ def create_app(
     async def api_search(request: Request, q: str = ""):
         if not q.strip():
             return JSONResponse({"hits": [], "query": q})
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         return JSONResponse(build_search_results(q, result.turns, result.sessions))
 
     @app.get("/api/prefs")
@@ -395,7 +412,7 @@ def create_app(
     @app.get("/api/breakdown/summary")
     async def api_breakdown_summary(request: Request, range: str = "30d"):
         _validate_breakdown_range(range)
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today()) if range != "all" else None
         if since is None:
             turns = list(result.turns)
@@ -422,7 +439,7 @@ def create_app(
     @app.get("/api/breakdown/daily-tokens")
     async def api_breakdown_daily_tokens(request: Request, range: str = "30d"):
         _validate_breakdown_range(range)
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today()) if range != "all" else None
         if since is None:
             turns = list(result.turns)
@@ -449,7 +466,7 @@ def create_app(
     @app.get("/api/breakdown/by-project")
     async def api_breakdown_by_project(request: Request, range: str = "30d"):
         _validate_breakdown_range(range)
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today()) if range != "all" else None
 
         cwd_by_sid = _grouped_cwd_by_sid(result.sessions)
@@ -477,7 +494,7 @@ def create_app(
     @app.get("/api/breakdown/by-model")
     async def api_breakdown_by_model(request: Request, range: str = "30d"):
         _validate_breakdown_range(range)
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today()) if range != "all" else None
 
         buckets = _bucket_turns(
@@ -501,7 +518,7 @@ def create_app(
     @app.get("/api/breakdown/tools")
     async def api_breakdown_tools(request: Request, range: str = "30d"):
         _validate_breakdown_range(range)
-        result = request.app.state.snapshot_result or _build_and_cache_snapshot(request)
+        result = _current_snapshot_result(request)
         since = range_since(range, date.today()) if range != "all" else None
 
         total: Counter[str] = Counter()

{tokenol-0.3.0 → tokenol-0.3.2}/src/tokenol/serve/static/app.js

@@ -50,18 +50,44 @@ function _setPeriod(p) { localStorage.setItem(_LS_PERIOD, p); }
 
 // ---- SSE dot ----
 const _dot = $('sse-dot');
+let _dotBaseTitle = '';
 function _dotState(cls, title) {
   _dot.className = 'sse-dot' + (cls ? ' ' + cls : '');
+  _dotBaseTitle = title;
   _dot.title = title;
 }
+// Live tooltip: "Live — connected · last update 5s ago" — updated every second
+// so you can hover-and-tell whether the page is genuinely stale.
+setInterval(() => {
+  if (!_dot) return;
+  if (_lastMsgAt) {
+    const ageS = Math.round((Date.now() - _lastMsgAt) / 1000);
+    _dot.title = `${_dotBaseTitle} · last update ${ageS}s ago`;
+  } else {
+    _dot.title = _dotBaseTitle;
+  }
+}, 1_000);
 
 // ---- SSE connection ----
 let _es = null;
 let _reconnectDelay = 1_000;
 let _fiveXXSince    = null;
+let _lastMsgAt      = 0;
+// Server heartbeat is ≤60s; >90s without a message means the connection
+// silently stalled (system sleep, NAT drop, transparent proxy).
+const _STALE_MS = 90_000;
+
+function _scheduleReconnect(reason) {
+  if (_es) { _es.close(); _es = null; }
+  _lastMsgAt = 0;
+  _dotState('amber', `SSE ${reason} — reconnecting…`);
+  setTimeout(() => _connect(_getPeriod()), _reconnectDelay);
+  _reconnectDelay = Math.min(_reconnectDelay * 2, 30_000);
+}
 
 function _connect(period) {
   if (_es) { _es.close(); _es = null; }
+  _lastMsgAt = 0;
   _dotState('', 'SSE connecting…');
   _es = new EventSource(`/api/stream?period=${period}`);
 
@@ -69,22 +95,48 @@ function _connect(period) {
     _dotState('connected', 'Live — connected');
     _reconnectDelay = 1_000;
     _fiveXXSince    = null;
+    _lastMsgAt      = Date.now();
     _resetIdleTimer();
   };
 
   _es.onmessage = ev => {
+    _lastMsgAt = Date.now();
     try { _applyPayload(JSON.parse(ev.data)); }
     catch (e) { console.error('SSE parse', e); }
   };
 
-  _es.onerror = () => {
-    _dotState('amber', 'SSE disconnected — reconnecting…');
-    _es.close(); _es = null;
-    setTimeout(() => _connect(_getPeriod()), _reconnectDelay);
-    _reconnectDelay = Math.min(_reconnectDelay * 2, 30_000);
-  };
+  _es.onerror = () => _scheduleReconnect('disconnected');
 }
 
+// Watchdog: EventSource doesn't reliably fire onerror on silent stalls.
+setInterval(() => {
+  if (!_es || !_lastMsgAt) return;
+  if (Date.now() - _lastMsgAt > _STALE_MS) _scheduleReconnect('stalled');
+}, 10_000);
+
+// Browsers throttle background tabs — timers slow, SSE may pause. On tab
+// return, if our last message is older than one tick + slack, force a fresh
+// reconnect so the user never sees stale data.
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState !== 'visible') return;
+  if (!_lastMsgAt || Date.now() - _lastMsgAt > 15_000) {
+    _reconnectDelay = 1_000;
+    _scheduleReconnect('tab visible');
+  }
+});
+
+// Backstop: re-fetch the authoritative snapshot periodically. SSE is the
+// fast path; this catches any case where SSE flows but the merged client
+// state drifts (browser extension hooks, long-lived tab quirks, etc.).
+// Skipped while hidden — visibilitychange handler covers the wakeup case.
+setInterval(() => {
+  if (document.visibilityState !== 'visible') return;
+  _fetchSnapshot(_getPeriod());
+}, 30_000);
+
+// Debug: window.__tokenolForceReconnect() simulates a silent stall.
+window.__tokenolForceReconnect = () => _scheduleReconnect('forced (debug)');
+
 // ---- initial fetch ----
 async function _fetchSnapshot(period) {
   try {

{tokenol-0.3.0 → tokenol-0.3.2}/src/tokenol/serve/streaming.py

@@ -177,6 +177,8 @@ class SnapshotBroadcaster:
         self._heartbeat_s = heartbeat_s
         self._groups: dict[str, _Group] = {}
         self._lock = asyncio.Lock()
+        # turns/sessions are period-agnostic, so any producer's freshest result serves all readers.
+        self._latest_result: SnapshotResult | None = None
 
     def _compute_active_keys(self) -> frozenset[tuple[str, int, int]]:
         return compute_active_keys(self._all_projects)
@@ -190,8 +192,12 @@ class SnapshotBroadcaster:
             period=period,
             thresholds=self._get_thresholds(),
         )
+        self._latest_result = result
         return result.payload
 
+    def latest_result(self) -> SnapshotResult | None:
+        return self._latest_result
+
     async def subscribe(self, period: str) -> AsyncGenerator[str, None]:
         sub = _Subscriber()
         async with self._lock:
@@ -243,3 +249,8 @@ class SnapshotBroadcaster:
     def group_count(self) -> int:
         """Number of active producer groups (testing aid)."""
         return len(self._groups)
+
+    def cached_payload(self, period: str) -> dict | None:
+        """Latest broadcast payload for *period*, or None if no group is live."""
+        grp = self._groups.get(period)
+        return grp.last_payload if grp is not None else None

{tokenol-0.3.0 → tokenol-0.3.2}/tests/test_serve_app.py

@@ -1052,3 +1052,91 @@ async def test_api_tool_detail_404_on_unknown(tmp_path: Path) -> None:
         async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
             resp = await client.get("/api/tool/NoSuchTool")
     assert resp.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_api_hourly_reflects_broadcaster_freshness(tmp_path: Path) -> None:
+    """Regression: /api/hourly must track the broadcaster, not stale app.state.snapshot_result."""
+    import asyncio
+    from datetime import datetime, timezone
+
+    from httpx import ASGITransport, AsyncClient
+
+    today = datetime.now(tz=timezone.utc).date()
+    target_date = today.isoformat()
+
+    def _turn_line(uuid: str, hour: int, minute: int) -> bytes:
+        ts = f"{target_date}T{hour:02d}:{minute:02d}:00Z"
+        return (
+            b'{"type":"assistant","timestamp":"' + ts.encode() + b'",'
+            b'"sessionId":"sess-001","requestId":"req-' + uuid.encode() + b'",'
+            b'"uuid":"' + uuid.encode() + b'","isSidechain":false,'
+            b'"model":"claude-opus-4-7",'
+            b'"message":{"id":"msg-' + uuid.encode() + b'","role":"assistant",'
+            b'"stop_reason":"end_turn",'
+            b'"usage":{"input_tokens":10,"output_tokens":20,'
+            b'"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}\n'
+        )
+
+    sess_path = tmp_path / "projects" / "sess-001.jsonl"
+    sess_path.parent.mkdir(parents=True)
+    sess_path.write_bytes(_turn_line("evt-001", 10, 0) + _turn_line("evt-002", 10, 5))
+
+    with _mock_dirs(tmp_path):
+        app = create_app(ServerConfig())
+        bc = app.state.broadcaster
+        # Force the producer to rebuild on every mtime change with no heartbeat delay.
+        bc._get_tick_seconds = lambda: 0
+        bc._heartbeat_s = 0.0
+
+        agen = bc.subscribe("today").__aiter__()
+        try:
+            await asyncio.wait_for(agen.__anext__(), timeout=5.0)
+
+            async with AsyncClient(
+                transport=ASGITransport(app=app), base_url="http://test"
+            ) as client:
+                resp = await client.get(
+                    f"/api/hourly/{target_date}?metric=cost_per_kw"
+                )
+                turns_before = sum(
+                    p["turns"] for s in resp.json()["series"] for p in s["points"]
+                )
+                assert turns_before == 2, (
+                    f"fixture has 2 assistant turns, /api/hourly saw {turns_before}"
+                )
+
+            sess_path.write_bytes(sess_path.read_bytes() + _turn_line("evt-003", 10, 30))
+
+            # Poll /api/snapshot as the sync barrier — it exercises the same fast-path
+            # the fix targets, without reaching into broadcaster internals.
+            async with AsyncClient(
+                transport=ASGITransport(app=app), base_url="http://test"
+            ) as client:
+                snapshot_turns = 0
+                for _ in range(200):
+                    resp = await client.get("/api/snapshot?period=today")
+                    snapshot_turns = sum(
+                        s["turns"]
+                        for s in resp.json()["hourly_today"]["series"]
+                    )
+                    if snapshot_turns >= 3:
+                        break
+                    await asyncio.sleep(0.02)
+                assert snapshot_turns == 3, (
+                    "broadcaster did not pick up appended turn within 4 s "
+                    f"(snapshot still reports {snapshot_turns} turns)"
+                )
+
+                resp = await client.get(
+                    f"/api/hourly/{target_date}?metric=cost_per_kw"
+                )
+                turns_after = sum(
+                    p["turns"] for s in resp.json()["series"] for p in s["points"]
+                )
+                assert turns_after == 3, (
+                    "/api/hourly returned stale turns "
+                    f"({turns_after}); expected 3 after appending one turn"
+                )
+        finally:
+            await agen.aclose()

{tokenol-0.3.0 → tokenol-0.3.2}/uv.lock

@@ -741,7 +741,7 @@ wheels = [
 
 [[package]]
 name = "tokenol"
-version = "0.2.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },