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, 24 insertions, 0 deletions

diff --git a/packages/transport-http/src/logic.test.ts b/packages/transport-http/src/logic.test.ts
index 1e33f40..19b47ef 100644
--- a/packages/transport-http/src/logic.test.ts
+++ b/packages/transport-http/src/logic.test.ts
@@ -1,6 +1,7 @@
 import type { AgentEvent } from "@dispatch/kernel";
 import { describe, expect, it } from "vitest";
 import {
+	computeExpectedCacheRate,
 	isParseError,
 	isSinceSeqError,
 	parseChatBody,
@@ -197,3 +198,26 @@ describe("serializeEventLine", () => {
 		expect(parsed.reason).toBe("stop");
 	});
 });
+
+describe("computeExpectedCacheRate", () => {
+	it("returns round(cacheRead/(cacheRead+cacheWrite)*100)", () => {
+		expect(computeExpectedCacheRate(800, 200)).toBe(80);
+	});
+
+	it("returns 0 when cacheRead+cacheWrite is 0", () => {
+		expect(computeExpectedCacheRate(0, 0)).toBe(0);
+	});
+
+	it("returns 100 when all tokens are cacheRead", () => {
+		expect(computeExpectedCacheRate(500, 0)).toBe(100);
+	});
+
+	it("returns 0 when all tokens are cacheWrite", () => {
+		expect(computeExpectedCacheRate(0, 500)).toBe(0);
+	});
+
+	it("rounds to nearest integer", () => {
+		expect(computeExpectedCacheRate(1, 2)).toBe(33);
+		expect(computeExpectedCacheRate(2, 1)).toBe(67);
+	});
+});