From 48c120e5cd400b2e2b8afae0afcc7c8bc4d2ccb4 Mon Sep 17 00:00:00 2001
From: Adam Malczewski <github@tradam.dev>
Date: Tue, 2 Jun 2026 13:34:33 +0900
Subject: fix: reconcile live cacheStats to DB truth on turn-sealed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the live-accumulator overshoot a Gemini review surfaced: the
frontend adds every streamed usage event to cacheStats, but a rate-limited
fallback attempt's usage is discarded server-side (never persisted). Live
numbers overshot until a reload re-seeded from the DB aggregate.

Fix: turn-sealed (emitted AFTER the atomic usage-row write) now carries the
authoritative getUsageStatsForTab aggregate. The store REPLACES (not adds)
cacheStats with it every turn — landing the just-sealed turn's usage AND
self-healing any live drift, including the discarded-fallback overshoot. No
extra round-trip (piggybacks turn-sealed); idempotent in the happy path.

- core: add UsageStats type; getUsageStatsForTab returns it; turn-sealed gains
  optional usageStats field.
- api: agent-manager reads getUsageStatsForTab post-flush and attaches it to
  the turn-sealed emit (try/catch: omit on DB error).
- frontend: turn-sealed handler replaces cacheStats (undefined ⇒ untouched
  back-compat; null ⇒ clear).

Tests: frontend reconcile/self-heal/back-compat/null-clear; api turn-sealed
carries aggregate. 509 -> 514 passing; typecheck + biome green.
---
 packages/frontend/src/lib/tabs.svelte.ts | 18 ++++++++++++++----
 packages/frontend/src/lib/types.ts       |  7 ++++++-
 2 files changed, 20 insertions(+), 5 deletions(-)

(limited to 'packages/frontend/src/lib')

diff --git a/packages/frontend/src/lib/tabs.svelte.ts b/packages/frontend/src/lib/tabs.svelte.ts
index 54f17d9..65e35a8 100644
--- a/packages/frontend/src/lib/tabs.svelte.ts
+++ b/packages/frontend/src/lib/tabs.svelte.ts
@@ -756,10 +756,11 @@ export function createTabStore() {
 			modelId?: string | null;
 			parentTabId?: string | null;
 			// Backend usage aggregate (GET /tabs). Structurally identical to
-			// CacheStats, so it seeds `cacheStats` directly on reload. Seeding
-			// happens ONLY here (hydrate runs when tabs.length === 0, i.e. a true
-			// reload) — never on `statuses` reconnect or `turn-sealed` — so the
-			// persisted aggregate and in-session live `usage` events never overlap.
+			// CacheStats, so it seeds `cacheStats` directly on reload. This is the
+			// initial seed (hydrate runs only when tabs.length === 0, i.e. a true
+			// reload); thereafter `turn-sealed` REPLACES cacheStats with the same
+			// aggregate each turn, keeping the live accumulator reconciled to the DB
+			// truth. Neither path ADDS to live events, so there is no double-count.
 			usageStats?: CacheStats | null;
 		}> = [];
 		try {
@@ -934,6 +935,15 @@ export function createTabStore() {
 				// tail into the sealed chunk log (refetch real seqs), preserving any
 				// newer in-flight turn. Deferred while scrolled up.
 				reconcileSealedTurn(tabId, event.turnId);
+				// Reconcile cacheStats to the DB source-of-truth carried on the event.
+				// REPLACE (not add): the aggregate already includes every persisted
+				// usage row for this tab, so this both lands the just-sealed turn's
+				// usage AND self-heals any live overshoot (e.g. a rate-limited
+				// fallback attempt streamed usage live but was discarded server-side).
+				// `usageStats === undefined` (older backend) leaves cacheStats as-is.
+				if (event.usageStats !== undefined) {
+					updateTab(tabId, { cacheStats: event.usageStats ?? undefined });
+				}
 				break;
 			}
 			case "statuses": {
diff --git a/packages/frontend/src/lib/types.ts b/packages/frontend/src/lib/types.ts
index 285b4d2..173f68c 100644
--- a/packages/frontend/src/lib/types.ts
+++ b/packages/frontend/src/lib/types.ts
@@ -140,7 +140,12 @@ export type AgentEvent =
 	| { type: "turn-start"; turnId: string }
 	// Fires after the turn settled AND its chunks were persisted (after the DB
 	// write, post status:idle). Triggers the frontend's reconcile-from-DB.
-	| { type: "turn-sealed"; turnId: string }
+	// `usageStats` carries the tab's authoritative usage aggregate (read after the
+	// usage rows were persisted); the store REPLACES `cacheStats` with it,
+	// reconciling the live accumulator to the DB truth (self-heals the live
+	// overshoot from a discarded rate-limited fallback attempt). null ⇒ no usage
+	// rows; absent ⇒ leave cacheStats untouched.
+	| { type: "turn-sealed"; turnId: string; usageStats?: CacheStats | null }
 	// Sent on every WS (re)connect: a snapshot of every tab the backend is
 	// currently tracking and its live status. The frontend uses this to
 	// detect desync after a reconnect (e.g. bun --watch restart killed the
-- 
cgit v1.2.3