fix(cache-warming): accurate cache rate + expectedCacheRate (retention) metric

The Claude cache % read 100% whenever anything was cached, because the metric's
denominator (inputTokens) excluded cached tokens on Anthropic. Fixed upstream in
../claude/provider-anthropic (inputTokens = total prompt); this commit adds the
companion retention metric and exposes it:
- transport-contract: WarmResponse += expectedCacheRate
- transport-http: POST /chat/warm returns expectedCacheRate = cacheRead/(cacheRead+cacheWrite)
- cache-warming: computeExpectedCacheRate + a per-conversation 'cache retention' surface stat
- handoff: documents the fix + cache-rate vs expected-cache (cross-turn) for the FE

Live-verified vs claude haiku: real turn cache rate 61% (was inflated 100%);
warm within TTL expectedCacheRate=100%, after expiry=0%.

1 files changed, 5 insertions, 1 deletions

diff --git a/packages/cache-warming/src/warmer.ts b/packages/cache-warming/src/warmer.ts
index 31dd41e..f50f346 100644
--- a/packages/cache-warming/src/warmer.ts
+++ b/packages/cache-warming/src/warmer.ts
@@ -5,6 +5,7 @@ import {
 	type ConversationSettings,
 	type ConversationState,
 	computeCachePct,
+	computeExpectedCacheRate,
 	DEFAULT_INTERVAL_MS,
 	isTokenCurrent,
 	MIN_INTERVAL_MS,
@@ -63,6 +64,7 @@ const DEFAULT_STATE: ConversationState = {
 	intervalMs: DEFAULT_INTERVAL_MS,
 	active: false,
 	lastPct: null,
+	lastExpectedPct: null,
 	token: 0,
 };
 
@@ -145,11 +147,13 @@ export function createCacheWarmer(deps: CacheWarmerDeps): CacheWarmer {
 			});
 		} else {
 			const pct = computeCachePct(result.inputTokens, result.cacheReadTokens);
-			setState(conversationId, { ...currentState, lastPct: pct });
+			const expectedPct = computeExpectedCacheRate(result.cacheReadTokens, result.cacheWriteTokens);
+			setState(conversationId, { ...currentState, lastPct: pct, lastExpectedPct: expectedPct });
 			deps.onSurfaceChange();
 			deps.logger.debug("cache-warming: warm complete", {
 				conversationId,
 				pct,
+				expectedPct,
 			});
 		}