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

diff --git a/packages/transport-http/src/app.test.ts b/packages/transport-http/src/app.test.ts
index 7352b5d..22b26fc 100644
--- a/packages/transport-http/src/app.test.ts
+++ b/packages/transport-http/src/app.test.ts
@@ -449,12 +449,64 @@ describe("POST /chat/warm", () => {
 			cacheReadTokens: number;
 			cacheWriteTokens: number;
 			cachePct: number;
+			expectedCacheRate: number;
 		};
 		expect(body.inputTokens).toBe(1000);
 		expect(body.outputTokens).toBe(200);
 		expect(body.cacheReadTokens).toBe(800);
 		expect(body.cacheWriteTokens).toBe(100);
 		expect(body.cachePct).toBe(80);
+		expect(body.expectedCacheRate).toBe(89);
+	});
+
+	it("POST /chat/warm returns expectedCacheRate = round(cacheRead/(cacheRead+cacheWrite)*100)", async () => {
+		const app = createApp({
+			conversationStore: createFakeConversationStore(),
+			orchestrator: createFakeOrchestrator([]),
+			credentialStore: createFakeCredentialStore([]),
+			warmService: createFakeWarmService({
+				inputTokens: 500,
+				outputTokens: 100,
+				cacheReadTokens: 400,
+				cacheWriteTokens: 100,
+			}),
+			logger: noopLogger,
+		});
+
+		const res = await app.request("/chat/warm", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ conversationId: "conv1" }),
+		});
+
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as { expectedCacheRate: number };
+		expect(body.expectedCacheRate).toBe(80);
+	});
+
+	it("POST /chat/warm returns expectedCacheRate = 0 when cacheRead+cacheWrite is 0", async () => {
+		const app = createApp({
+			conversationStore: createFakeConversationStore(),
+			orchestrator: createFakeOrchestrator([]),
+			credentialStore: createFakeCredentialStore([]),
+			warmService: createFakeWarmService({
+				inputTokens: 100,
+				outputTokens: 50,
+				cacheReadTokens: 0,
+				cacheWriteTokens: 0,
+			}),
+			logger: noopLogger,
+		});
+
+		const res = await app.request("/chat/warm", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ conversationId: "conv1" }),
+		});
+
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as { expectedCacheRate: number };
+		expect(body.expectedCacheRate).toBe(0);
 	});
 
 	it("POST /chat/warm returns 409 when the warm service reports the conversation is generating", async () => {