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, 13 insertions, 2 deletions

diff --git a/packages/transport-contract/src/index.ts b/packages/transport-contract/src/index.ts
index fbb61fc..95111ae 100644
--- a/packages/transport-contract/src/index.ts
+++ b/packages/transport-contract/src/index.ts
@@ -192,10 +192,21 @@ export interface WarmResponse {
 	readonly cacheReadTokens: number;
 	readonly cacheWriteTokens: number;
 	/**
-	 * Cache-hit percent: `round(clamp(cacheReadTokens / inputTokens, 0, 1) * 100)`
-	 * (0 when `inputTokens <= 0`).
+	 * **Cache rate** — what fraction of THIS request's prompt was served from cache:
+	 * `round(cacheReadTokens / inputTokens * 100)` (0 when `inputTokens <= 0`).
+	 * (`inputTokens` is the TOTAL prompt incl. cached, so this is in [0,100].)
 	 */
 	readonly cachePct: number;
+	/**
+	 * **Expected cache (retention)** — of the cacheable prefix this warm touched, how
+	 * much was still warm and read back vs. had to be (re)written:
+	 * `round(cacheReadTokens / (cacheReadTokens + cacheWriteTokens) * 100)` (0 when the
+	 * sum is 0). For a healthy warm this is ~**100%** (the whole prefix was still
+	 * cached); it drops toward 0 as the cache expires/busts and the warm has to rewrite
+	 * it. This is the warming HEALTH signal — distinct from `cachePct` (which a warm's
+	 * tiny fresh probe makes ~equal, but which on a real turn reflects new content).
+	 */
+	readonly expectedCacheRate: number;
 }
 
 // ─── WebSocket chat ops ───────────────────────────────────────────────────────